Drag_and_Drop_Reordering_of_Relationships

Drag and Drop Reordering of Related Records in Xataface

One powerful aspect of Xataface is its abstraction of relationships between tables. Once you define a relationship users can browse related records, add new and existing related records, and delete related records to or from the relationship. For example, suppose you have a people table and a publications, you could define a relationship from people to publications to identify publications that belong to a particular person. The table's might look something like:

people table

publications table

See http://xataface.com/documentation/tutorial/getting_started/relationships for an introduction to relationships in Xataface, and how to define them.

Our relationship definition in the people table's relationships.ini file might look something like:

[my_pubications]
    publications.owner_id="$person_id"

This indicates that any publication whose owner_id column matches the current people record's person_id field is considered part of the relationship. Using our example data above, this would mean that Ben Stein's my_publications relationship would contain 3 records: "Introduction to Widgetry", "Intermediate Widgetry", and "Advanced Widgetry". In our Xataface application this means that in the "Details" tab for the "Ben Stein" record, we would see a sub-tab My Publications which would contain a list of Ben Stein's publications.

Adding Publication Order

Now that we have our relationship, what if Ben Stein wants his publications to appear in a particular order whenever they are displayed to the user. Xataface allows us to specify an "order" column for our relationship, which will cause the related records to be orderable by drag and drop (if the user has appropriate permissions).

1. Add a field to the publications table named "pub_order"
2. Change the relationship definition in the people table's relationships.ini file to tell Xataface to use the pub_order field for sorting:

   [my_pubications]
       publications.owner_id="$person_id"
       metafields:order="pub_order"

Now load up your application and navigate to the "My Publications" tab for the "Ben Stein" record. Now you're able to drag and drop rows in your application to reorder them.

Permission to Reorder Records

Only users who have been assigned the reorder_related_records permission for a record's relationship are allowed to reorder records of that relationship. By default the EDIT role contains this permission, as does any role that permits the user to edit the parent record of the relationship. The READ ONLY role does not contain this permission. If you want to explicitly deny this permission for all relationships in a record, you can simply set this permission to 0 in the associated role within your application's permissions.ini file:

[MY ROLE]
     reorder_related_records=0

For more information about permssions see:

• The Permissions.ini file reference
• Introduction to Permissions

Loading Related Records using the Xataface API

The ordering that is set via this drag and drop method is also honoured by the Xataface API when fetching related records. You can load related records using the getRelatedRecordObjects method of the Dataface_Record class. E.g.

$benStein = df_get_record('people', array('person_id'=>2));
$pubs = $benStein->getRelatedRecordObjects('my_publications');
foreach ($pubs as $pub){
    echo $pub->val('pub_title').'<br/>';
}