Tag: Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
← Older editNewer edit →
Maxim@tygron.com (talk | contribs)
Tygron, Tygron_admin, Bureaucrats, Administrators
5,182 edits
Maxim@tygron.com (talk | contribs)
Tygron, Tygron_admin, Bureaucrats, Administrators
5,182 edits
No edit summary
Maxim@tygron.com (talk | contribs)
Tygron, Tygron_admin, Bureaucrats, Administrators
5,182 edits
No edit summary
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. TQL tags are calculated when the simulation is updated.
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:
 
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 content of a text panel is always presented as HTML. In case the text content is not presented as HTML, the <code>&lt;html&gt;</code> and <code>&lt;body&gt;</code> tags are added around the text content.
 
==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
| $TOKEN
| Inserts the [[Web Token]] of the [[Project]]'s [[Session]].
| 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.
|-
|-
| $SESSION
| Inserts the url web endpoint 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 [[Item]] the [[Panel]] is related to.<br>
| Replaced with empty string
If not used with a [[Template Panel]], an empty string is inserted.
|-
|-
| $ID
| $ID
| Inserts the [[ID]] of the [[Panel]].<br>
| Replaced with the id of the linked item.
If not used with a [[Template Panel]], "-1" is inserted.
|-
|-
| $NAME
| $STAKEHOLDER_ID
| Replaced with the name of the linked item.
| Inserts the [[ID]] of the user's [[Stakeholder]].
|-  
|-
| $ATTRIBUTE_
| $STAKEHOLDER
| Replaced with the value for the attribute specified after <code>$ATTRIBUTE_</code>, obtained from the linked item.  
| Inserts the name of the user's [[Stakeholder]].
|-  
| $GLOBAL_
| Obtains the value of the [[Global]] specified after <code>$GLOBAL_</code> from the linked item.
|}
|}


===Attributes tags===
==Limitations==
{|class=wikitable
Tags, as well as [[Globals]], [[attribute]]s and [[Select (TQL)|TQL Select statement]]s are only replaced in the text content; They cannot be stated dynamically with javascript. I.e.  
! 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.<br>
const tableData = [];
If the [[Attribute]] does not exist for the [[Item]], an empty array is inserted, i.e. "[]".
for (const nh of neighborhoods) {
If not used with a [[Template Panel]], the tag is not replaced.
  const nameQuery = `$SELECT_NAME_WHERE_NEIGHBORHOOD_IS_${nh.id}`;
|-
  const valueQuery = `$SELECT_ATTRIBUTE_WHERE_NEIGHBORHOOD_IS_${nh.id}_AND_NAME_IS_INHABITANTS`;
| $GLOBAL_GLOBALNAME, where GLOBALNAME is the [[TQL name|name]] of the [[Global]].
  tableData.push({
| Inserts the value of the indicated [[Global]]s. If the [[Global]] does not exist, it is considered "0".
    name: nh.name,
|}
    inhabitants: valueResult[0] // TQL returns an array of results
  });
}
</syntaxhighlight>
 
Instead, the select statement should written as followed:
<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>


===TQL tags===
For further specification details, see [[Global]], [[Attribute]] and [[Select (TQL)]] respectively.
{|class=wikitable
! Tag
! Effect
|-
| $SELECT_LANDSIZE_WHERE_NEIGHBORHOOD_IS_0
| Inserts area of the Neighborhood with ID 0. e.g. '100.0'
|-
| $SELECT_LANDSIZE_WHERE_NEIGHBORHOOD_IS_X
| Inserts areas of all Neighborhoods. e.g. '100.0, 200.0, 15.0'
|}


{{article end
{{article end
| notes=
|seealso=*[[Text Panel]]  
* Tags can also be used in the output of [[Panel]]s based on an [[Excel]], and in [[Indicator]]s.
*[[Panel]]
* 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.
*[[Select (TQL)]]
* [[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.
*[[JavaScript]]
* 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]]
* [[Template Panel]]
* [[Global]]
* [[Attribute]]
}}
}}

Revision as of 13:09, 6 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:

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 content of a text panel is always presented as HTML. In case the text content is not presented as HTML, the <html> and <body> tags are added around the text content.

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, as well as Globals, attributes and TQL Select statements are only replaced in the text content; They cannot be stated dynamically with javascript. I.e. 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 written as followed: 

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.

See also

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