Using the Xataface Tagger Widget for n:m relationships

The Xataface tagger widget allows you to add and remove records from a many-to-many relationship with a simple "Tag" interface.  This widget is meant to be used with a transient field (similar to the grid widget) so that users can manipulate the records in the relationship directly on the edit/new record form.

The user is able to type into a text field free form, and is assisted by auto-complete suggestions.  If they select one of the auto-complete suggestions, then they will be adding a link to an existing record.  If they don't choose one of the suggestions, they will be creating a new record in the related table and adding it to the relationship.

Since a single string isn't sufficient (in most cases) to create a new record (e.g. which field should the string be saved in?), you may need to implement that fieldname__addTag() method in the table delegate class to help guide how a tag should be added.

After the tag has been created, the user can double-click the tag to open the record's edit form and make further modifications.

Prerequisites

• You'll need to be running Xataface 2.0 or higher.

Installation

1. Create a directory named "modules" inside your application's folder, if it doesn't already exist.  (e.g. /path/to/my/app/modules).
   $ cd /path/to/my/app
$ mkdir modules
2. Change directories to the modules directory that you just created:
   $ cd modules
3. Check out the latest source of the tagger module from the SVN trunk:
   $ svn co http://weblite.ca/svn/dataface/modules/tagger/trunk tagger
   When you are done you should have the tagger source in the directory modules/tagger.  Ensure that you have modules/tagger/tagger.php, etc....  If not, you need to move it or rename it so that the path is correct.
4. Add a [_modules] section to your application's conf.ini file, if it doesn't already exist.
5. Add a line in the [_modules] section of your conf.ini file as follows:
   modules_tagger=modules/tagger/tagger.php 

Configuring a Relationship to use the Tagger Widget

Now that the tagger module is installed, we can set up our n:m relationships to be editable via a tagger widget on the edit form of the parent record.

For example, suppose we have a database with a "cities" table and a "articles" table, where cities can be associated with multiple articles and vice-versa.  I.e. There is an n:m relationship between cities and articles.

The cities relationship is defined in the articles table relationships.ini file as follows:

[cities]
    cities.id = articlecity.city_id
    articlecity.article_id = "$id"

You can see that this is a n:m relationship (among other things) because it makes use of a join table named articlecity to join them together.

Steps to Set up Tagger Widget on Cities relationship:

1. Add a transient field to the articles table's fields.ini file as follows:
   

   [cities]
       widget:type=tagger
       relationship=cities
       transient=1
       tagger_label=name
   

   
   This says that we are creating a transient field (i.e. a field that doesn't really exist in the database, but should appear on the edit and new record forms) named "cities" using the "tagger" widget.  The relationship directive sets the widget to work on the "cities" relationship.  The tagger_label directive specifies which field from the "cities" table should be used as the text that is displayed in each tag.
2. Load the "New Article" form in your browser to make sure that the tagger field shows up.  If you receive errors, you should check your PHP error log to find out what the error is.  If it worked it will look almost like a normal text field:

   

   The "Cities" field rendered with the tagger widget.

   When you start typing in the field, it will give you auto-complete suggestions as follows:

   

   Auto-complete in tagger widget.  If it finds any matching records in the related table, it will show them here.
   
   

3. Implement the cities__addTag() method in the articles delegate class.  At this point (before implementing cities__addTag()), you should be able to add existing cities as tags without error.  But if you try to enter a new city, you'll receive a little error indicator because it wasn't able to add the city to the cities table.  This is because the cities table has other NOT NULL fields that need to be filled in, other than the city name.  E.g. it needs a province or state.
   The cities__addTag() method.  Our method looks like:
   
   

   function cities__addTag(Dataface_Record $record, $value){
       $city = new Dataface_Record('cities', array());
       $city->setValues(array(
           'prov_state_id' => DEFAULT_PROV_ID,
           'name' => $value,
           'url' => strtolower($value)
       ));
       return $city;
   }
   

   
   This method takes the "article" record as the first parameter, and the string value of the tag to add as the 2nd parameter.  In this case, we are creating a new Dataface_Record for the cities table with the name specified by $value, and a default province ID.
4. Test out adding a new tag.   You can do this by clicking on "New Article", then start to type in the "Cities" field.
   
5. You should also be able to double-click the tag to reveal the edit form for the city:
   

Video Tutorial