Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "View-builder vocabulary"

(Attributes)
(Tree Flattening)
 
(42 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{#eclipseproject:technology.higgins|eclipse_custom_style.css}} [[Image:Higgins logo 76Wx100H.jpg|right]]
+
{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}  
 
+
 
Vocabulary to describe a view of a context. A view is a tree structure of groups of attributes to be displayed/edited. Part of the [[Persona Data Model 2.0]].  
 
Vocabulary to describe a view of a context. A view is a tree structure of groups of attributes to be displayed/edited. Part of the [[Persona Data Model 2.0]].  
  
Line 9: Line 8:
 
==UML Overview ==
 
==UML Overview ==
  
[[Image:View-builder 2.0.0107.png|center]]
+
[[Image:View-builder-2.0.111.png|center]]
  
 
==Classes==
 
==Classes==
Line 18: Line 17:
 
* 1..1 skos:prefLabel
 
* 1..1 skos:prefLabel
 
* 1..N child
 
* 1..N child
 +
* 0..1 layoutRule
 +
 +
===LayoutRule===
 +
Allowed values of layoutRule attribute. Instances:
 +
* Vbox - Display all children (e.g. Slots) in a single vertical area spacing them out evenly.
 +
* Hbox - Display all children (e.g. Slots) in a single horizontal area spacing them out evenly.
  
 
===MultiGroup===
 
===MultiGroup===
Line 25: Line 30:
 
* subClassOf: Group
 
* subClassOf: Group
 
* 1..1 attribute
 
* 1..1 attribute
 +
* 0..1 app-data:script
  
 
===Slot===
 
===Slot===
Line 30: Line 36:
 
* subClassOf: ViewNode
 
* subClassOf: ViewNode
 
* 1..1 attribute
 
* 1..1 attribute
* 0..N role
+
* 0..1 app-data:script
  
 
===ViewNode===
 
===ViewNode===
A node in the view hierarchy
+
(Abstract) A node in the view hierarchy
 
* 1..1 displayOrder
 
* 1..1 displayOrder
* 1..1 skos:prefLabel
 
 
* 0..1 layout
 
* 0..1 layout
  
Line 60: Line 65:
 
* value: URI
 
* value: URI
  
===role===
+
===layoutRule===
Optional, potentially multi-valued attribute. Used in conjunction with ''attribute''. For example if the Slot wishes to display a person's home zipcode, they would build a Slot with :attribute=fp:postalCode and :role=p:Home.
+
Indicates what layout algorithm to use to layout its contents (child Slots & Groups). If no value is provided then a Vbox is assumed.
* domain: ViewNode
+
* domain: Group
* value: p:Role
+
* value: LayoutRule
 +
 
 +
===script===
 +
After the user edits a slot, this script should be executed. (e.g. to push the updated value to an external website).
 +
* domain: Slot
 +
* value: app-data:Push
  
 
== Displaying Groups ==
 
== Displaying Groups ==
Line 69: Line 79:
 
Each Group MUST have a skos:prefLabel that describes the internationalized string label for the group.
 
Each Group MUST have a skos:prefLabel that describes the internationalized string label for the group.
  
== Displaying Attributes ==
+
A Group is a logical collection of Slots (and sub-groups). It is entirely up to the look & feel of the UI to determine how this grouping (and sub-grouping) is represented.
  
Each Slot holds an attribute called ''attribute'' whose value, ''A'', is an rdf:Property.  
+
There is a special kind of (non-top level) Group called a MultiGroup. Unlike regular Groups it has (like a Slot) a view-builder:attribute. As described in the MultiGroup class above, a MultiGroup is a pattern that describes how its child Slots should be collected together into N groups. N is the number of values of the MultiGroup's view-builder:attribute attribute. This attribute's values are always p:Person instances. Each of these p:Person instances acts as a source of attribute/values for one of these N groups.  
  
* ''A'' may be defined in the template context of the current context. In this case its domain is :Person (i.e. the Person class in the template's default namespace).  
+
MultiGroups are used to display a set of attributes (e.g. credit card number, name, address, phone, etc.) for each of N p:Person entities.
** If no mapping rule is found for ''A'' (i.e. no rule can be found in the :Person class such that the value of its ''map:predicate'' is ''A'') then
+
*** The value of ''A'' is simply the value of the attribute ''A'' of the current p:Person instance in the current context being displayed using this view-builder metadata.
+
*** Metadata about ''A'' (label, tooltip text, example value, etc.) are defined in [[Higgins Data Model 2.0#Attribute_Definitions]]
+
** If a mapping rule is found for ''A'' then follow the ''Mapping Procedure'' below.
+
* ''A'' may be defined in the [[Flat Persona vocabulary]]. If so then follow the ''Mapping Procedure'' below.
+
* ''A'' may be ''proxy:userid'' or ''proxy:password''.
+
** The value of ''A'' is the value of attribute ''A'' of the current Proxy object (see [[Proxy vocabulary]])
+
** Metadata attributes about ''A'' (e.g. a skos:prefLabel annotation) in general are found in the [[Proxy vocabulary]]. However metadata attributes (especially skos:prefLabal) MAY be found in the template context of the current context and if present their value overrides the value of the corresponding attribute (if any) in the [[Proxy vocabulary]].
+
  
'''Mapping Procedure'''
+
== Cascading Metadata ==
* If the mapping rule is ''roleSameAs(B)'' then
+
** The value of ''A'' is the value of attribute ''B'' of the current p:Person instance in the current context
+
** Metadata about ''A'' is the metadata about ''B'' as described in the vocabulary that defines ''B''
+
* If the mapping rule is ''roleDiscreteRange*()'' then the equivalent attribute in the persona data model, ''B'' and the range of values is ''R'':
+
** The value of ''A'' is the value of attribute ''B'' of the current p:Person instance in the current context such that the value is a member of ''R''
+
** Metadata about ''A'' is the metadata about ''B'' as described in the vocabulary that defines ''B''
+
  
NOTE: the skos:prefLabel is not used for Slots. It should be "moved" to Group.
+
Each Slot or MultiGroup holds an attribute '''A'''. In order to display the slot both the form and the value of '''A''' must be retrieved. The value might be a boolean, a string, etc. The form of A is described by attribute metadata (as described in [[Persona Data Model 2.0#Attribute_Metadata|Attribute Metadata]] and in [[Higgins Data Model 2.0#Attribute_Definitions|Attribute Definitions]]) --a set of attributes about '''A'''. How to retrieve the value of '''A''' is out of the scope of this document. We are concerned here about how to retrieve metadata that describes the form of '''A'''.<br>
 +
 
 +
We have recently introduced a convention that the context id of metadata attribute M must be the same as the context id of A. If the currie form of A is ''ctxt:attname'' then the currie form of '''M''' must also have a prefix of ''ctxt''. For example if the attribute is ''fp:postalCode'' then metadata statements about ''fp:postalCode'' must be in the [[Flat Persona vocabulary]] context (fp being a prefix for this vocabulary) along with the definition of ''fp:postalCode'' itself.
 +
 
 +
However...
 +
 
 +
In the case where '''A''' has an associated mapping rule (details: [[Mapping vocabulary]]) that maps it to attribute '''B''', the situation is more complex. In this case the final, computed metadata about '''A''' is derived by merging the metadata about '''A''' found in its same context (as described in the previous paragraph) with the metadata found about '''B''' in its context, overriding the latter with the former if the same metadata attribute is found on both. This is roughly analogous to how cascading stylesheets work in HTML CSS. Lastly, since '''B''' may in turn be mapped to '''C''' the cascading is recursive.
 +
 
 +
=== Cascading Cardinality ===
 +
 
 +
We now discuss a special case of cascading metadata, namely cardinality metadata. Unlike all other kinds of attribute metadata, cardinality statements are not a part of the attribute definition, they are a part of a class that uses the attribute. For example (theoretically, although not in practice) the vcard:Address class could state that the maximum cardinality of the vcard:country attribute was 1. This owl:maxCardinality predicate is an attribute of an owl:Restriction of which the Address is a subclass. This is expressed as follows:
 +
 
 +
  :Address
 +
      a      owl:Class ;
 +
      rdfs:subClassOf
 +
              [ a      owl:Restriction ;
 +
                owl:onProperty :country ;
 +
                owl:minCardinality "1"^^xsd:nonNegativeInteger
 +
              ] ;
 +
 
 +
Not only are cardinality statements expressed differently from other kinds of metadata, but the requirements for cardinality are a bit different as well. Unlike other kinds of metadata, depending on the context where the attribute is used (e.g. a connection context to an external website), the cardinality restrictions on it may differ. For example, in a connection context to say, amazon.com, the site may ask for a street address but not require that the country to be specified. In this case the view-builder-powered dynamic form might, based on the UI designer's preference, either (a) simply omit the country slot or (b) include the country slot but indicate that it is not required. Making things more complicated, cardinality of a single attribute may vary within the context. For example, a site might allow an attribute to be optional during one kind of interaction (e.g. subscribing to an email list), but require that same attribute in a different interaction (e.g. registering for an account, or at checkout).
 +
 
 +
To support these requirements we allow cardinality sub-class restrictions to be placed on the root ViewNode of a view-builder tree structure, in addition to placing them in the usual place, namely, the :Person class in the template context, with the former values overriding the latter if both are present. To make this legal in owl, we add an rdf:type = owl:Class statement about the root ViewNode. Thus this special entity is simultaneously an instance of ViewNode class, and a class (subclass of Thing) at the same time.
  
 
== Example ==
 
== Example ==
  
Here is an example of a view-builder:
+
Here is an example of a view-builder structure:
 
   
 
   
 
  :AgeRange
 
  :AgeRange
 
       rdf:type view:Slot ;
 
       rdf:type view:Slot ;
 
       view:attribute fp:ageRange ;
 
       view:attribute fp:ageRange ;
       view:displayOrder 1 ;
+
       view:displayOrder 1 .
      skos:prefLabel "Age range"^^xsd:string .
+
 
   
 
   
 
  :DemographicsGroup
 
  :DemographicsGroup
Line 112: Line 129:
 
       rdf:type view:Slot ;
 
       rdf:type view:Slot ;
 
       view:attribute fp:gender ;
 
       view:attribute fp:gender ;
       view:displayOrder 2 ;
+
       view:displayOrder 2 .
      skos:prefLabel "Gender"^^xsd:string .
+
 
   
 
   
 
  :Interest
 
  :Interest
 
       rdf:type view:Slot ;
 
       rdf:type view:Slot ;
 
       view:attribute p:like ;
 
       view:attribute p:like ;
       view:displayOrder 1 ;
+
       view:displayOrder 1 .
      skos:prefLabel "Interest"^^xsd:string .
+
 
   
 
   
 
  :InterestsGroup
 
  :InterestsGroup
Line 130: Line 145:
 
       rdf:type view:Slot ;
 
       rdf:type view:Slot ;
 
       view:attribute fp:postalCode ;
 
       view:attribute fp:postalCode ;
       view:displayOrder 10 ;
+
       view:displayOrder 10 .
      skos:prefLabel "Zip code"^^xsd:string .
+
 
   
 
   
 
  :ViewRoot
 
  :ViewRoot
Line 138: Line 152:
 
       view:displayOrder 1 ;
 
       view:displayOrder 1 ;
 
       skos:prefLabel "Advertising Profile"^^xsd:string .
 
       skos:prefLabel "Advertising Profile"^^xsd:string .
 
 
Here is a visual representation:
 
 
[[Image:View-builder-example.png|center]]
 
  
 
The demographics group shown above has slots whose attributes, fp:gender, fp:ageRange, fp:postalCode, are all from the [[Flat Persona vocabulary]].  
 
The demographics group shown above has slots whose attributes, fp:gender, fp:ageRange, fp:postalCode, are all from the [[Flat Persona vocabulary]].  
Line 153: Line 162:
  
 
Displaying the "interests" of a user is a case where the flat persona approach won't work because a single p:Person node has a multi-valued (multi-entity-valued) "p:like" attribute. You'll notice in the view hierarchy under the interests Group there is a Slot whose  view:attribute attribute whose value is p:like--a value that is from the persona vocabulary and NOT from the flat persona vocabulary. We have to get all of the values of this attribute. These values are (multiple) int:InterestTopic-class entities. The specific class of this InterestTopic might be "Satire", but of course we probably want to display something like "Humor > Satire" --in other words rendering not just the "leaf" class name but where it sits in relation to the (up to 6 levels) of super-classes ("Humor" being the super-class of "Satire" in this case).
 
Displaying the "interests" of a user is a case where the flat persona approach won't work because a single p:Person node has a multi-valued (multi-entity-valued) "p:like" attribute. You'll notice in the view hierarchy under the interests Group there is a Slot whose  view:attribute attribute whose value is p:like--a value that is from the persona vocabulary and NOT from the flat persona vocabulary. We have to get all of the values of this attribute. These values are (multiple) int:InterestTopic-class entities. The specific class of this InterestTopic might be "Satire", but of course we probably want to display something like "Humor > Satire" --in other words rendering not just the "leaf" class name but where it sits in relation to the (up to 6 levels) of super-classes ("Humor" being the super-class of "Satire" in this case).
 +
 +
== Tree Flattening ==
 +
 +
In some cases view-builder tree structures are too tall and thin and need to be flattened to eliminate too many levels of nested display structures. In these cases we use a tree flattening algorithm, developed by Valeska O'Leary, that reduces the height of the tree. We eliminate the extra "upper" branch nodes and retain only the immediate parent node. Visually:
 +
 +
[[Image:Valeskas algorithm 2.0.101.png|center]]
 +
 +
  
 
[[Category:Higgins 2 Vocabularies]]
 
[[Category:Higgins 2 Vocabularies]]

Latest revision as of 11:57, 26 May 2012

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}} Vocabulary to describe a view of a context. A view is a tree structure of groups of attributes to be displayed/edited. Part of the Persona Data Model 2.0.

Files

UML Overview

View-builder-2.0.111.png

Classes

Group

A logical group of Slots and/or sub-Groups

  • subClassOf: ViewNode
  • 1..1 skos:prefLabel
  • 1..N child
  • 0..1 layoutRule

LayoutRule

Allowed values of layoutRule attribute. Instances:

  • Vbox - Display all children (e.g. Slots) in a single vertical area spacing them out evenly.
  • Hbox - Display all children (e.g. Slots) in a single horizontal area spacing them out evenly.

MultiGroup

Similar to a regular Group, a MultiGroup is parent for a set of child Slots. Different from a Group, it also has an view-builder:attribute attriubte. Another difference is that a MultiGroup self-replicates such that there end up being N instances of itself--one for each of the N values of its attribute attribute. Each of these N values is an instance of p:Person (p1, p2, ... pN). The view-builder:attribute attributes of its child Slot should be evaluated within the scope of its parent p:Person p1..pN.

It is used in view that need to display a set of N "credit cards" (really p:Person nodes with p:Buyer roles), or a set of N "addresses" (really p:Person nodes).

  • subClassOf: Group
  • 1..1 attribute
  • 0..1 app-data:script

Slot

Metadata about how an attribute from the Persona vocabulary (or one of its imports) or from the Flat Persona vocabulary or from the rdf (e.g. rdf:class) should be presented.

  • subClassOf: ViewNode
  • 1..1 attribute
  • 0..1 app-data:script

ViewNode

(Abstract) A node in the view hierarchy

  • 1..1 displayOrder
  • 0..1 layout

Attributes

attribute

The attribute that should be displayed in this Slot, or the attribute to evaluate when handling a MultiGroup.

  • domain: Slot
  • value: rdf:Property

child

A child of a Group

  • domain: Group
  • value: ViewNode

displayOrder

A number that indicates the relative position with respect to the displayOrder of sibling objects with this same attribute. Lower numbers indicate precedence.

  • domain: Slot or Group
  • value: xsd:Integer

layout

An optional URL of an html/javascript template sub-page of a web app.

  • domain: ViewNode
  • value: URI

layoutRule

Indicates what layout algorithm to use to layout its contents (child Slots & Groups). If no value is provided then a Vbox is assumed.

  • domain: Group
  • value: LayoutRule

script

After the user edits a slot, this script should be executed. (e.g. to push the updated value to an external website).

  • domain: Slot
  • value: app-data:Push

Displaying Groups

Each Group MUST have a skos:prefLabel that describes the internationalized string label for the group.

A Group is a logical collection of Slots (and sub-groups). It is entirely up to the look & feel of the UI to determine how this grouping (and sub-grouping) is represented.

There is a special kind of (non-top level) Group called a MultiGroup. Unlike regular Groups it has (like a Slot) a view-builder:attribute. As described in the MultiGroup class above, a MultiGroup is a pattern that describes how its child Slots should be collected together into N groups. N is the number of values of the MultiGroup's view-builder:attribute attribute. This attribute's values are always p:Person instances. Each of these p:Person instances acts as a source of attribute/values for one of these N groups.

MultiGroups are used to display a set of attributes (e.g. credit card number, name, address, phone, etc.) for each of N p:Person entities.

Cascading Metadata

Each Slot or MultiGroup holds an attribute A. In order to display the slot both the form and the value of A must be retrieved. The value might be a boolean, a string, etc. The form of A is described by attribute metadata (as described in Attribute Metadata and in Attribute Definitions) --a set of attributes about A. How to retrieve the value of A is out of the scope of this document. We are concerned here about how to retrieve metadata that describes the form of A.

We have recently introduced a convention that the context id of metadata attribute M must be the same as the context id of A. If the currie form of A is ctxt:attname then the currie form of M must also have a prefix of ctxt. For example if the attribute is fp:postalCode then metadata statements about fp:postalCode must be in the Flat Persona vocabulary context (fp being a prefix for this vocabulary) along with the definition of fp:postalCode itself.

However...

In the case where A has an associated mapping rule (details: Mapping vocabulary) that maps it to attribute B, the situation is more complex. In this case the final, computed metadata about A is derived by merging the metadata about A found in its same context (as described in the previous paragraph) with the metadata found about B in its context, overriding the latter with the former if the same metadata attribute is found on both. This is roughly analogous to how cascading stylesheets work in HTML CSS. Lastly, since B may in turn be mapped to C the cascading is recursive.

Cascading Cardinality

We now discuss a special case of cascading metadata, namely cardinality metadata. Unlike all other kinds of attribute metadata, cardinality statements are not a part of the attribute definition, they are a part of a class that uses the attribute. For example (theoretically, although not in practice) the vcard:Address class could state that the maximum cardinality of the vcard:country attribute was 1. This owl:maxCardinality predicate is an attribute of an owl:Restriction of which the Address is a subclass. This is expressed as follows:

 :Address
     a       owl:Class ;
     rdfs:subClassOf
             [ a       owl:Restriction ;
               owl:onProperty :country ;
               owl:minCardinality "1"^^xsd:nonNegativeInteger 
             ] ;

Not only are cardinality statements expressed differently from other kinds of metadata, but the requirements for cardinality are a bit different as well. Unlike other kinds of metadata, depending on the context where the attribute is used (e.g. a connection context to an external website), the cardinality restrictions on it may differ. For example, in a connection context to say, amazon.com, the site may ask for a street address but not require that the country to be specified. In this case the view-builder-powered dynamic form might, based on the UI designer's preference, either (a) simply omit the country slot or (b) include the country slot but indicate that it is not required. Making things more complicated, cardinality of a single attribute may vary within the context. For example, a site might allow an attribute to be optional during one kind of interaction (e.g. subscribing to an email list), but require that same attribute in a different interaction (e.g. registering for an account, or at checkout).

To support these requirements we allow cardinality sub-class restrictions to be placed on the root ViewNode of a view-builder tree structure, in addition to placing them in the usual place, namely, the :Person class in the template context, with the former values overriding the latter if both are present. To make this legal in owl, we add an rdf:type = owl:Class statement about the root ViewNode. Thus this special entity is simultaneously an instance of ViewNode class, and a class (subclass of Thing) at the same time.

Example

Here is an example of a view-builder structure:

:AgeRange
     rdf:type view:Slot ;
     view:attribute fp:ageRange ;
     view:displayOrder 1 .

:DemographicsGroup
     rdf:type view:Group ;
     view:child :PostalCode , :AgeRange , :Gender ;
     view:displayOrder 1 ;
     skos:prefLabel "Demographics"^^xsd:string .

:Gender
     rdf:type view:Slot ;
     view:attribute fp:gender ;
     view:displayOrder 2 .

:Interest
     rdf:type view:Slot ;
     view:attribute p:like ;
     view:displayOrder 1 .

:InterestsGroup
     rdf:type view:Group ;
     view:child :Interest ;
     view:displayOrder 2 ;
     skos:prefLabel "Interests"^^xsd:string .

:PostalCode
     rdf:type view:Slot ;
     view:attribute fp:postalCode ;
     view:displayOrder 10 .

:ViewRoot
     rdf:type view:Group ;
     view:child :InterestsGroup , :DemographicsGroup ;
     view:displayOrder 1 ;
     skos:prefLabel "Advertising Profile"^^xsd:string .

The demographics group shown above has slots whose attributes, fp:gender, fp:ageRange, fp:postalCode, are all from the Flat Persona vocabulary.

The interests group shown above has a slot whose attribute is the complex valued attribute, online-behavior:interest. In this rather special case the presentation logic should render the name of the class of the instance (e.g. "Humor > Satire" or "World Destinations > Africa > East Africa > Nigeria") as opposed to rendering the value of an attribute of the instance as is done in the usual case.

A few additional notes on the above example

The FlatPersona namespace is only useful when either (a) there are not multiple entity values of the same attribute being requested, or, (b) there are just a few alternative entities and the "right" one can be figured out by matching using the role tags (e.g. "home" vCard entity vs. "work" vCard entity). Flattening, a simplification. It is an attempt to hide some complexity. But there are times when we can't hide the complexity. Multiple non-role-tagged entity values of an attribute is one of those times.

Displaying the "interests" of a user is a case where the flat persona approach won't work because a single p:Person node has a multi-valued (multi-entity-valued) "p:like" attribute. You'll notice in the view hierarchy under the interests Group there is a Slot whose view:attribute attribute whose value is p:like--a value that is from the persona vocabulary and NOT from the flat persona vocabulary. We have to get all of the values of this attribute. These values are (multiple) int:InterestTopic-class entities. The specific class of this InterestTopic might be "Satire", but of course we probably want to display something like "Humor > Satire" --in other words rendering not just the "leaf" class name but where it sits in relation to the (up to 6 levels) of super-classes ("Humor" being the super-class of "Satire" in this case).

Tree Flattening

In some cases view-builder tree structures are too tall and thin and need to be flattened to eliminate too many levels of nested display structures. In these cases we use a tree flattening algorithm, developed by Valeska O'Leary, that reduces the height of the tree. We eliminate the extra "upper" branch nodes and retain only the immediate parent node. Visually:

Valeskas algorithm 2.0.101.png

Back to the top