Page Comparison

Contexts are a way of grouping entities within a configuration. For example, a Weave configuration may include entities from a broad cross section of categories. - It may include reference information (roads, rivers, towns, administrative boundaries, property boundaries etc), plus various categories of information, for example :
a) Land classifications (wetlands, rainforest, grasslands, grazing, cropping, etc.)
b) Tourist information (motels, restaurants, Places of Interest, etc.)

Contexts allow such categories to be grouped and referred to by a context identifier (eg. landType, tourism); As a consequence, Weave clients may optionally specify categories (ie. "contexts") of entities that they will be working with. For example, the below client config specifies that the Holiday_client will utilise information from the tourism context group.
<client:config id='Holiday_client' context='tourism'>
... Hence only entities that include the 'tourism' context will be used by the subject client, in additon to entities that do not have a context specification.

The required context specification per entity, takes the following form :

<entity:entity id='roads' label='Roads'/>
<entity:entity id='rivers'      label='Rivers'/>
<entity:entity id='wetlands'    label='Wetlands'    context='landType' />
<entity:entity id='rainforest'  label='Rainforest'  context='landType' />
<entity:entity id='restaurants' label='Restaurants' context='tourism'/>
<entity:entity id='motels'      label='Motels'      context='tourism'/>

Consequently, for the above defined Holiday_client, it would subsequently utilise entities :
Roads, Rivers, Restaurants and Motels, without there needing to be an explicit specification of relevant entities, per utilised client configuration item.

The "Context" capability was introduced at Weave 2.6.8. It is a powerful feature that significantly simplifies the process of working with many entities within a Weave configuration, where numerous clients may exist. More discussion and examples are provided below.

Prior to the Advent of Contexts

Before 2.6.8 when a user opens a Weave client all of the entities that are registered with Weave are sent to the browser but if you do not need all of the entities to be available in the client then individual panels and components, if they support it, would each have to be configured to refine which entities that they would display.
Weave 2.6.8 adds the concept of a “context” to Weave that will allow you to group entities, and other configuration items, and then specify that a client should only present the entities that have been assigned to that context, removing the need to apply additional configuration too to all of the panels/componentcomponents. The panels/components can be cleaned up to remove the additional configuration that specifies which entities they should include and switch back to including all entities, since now “all entities” means the entities that were linked to the context specified by the client.

...

For example suppose we have four entities configured for a Weave instance

<entity:entity id='properties' label='Properties'/>
<entity:entity id='parks'      label='Parks'/>
<entity:entity id='trees'      label='Trees'/>
<entity:entity id='lights'     label='Lights'/>

Prior to Weave 2.6.8 if you wanted to create two specialised editing clients, one for just editing trees and another for just editing lights, and you don’t want trees in the lights client or lights in the trees client but you do want properties and parks in both, then you would create two separate client configuration and for certain components in the client you would have to add additional configuration to the component to tell it only to include the entities it was interested in, for example for the tree editing client the entity selector would be something like:

<client:config id='tree_edit'>
  <!-- other config -->
    <item component='weave.entitySelector'>
      <entity>properties</entity>
      <entity>parks</entity>
      <entity>trees</entity>
    </item>
  <!-- other config -->
</client:config>

and in the light editing client it would be configured something like:

<client:config id='light_edit'>
  <!-- other config -->
    <item component='weave.entitySelector'>
      <entity>properties</entity>
      <entity>parks</entity>
      <entity>lights</entity>
    </item>
  <!-- other config -->
</client:config>

this would have to be done for every other component in the client that needed to only show a subset of the available entities, and this is with only four entities, it can quickly get out of hand if there are dozens or hundreds of entities.
Note that if the entitySelector component configuration did not include the list of entity sub-tags then both clients would display all four entities.

As of Weave 2.6.8 you would first assign the entities to the appropriate contexts, in our example we’ll create two contexts, “tree” and “light”. We do this by adding a “context” attribute to the entities, e.g.

<entity:entity id='properties' label='Properties'/>
<entity:entity id='parks'      label='Parks'/>
<entity:entity id='trees'      label='Trees'      context='tree'/>
<entity:entity id='lights'     label='Lights'     context='light'/>

Then the client configuration would be updated to reference the context that it should use, by adding a “context” attribute to the client configuration, so the tree editing client would be changed to something like:

<client:config id='tree_edit' context='tree'>
  <!-- other config -->
    <item component='weave.entitySelector'/>
  <!-- other config -->
</client:config>

and the light editing client:

<client:config id='light_edit' context='light'>
  <!-- other config -->
    <item component='weave.entitySelector'/>
  <!-- other config -->
