...
This allows you to centralize common configuration items from multiple client configurations that you want to be the same for all client configurations, for example setting the extents for map views, or ensuring the same label for every ToC view, creating common layouts. Something like this can also be performed using the set processing instruction, but this method makes it much easier.
...
| Code Block |
|---|
| xml |
|---|
| xml |
|---|
| 2 | Example configurations altered to use a snippet |
|---|
| linenumbers | true |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config 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:
...
| Note |
|---|
One thing you can't currently do is to remove a sub-tag from a snippet via the reference. |
Nested snippets
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: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 | true |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config 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 version="1.0" encoding="UTF-8"?>
<config 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 | true |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config 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 | true |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config 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
| Warning |
|---|
This is not yet implemented, it is just an idea for a refinement of the snippet syntax to help with snippets that use an id |
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 | true |
|---|
|
<?xml version="1.0" encoding="UTF-8"?>
<config 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.