Templates allow an element to be defined once in a separate file and used across multiple layouts multiple times.

This guide is a direct follow-up from the adding buttons guide and will refer to elements created from there.

Just like the layout and style sheet, add a new XML file called "Templates.xml" within the Gui folder and set it to "Copy if newer". Add a new node called "Templates".

<Templates>

</Templates>

Now to link the template sheet within the layout sheet, first open the "Layout.xml" file from the previous guides. Add a "Templates" attribute and set the value to be the path of the Templates.xml file relative to the content folder. Note that you can link up as many templates as you'd like by separating each path with a comma, but for now just add the one.

<Main Styles="Gui\\Style" DefaultStyle="Default" Templates="Gui\\Templates">

Now this layout will load every template defined in Templates.xml when you run the project.

The goal here is to move the button panel created in the previous guide into the templates file. Open Templates.xml again, and add a node. This node's name will be the name of the template, here it is "CounterPanel".

<Templates>
    <CounterPanel>

    <CounterPanel/>
</Templates>

This CounterPanel node replaces the Partition node in the layout, so the next step is to copy and paste the partition's child elements from the layout sheet into the CounterPanel node in the templates sheet. Also copy and paste the attributes from the partition into the CounterPanel node itself.

From Layout.xml

<Partition Position="50%" Pivot="50%" Size="128, 64">
    <TextBox Size="100%, 50%" Text="Hello World!" Tag="Display"/>
    <TextButton Position="0%, 50%" Size="50%, 50%" Text="-" Tag="SubtractButton"/>
    <TextButton Position="50%, 50%" Size="50%, 50%" Text="+" Tag="AddButton"/>
</Partition>

Into Templates.xml

<CounterPanel Position="50%" Pivot="50%" Size="128, 64">
    <TextBox Size="100%, 50%" Text="Hello World!" Tag="Display"/>
    <TextButton Position="0%, 50%" Size="50%, 50%" Text="-" Tag="SubtractButton"/>
    <TextButton Position="50%, 50%" Size="50%, 50%" Text="+" Tag="AddButton"/>
<CounterPanel/>

The last thing to do is name each of the child nodes of the CounterPanel template. Names aren't 100% required for GuiCookie templates, but it is heavily recommended as it allows children to be overridden. Just replace the "Tag" attribute with the "Name" attribute, re-using the values from before.

<CounterPanel Position="50%" Pivot="50%" Size="128, 64">
    <TextBox Size="100%, 50%" Text="Hello World!" Name="Display"/>
    <TextButton Position="0%, 50%" Size="50%, 50%" Text="-" Name="SubtractButton"/>
    <TextButton Position="50%, 50%" Size="50%, 50%" Text="+" Name="AddButton"/>
<CounterPanel/>

You may ask, "What's the difference between a name and a tag?" since the names are the same as the tags. Only one element can have a specific tag in a layout, adding an element with a duplicate tag throws an exception. With names, there can be as many duplicate-named elements in the layout as you wish, but there cannot be duplicate names as children of the same element.

The Root class allows you to get elements by tag, which can be useful for elements you know you will only need one of; for example a points counter in a platforming game.

For named elements, the Element class allows you to access its children by name. This is useful for child elements that the element should control; for example a list of save games would be made of list entry elements, where each list entry may have child elements named "PlayButton", "PlayerName", etc.

Now the element in the layout sheet can be replaced with the template. Open the Layout.xml file and change "Partition" to "CounterPanel", or whatever you named the template. All of the attributes can be deleted, as they have been defined in the template itself.

<CounterPanel>
    <TextBox Size="100%, 50%" Text="Hello World!" Tag="Display"/>
    <TextButton Position="0%, 50%" Size="50%, 50%" Text="-" Tag="SubtractButton"/>
    <TextButton Position="50%, 50%" Size="50%, 50%" Text="+" Tag="AddButton"/>
<CounterPanel/>

Now give each child element a name that matches that given in the template. This tells GuiCookie that the child element is going to override the properties of the template's child element with the same name. All other attributes except for the "Tag" can be deleted.

<CounterPanel>
    <TextBox Name="Display" Tag="Display"/>
    <TextButton Name="SubtractButton" Tag="SubtractButton"/>
    <TextButton Name="AddButton" Tag="AddButton"/>
<CounterPanel/>

If you run the project now, you should see the exact same thing as before, which means it has all worked.

Note that you do not have to override a template's children normally, the only reason it is needed here is due to the "Tag" attribute. This will be replaced in the next guide and CounterPanels will be created in a single line.

Even though the CounterPanel now exists as a template, it is quite hard to re-use due to it needing to be tagged and linked up manually. In the next guide, you will learn to make a controller class that is created for each instance of a CounterPanel, which makes templates far more powerful.