data.getStaticData: Difference between revisions
(Generic namespaces) |
m (Apparently, the 'syntaxhighlight' tag must not have a leading space) |
||
(2 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
{{MacroFunction | |||
|name=data.getStaticData | |||
|proposed=false | |||
|trusted=true | |||
|version=1.11.0 | |||
|description= | |||
Currently, the only type of data this function can return is for [[Add-On Library|Add-On Libraries]], but this may be expanded in the future. | |||
This function can be used to access text files, JSON, or even images within an add-on. Images are returned in the {{code|asset://}} format so they can be used in image tags. | |||
|usage= | |||
data.getStaticData(namespace, path) | <syntaxhighlight lang="mtmacro" line> | ||
[data.getStaticData(namespace, path)] | |||
</syntaxhighlight > | |||
If called from outside of an add-on, {{code|getStaticData()}} can only access files in the {{code|library/public/}} directory. | |||
Refer to [[Technical definition of Add-on Libraries]] for a description of the internal file structure of the add-on. | |||
|example= | |||
This example demonstrates how to retrieve raw text from the {{code|my.name.space/library/public/testData.txt}} file contained within the add-on library and display it in the chat panel. | |||
{{note|Excessively large text may produce errors as the chat panel may not be able to handle all of it. In such a case, no partial output will appear.}} | |||
Text will always be read as UTF-8, so ensure that you use that encoding when creating the content. | |||
<syntaxhighlight lang="mtmacro" line> | |||
[r: data.getStaticData("my.name.space", "public/testData.txt")] | [r: data.getStaticData("my.name.space", "public/testData.txt")] | ||
</syntaxhighlight > | |||
Returns the contents of the file, possibly with embedded control codes, such as {{code|\n}} or similar. | |||
This example retrieves the content of the {{code|my.name.space/library/example/testData2.txt}} file from the {{code|my.name.space}} add-on. This will only succeed when executed from ''within'' the add-on. | |||
<syntaxhighlight lang="mtmacro" line> | |||
[r: data.getStaticData("my.name.space", "example/testData2.txt")] | [r: data.getStaticData("my.name.space", "example/testData2.txt")] | ||
</syntaxhighlight > | |||
Returns the contents of the file. | |||
When called from within the code of the add-on, {{code|getStaticData()}} can '''only''' access files in the {{code|library/}} directory and subdirectories. For example, to display the contents of a {{code|testData2.txt}} file in a directory {{code|library/example/}} from one of the add-on's macros, use this line is the macro: | |||
{{note| | |||
* Do NOT include the {{code|library/}} directory prefix when retrieving content. | |||
* The context menu for [[Library Token|library tokens]] has the '''Export Library Token as Addon...''' option. This option creates a separate file in the add-on's {{code|library/property/}} directory for each non-empty property on the token. Given that they are not under {{code|library/public}}, they will not be accessible outside from the add-on. Move them into {{code|library/public/}} if you want them to be available. | |||
* If {{code|getStaticData()}} is unable to access the file, the result will be an empty string. | |||
* The full namespace of the add-on must be used (as defined by the {{code|name}} property in the add-on's {{code|library.json}} file). You cannot use {{code|this}} as the namespace — trying to do so will produce the error, "Library with namespace 'this' does not exist." | |||
}} | |||
}} | |||
[[Category:Macro Function]] | [[Category:Macro Function]] | ||
[[Category:Add-on Library Functions]] |
Revision as of 01:11, 15 February 2024
data.getStaticData() Function
Note: This function can only be used in a Trusted Macro
asset://
format so they can be used in image tags.Usage
[data.getStaticData(namespace, path)]
If called from outside of an add-on, getStaticData()
can only access files in the library/public/
directory.
Refer to Technical definition of Add-on Libraries for a description of the internal file structure of the add-on.
Example
my.name.space/library/public/testData.txt
file contained within the add-on library and display it in the chat panel.
Text will always be read as UTF-8, so ensure that you use that encoding when creating the content.
[r: data.getStaticData("my.name.space", "public/testData.txt")]
Returns the contents of the file, possibly with embedded control codes, such as \n
or similar.
This example retrieves the content of the my.name.space/library/example/testData2.txt
file from the my.name.space
add-on. This will only succeed when executed from within the add-on.
[r: data.getStaticData("my.name.space", "example/testData2.txt")]
Returns the contents of the file.
When called from within the code of the add-on, getStaticData()
can only access files in the library/
directory and subdirectories. For example, to display the contents of a testData2.txt
file in a directory library/example/
from one of the add-on's macros, use this line is the macro:
- Do NOT include the
library/
directory prefix when retrieving content. - The context menu for library tokens has the Export Library Token as Addon... option. This option creates a separate file in the add-on's
library/property/
directory for each non-empty property on the token. Given that they are not underlibrary/public
, they will not be accessible outside from the add-on. Move them intolibrary/public/
if you want them to be available. - If
getStaticData()
is unable to access the file, the result will be an empty string. - The full namespace of the add-on must be used (as defined by the
name
property in the add-on'slibrary.json
file). You cannot usethis
as the namespace — trying to do so will produce the error, "Library with namespace 'this' does not exist."