data.getStaticData: Difference between revisions

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

[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

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.

[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 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."

@@ Line 1: / Line 1: @@
-A function added to MapTool Macro Script to work with data. Currently, the only type of data stored is for [[Add-On Library|Add-On Libraries]], but this will be expanded in the future. This can be used to access text files, JSON, or even images within the add-on. Images are returned in the asset:// format so they can be used in image tags.
+{{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.
-Usage:
+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)
+<source lang="mtmacro" line>
+[data.getStaticData(namespace, path)]
+</source>
-If called from outside of the Add-on, getStaticData() can only access files in the library/public/ directory. For example, to display the contents of a testData.txt file in the chat window, make sure testData.txt is in the library/public/ directory and type:
+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.
+<source lang="mtmacro" line>
 [r: data.getStaticData("my.name.space", "public/testData.txt")]
+</source>
+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.
-If 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:
+<source lang="mtmacro" line>
 [r: data.getStaticData("my.name.space", "example/testData2.txt")]
+</source>
+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:
-Notes:
+{{note|
+* Do NOT include the {{code|library/}} directory prefix when retrieving content.
-# Do not include the library/ directory name in the path passed to getStaticData()
+* 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.
-# The 'Export Library Token as Addon' tool turns each token property into a file in a property/ directory. As per above, that directory cannot be accessed by getStaticData() - the files will need to be moved into the library/ directory or a subdirectory of library/ (e.g. library/public/ if desired to access from outside the Add-on)
+* If {{code|getStaticData()}} is unable to access the file, the result will be an empty string.
-# If getStaticData() is unable to access the the file (e.g. if trying access a directory other than public/ from outside of the Add-on, or if the directory/file doesn't exist), no output will be produced.
+* 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."
-# The full namespace must be written (as defined 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."
+}}
+}}
 [[Category:Macro Function]]
+[[Category:Add-on Library Functions]]

data.getStaticData: Difference between revisions

Revision as of 04:09, 11 February 2024

data.getStaticData() Function

Usage

Example

Navigation menu