| 178 | == current.s3db == |
| 179 | |
| 180 | {{{current.s3db}}} is a global, empty instance of the S3Model class that loads tables, functions and variables from other models on demand. |
| 181 | |
| 182 | === Loading Tables, Functions and Variables from Models === |
| 183 | |
| 184 | {{{current.s3db}}} allows easy access to names using the ''attribute''-notation: |
| 185 | |
| 186 | Loading a table: |
| 187 | |
| 188 | {{{#!python |
| 189 | table = current.s3db.my_table |
| 190 | }}} |
| 191 | |
| 192 | Loading a function: |
| 193 | |
| 194 | {{{#!python |
| 195 | my_function = current.s3db.my_function |
| 196 | }}} |
| 197 | |
| 198 | If you have the name in a variable, you can use the ''item''-notation instead: |
| 199 | |
| 200 | {{{#!python |
| 201 | tablename = "my_table" |
| 202 | table = s3db[tablename] |
| 203 | }}} |
| 204 | |
| 205 | '''Note:''' The attribute- or item-notations will raise an {{{AttributeError}}} if the name can not be found (e.g. when the respective module is disabled). |
| 206 | |
| 207 | To avoid exceptions due to disabled modules, one can use the {{{table()}}} function to access tables: |
| 208 | |
| 209 | {{{#!python |
| 210 | # Returns None if "my_table" is not found |
| 211 | table = current.s3db.table("my_table") |
| 212 | }}} |
| 213 | |
| 214 | '''Note:''' {{{s3db.table()}}} will also return functions or variables with the specified name. |
| 215 | |
| 216 | To limit the lookup to tables, use {{{db_only}}}: |
| 217 | |
| 218 | {{{#!python |
| 219 | # Returns only tables, but not functions or variables |
| 220 | table = current.s3db.table("my_table", db_only=True) |
| 221 | }}} |
| 222 | |
| 223 | To only lookup functions and variables, but not tables, you can use the {{{get()}}} function: |
| 224 | |
| 225 | {{{#!python |
| 226 | # Returns only functions or variables, but not tables |
| 227 | my_function = current.s3db.get("my_function") |
| 228 | }}} |
| 229 | |
| 230 | === Utility Functions === |
| 231 | |
| 232 | {{{current.s3db}}} also provides the {{{S3Model}}} utility functions, e.g.: |
| 233 | |
| 234 | {{{#!python |
| 235 | # Change a table configuration |
| 236 | current.s3db.configure("my_table", list_fields=["id", "name", "other_field"]) |
| 237 | }}} |
| 238 | |
| 239 | '''Note:''': {{{s3db.get_config()}}} does not load the respective model, so unless you have loaded the model before, you can not access its configuration settings! |
| 240 | |
| 241 | === Constructing Resources === |
| 242 | |
| 243 | {{{current.s3db}}} also provides a method to define a resource (see [wiki:S3/S3Resource]): |
| 244 | |
| 245 | {{{#!python |
| 246 | # Define a resource |
| 247 | resource = current.s3db.resource("my_table") |
| 248 | |
| 249 | # Limit to certain record IDs |
| 250 | resource = current.s3db.resource("my_table", id=[1, 3, 7]) |
| 251 | |
| 252 | # Use a filter |
| 253 | from s3 import S3FieldSelector |
| 254 | resource = current.s3db.resource("my_table", filter=S3FieldSelector("id").belongs([1, 3, 7])) |
| 255 | |
| 256 | # Apply a URL filter |
| 257 | resource = current.s3db.resource("my_table", vars={"~.id__belongs": "1, 3, 7"}) |
| 258 | }}} |
| 259 | |