Tuesday, 7 May 2013

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

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

7 comments:

  1. An unbelievable blog. This blog will indisputably be definitely recommended to my friends as well.understanding men

    ReplyDelete
  2. Thanks for taking the time to discuss this, I feel strongly about it and love learning more on this topic. If possible, as you gain expertise, would you mind updating your blog with more information? It is extremely helpful for me. The Psystrology Method

    ReplyDelete
  3. Modular Kitchens have changed the idea of kitchen these days because it has provided household women with a comfortable yet an elegant place through which they can spend their quality time and space. https://adamfantacy.tumblr.com/

    ReplyDelete
  4. I got this web page from my pal who shared with me on the topic of this site and at the moment this time I am visiting this website and reading very informative articles or reviews at this place. My Blog https://hollzone.tumblr.com/

    ReplyDelete
  5. Hi, I think your blog might be having browser compatibility issues. When I look at your website in Safari, it looks fine but when opening in Internet Explorer, it has some overlapping. I just wanted to give you a quick heads up! Other then that, excellent blog! My Blog http://www.freewebsite-service.com/moviemania/

    ReplyDelete