...
For example, lets assume that we want to create a snippet for the map extents in a map view, that way we can have multiple client configurations all with the same extents and only one location to set them, making it easier to change all of the clients at once.
So, if we currently have something like the following:
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Example, all be it incomplete, showing some client configurations |
|---|
| linenumbers | true | xml |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">
<client:config id="test1">
<view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
<client:config id="test2">
<view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
<client:config id="test3">
<view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
</config>
|
To create a new snippet for the extents in the above sample we would extract the part of the configuration we want to make common, like this:
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Common extents extracted into a snippet with the id 'defaults' |
|---|
| linenumbers | true | xml |
|---|
|
...
<client:extents id="defaults">
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</client:extents>
... |
This would create a new snippet, called defaults of type extents. The id, defaults in the above example, isn't important and we can use anything that makes sense here (it's just used to refer to a specific snippet later when we want to use it). The type, extents in the above example, is important however and must be the same as the target tag that we're actually creating the snippet for, and it's the combination of the id and type that's used later on to include the snippet within a client configuration.
At the simplest to use the snippet within the client configuration simply requires a reference to the snippet to be added in place of the original tags, so to reference the new snippet we created you would replace the original extents tags with the following:
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Referencing the new snippet |
|---|
| linenumbers | true | xml |
|---|
|
<extents ref="defaults"/>
|
...
So to complete our example I'll show the complete client configurations that will replace the original using snippets:
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| 2 | Example configurations altered to use a snippet |
|---|
| linenumbers | true | xml |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">
<client:extents id="defaults">
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</client:extents>
<client:config id="test1">
<view id="com.cohga.html.client.map.mapView">
<extents ref="defaults"/>
</view>
</client:config>
<client:config id="test2">
<view id="com.cohga.html.client.map.mapView">
<extents ref="defaults"/>
</view>
</client:config>
<client:config id="test3">
<view id="com.cohga.html.client.map.mapView">
<extents ref="defaults"/>
</view>
</client:config>
</config>
|
Refining snippets
Beyond just including the snippet in the client configuration you can also alter the snippet by including extra sub-tags in the reference.
For example if we wanted to setup one client configuration to have a different initial extent and another to add a limit extent we could do the following:
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Altering included snippets |
|---|
| linenumbers | true | xml |
|---|
|
<<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">
<client:extents id="defaults">
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</client:extents>
<client:config id="test1">
<view id="com.cohga.html.client.map.mapView">
<extents ref="defaults"/>
</view>
</client:config>
<client:config id="test2">
<view id="com.cohga.html.client.map.mapView">
<extents ref="defaults">
<initial minx="327000" miny="5811000" maxx="330000" maxy="5813000"/>
</extents>
</view>
</client:config>
<client:config id="test3">
<view id="com.cohga.html.client.map.mapView">
<extents ref="defaults">
<limit minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
</config>
|
this would be the equivalent of
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Altered example shown not using snippets |
|---|
| linenumbers | truexml |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">
<client:config id="test1">
<view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
<client:config id="test2">
<view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327000" miny="5811000" maxx="330000" maxy="5813000"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
<client:config id="test3">
<view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<limit minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
</config>
|
| Note |
|---|
One thing you can't currently do is to remove a sub-tag from a snippet via the reference. |
...
Snippets can include references to other snippets and references can include references to other snippets. For example we could've created our extents snippet as follows
| Code Block |
|---|
|
...
<client:initial id="default" minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<client:full id="default" minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<client:limit id="default" minx="320000" miny="5810000" maxx="360000" maxy="5840000"/>
<client:extents id="defaults">
<initial ref="default"/>
<full ref="default"/>
<limit ref="default"/>
</client:extents>
... |
And if we wanted to we could create a separate snippet for a "custom" extent
| Code Block |
|---|
|
...
<client:initial id="custom" minx="328000" miny="5811000" maxx="331000" maxy="5817000"/>
... |
Then in our "custom" client configuration we could use the following to accomplish the same as we did previously
| Code Block |
|---|
|
...
<client:config id="custom">
<view id="com.cohga.html.client.map.mapView">
<extents ref="defaults">
<initial ref="custom"/>
</extents>
</view>
</client:config>
... |
Replacing content with an id attributes
Because snippets use an id attribute to uniquely identify a snippet, along with the type, you may be wondering how to create a snippet out of a configuration item that includes an id attribute.
For example if we want to create a common map view that we include in multiple clients how can we do it since the view tag has an id, and when we create the snippet the id which is used to identify which particular view is to be used will now become the identifier for the snippet.
So if we tried to extract the map view from the following examples:
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Example with two client configurations |
|---|
| linenumbers | truexml |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">
<client:config id="test1">
<view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
<client:config id="test2">
<view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
</config>
|
we might come up with the following, which would not work.
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Extracting map view into a snippet the wrong way |
|---|
| linenumbers | true | xml |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">
<client:view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</client:view>
<client:config id="test1">
<view ref="com.cohga.html.client.map.mapView"/>
</client:config>
<client:config id="test2">
<view ref="com.cohga.html.client.map.mapView"/>
</client:config>
</config>
|
| Info |
|---|
The reason the above code does not work is that the code that processes the snippets does not know that the id for the view tag is important, and just treats it an an identifier used to provide the link between the snippet and the reference to include it.
But as part of the including process it's the content of the snippet, which does not include the id, that replaces the reference, thereby loosing the id as part of the include process. |
To help explain why the above example doesn't work the following is the equivalent of the above example if snippets were not used, which show that the view tags do not have an id
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Example with two client configurations |
|---|
| linenumbers | truexml |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">
<client:config id="test1">
<view>
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
<client:config id="test2">
<view>
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:config>
</config>
|
The way to fix this problem is to include the id in the reference, as follows:
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Example with two client configurations |
|---|
| linenumbers | truexml |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">
<client:view id="map">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</client:view>
<client:config id="test1">
<view ref="map" id="com.cohga.html.client.map.mapView"/>
</client:config>
<client:config id="test2">
<view ref="map" id="com.cohga.html.client.map.mapView"/>
</client:config>
</config>
|
Possible alternative format
...
While updating this documentation an alternate format for the snippet occurred to me that may help with snippets that include id's.
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| title | Possible future syntax for snippets |
|---|
| linenumbers | truexml |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="urn:com.cohga.server.config#1.0" xmlns:client="urn:com.cohga.html.client#1.0">
<client:snippet id="map">
<view id="com.cohga.html.client.map.mapView">
<extents>
<initial minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
<full minx="327098" miny="5811358" maxx="351971" maxy="5827675"/>
</extents>
</view>
</client:snippet>
<client:config id="test1">
<view ref="map"/>
</client:config>
<client:config id="test2">
<view ref="map"/>
</client:config>
</config>
|
This has the added bonus that the snippet can contain more than one item, although if that's actually useful is as yet unclear.