Tag: Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
← Older edit
Frank@tygron.nl (talk | contribs)
Tygron, Tygron_admin, Bureaucrats, Interface administrators, Administrators
46,429 edits
mNo edit summary
No edit summary
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Text in [[Panel]]s can contain special tags that are replaced by the {{software}} based on the Project's data, the [[Session]]'s data, and the context of the [[Panel]], such as the [[Stakeholder|owner]] or related [[Item]]s of the [[Panel]]. A tag can be placed anywhere in the text of a [[Panel]], and when the content of that [[Panel]] is rendered for display to the user, the tag is replaced by the appropriate data. In other words, the tag specifies a specific kind of data, and that data is inserted into the [[Panel]]'s text in the location of the tag.
When requesting the text content of a panel through any of the web endpoints, the content returned is formatted and tags are replaced. These tags can be general tags, values of [[attribute]]s and [[global]]s, as well as [[Select (TQL)|TQL Select statements]].


===General tags===
Tags should always be preceded by a dollar sign ($), for example:
<code>$SELECT_GLOBAL_WHERE_NAME_IS_FOO</code>
 
==$TQL Tags==
Select queries can also be added to a text panel to obtain Project Session data. These select queries should always be preceded by a dollar sign ($) and need a [[Calculation Cloud|Calculation]] to be updated. For example:
f
To get an attribute named FOO of the item linked to this panel:
 
<code>$SELECT_ATTRIBUTE_WHERE_PANEL_IS_ID_AND_RELATION_IS_CONTENT_AND_NAME_IS_FOO</code>.
 
To get the name of the item linked to this panel (note: available in version 2026.1.1+):
 
<code>$SELECT_NAME_WHERE_PANEL_IS_ID_AND_RELATION_IS_CONTENT</code>.
 
To get the contents of a global named FOO:
 
<code>$SELECT_GLOBAL_WHERE_NAME_IS_FOO</code>.
 
To get all the neighborhood names in the Project. Note [[X (TQL)|X]] is a wildcard here:
 
<code>$SELECT_NAME_WHERE_NEIGHBORHOOD_IS_X</code>.
 
Only select queries can be used and require a [[Recalculate|recalculation]] when added or adjusted.
 
==HTML, CSS and Javascript==
Text panel content is always returned as HTML; if it isn't already, <code>&lt;html&gt;</code> and <code>&lt;body&gt;</code> tags are automatically added.
 
==General Tags==
{|class=wikitable
{|class=wikitable
! Tag
!Name
! Effect
!Description
|-
|-
| $PROJECT_NAME
| $PROJECT_NAME
| Inserts the name of the [[Project]].
| Formatted project name
|-
| $PLATFORM_DESCRIPTION
| Client description of the {{software}}
|-
| $LIB_CUSTOM
| Lower-case underscored project name
|-
| $TITLE
| Title of the panel
|-
| $CSS
| Replaced with relative stylesheet link: <code>&lt;link rel=\"stylesheet\" type=\"text/css\" href=\"tygron.css?token=$TOKEN\"&gt;</code>
|-
| $LIB_PLOTLY
| Replaced with header script entry for Plotly; <code>&lt;script src=\"plotly.js?token=$TOKEN\" type=\"text/javascript\"&gt;</script>
|-
| $TOKEN
| Web token or Api token, depending on the context.
|-
| $STAKEHOLDER_ID
| id of the stakeholder; Stakeholder is obtained from the accessing web stakeholder or from a specified stakeholder id in the end point.
|-
| $STAKEHOLDER_SHORT
| short name of the stakeholder; Stakeholder is obtained from the accessing web stakeholder or from a specified stakeholder id in the end point.
|-
| $STAKEHOLDER
| name of the stakeholder; Stakeholder is obtained from the accessing web stakeholder or from a specified stakeholder id in the end point.
|-
|-
| $TOKEN
| Inserts the [[Web Token]] of the Project's [[Session]]
|}
|}


