docs: Added documentation about templates (#1703)

docs/index.rst

@@ -22,6 +22,7 @@ Manual
    manual/editing-tile-layers
    manual/objects
    manual/custom-properties
+   manual/using-templates
    manual/using-the-terrain-tool
    manual/using-commands
    manual/automapping

docs/manual/using-templates.rst

@@ -0,0 +1,97 @@
+.. raw:: html
+
+   <div class="new">
+
+New in Tiled 1.1
+
+.. raw:: html
+
+   </div>
+
+Using Templates
+===============
+
+Any created object can be saved as a template. These templates can then be
+instantiated elsewhere as objects that inherit the template's properties. This
+can save a lot of tedious work of setting up the object type and properties, or
+even just finding the right tile in the tileset.
+
+Templates are organized into template groups. Template groups can be part of
+your project and are referred to by the map. You can save them in either XML
+or JSON format, just like map and tileset files.
+
+.. figure:: images/templates/overview.png
+   :alt: Templates Overview
+
+Creating Templates
+------------------
+
+A template can be created by right clicking on any object in the map and
+selecting "Save as Template". You will be asked to choose the name and the
+template group to save the template to. If the object already has a name the
+name field will be auto-filled with it.
+
+Template groups can be created from the New Template Group button in the
+Templates view or from the New Template dialog.
+
+.. figure:: images/templates/creating-templates.gif
+   :alt: New Template Dialog
+
+.. note:: You can't create a template from a tile object that uses a
+   tile from an embedded tileset, because the
+   :ref:`template group format <templategroup-format>` does not support
+   referring to such tilesets.
+
+The Templates View
+------------------
+
+Working with templates is done through the Templates view. The Templates view
+is divided into two parts, the left part is a tree view that shows the loaded
+template groups and their templates, the right part shows a preview of the
+selected template.
+
+Creating Template Instances
+---------------------------
+
+Shortcut: ``V``
+
+Template instantiation works by either dragging and dropping the template from
+the list of templates to the map, or by using the "Insert Template" tool
+by selecting a template and clicking on the map which is more convenient when
+you want to create many instances.
+
+.. figure:: images/templates/creating-instances.gif
+   :alt: Creating Instances
+
+
+Editing Templates
+-----------------
+
+Selecting a template will show an editable preview in the Templates view and
+will show the template's properties in the Properties view where they can be
+edited.
+
+All template instances are linked to their template, so all edits will be
+immediately reflected upon all the template instances on the map.
+
+.. figure:: images/templates/editing-templates.gif
+   :alt: Editing Templates
+
+If a property of a template instance is changed, it will be internally marked
+as an overridden property and won't be changed when the template changes.
+
+Detaching Template Instances
+----------------------------
+
+Detaching a template instance will disconnect it from its template, so any
+further edits to the template will not affect the detached instance.
+
+To detach an instance, right click on it and select *Detach*.
+
+Future Extensions
+-----------------
+
+- Reseting overridden properties.
+- Locking template properties.
+- Handling wrong file paths.
+- Managing template groups, e.g. removing a template or a template group.

docs/reference/tmx-changelog.rst

@@ -4,6 +4,24 @@ TMX Changelog
 Below are described the changes/additions that were made to the
 :doc:`tmx-map-format` for recent versions of Tiled.
 
+Tiled 1.1
+---------
+
+-  :doc:`Templates </manual/using-templates>` were added, a
+   :ref:`template group <tmx-templategroup>` is an external file
+   referenced by maps:
+
+   .. code:: xml
+
+      <templategroup firsttid="1" source="platforms.ttx"/>
+
+-  An object can be a template instance, by referring to a template by a
+   template id (the :ref:`tid attribute <tmx-object>`):
+
+   .. code:: xml
+
+      <object id="1363" tid="14" x="20" y="55"/>
+
 Tiled 1.0
 ---------
 

docs/reference/tmx-map-format.rst

@@ -74,7 +74,8 @@ rendered by Tiled.
 
 Can contain: `properties <#properties>`__, `tileset <#tileset>`__,
 `layer <#layer>`__, `objectgroup <#objectgroup>`__,
-`imagelayer <#imagelayer>`__, `group <#group>`__ (since 1.0)
+`imagelayer <#imagelayer>`__, `group <#group>`__ (since 1.0),
+`templategroup <#templategroup>`__ (since 1.1)
 
 .. _tmx-tileset:
 
@@ -374,9 +375,10 @@ Can contain: `properties <#properties>`__, `object <#object>`__
 -  **height:** The height of the object in pixels (defaults to 0).
 -  **rotation:** The rotation of the object in degrees clockwise (defaults
    to 0). (since 0.10)
--  **gid:** An reference to a tile (optional).
+-  **gid:** A reference to a tile (optional).
 -  **visible:** Whether the object is shown (1) or hidden (0). Defaults to
    1. (since 0.9)
+-  **tid:** A reference to a template (optional).
 
 While tile layers are very suitable for anything repetitive aligned to
 the tile grid, sometimes you want to annotate your map with other
@@ -392,6 +394,10 @@ of the tile with that global ID. The image alignment currently depends
 on the map orientation. In orthogonal orientation it's aligned to the
 bottom-left while in isometric it's aligned to the bottom-center.
 
+When the object has a ``tid`` set, it will borrow all the properties from
+the specified template, properties saved with the object will have higher
+priority, i.e. they will override the template properties.
+
 Can contain: `properties <#properties>`__, `ellipse <#ellipse>`__ (since
 0.9), `polygon <#polygon>`__, `polyline <#polyline>`__, `text <#text>`__
 (since 1.0), image
@@ -529,6 +535,72 @@ element rather than as the ``value`` attribute. It is possible that a
 future version of the TMX format will switch to always saving property
 values inside the element rather than as an attribute.
 
+.. _tmx-templategroup:
+
+<templategroup>
+---------------
+
+Unlike tilesets, embedding a template group inside a map is not supported, so the map must reference the external template group.
+
+Usage inside the map
+~~~~~~~~~~~~~~~~~~~~
+
+   .. code:: xml
+
+      <templategroup firsttid="1" source="platforms.tgx"/>
+
+-  **firsttid:** the first ID of this template group (this ID maps to the
+   first template in this templategroup).
+-  **source:** The reference to the template group.
+
+Objects inside the map can be template instances by referring to a specific
+template inside a template group:
+
+   .. code:: xml
+
+      <object id="1363" tid="14" x="20" y="55"/>
+
+.. _templategroup-format:
+
+The Template Group Format
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  **name:** The name of the template group.
+-  **nexttemplateid:** Stores the next available ID for new templates. This
+   number is stored to prevent reuse of the same ID after templates have
+   been removed.
+
+Template groups are saved as external files, and are referenced by the map. A
+template group can contain multiple :ref:`tileset <tmx-tileset>` elements
+that point to external tilesets.
+
+Can contain: `tileset <#tileset>`__, `template <#template>`__
+
+<template>
+^^^^^^^^^^
+
+-  **name:** The name of the template.
+-  **id:** Unique ID for the template inside the template group.
+
+Each template element contains the saved :ref:`map object <tmx-object>`.
+
+Example of a template group file:
+
+   .. code:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <templategroup name="Plants" nexttemplateid="2">
+     <tileset firstgid="1" source="desert.tsx"/>
+     <template name="cactus" id="0">
+      <object gid="31" width="81" height="101"/>
+     </template>
+     <template name="tree" id="1">
+      <object gid="38" width="128" height="96"/>
+     </template>
+    </templategroup>
+
+Can contain: `object <#object>`__
+
 --------------
 
 .. figure:: CC-BY-SA.png