Changes between Version 39 and Version 40 of S3/S3Model/ComponentResources

Timestamp:

02/04/14 13:16:11 (11 years ago)

Author:

Dominic König

Comment:

--

S3/S3Model/ComponentResources

@@ -2 +2 @@
 [[TOC]]
 
-Component resources are an S3 framework concept to simplify the implementation of and access to aggregation models, which is the most common type of data models used in Sahana-Eden.
+'''Component Resources''' (more commonly referred to as simply "components") are an S3 framework concept to simplify the access to sub-entities related to a master entity.
 
-Typically, such an aggregation model has a master entity and a number of associated (sub-)entities ("have"-relationships):
+Typically, a master entity has a number of associated sub-entities ("have"-relationships), e.g.:
 
   - organisations = have => offices, projects, teams
@@ -10 +10 @@
   - groups = have => members, tasks
 
-Each of these relationships can be represented as a join between the respective tables.
+These sub-entities are called ''components'' of the master entity.
 
-The "Component Resource" extension provides the functionality to pre-configure and re-use these joins as pseudo-attributes ("components") of the master entity, thereby replacing the joins by simple identifiers (aliases) which can be used to construct queries, e.g. in URLs:
+A component relationship constitutes a join between the master entity and the sub-entity. The S3 framework provides functionality to pre-define such joins and then use them as pseudo-attributes of the master entity.
+
+In URLs, component relationships can be utilized to construct implicit queries (also called "projections"):
 
 {{{
-    # Join "office": org_organisation <-- id/organisation_id --> org_office
+    # Offices of organisation 5
+    # "office" is a component of "org/organisation"
+    # Join: org_organisation <-- id/organisation_id --> org_office
 
     /org/organisation/5/office
 }}}
 
-or
+...likewise in URL filter queries:
 
 {{{
-    # Join "contact": pr_person <-- pe_id/pe_id --> pr_contact
+    # Persons with the email address user@example.com
+    # "contact" is a component of "pr/person"
+    # Join: pr_person <-- pe_id/pe_id --> pr_contact
 
     /pr/person?contact.contact_method=EMAIL&contact.value=user@example.com
 }}}
 
-The "Component Resource" extension is one of the fundamental RAD concepts of the S3 framework. 
-
-Besides simplified construction of queries and views, it also facilitates keyless (=implicit) constraints e.g. in CRUD forms and XML imports:
+Besides simplified construction of queries and views, it also facilitates implicit (=keyless) constraints e.g. in CRUD forms and XML imports:
 
 {{{#!xml