Changes between Version 1 and Version 2 of S3/DynamicTables


Ignore:
Timestamp:
02/21/17 10:22:36 (5 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/DynamicTables

    v1 v2  
    66== Dynamic Models ==
    77
    8    ''tbw''
     8Dynamic models are stored in the database, in the {{{s3_table}}} and {{{s3_field}}} tables (modules/s3db/s3.py).
     9
     10=== Creating a dynamic model ===
     11
     12Dynamic table names must have the {{{s3dt_}}} prefix. This prefix will indicate to {{{s3db}}} that the model is to be loaded from the database.
     13
     14A dynamic table can be created as follows:
     15
     16{{{#!python
     17ttable = current.s3db.s3_table
     18
     19# Create dynamic table
     20table_id = ttable.insert(name = "s3dt_example",
     21                         title = "Example Table",
     22                         )
     23}}}
     24
     25Fields in the {{{s3_table}}} table:
     26
     27||= '''Field''' =||= '''Type''' =||= '''required?''' =||= '''Explanation''' =||
     28||name||string||yes, defaults to random name||the table name, must be unique and must start with s3dt_ prefix||
     29||title||string||no||a title for the table, will be shown e.g. in mobile forms selection||
     30
     31  '''Note''': A dynamic table can not be accessed until at least one field has been defined for it.
     32
     33Fields can be added to the dynamic table like this:
     34
     35{{{#!python
     36from gluon.storage import Storage
     37
     38s3db = current.s3db
     39ftable = s3db.s3_field
     40onaccept = s3db.onaccept
     41
     42# Define the model
     43model = (
     44    # String field
     45    {"name": "name",
     46     "field_type": "string",
     47     "label": "Name",
     48     "comments": "Explanation of the field",
     49     },
     50    # Numeric field
     51    {"name": "some_number",
     52     "field_type": "integer",
     53     },
     54    )
     55
     56# Insert the fields into s3_field
     57for field_def in model:
     58
     59    # Insert field definition
     60    record = Storage(field_def)
     61    record["table_id"] = table_id
     62    record_id = ftable.insert(**record)
     63
     64    # Run onaccept (required!)
     65    record["id"] = record_id
     66    s3db.onaccept(ftable, record)
     67
     68db.commit()
     69
     70}}}
     71
     72Fields in the {{{s3_field}}} table:
     73
     74||= '''Field''' =||= '''Type''' =||= '''required?''' =||= '''Explanation''' =||
     75||name||string||yes||the field name, must be unique within the table||
     76||field_type||string||yes||the field type, must be a valid web2py field type, list-types are not supported||
     77||label||string||no||the field label in forms, will be translated automatically||
     78||options||JSON||no||selectable options for the field||
     79||comments||text||no||comments to be shown as help text for the field (Field.comment)||
     80||require_not_empty||boolean||default False||indicates that the field must not be empty||
     81||require_unique||boolean||default False||indicates that the field value must be unique||
     82||settings||JSON||no||other field settings and constraints||
     83
     84=== Managing dynamic models through the web UI ===
     85
     86Obviously, dynamic table models can be managed through the web interface. A standard CRUD interface is available through the {{{/default/tables}}} controller.
     87
     88=== Accessing dynamic tables ===
     89
     90Dynamic tables can be instantiated through {{{s3db}}} (equivalently to static tables):
     91
     92{{{#!python
     93table = current.s3db.s3dt_example
     94}}}
     95
     96Note that this will raise an !AttributeError if the dynamic table is not defined. In order to check for success, it is better to use the {{{table()}}} method:
     97
     98{{{#!python
     99table = current.s3db.table("s3dt_example")
     100if table:
     101    # Perform database operations
     102else:
     103    # Table not defined! => do something else
     104}}}
     105
     106Similar, dynamic tables can also be instantiated as resources:
     107
     108{{{#!python
     109resource = current.s3db.resource("s3dt_example")
     110}}}
     111
     112This too will raise an !AttributeError if the dynamic table is not defined.
     113
     114=== Dynamic table controllers ===
     115
     116In the web interface and for web services, dynamic tables can be accessed through the {{{/default/table}}} controller.
     117
     118This controller behaves like a normal REST controller, except that the URL has the table name (without the s3dt_ prefix) as an additional first argument:
     119
     120{{{
     121# Access record #1 in the s3dt_example table:
     122GET http://localhost:8000/eden/default/table/example/1
     123}}}
     124
     125Dynamic table controllers can be added easily in other modules, using {{{s3_rest_controller}}} with the {{{dynamic}}}-option.
     126
     127{{{
     128def dynamic_table_controller():
     129    """ REST Controller for the s3dt_example dynamic table """
     130
     131    return s3_rest_controller(dynamic = "example")
     132}}}
    9133
    10134== Dynamic Components ==