Changes between Version 11 and Version 12 of S3/S3Model

Timestamp:

01/17/14 12:00:33 (12 years ago)

Author:

Dominic König

Comment:

--

S3/S3Model

@@ -176 +176 @@
 These functions should not be overwritten in the subclass.
 
+== current.s3db ==
+
+{{{current.s3db}}} is a global, empty instance of the S3Model class that loads tables, functions and variables from other models on demand.
+
+=== Loading Tables, Functions and Variables from Models ===
+
+{{{current.s3db}}} allows easy access to names using the ''attribute''-notation:
+
+Loading a table:
+
+{{{#!python
+table = current.s3db.my_table
+}}}
+
+Loading a function:
+
+{{{#!python
+my_function = current.s3db.my_function
+}}}
+
+If you have the name in a variable, you can use the ''item''-notation instead:
+
+{{{#!python
+tablename = "my_table"
+table = s3db[tablename]
+}}}
+
+  '''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).
+
+To avoid exceptions due to disabled modules, one can use the {{{table()}}} function to access tables:
+
+{{{#!python
+# Returns None if "my_table" is not found
+table = current.s3db.table("my_table")
+}}}
+
+  '''Note:''' {{{s3db.table()}}} will also return functions or variables with the specified name.
+
+To limit the lookup to tables, use {{{db_only}}}:
+
+{{{#!python
+# Returns only tables, but not functions or variables
+table = current.s3db.table("my_table", db_only=True)
+}}}
+
+To only lookup functions and variables, but not tables, you can use the {{{get()}}} function:
+
+{{{#!python
+# Returns only functions or variables, but not tables
+my_function = current.s3db.get("my_function")
+}}}
+
+=== Utility Functions ===
+
+{{{current.s3db}}} also provides the {{{S3Model}}} utility functions, e.g.:
+
+{{{#!python
+# Change a table configuration
+current.s3db.configure("my_table", list_fields=["id", "name", "other_field"])
+}}}
+
+   '''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!
+
+=== Constructing Resources ===
+
+{{{current.s3db}}} also provides a method to define a resource (see [wiki:S3/S3Resource]):
+
+{{{#!python
+# Define a resource
+resource = current.s3db.resource("my_table")
+
+# Limit to certain record IDs
+resource = current.s3db.resource("my_table", id=[1, 3, 7])
+
+# Use a filter
+from s3 import S3FieldSelector
+resource = current.s3db.resource("my_table", filter=S3FieldSelector("id").belongs([1, 3, 7]))
+
+# Apply a URL filter
+resource = current.s3db.resource("my_table", vars={"~.id__belongs": "1, 3, 7"})
+}}}
+
 == Concepts ==