data.getStaticData: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
m (Added reference to add-ons; cleanup of grammar/formatting)
m (Oops, it's "source" that should be replaced with "syntaxhighlight")
Line 9: Line 9:
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.
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=
|usage=
<source lang="mtmacro" line>
< syntaxhighlight lang="mtmacro" line>
[data.getStaticData(namespace, path)]
[data.getStaticData(namespace, path)]
</source>
</syntaxhighlight >


If called from outside of an add-on, {{code|getStaticData()}} can only access files in the {{code|library/public/}} directory.
If called from outside of an add-on, {{code|getStaticData()}} can only access files in the {{code|library/public/}} directory.
Line 19: Line 19:
{{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.}}
{{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.
Text will always be read as UTF-8, so ensure that you use that encoding when creating the content.
<source lang="mtmacro" line>
< syntaxhighlight lang="mtmacro" line>
[r: data.getStaticData("my.name.space", "public/testData.txt")]
[r: data.getStaticData("my.name.space", "public/testData.txt")]
</source>
</syntaxhighlight >
Returns the contents of the file, possibly with embedded control codes, such as {{code|\n}} or similar.
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.
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.
<source lang="mtmacro" line>
< syntaxhighlight lang="mtmacro" line>
[r: data.getStaticData("my.name.space", "example/testData2.txt")]
[r: data.getStaticData("my.name.space", "example/testData2.txt")]
</source>
</syntaxhighlight >
Returns the contents of the file.
Returns the contents of the file.



Revision as of 04:15, 11 February 2024

data.getStaticData() Function

 Note: This function can only be used in a Trusted Macro

Introduced in version 1.11.0
Currently, the only type of data this function can return is for 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 asset:// format so they can be used in image tags.

Usage

< syntaxhighlight lang="mtmacro" line> [data.getStaticData(namespace, path)] </syntaxhighlight >

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

This example demonstrates how to retrieve raw text from the my.name.space/library/public/testData.txt file contained within the add-on library and display it in the chat panel.
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")] </syntaxhighlight > 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. < syntaxhighlight lang="mtmacro" line> [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, 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 under library/public, they will not be accessible outside from the add-on. Move them into library/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's library.json file). You cannot use this as the namespace — trying to do so will produce the error, "Library with namespace 'this' does not exist."