All this passing around of the related parameter originates with the user clicking an 'add' button in a list of entities that, in its turn, was shown in response to clicking a related tag when editing or viewing an item.
Those lists of entities are generated by the index() method of the Browse class, so we have to make sure that suitable information (that is, the name of the entity that is listed together with the ID of the instance) is passed on.
This means we have to:
- Enhance the
index()method to receive a related parameter that can be passed on when the 'add' button is clicked. - Extend the code that generated the form associated with this add button with a hidden
<input>element to hold this information, so that it may be passed on again to theindex()method of theDisplayclass.
If it sounds a little confusing how Display and Browse are connected, it may help to envision the following scenario:
- The user starts looking at a list of owners from the main menu and double-clicks a certain owner. This will result in an 'edit' form delivered by the
Displayclass. Because double-clicking on an item will not pass a related argument, this argument in theindex()method ofDisplaywill receive its default value ofNone. - The edit form shows the details of the owner in the sidebar labeled Related, we see a Carsentry.
- When the user clicks this Cars entry to show the list of cars related to this owner, this will result in the
index()method of aBrowseinstance for theCarentity to be called with both arelatedand apatternargument ofOwner,5, for example. - This will result in a list of cars of the indicated owner and when the 'add' button in this list is clicked, it is again the
index()method of theDisplayclass that is called, but this time, aDisplayinstance associated with theCarentity. It will be passed therelatedargument ofOwner,5. - Finally, when the user has entered the new car details and clicks 'add', the same
index()method of theDisplayclass is called, again with arelatedargument ofOwner,5but also with anaddargument. The car details will be used to create a newCarinstance and therelatedargument to identify theOwnerinstance and associate the new car instance with.
The following series of screenshots illustrates what is happening. We start with a list of owners:
When we double-click on Knut Larsson, the following URL is sent to the server: http://127.0.0.1:8080/owner/edit/?id=5&_=1295438048592 (the id=5 indicates the instance, the number at the end is what jQuery adds to an AJAX call to prevent caching by the web browser).
The result will be an edit form for Knut:
A click on Car will result in the following URL being sent to the server: http://127.0.0.1:8080/car/?_=1295438364192&pattern=Owner,5&related=Owner,5.
We recognize the related and pattern arguments of Owner,5 (that is, referring to Knut). Note that the commas in the arguments appended to this URL would be sent to the server encoded as %2C.
Note
Why do we send both a related argument and a pattern argument containing the same information? For adding an entity to another entity, this is indeed redundant but if we would like to add the ability to transfer ownership as well as add a new entity, we would like to filter those cars that belong to some other owner and therefore we need to separately provide the pattern and related arguments.
If this is the first time we will be adding a car to Knut, the list of related cars will be empty:
If we now click on the Add new button, the following URL is constructed:
http://127.0.0.1:8080/car/add/?_=1295438711800&related=Owner,5, which will result in an add form for a new car:
After filling in the details, clicking on the Add button will result in a new car instance that will be associated with Knut even if we leave the Owner field empty because of the related argument passed yet again in the URL:
http://127.0.0.1:8080/car/add/?_=1295439571424&make=Volvo&model=C30&color=Green&license=124-abc&Owner=&related=Owner,5&add=Add.
To allow a Browse instance to receive and pass on a related attribute in the same manner as a Display instance, we need to make a few small changes. First, we have to alter the signature of the index() method:
Chapter9/browse.py
@cherrypy.expose def index(self, _=None, start=0, pattern=None, sortorder=None, cacheid=None, next=None,previous=None, first=None, last=None, clear=None, related=None):
All that is left then is to make sure that clicking the Add new button will pass on this value by including a hidden<input> element to the form:
Chapter9/browse.py
yield '<form method="GET" action="add">' yield '<input name="related" type="hidden" value="%s">'%related yield '<button type="submit">Add new</button>' yield '</form>'