Suppose you have a database application where you need to store the authors for a particular paper.  Your database will include the following tables:

Papers

Stores the papers that have been submitted. Contains fields {PaperID, PaperTitle}.

Authors

Stores the authors in the system. Contains fields {AuthorID, AuthorName}.

PaperAuthors

A join table to track which authors worked on which paper. Contains fields {PaperID, AuthorID, Author_Order}.

In your Xataface application you will define an 'Authors' relationship in the relationships.ini file for the 'Papers' table as follows:

[Authors]
Authors.AuthorID=PaperAuthors.AuthorID
PaperAuthors.PaperID="$PaperID"

We want the 'Author_Order' field in the 'PaperAuthors' table to indicate the order of the Author in the list of  Authors (where an author with value 1 would be placed higher in the list than an author with value 2, etc...).  We could hard code this into our relationship with an "ORDER BY" clause, but there is a better way - a way that will allow the users to reorder the papers themselves using Xataface.

To achieve this we will modify the definition of the Authors relationship (from above), so that it becomes:

[Authors]
Authors.AuthorID=PaperAuthors.AuthorID
PaperAuthors.PaperID="$PaperID"
metafields:order = "Author_Order"

The 'metafields:order' directive allows you to specify a field that should be used as a default sort field for the relationship.  Defining the sort this way allows Xataface to add some additional user functionality to easily reorder the records within a relationship.

Now, load up your application in your web browser and look at the "Authors" tab for a table (one that has at least 2 or 3 authors in the relationship).  You will notice that the "Author_Order" column is displayed with little up/down arrows for each row as follows:

Clicking on the Up (Down) arrow for a row will move the author up (down) in the list.  This author_order field will automatically be used as the default order when displaying related records now.