</client:config>

...

Associating a context to an entity also means that other items that are associated with that entity will not display* in the client either, things like searches, reports, data, edits, etc., so if an entity is not part of the context that a client uses, then none of the other items related to that entity will be displayed in the client either, there is no need to set a context for these other items.

It’s likely that just associating contexts to entities will take care of 99% of the requirements to refine what’s available in the client, but it’s also possible to assign contexts to other configuration items.

For example, if there are multiple data sets associated with an entity and you have to multiple client configurations that reference the context for the entity but you don’t want all of the data for that entity available for all clients you can specify an a different context to the data sets and then add that context to the client configuration, along with the entity context. If you’re reading closely you just realised that that means that you can specify multiple context for a client.

Multiple client contexts

Extending out our example able to add a couple of data sets, with one associated with the “finance” context, e.g.

<data:data id='tree_details' label='Details'  entity='trees' datadefinition='tree_details'/>
<data:data id='tree_costs'   label='Costings' entity='trees' datadefinition='tree_costs'  context='finance'/>

In this case he the current tree_edit client won’t won't show the tree_costs data, since it’s it's associated with the finance context that is not set for the tree_edit client, so a new tree client could be added that includes the trees and the tree costing information, e.g.

<client:config id='tree_edit_advanced' context='tree,finance'>
  <!-- other config -->
    <item component='weave.entitySelector'/>
  <!-- other config -->
    <view id='weave.grid'>
      <!-- other config -->
    </view>
  <!-- other config -->
</client:config>

Now the previous tree_edit client will just show the tree_details data but the new tree_edit_advanced client will show both the tree_details and the tree_costs data. Also, note that the light_edit client will not show either the tree_details data or the tree_costs, since they are both associated with an entity that has a context that the light_edit client has not been configured to use.

Additionally if we were to create a light_costs data set and associate it with the finance context, similar to the tree_costs above, the new tree_edit_advanced client will still not display the light cost data, even though it is associated with the finance context, since the light_costs data is related to the lights entity and the light entity is associated with a context that the tree_edit_advanced client does not include.

Updates in 2.6.9

The example for the client context above shows one way of defining what contexts should be used in the client, namely as a comma separated list, where an item associated with any of those contexts, plus anything that’s not associated with any context, will be included in the client, but Weave 2.6.9 extends that to make the client context attribute more flexible.

Firstly, the examples above always include those items that are not associated with any context, along with those associated with the listed contexts, but in 2.6.9 it’s possible to specify that you want to include only the items that are associated with the listed context(s), and to ignore the items that are not associated with a context. You do this by prefixing the list of contexts with “only”, e.g.

<client:config id='tree_edit_advanced' context='only tree,finance'>
  <!-- other config -->
</client:config>

When you do this only items that are in the tree or finance contexts will be included in the client.

Another limitation of this format is that it’s always an “or” decision, without the “only” prefix, that is, it always includes items that are in either the tree or finance context, there wasn’t a way to specify that only items that are in both the tree and finance contexts should be included, but in 2.6.9 you can do this by providing an expression for the context, e.g.

<client:config id='tree_edit_advanced' context='tree and finance'>
  <!-- other config -->
</client:config>

In the above example only items that are in both the tree and finance contexts will be included in the client, along with anything that’s not assigned to any context, because we didn’t include the “only” prefix, which can still be used, e.g.

<client:config id='tree_edit_advanced' context='only tree and finance'>
  <!-- other config -->
</client:config>

The expression for the context also supports “or”, “not” and brackets, ( & ), so you can make more complex decisions about what should be included. The old comma separated list is the equivalent of an “or” expressions, e.g. the previous context='tree,finance' is actually this:

<client:config id='tree_edit_advanced' context='tree or finance'>
  <!-- other config -->
</client:config>

But you can go much further than that, e.g.

<client:config id='tree_edit_advanced' context='only (tree or finance) and not (nsw or vic)'>
  <!-- other config -->
</client:config>

Which will show everything associated with the tree or the finance contexts, but only if they’re not associated with the nsw or vic context, and only those items because of the “only” prefix being included in the example.

It’s useful to note that the “only” prefix is a separate thing from the rest of the context expression. All it does is determine if things that aren’t associated with a context are included or not, and does not have any relationship or effect on the rest of the expression. So you should create the expression to determine what needs to be included and then add “only” or not, depending on you wanting items without an context included or not.

Multiple item contexts

In the same way that a client can be include items from multiple contexts, the items themselves can also be associated with multiple contexts, by setting the context attribute for the item to a comma separated list.

...