Dealing with XML data

The PortableApps.com Launcher can deal with writing values to XML files and reading values from XML files.

New in version 2.1.

Enabling XML support

To enable XML support for your launcher, set [Activate]:XML to true.

Sections that support XML

XML is supported by the PortableApps.com Launcher for reading and writing configuration variables; for reading language strings, there is [LanguageFile]. For writing any strings (language or otherwise), there is [FileWriteN].

Example

FreeCol is one app which stores settings in an XML file. For language switching, it has the [LanguageFile] section and a [FileWriteN] section.

Here are those XML-specific parts of FreeCol configuration:

[LanguageFile]
File=%PAL:DataDir%\freecol\freecol\options.xml
Type=XML attribute
XPath=/clientOptions/languageOption[@id="model.option.languageOption"]
Attribute=value

[FileWrite1]
File=%PAL:DataDir%\freecol\freecol\options.xml
Type=XML attribute
XPath=/clientOptions/languageOption[@id="model.option.languageOption"]
Attribute=value
Value=%PAL:LanguageCustom%

This will work on an XML file like this:

<clientOptions>
    <!-- ... -->
    <languageOption
        id="model.option.languageOption"
        value="(language)"/>
    <!-- ... -->
</clientOptions>

Using XML in custom code

It’s possible that you’ll need to deal with XML files in custom code; when writing to an XML file, if you can, set an environment variable with ${SetEnvironmentVariable} or ${SetEnvironmentVariablesPath} and use the environment variable in a normal [FileWriteN] section. However, if this is not possible, you can use the write macros below. The NSIS code to read or write is like this (XML must be activated, of course):

${XMLReadAttrib} filename xpath attribute $output

${XMLReadText} filename xpath $output

${XMLWriteAttrib} filename xpath attribute value

${XMLWriteText} filename xpath value

XPaths in XML

XPaths are a way of selecting an element (or attributes, but we only deal with elements here) in an XML tree.

From the FreeCol example above, the XPath is /clientOptions/languageOption[@id="model.option.languageOption"]. This matches an XML document with the root element <clientOptions> and directly under it a languageOption element with the atttribute id set to model.option.languageOption. In other words, the simplest XML tree which could match that XPath is this:

<clientOptions>
    <langugeOption id="model.option.languageOption"/>
</clientOptions>

Note that when an attribute is being written to or read from, the XPath used does not include the attribute. That is given as a separate value (Attribute).

For more information about XPaths, see the Wikipedia article on XPaths and links that it has.