.. _tags-page:

#######################
Tag Behavior and Syntax 
#######################

There are different types of behavior when replacing tag data.

***********
Static Tags
***********

A static tag will map the tagged object to one specific snapshot in the repository. The tag contains object type and an 
index that tells which snapshot to get data from. For instance, "SIT3_PICTURE" will replace the tagged picture with the 
picture from snapshot with index 3 in the repository.

************
Generic Tags
************

Generic tags are used when you just specify the tag type without a snapshot index. This means that this part of the 
document should be duplicated 'number of snapshots' times and each duplicate will map to one snapshot in the repository. 
For MS Word, generic tags must be within a Group Content Control. This group will then be duplicated so that there is 
one copy for each snapshot in the repository. For MS PowerPoint, if a generic tag is found, the entire slide will be 
duplicated. You will get one copy of the slide for each snapshot in the repository. The syntax of a generic tag is the 
same as for a static tag, just without the index. For instance, "SIT_PICTURE". A scenario where this is useful can be a 
report where you want some descriptive pages at the start with certain images or models from the repository and a 
reference list just showing the title and picture for all snapshot at the end.

Generic snapshots will default unroll for all snapshots with matching type in the repository. If
only a sub-set of these should be used, you can specify this using 
:func:`setGenericSnapshotIndices() <cee::rep::ReportCreatorWord::setGenericSnapshotIndices>`. 
The generic snapshot will the only be unrolled for indexes found in this array.

.. image:: ../../images/template_ppt.png
    :width: 30%

.. image:: ../../images/template_word.png
    :width: 30%

.. image:: ../../images/template_html.png
    :width: 30%


**Example 1:**

A repository has three snapshots and the following syntax is found in the template:

:: 

    [Group][SIT_TITLE][/Group]

will unwrap to

::

    [SIT1_TITLE] [SIT2_TITLE] [SIT3_TITLE].

**Example 2:**

We have a template where we want the two first slides to contain some extensive data on the two first snapshots. 
Then we want all snapshots in the repository listed with just the title and a picture. We use the following tags in the 
slides:

::

    Slide 1: SIT1_TITLE + SIT1_PICTURE + SIT1_TEXT
    Slide 2: SIT2_TITLE + SIT2_VTFX + SIT2_TEXT
    Slide 3: SIT_TITLE + SIT_PICTURE

If this is run on a repository with 4 snapshots, you will get a report containing 6 slides:

::

    Slide 1: SIT1_TITLE + SIT1_PICTURE + SIT1_TEXT
    Slide 2: SIT2_TITLE + SIT2_VTFX + SIT2_TEXT
    Slide 3: SIT1_TITLE + SIT1_PICTURE
    Slide 4: SIT2_TITLE + SIT2_PICTURE
    Slide 5: SIT3_TITLE + SIT3_PICTURE
    Slide 6: SIT4_TITLE + SIT4_PICTURE

Notice that the generic slide is duplicated once for each snapshot.

**************
Reference Tags
**************

In certain circumstances it is useful to be able to combine two different repositories into one report. 
This can be done by using a reference repository which can be specified when creating a report. The tags 
must be prefixed with "REF\_" but will otherwise look and behave identical to normal tags. For instance: 
"REF_SIT4_VTFX". You can have both static and generic reference tags.

**Tag syntax**

The naming syntax for tags is as follows:

+-------------+---------------------+---------------------------------------------------------------+
|Object       | Tag                 | Description                                                   |
+=============+=====================+===============================================================+
|Images       | SIT?_PICTURE        | For instance SIT1_PICTURE for the picture of the first |br|   |
|             |                     | snapshot in the repository.                                   |
+-------------+---------------------+---------------------------------------------------------------+
|3D Model     | SIT?_VTFX           | For instance SIT2_VTFX for the 3D model of the second |br|    |
|             |                     | snapshot in the repository.                                   |
+-------------+---------------------+---------------------------------------------------------------+
|Table        | SIT?_TABLE          | For instance SIT3_TABLE for the table in the third |br|       |
|             |                     | snapshot in the repository.                                   |
+-------------+---------------------+---------------------------------------------------------------+
|Description  | SIT?_TEXT           | For instance SIT4_TEXT for the description of the fourth |br| |
|             |                     | snapshot in the repository (as supplied by the user when |br| |
|             |                     | capturing).                                                   |
+-------------+---------------------+---------------------------------------------------------------+
|Title        | SIT?_TITLE          | For instance SIT5_TITLE for the description of the fifth |br| |
|             |                     | snapshot in the repository (as supplied by the user when |br| |
|             |                     | capturing).                                                   |
+-------------+---------------------+---------------------------------------------------------------+
|Field values | SIT?_$'field_name'  | For instance SIT2_$DATABASE_NAME will insert the |br|         |
|             |                     | database name for the second snapshot in the repository.      |
+-------------+---------------------+---------------------------------------------------------------+

Tags with a specified snapshot index (SIT1_TITLE/SIT3_VTFX/...) are called static tags.

For generic tags, the same syntax applies, but without the index (just "SIT_PICTURE", "SIT_TEXT", "SIT_TITLE", 
"SIT_TABLE" and "SIT_VTFX").

