Changes between Version 35 and Version 36 of S3/S3Model/ComponentResources

Timestamp:

01/11/13 10:05:08 (13 years ago)

Author:

Dominic König

Comment:

--

S3/S3Model/ComponentResources

@@ -54 +54 @@
 
 Note that, for efficiency reasons, "components" can not be nested in queries.
+
+== Component Definition ==
+
+Components are defined using the {{{s3db.add_component}}} method.
+
+{{{
+s3db.add_component(<component_name>, <master_name>=<join>, <master_name>=<join>, ...)
+}}}
+
+IMPORTANT: Component definitions in dynamically loaded models must be in the class which defines the ''master table''! (because otherwise the component definition would not be found when the model is loaded).
+
+For simple components, it is sufficient to specify the foreign key as join:
+
+{{{
+s3db.add_component("org_office", org_organisation="organisation_id")
+}}}
+
+This assumes that the component alias is the same as the name of the component table without prefix, e.g. {{{tablename = "org_office" => component alias = "office"}}}. If you want set the alias explicitly, you can instead describe the join in a dict:
+
+{{{
+s3db.add_component("org_office", org_organisation={
+                                        "name": "headquarters",         # the component alias
+                                        "joinby": "organisation_id"     # the foreign key
+                                 })
+}}}
+
+Component joins can be filtered, so that only a subset of the records in the component table forms the actual component:
+
+{{{
+s3db.add_component("org_office", org_organisation={
+                                        "name": "headquarters",         # the component alias
+                                        "joinby": "organisation_id"     # the foreign key
+                                        "filterby": "office_type_id",   # the name of the field in the component table to filter by
+                                        "filterfor": 4,                 # the value(s) to filter for
+                                 })
+}}}
+
+Currently only inclusive filters are supported.
+
+It is possible to link the same component table to the same master table more than once using different joins and/or filters.
+
 == Link-Table Components ==
 
@@ -112 +153 @@
                        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
-                       filterby="fieldname",     # Field use in the left join filter        
-                       filterfor="filter",       # filter value for the filterby field        
                    ))
                               
@@ -122 +161 @@
 Important: if you specify a widget for embedding (e.g. S3AddPersonWidget), then you must ensure that the foreign key in the link-table doesn't also use either this widget or any other widget validator!
 
-If {{{name='alias'}}} is specified, the component would not be addressed in the URL as {{{master/component}}} but as {{{master/alias}}}. This allows to link the same component table to the same master table more than once using different link tables.
-
 ----