Xataface has supported 1:n (i.e. one-to-many) and n:m (i.e. many-to-many) relationships from the beginning. By default, when a relationship is defined, it causes a corresponding tab to appear in the UI for each record of the originating table. E.g. If I define a relationship named "Courses" on the `Students` table that represents all of the courses for which a student is registered (i.e. a 1:n relationship from the `Students` table to the `Courses` table), it causes a "Courses" tab to appear inside the details view of a Student record.
The relationship tab will include a list of all records in the relationship as well as buttons to add or remove related records.
The "Courses" tab showing the records in the courses relationship for a particular student.
Adding related records one at a time using the "Add New Related Record" form can be cumbersome, especially in cases where you routinely need to add multiple records to the relationship for every record in the originating table. Xataface provides the ability to add and remove related records directly on the "edit" and "new" forms of the originating table. In cases where the size of the relationship is small, this makes a lot of sense, as it puts all of the "editing" functionality in one place for the user.
The "relationship" directive specifies the relationship that should be used to populate the grid. It happens to be the same as the column name we've chosen for the transient field, but it doesn't necessarily have to. We could have named this field anything we like.
The "widget:columns" directive is a comma-delimited list of the columns in the related table that should appear in the grid.
(Please note that the example here using a 1:n relationship from students to courses is somewhat unrealistic - it assumes that the course records are not entities themselves, but just value records that are entirely owned by a student. In the real world you would probably have a much more complex table structure - and most certainly would be using a n:m relationship between students and courses).
Using the grid widget to edit the Courses relationship. In this case the courses relationship is a 1:n relationship so it doesn't allow you to add existing records.
When you enter a value into any field of the last row, it will create a new empty row at the end of the widget for you to add a new record. In this way, you can add as many related records as you like.
Notice that this definition uses the same key elements as the grid widget, but it doesn't require a "widget:columns" directive because it is only displaying the "title" of each related record - no need to specify columns.
Using the checkbox widget to edit the courses in the Student's courses relationship.
Now you can specify which courses a user is registered in by simply checking the courses' checkboxes on the Student edit form.
The tagger widget can also be used to manage n:m relationships. It provides an intuitive "Tagging" interface for the user. To use it, you will need to install the tagger module. For more information about the tagger widget see this post.
Transient widgets are displayed as one of the first fields on the form by default. You may want to adjust the field order to move it to a more appropriate place.
Now that you are providing a way for users to add and remove related records on the edit form, you may want to disable the standard way of adding records in the related tab.
For some relationships, it is sufficient to just have it displayed in the edit form. You may want to hide the default relationship tab altogether, or to move the related list inside the "View" tab as a section.
You can find information on most of these issues in the Xataface forum and wiki. And I hope to write more articles on these in the future so stay tuned.
Master - The default application with a single 1:n relationship from Students to Courses with standard relationship management.
grid_widget_1_to_n : Version of the application that uses a grid widget to edit the Students->Courses relationship on the Student edit form. Still using a 1:n relationship.
grid_widget_n_to_m : Changes the table structure and relationship to n:m; still using grid widget for editing the relationship.
checkbox_widget : Same as the grid_widget_n_to_m branch except using a checkbox widget for adding/removing related records on the Student edit form.