| 56 | |
| 57 | == Component Definition == |
| 58 | |
| 59 | Components are defined using the {{{s3db.add_component}}} method. |
| 60 | |
| 61 | {{{ |
| 62 | s3db.add_component(<component_name>, <master_name>=<join>, <master_name>=<join>, ...) |
| 63 | }}} |
| 64 | |
| 65 | 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). |
| 66 | |
| 67 | For simple components, it is sufficient to specify the foreign key as join: |
| 68 | |
| 69 | {{{ |
| 70 | s3db.add_component("org_office", org_organisation="organisation_id") |
| 71 | }}} |
| 72 | |
| 73 | 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: |
| 74 | |
| 75 | {{{ |
| 76 | s3db.add_component("org_office", org_organisation={ |
| 77 | "name": "headquarters", # the component alias |
| 78 | "joinby": "organisation_id" # the foreign key |
| 79 | }) |
| 80 | }}} |
| 81 | |
| 82 | Component joins can be filtered, so that only a subset of the records in the component table forms the actual component: |
| 83 | |
| 84 | {{{ |
| 85 | s3db.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 | |
| 93 | Currently only inclusive filters are supported. |
| 94 | |
| 95 | It is possible to link the same component table to the same master table more than once using different joins and/or filters. |
| 96 | |