Friday, 6 September 2013

Making Adding/Removing Related Records Easier


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.

View the source for this example application on GitHub

Editing Relationships from the Edit/New Record Form

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 following widget types can be used to edit relationships:

Widget Type Supports 1:n Supports n:m
gridYesYes
checkboxNoYes
taggerNoYes

Using the grid Widget

The grid widget allows you to add, remove, and edit related records in a grid with one row per record.    The configuration happens in the originating table of the relationship, inside its fields.ini file.  The fields.ini definition a grid widget looks like:


[Courses]
    transient=1
    widget:type=grid
    relationship=Courses
    widget:columns="subject,course_number,course_title"


The key elements of this definition are:

  • The "transient" directive tells Xataface that this field is not backed by an actual column in the Students table.  (It is sort of a way of saying to XF "No, I'm not loopy!  I realize that there is no such column, but I want this anyways!)
  • 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).

After adding this configuration, let's visit the "Edit" form of a Student record.  It should display our grid widget as follows:

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.

Using Checkboxes

If you are using a n:m relationship and you want to provide a simple way for the user to indicate which records from table A are related to which records in table B, you can appropriate the checkbox widget to generate a simple checkbox grid from which the user can select the related records.  The configuration for this might look as follows (assuming that the "Courses" relationship is now an n:m relationship):


[Courses]
    transient=1
    widget:type=checkbox
    relationship=Courses


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.

After adding this configuration, we can visit the "Edit" form for a Student record, and it should display our widget as follows:

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.

View the source for this example on GitHub

Using the Tagger Widget

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.

Caveats

This article glossed over a few items that you will likely face if you set up your relationships to be edited by a widget.  Some of these include:

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

Source Code

All of the source code for this article is available on Github.  The repository includes 4 branches:

  1. Master - The default application with a single 1:n relationship from Students to Courses with standard relationship management.
  2. 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.
  3. grid_widget_n_to_m : Changes the table structure and relationship to n:m; still using grid widget for editing the relationship.
  4. 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.


8 comments:

  1. If you want your ex-girlfriend or ex-boyfriend to come crawling back to you on their knees (no matter why you broke up) you must watch this video
    right away...

    (VIDEO) Get your ex back with TEXT messages?

    ReplyDelete
  2. Very informative post! There is a lot of information here that can help any business get started with a successful social networking campaign. fake documents

    ReplyDelete
  3. replica Alexander McQueen shoes, combining elegant style and cutting-edge technology, a variety of styles of Cheap Alexander McQueen womens shoes, the pointer walks between your exclusive taste style.

    ReplyDelete
  4. I was searching for help on the internet to get my ex husband back after he divorced me 5 months ago, i came across so many testimonies from different people and they are all talking about this wonderful man called Doctor ODIBOH DADA on how he help them to save their marriage and relationships and i also contact him on his email (odibohsolutionhome@gmail.com) and explain my problem to him and he did a nice job by helping me to get my divorced husband back within 3 days and later on i got pregnant for him, for we have been married for 6 years no pregnancy .. I never believe that such things like this can be possible but now i am a living testimony to it because Doctor ODIBOH DADA actually brought my lover back and also help me got pregnant, If you are having any relationship problems or any problem concerning life itself why not contact Doctor ODIBOH DADA for help via his email: odibohsolutionhome@gmail.com or whatsapp +2347048883838. Then i promise you that after all said and done you will have reasons to celebrate just like me.

    ReplyDelete
  5. I really want to thank Dr Emu for saving my marriage. My wife really treated me badly and left home for almost 3 month this got me sick and confused. Then I told my friend about how my wife has changed towards me then she told me to contact Dr Emu that he will help me bring back my wife and change her back to a good woman. I never believed in all this but I gave it a try. Dr Emu casted a spell of return of love on her, and my wife came back home for forgiveness and today we are happy again. If you are going through any relationship stress or you want back your Ex or Divorce husband you can contact his whatsapp +2347012841542 or email emutemple@gmail.com 

    ReplyDelete
  6. CHRISTMAS LOAN! CHRISTMAS LOAN !! CHRISTMAS LOAN !!! WE OFFER ALL TYPES OF LOANS AT 3%. WE CAN HELP ANYONE TO GET A LOAN, WITH SMOOTH AND EFFECTIVE SERVICES. I am Mr. Mike Morgan, in good standing, the money legitimate and reputable company Lender I lend money to people who need financial assistance. Do you have bad credit or do you
    need money to pay the bills? I want to use this medium to inform you that I am trustworthy to the beneficiary as I will be happy to offer you a loan. No credit check, 100% guaranteed. email: muthooth.finance@gmail.comNote: Only welcome serious people because we are legit and willing to fund loans for real people and serious. To return to us with the following information if you are interested:
    First and Last Name: Country: State: Phone: Amount Needed as Loan: Loan Duration: Sex: Workplace: Monthly Income:
    Once we receive your email, we will send you our loan conditions for the procedure. please contact our company email or whatsapp: Company email: muthooth.finance@gmail.com WhatsApp: +91-7428831341

    ReplyDelete
  7. My husband and I have been having lots of problems living together, he never gives me attention or makes me happy because he has fallen in love with another woman outside our marriage. I tried my best to make sure that my husband leaves this woman but the more I talk to him about it the more he makes me feel sad and unhappy, My marriage started leading to divorce because he no longer gives me attention. I wanted to forget him but i love him and didn't want to lose him. We have been married for years and he is all I could call a true best friend and best in all, the man that handles my problems perfectly, the man that makes sacrifices for my happiness. I wanted him back in my life badly and I was so confused. My Friends told me to buy books about relationships, so I went online for relationship books while I came across a spell caster called Dr Emu. I read testimonies and reviews about him so I contacted him immediately, explained my problems to him. Same day , he casted a spell for me and assured me for 2 days that my husband will return to me and to my greatest surprise the third day my husband came knocking on my door and begged for forgiveness. I am so happy that my love is back again and not only that, we are about to get married again, he proposed. I wouldn't stop talking about him. Contact him today if you need his help via email: emutemple@gmail.com and you will see that your problem will be solved without any delay. Website: https://emutemple.wordpress.com/

    ReplyDelete