How to Make and Use Snippets

Owned by Lucy Minato (Deactivated)
Last updated: 16 Oct, 2017 by Shaun Forbes
3 min read

A snippet is useful when you want to reuse a piece of client configuration in multiple client configurations. This can be useful when you have more than one client XML file but have common elements across them. Note that snippets can only be used for Weave client configuration items and not for Weave server configuration items.

Note that the following examples create a separate file to contain the snippets that are used but this is not a requirement, snippets are just like any other configuration item and can be added to any valid XML configuration file.

Step-by-step guide

  1. Create an XML file for your snippets. This file can have any name and will depend on the naming convention you have adopted for your XML files. In the following example we will use client_snippets.xml (as a reminder that snippets can only be used for anything in the client configuration file). It is good practice to store this file in the same location as your other client XML files. 
     

  2. An element that you might want to create a snippet for is the coordinate extents used by Weave (since this is likely to be common across all your Weave clients). In your original client configuration file, this may have looked like:

    client.xml
    ...
	<extents>
		<initial crs="EPSG:28355" minx="329090" miny="5813180" maxx="350260" maxy="5826500" />
		<full crs="EPSG:28355" minx="329090" miny="5813180" maxx="350260" maxy="5826500" />
		<limit crs="EPSG:28355" minx="325557" miny="5811130" maxx="352957" maxy="5826257" />
	</extents>
...

    This same text is now put into your snippets file in a slightly altered format. The sample snippets file below contains two snippets, the first one is the one that defines all the coordinate extents.

    client_snippets.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="default_extents">
		<initial crs="EPSG:28355" minx="329090" miny="5813180" maxx="350260" maxy="5826500" />
		<full crs="EPSG:28355" minx="329090" miny="5813180" maxx="350260" maxy="5826500" />
		<limit crs="EPSG:28355" minx="325557" miny="5811130" maxx="352957" maxy="5826257" />
	</client:extents>

	<client:highlight id="highlight_style">
		<marker>
			<!-- more config goes here -->
		</marker>
		<vector>
			<!-- and more config that we're not showing -->
		</vector>
	</client:highlight>

</config>

  3. You now need to tell Weave to read this file, so the snippets file needs to be included in the config.xml file.

    config.xml
    <?include client_snippets.xml?>

  4. The last part is telling your client file that it will have to go elsewhere to get all the parameters it needs for setting up with Weave GUI. This is done by setting a ref tag ("default_extents") which matches the id from the snippets file. 

    So the client XML file previously had the following lines to set the coordinate extents:

    client.xml
    ...
	<extents>
		<initial crs="EPSG:28355" minx="329090.0" miny="5813180.0" maxx="350260.0" maxy="5826500.0" />
		<full crs="EPSG:28355" minx="329090.0" miny="5813180.0" maxx="350260.0" maxy="5826500.0" />
		<limit crs="EPSG:28355" minx="325557.735" miny="5811130.676" maxx="352957.634" maxy="5826257.148" />
	</extents>
...

    But these five lines have now been replaced with just:

    client.xml
    ...
	<extents ref="default_extents"/>
...

  5. In summary, Weave reads the client XML file and gets to the <extents> section and was expecting some coordinate values here but is directed elsewhere to find these values (by the ref tag). Weave knows about the client_snippets.xml file because it's been included it in the config.xml file, so it goes searching and finds a matching id in the client_snippets.xml file and reads the parameters from that file. 

    The key part is that in the snippets file you have to make sure the type matches what you would have had in the client XML file, the "id" can be anything as long as the same name in used in the client XML file, but the "extent" from "client:extents" is called the type and it is defined by Weave, and was used in the client XML file.

 

For further details on snippets refer to: Client Snippets