Changes between Version 15 and Version 16 of S3/S3Model

Timestamp:

01/24/14 08:30:02 (11 years ago)

Author:

Dominic König

Comment:

--

S3/S3Model

@@ -275 +275 @@
 }}}
 
-=== 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 ===
 
@@ -305 +294 @@
 }}}
 
+== Utilities ==
+
+=== Table Configuration Settings ===
+
+{{{S3Model}}} provides a key-value store for each table which is used to store per-table configuration settings. 
+
+The following functions can be used to manage table configuration settings:
+
+||= '''Function''' =||= '''Use-Case''' =||
+||{{{configure(<tablename>, <key>=<value>, <key>=<value>, ...)}}}||to add or change configuration settings for a table||
+||{{{get_config(<tablename>, <key>, <default>)}}}||to retrieve a configuration setting||
+||{{{clear_config(<tablename>, <key>)}}}||to remove a configuration setting for a table||
+
+  '''Note:''' In {{{get_config()}}}, the <default> parameter is optional (default: {{{None}}}), it will be returned if <key> is not configured for this table.
+
+  '''Note:''' These functions are available both as instance methods in S3Models (self.* or current.s3db.*) and as class methods (S3Model.*).
+
+  '''Important:''': {{{get_config()}}} does ''not'' load the respective model class. Settings configured inside the model class are therefore only available outside of it (e.g. with {{{s3db.get_config()}}}) if the model has been loaded before (e.g. with {{{s3db.<tablename>}}})!
+
+Example:
+{{{#!python
+# Configure list_fields for the org_organisation table
+s3db.configure("org_organisation", 
+               list_fields=["id",
+                            "name", 
+                            "acronym", 
+                            "organisation_type_id", 
+                            "country", 
+                            "website"])
+}}}
+
 ----