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


Ignore:
Timestamp:
01/11/13 10:05:08 (9 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3Model/ComponentResources

    v35 v36  
    5454
    5555Note that, for efficiency reasons, "components" can not be nested in queries.
     56
     57== Component Definition ==
     58
     59Components are defined using the {{{s3db.add_component}}} method.
     60
     61{{{
     62s3db.add_component(<component_name>, <master_name>=<join>, <master_name>=<join>, ...)
     63}}}
     64
     65IMPORTANT: 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).
     66
     67For simple components, it is sufficient to specify the foreign key as join:
     68
     69{{{
     70s3db.add_component("org_office", org_organisation="organisation_id")
     71}}}
     72
     73This 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:
     74
     75{{{
     76s3db.add_component("org_office", org_organisation={
     77                                        "name": "headquarters",         # the component alias
     78                                        "joinby": "organisation_id"     # the foreign key
     79                                 })
     80}}}
     81
     82Component joins can be filtered, so that only a subset of the records in the component table forms the actual component:
     83
     84{{{
     85s3db.add_component("org_office", org_organisation={
     86                                        "name": "headquarters",         # the component alias
     87                                        "joinby": "organisation_id"     # the foreign key
     88                                        "filterby": "office_type_id",   # the name of the field in the component table to filter by
     89                                        "filterfor": 4,                 # the value(s) to filter for
     90                                 })
     91}}}
     92
     93Currently only inclusive filters are supported.
     94
     95It is possible to link the same component table to the same master table more than once using different joins and/or filters.
     96
    5697== Link-Table Components ==
    5798
     
    112153                       widget=Widget,            # Widget to use for embedding (optional, defaults to S3EmbedComponentWidget)
    113154                       autocomplete="fieldname", # Field in the component to use for autocomplete when embedding the component
    114                        filterby="fieldname",     # Field use in the left join filter       
    115                        filterfor="filter",       # filter value for the filterby field       
    116155                   ))
    117156                             
     
    122161Important: 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!
    123162
    124 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.
    125 
    126163----
    127164