Changes between Version 38 and Version 39 of S3/S3Model/ComponentResources


Ignore:
Timestamp:
02/02/14 21:49:32 (8 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3Model/ComponentResources

    v38 v39  
    3232Besides simplified construction of queries and views, it also facilitates keyless (=implicit) constraints e.g. in CRUD forms and XML imports:
    3333
    34 {{{
     34{{{#!xml
    3535<s3xml>
    3636    <!-- an organisation record -->
     
    5656== Component Definition ==
    5757
    58 Components are defined using the {{{s3db.add_component}}} method.
     58Components are defined using the {{{s3db.add_components}}} method.
    5959
    60 {{{
    61 s3db.add_component(<component_name>, <master_name>=<join>, <master_name>=<join>, ...)
     60{{{#!python
     61s3db.add_components(<master_name>, <component_name>=<join>, <component_name>=<join>, ...)
    6262}}}
    6363
     
    6666For simple components, it is sufficient to specify the foreign key as join:
    6767
    68 {{{
    69 s3db.add_component("org_office", org_organisation="organisation_id")
     68{{{#!python
     69s3db.add_components("org_organisation", org_office="organisation_id")
    7070}}}
    7171
    7272This 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:
    7373
    74 {{{
    75 s3db.add_component("org_office", org_organisation={
    76                                         "name": "headquarter",          # the component alias
    77                                         "joinby": "organisation_id"    # the foreign key
    78                                  })
     74{{{#!python
     75s3db.add_components("org_organisation",
     76                    org_office={"name": "headquarter",       # the component alias
     77                                "joinby": "organisation_id", # the foreign key
     78                               })
    7979}}}
    8080
    8181Component joins can be filtered, so that only a subset of the records in the component table forms the actual component:
    8282
    83 {{{
    84 s3db.add_component("org_office", org_organisation={
    85                                         "name": "headquarter",          # the component alias
    86                                         "joinby": "organisation_id"     # the foreign key
    87                                         "filterby": "office_type_id",  # the name of the field in the component table to filter by
    88                                         "filterfor": 4,                 # the value(s) to filter for
    89                                  })
     83{{{#!python
     84s3db.add_components("org_organisation",
     85                    org_office={"name": "headquarter",        # the component alias
     86                                "joinby": "organisation_id"   # the foreign key
     87                                "filterby": "office_type_id", # the name of the field in the component table to filter by
     88                                "filterfor": 4,               # the value(s) to filter for
     89                               })
    9090}}}
    9191
     
    9898This requirement is often called "singe-record component" or "subtable", and can be defined in the join dict:
    9999
    100 {{{
    101 s3db.add_component("org_office", org_organisation={
    102                                         "name": "headquarter",          # the component alias
    103                                         "joinby": "organisation_id"     # the foreign key
    104                                         "filterby": "office_type_id",  # the name of the field in the component table to filter by
    105                                         "filterfor": 4,                 # the value(s) to filter for
    106                                         "multiple": False               # there can be only one component record per master record
    107                                  })
     100{{{#!python
     101s3db.add_components("org_organisation",
     102                    org_office={"name": "headquarter",        # the component alias
     103                                "joinby": "organisation_id"   # the foreign key
     104                                "filterby": "office_type_id", # the name of the field in the component table to filter by
     105                                "filterfor": 4,               # the value(s) to filter for
     106                                "multiple": False             # there can be only one component record per master record
     107                               })
    108108}}}
    109109
     
    158158The basic syntax of a link-table component link declaration is:
    159159
    160 {{{
    161 s3db.add_component("my_component",               # Tablename of the component
    162                    my_master=dict(               # Tablename of the master table
    163                        name="alias",             # Use this 'alias' as the component name
    164                        link="my_linktable",      # Tablename of the link table
    165                        joinby="fieldname",       # FK of the master table (=left key constraint)
    166                        key="fieldname",          # FK of the component table (=right key constraint)
    167                        actuate="replace",        # Actuation option (see above, optional, defaults to "link")
    168                        autodelete=False          # Delete the component record together with the last link (optional, default is False)
    169                        widget=Widget,            # Widget to use for embedding (optional, defaults to S3EmbedComponentWidget)
    170                        autocomplete="fieldname", # Field in the component to use for autocomplete when embedding the component
    171                    ))
    172                              
     160{{{#!python
     161s3db.add_components("my_master",                  # Tablename of the master table
     162                    my_component={                # Tablename of the component
     163                        name="alias",             # Use this 'alias' as the component name
     164                        link="my_linktable",      # Tablename of the link table
     165                        joinby="fieldname",       # FK of the master table (=left key constraint)
     166                        key="fieldname",          # FK of the component table (=right key constraint)
     167                        actuate="replace",        # Actuation option (see above, optional, defaults to "link")
     168                        autodelete=False          # Delete the component record together with the last link (optional, default is False)
     169                        widget=Widget,            # Widget to use for embedding (optional, defaults to S3EmbedComponentWidget)
     170                        autocomplete="fieldname", # Field in the component to use for autocomplete when embedding the component
     171                    })                         
    173172}}}
    174173