page_name,page_id,page_title,content,keywords,language,original_page
Drag_and_Drop_Reordering_of_Relationships,39,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===

{| class=""listing listing2""
! person_id
! person_name
|-
| 1
| John Smith
|-
| 2
| Ben Stein
|-
| 3
| Harley Davidson
|-
| 4
| Trevor Linden
|}


===publications table===

{| class=""listing listing2""
! publication_id
! owner_id
! pub_title
|-
| 1
| 2
| Introduction to widgetry
|-
| 2
| 2
| Intermediate Widgetry
|-
| 3
| 2
| Advanced Widgetry
|-
| 4
| 3
| How to play the violin
|}


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:

<code>
[my_pubications]
    publications.owner_id=""$person_id""
</code>

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).

# Add a field to the ''publications'' table named ""pub_order""
# Change the relationship definition in the people table's [[relationships.ini file]] to tell Xataface to use the pub_order field for sorting:<code>
[my_pubications]
    publications.owner_id=""$person_id""
    metafields:order=""pub_order""
</code>

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]]:

<code>
[MY ROLE]
     reorder_related_records=0
</code>

For more information about permssions see:

* [[permissions.ini file|The Permissions.ini file reference]]
* [http://xataface.com/documentation/tutorial/getting_started/permissions 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 [http://dataface.weblite.ca/getRelatedRecordObjects getRelatedRecordObjects] method of the [http://dataface.weblite.ca/Dataface_Record Dataface_Record] class. E.g.

<code>
$benStein = df_get_record('people', array('person_id'=>2));
$pubs = $benStein->getRelatedRecordObjects('my_publications');
foreach ($pubs as $pub){
    echo $pub->val('pub_title').'<br/>';
}
</code>
This will list up to the first 30 publications of Ben stein in the order prescribed by our drag and drop ordering scheme.
",,en,0