===Web tags===
==Legacy Tags==
The following tags are deprecated and not to be used anymore, but kept for backwards compatibility.
{|class=wikitable
{|class=wikitable
! Tag
!Name
! Effect
!Description
|-
|-
| $LIB_CUSTOM
| $SESSION
| Inserts the name of the [[custom javascript library]], part of the [[web interface]] configuration.
| Replaced with empty string
|}
 
===Contextual tags===
{|class=wikitable
! Tag
! Effect
|-
|-
| $NAME
| $SLOT
| Inserts the name of the [[Panel]].
| Replaced with empty string
|-
|-
| $ID
| $ID
| Inserts the [[ID]] of the [[Panel]].
| Replaced with the id of the linked item.
|-
|-  
| $STAKEHOLDER_ID
| $NAME
| Inserts the [[ID]] of the user's [[Stakeholder]].
| Replaced with the name of the linked item.
|-
|-
| $STAKEHOLDER
| $ATTRIBUTE_
| Inserts the name of the user's [[Stakeholder]].
| Replaced with the value for the attribute specified after <code>$ATTRIBUTE_</code>, obtained from the linked item.  
|-  
| $GLOBAL_
| Obtains the value of the [[Global]] specified after <code>$GLOBAL_</code> from the linked item.
|}
|}


===Attributes tags===
==Limitations==
{|class=wikitable
Tags, [[Globals]], [[attribute]]s, and [[Select (TQL)|TQL Select statements]] are only replaced in the text content and cannot be generated dynamically via JavaScript.
! Tag
Generally only capital letters, numbers, underscores are supported for tags. Characters such as <code>, ( ) [ ] { } &lt; and &gt</code> cannot be used.
! Effect
 
|-
In the following example, the Select statements are not properly replaced and will therefore not work.
| $ATTRIBUTE_ATTRIBUTENAME, where ATTRIBUTENAME is the [[TQL name|name]] of the [[Attribute]].
<syntaxhighlight>
| Inserts the value of the indicated [[Attribute]] of the [[Item]] the [[Panel]] is related to. If the value does not exist, an empty array is inserted, i.e. "[]".
const tableData = [];
|-
for (const nh of neighborhoods) {
| $GLOBAL_GLOBALNAME, where GLOBALNAME is the [[TQL name|name]] of the [[Global]].
  const nameQuery = `$SELECT_NAME_WHERE_NEIGHBORHOOD_IS_${nh.id}`;
| Inserts the value of the indicated [[Global]]s. If the [[Global]] does not exist, it is considered "0".
  const valueQuery = `$SELECT_ATTRIBUTE_WHERE_NEIGHBORHOOD_IS_${nh.id}_AND_NAME_IS_INHABITANTS`;
|}
  tableData.push({
    name: nh.name,
    inhabitants: valueResult[0] // TQL returns an array of results
  });
}
</syntaxhighlight>
 
Instead, the select statement should be written as follows:
<syntaxhighlight copy>
const neighborhoodNames = [ $SELECT_NAME_WHERE_NEIGHBORHOOD_IS_X ];
const neigbhorhoodInhabitants = [ $SELECT_ATTRIBUTE_WHERE_NEIGHBORHOOD_IS_X_AND_NAME_IS_INHABITANTS ];
 
const tableData = [];
for(let n = 0; n < neighbhorhoodNames.length && n < neighborhoodInhabitants.length; n++){
  tableData.push({
    name: neighborhoodNames[n];
    inhabitants: neighborhoodInhabitants[n];
  });
}
</syntaxhighlight>
 
For further specification details, see [[Global]], [[Attribute]] and [[Select (TQL)]] respectively.


{{article end
{{article end
| notes=
| notes=
* Tags can also be used in the output of [[Panel]]s based on an [[Excel]], and in [[Indicator]]s.
* Tags can also be used in the output of [[Panel]]s based on an [[Excel]], and in [[Indicator]]s.
* Text in the output which starts with a dollar-sign (like a tag) but is not explicitly a tag to the {{software}}, is not replaced or overwritten.
|seealso=
* If the tag is not used on a [[Template Panel]], and thus no [[Item]] is related to it, the $ATTRIBUTE tag is not replaced or overwritten.
* [[Attribute]] and [[Global]] values are inserted with at least one decimal. I.e. "2" and "2.203" are displayed as "2.0" and "2.203" respectively.
* If an [[Attribute]] is inserted which does not have exactly one value (i.e. does not exist, or is an [[Attribute array]] with multiple values), an array of values is inserted compatible with a [[javascript]] array definition.
| seealso=
* [[Panel]]
* [[Panel]]
* [[Template Panel]]
* [[Template Panel]]
* [[Global]]
* [[Global]]
* [[Attribute]]
* [[Attribute]]
* [[Select (TQL)]]
* [[JavaScript]]
|api=
* [[Api session items panels]]
* [[Api session event editor panel]]
}}
}}

Latest revision as of 12:36, 8 July 2026

