getPropertyNames: Difference between revisions

Latest revision as of 19:36, 14 March 2023

getPropertyNames() Function

• Introduced in version 1.3b48

Returns a String List or JSON Array containing the names of the Token Properties for the Current Token. The type of the value returned depends on the delimiter parameter. All names returned will be in lower case. Use getPropertyNamesRaw() to get the names as they are shown in Campaign Properties.

When a token is added to a campaign it inherits the currently defined properties of the current campaign. These properties are persistent in the token even if the properties are subsequently removed from the campaign. Properties that have been removed from the campaign are no longer editable via the Edit Token dialog but they are still present on the token and may be read and set with getProperty() and setProperty() respectively. To get all properties defined on a token, including those removed from the campaign, use getPropertyNames(). To see only the currently defined properties for the campaign, use getAllPropertyNames().

Usage

getPropertyNames()
getPropertyNames(delim)
getPropertyNames(delim, id)
getPropertyNames(delim, id, mapname)

Parameters

delim - The delimiter used to separate the values in the String List, defaults to ",". Returns a JSON Array if set to "json".
id - The token id of the token which has its property names returned, defaults to the Current Token.
Note: This parameter can only be used in a Trusted Macro.
mapname - The name of the map to find the token. Defaults to the current map.

Example

To display the names of all of the properties on the current token use.

[h: names = getPropertyNames()]
[foreach(name, names, "<br>"): name]

Version Changes

1.3b49 - Added json delimiter option.
1.3b51 - Added id parameter option.
1.5.4 - Added mapname parameter option.

@@ Line 3: / Line 3: @@
 |version=1.3b48
 |description=
-Returns a list containing the names of the names of the [[Token:property|properties]] on the [[Token:Current Token|Current Token]].
+Returns a [[String List]] or [[JSON Array]] containing the names of the [[Introduction_to_Tokens#Properties|Token Properties]] for the [[Current Token]]. The type of the value returned depends on the delimiter parameter. All names returned will be in lower case. Use {{func|getPropertyNamesRaw}} to get the names as they are shown in [[Introduction_to_Properties|Campaign Properties]].
-The type of the value returned depends on the delimiter parameter.
-* If the delimiter is not specified then a [[Macros:string list|string list]] is returned with the default value of {{code|","}} is used.
+{{note|When a token is added to a campaign it inherits the currently defined properties of the current campaign.  These properties are persistent in the token even if the properties are subsequently removed from the campaign.  Properties that have been removed from the campaign are no longer editable via the Edit Token dialog but they are still present on the token and may be read and set with {{func|getProperty}} and {{func|setProperty}} respectively. To get ''all'' properties defined on a token, including those removed from the campaign, use ''getPropertyNames()''.  To see only the currently defined properties for the campaign, use {{func|getAllPropertyNames}}.}}
-* If the delimiter {{code|json}} then a [[Macros:json array|json array]] is returned.
-* Otherwise a [[Macros:string list|string list]] is returned with the delimiter passed in.
 |usage=
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 getPropertyNames()
-</source>
-<source lang="mtmacro" line>
 getPropertyNames(delim)
-</source>
+getPropertyNames(delim, id)
-{{code|delim}} is the delimiter used to separate the values in the  [[Macros:string list|string list]] which defaults to {{code|","}} if not specified.
+getPropertyNames(delim, id, mapname)
+</syntaxhighlight>
+'''Parameters'''
+{{param|delim|The delimiter used to separate the values in the [[String List]], defaults to {{code|","}}. Returns a [[JSON Array]] if set to {{code|"json"}}. }}
+{{param|id|The token {{code|id}} of the token which has its property names returned, defaults to the [[Current Token]]. {{TrustedParameter}} }}
+{{param|mapname|The name of the map to find the token.  Defaults to the current map.}}
 |example=
-To display the names of all of the [[Token:property|properties]] on the current [[Token:token|token]] use.
+To display the names of all of the [[Introduction_to_Tokens#Properties|properties]] on the current [[Token:token|token]] use.
-<source lang="mtmacro" line>
+<syntaxhighlight lang="mtmacro" line>
 [h: names = getPropertyNames()]
 [foreach(name, names, "<br>"): name]
-</source>
+</syntaxhighlight>
 |changes=
 {{change|1.3b49|Added {{code|json}} delimiter option.}}
+{{change|1.3b51|Added {{code|id}} parameter option.}}
+{{change|1.5.4|Added {{code|mapname}} parameter option.}}
 }}
-===Notes===
+[[Category:Token Function]][[Category:Property Function]]
-When token properties are created during campaign, they are persistent in the MapTool campaign, regardless of whether they are editable in the Edit Token window. In other words, even though a property is removed from the campaign properties, it remains available in the MapTool code.  ''getPropertyNames()'' will return ''all'' token properties that exist or have ever existed in the particular campaign, even if users cannot directly edit those properties (''i.e.'', they do not appear in the token's properties when you double click on a token). To get only properties that are currently visible and editable, use [[getAllPropertyNames|getAllPropertyNames()]].
-[[Category:Token Function]]