config.xml File Import Extension

A Function extension supplies a button in the PYTHA user interface. The user can invoke the function by pressing that button.

Declaration of a function extension in the config.xml:

<extension type="file-import">
    <entry-point>import</entry-point>
    <id>extension-id</id>
    <caption>Text of the Button</caption>
    <file-filter>*.txt</file-filter>
    <scope>file</scope>
    <help-file>help.html</help-file>
</extension>

The following information can be supplied:

• entry-point - (Mandatory) Name of the lua function that is invoked when the user invokes the import. Note that the name can be chosen freely. import, above, is just an example.
• caption - (Mandatory) The text that is displayed in the Import menu. This text is translatable in the .xlif file.
• id - The extension ID of the import extension.
• file-filter - The file type (or file types) that the extension will handle. The extension must be written with a leading asterisk, e.g. as *.txt for a file with the extension "txt".
• scope - (Optional) If and to what extent the file system is accessible to the import plugin. One of:
  • file (default) - Only the imported file is accessible. The entry point receives a single path handle.
  • folder - The entry point additionally receives a handle to the folder the file lives in, allowing read access to sibling files as well
  • recursive - As folder, but the handle also grants read access to the whole sub-tree below it.
• help-file - The name of a help file (should be .html or .pdf or .txt). This file is opened when the user right-clicks on the button and invokes help. This name of the file is translatable in the .xlif file if separate help files are supplied for different languages.

When the user invokes the import and has selected a file, the entry-point is invoked with the corresponding path handle as its argument

function import(file)

If scope is folder or recursive, the entry-point additionally receives a handle to the folder the file lives in:

function import(file, directory)

Parameter	Type	Description
file	path_handle	Handle of the file that the user has selected for import. This is always a plain path handle and cannot be used to browse the directory.
directory	path_handle or nil	(only when scope is folder or recursive) A path handle to the folder the file lives in, with the corresponding access level.

See the file parsing functions, e.g. parse_csv(), parse_xml() etc. for options how to access the file contents.

Remarks:

You can automatically call the import extension from the command line via /Plugin "plugin_guid/extension_id" "file_path".

Version Support:

Minimum PYTHA Version: V26

See also:

config.xml, Edit Extension, Attribute Extension, Anatomy of a Lua Api Plugin, Localization and Translation