Changes between Version 25 and Version 26 of S3/S3Model/SuperEntities

Timestamp:

03/03/14 10:45:45 (11 years ago)

Author:

Dominic König

Comment:

--

S3/S3Model/SuperEntities

@@ -21 +21 @@
 === Defining a Super-Entity ===
 
-To define a super-entity, you can use the {{{super_entity()}}} function:
+A super-entity can be defined using the {{{super_entity()}}} method of S3Model:
 
-{{{
-table = s3db.super_entity(tablename, "sit_id", situation_types,
-                          Field("datetime", "datetime"), # shared field
-                          location_id())                 # shared field
+{{{#!python
+class MyModel(S3Model):
+
+    def model(self):
+
+        # Define a dict with nice names for the instance types:
+        my_instance_types = {
+            "my_instance_tablename": T("Nice name for the instance type"),
+        }
+
+        # Define the super-entity
+        tablename = "my_super_entity"
+        table = self.super_entity(tablename, 
+                                  "my_super_id",                   # specify the super ID
+                                  my_instance_types,               # specify the instance types
+                                  Field("start_date", "datetime"), # shared field
+                                  location_id())                   # shared field
 
 }}}
 
-You can define so-called ''shared fields'' in the super-entity, which are mirrored from the respective resource record. This allows to easily access these data from the component without the need to involve the primay instance table in the backward-join:
+Shared fields will mirror the values from the respective instance record, which allows easy access without need to join multiple tables.
 
-In case the names of the shared fields in your instance table differ from those of the super-entity, you can define a field mapping:
+If the names of shared fields are different in certain instance tables, you can define a field mapping when you configure the instance table:
 
+{{{#!python
+
+        # Define the instance table
+        tablename = "my_instance_table"
+        table = self.define_table(tablename,
+                                  Field("first_date", "datetime"),
+                                  Field("last_date", "datetime"),
+                                  *s3_meta_fields())
+
+        # Configure the instance table
+        self.configure("my_instance_table",
+                       # Configure the super entity
+                       super_entity = "my_super_entity",
+                       # Map the "first_date" field in my_instance_table to "start_date" in my_super_entity
+                       my_super_entity_fields = {"start_date": "first_date"},
+                  )
+
+}}}
 === Defining an Instance of a Super-Entity ===