When requesting the text content of a panel through any of the web endpoints, the content returned is formatted and tags are replaced. These tags can be general tags, values of attributes and globals, as well as TQL Select statements.

Tags should always be preceded by a dollar sign ($), for example: $SELECT_GLOBAL_WHERE_NAME_IS_FOO

$TQL Tags

Select queries can also be added to a text panel to obtain Project Session data. These select queries should always be preceded by a dollar sign ($) and need a Calculation to be updated. For example: f To get an attribute named FOO of the item linked to this panel:

$SELECT_ATTRIBUTE_WHERE_PANEL_IS_ID_AND_RELATION_IS_CONTENT_AND_NAME_IS_FOO.

To get the name of the item linked to this panel (note: available in version 2026.1.1+):

$SELECT_NAME_WHERE_PANEL_IS_ID_AND_RELATION_IS_CONTENT.

To get the contents of a global named FOO:

$SELECT_GLOBAL_WHERE_NAME_IS_FOO.

To get all the neighborhood names in the Project. Note X is a wildcard here:

$SELECT_NAME_WHERE_NEIGHBORHOOD_IS_X.

Only select queries can be used and require a recalculation when added or adjusted.

HTML, CSS and Javascript

Text panel content is always returned as HTML; if it isn't already, <html> and <body> tags are automatically added.

General Tags

Name Description
$PROJECT_NAME Formatted project name
$PLATFORM_DESCRIPTION Client description of the Tygron Platform
$LIB_CUSTOM Lower-case underscored project name
$TITLE Title of the panel
$CSS Replaced with relative stylesheet link: <link rel=\"stylesheet\" type=\"text/css\" href=\"tygron.css?token=$TOKEN\">
$LIB_PLOTLY Replaced with header script entry for Plotly; <script src=\"plotly.js?token=$TOKEN\" type=\"text/javascript\"></script>
$TOKEN Web token or Api token, depending on the context.
$STAKEHOLDER_ID id of the stakeholder; Stakeholder is obtained from the accessing web stakeholder or from a specified stakeholder id in the end point.
$STAKEHOLDER_SHORT short name of the stakeholder; Stakeholder is obtained from the accessing web stakeholder or from a specified stakeholder id in the end point.
$STAKEHOLDER name of the stakeholder; Stakeholder is obtained from the accessing web stakeholder or from a specified stakeholder id in the end point.

Legacy Tags

The following tags are deprecated and not to be used anymore, but kept for backwards compatibility.

Name Description
$SESSION Replaced with empty string
$SLOT Replaced with empty string
$ID Replaced with the id of the linked item.
$NAME Replaced with the name of the linked item.
$ATTRIBUTE_ Replaced with the value for the attribute specified after $ATTRIBUTE_, obtained from the linked item.
$GLOBAL_ Obtains the value of the Global specified after $GLOBAL_ from the linked item.

Limitations

Tags, Globals, attributes, and TQL Select statements are only replaced in the text content and cannot be generated dynamically via JavaScript. Generally only capital letters, numbers, underscores are supported for tags. Characters such as , ( ) [ ] { } < and &gt cannot be used.

In the following example, the Select statements are not properly replaced and will therefore not work. 

const tableData = [];
for (const nh of neighborhoods) {
  const nameQuery = `$SELECT_NAME_WHERE_NEIGHBORHOOD_IS_${nh.id}`;
  const valueQuery = `$SELECT_ATTRIBUTE_WHERE_NEIGHBORHOOD_IS_${nh.id}_AND_NAME_IS_INHABITANTS`;
  tableData.push({
    name: nh.name,
    inhabitants: valueResult[0] // TQL returns an array of results
  });
}

Instead, the select statement should be written as follows: 

const neighborhoodNames = [ $SELECT_NAME_WHERE_NEIGHBORHOOD_IS_X ];
const neigbhorhoodInhabitants = [ $SELECT_ATTRIBUTE_WHERE_NEIGHBORHOOD_IS_X_AND_NAME_IS_INHABITANTS ];

const tableData = [];
for(let n = 0; n < neighbhorhoodNames.length && n < neighborhoodInhabitants.length; n++){
  tableData.push({
    name: neighborhoodNames[n];
    inhabitants: neighborhoodInhabitants[n];
  });
}

For further specification details, see Global, Attribute and Select (TQL) respectively.

Notes

See also

API Endpoints

Retrieved from "https://support.tygron.com/w/index.php?title=Tag&oldid=90221"