|Version 4 (modified by 11 years ago) ( diff ),|
- coming soon...
Components can be bound to their master records via link-tables. In such cases, the foreign key constraints for the component link are all in a separate link-table, whereas both the master table and the component table are completely independent:
master (primary key) <==== (foreign key) link table (foreign key) ====> (primary key) component
Link-table component links have some advantages over simple foreign key constraints:
- they can carry attributes of their own (qualified link)
- they provide the option to bind the same component record to multiple master records (many-to-many)
- there are several different ways to actuate such links
However, they do have disadvantages too:
- overhead to maintain a separate database table (processing time, migration issues etc.)
- increased complexity to access and query resources (3 tables instead of 2)
- increased complexity to handle such links in CRUD and XML/XSLT
Link Actuation Methods
With link-table component links, you have several different methods available to "actuate" the link. That is, RESTful methods can operate either on the link table, on the component table or both - depending on the request method and the link configuration. The basic "actuation" methods are:
- replace: hides the link table and always operates on the component table
- hide: hides the component table and always operates on the link table
- link: operates on the component table for single-record requests, and on the link table for summary requests (=without record ID) and delete
- embed: operates on the link table, embeds the component record in single-record requests
The following table gives an overview over link actuation in S3CRUD:
|Link Actuation Method||replace||hide||link||embed|
|create||create-form for component||create-form for link||create-form for link||create-form for link with component embedded|
|read||read view of component||read view of link||read-view of component||read-view of link (with component embedded2)|
|update||update-form for component||update-form for link||update-form for component||update-form for link with component embedded|
|delete||deletes both, component and link||deletes the link||deletes the link1||deletes the link1|
|list||list view of component||list view of link||list view of link||list view of link (with component embedded2)|
- 1 = deletes the component together with the last link if autodelete option is set
- 2 = not implemented yet
Other RESTful methods such as S3Search or S3Cube may have their own definitions.
The basic syntax of a link-table component link declaration is:
s3mgr.model.add_component("my_component", # Tablename of the component my_master=dict( # Tablename of the master table link="my_linktable", # Tablename of the link table joinby="fieldname", # FK of the master table (=left key constraint) key="fieldname", # FK of the component table (=right key constraint) actuate="replace", # Actuation method (see above, optional, defaults to "link") autodelete=False # Delete the component record together with the last link (optional, default is False) widget=Widget, # Widget to use for embedding (optional, defaults to S3EmbedComponentWidget) autocomplete="fieldname", # Field in the component to use for autocomplete when embedding the component ))
If no field is defined for autocomplete, then no autocomplete-widget will be used, but a standard SELECT of options for key (default behavior).
Important: if you specify a widget for embedding (e.g. S3AddPersonWidget), then you must not use this widget or a widget validator for the right key constraint!