Package Configuration

Creating a package configuration interface for your Scripter-X package is relatively simple.   There are 3 components to Package Configuration:

PackageConfig.html,  PackageConfig.xml and the ScripterX.Config context.

Design is the method of putting form and content together. Design, just as art, has multiple definitions; there is no single definition. Design can be art. Design can be aesthetics. Design is so simple, that's why it is so complicated.  -Paul Rand

PackageConfig.html

This file is your configuration interface markup.  Any valid HTML is supported in this file, however you should know that due to the Emby Configuration Framework, javascript can be of an issue here; so we must avoid it for now.

If we want to request and store valid configuration from our intended package end-user, we should display them using simple HTML input markup.  The name of your input defines the key for that configuration value in your XML configuration file.  The value of the input defines the value of this item in your configuration file.   You can read more about your PackageConfig.xml file below this section. Let's take a look at some examples.

Text Input

Test Setting 1: <input type="text" name="testSetting1" value="%testSetting1%"><br/>

In this example, we define the input type to text.  We set the name to 'testSetting1', and the value to '%testSetting1%'.  When this input is rendered, it will display a textbox on your configuration interface, which represents the 'testSetting1' configuration value in your XML file.  We set the value of the textbox to %testSetting1%, which will be interpreted automatically to the value in your configuration XML with the id (or key) of testSetting1.   You can read more about the XML configuration below.


Checkbox, Option, Select 
are supported however are not yet finalised for rendering back the values; this is in progress.   However, it functions very similar.

Loading and Saving your configuration values is handled by Scripter-X's internal functions.

 

PackageConfig.xml

This file is where all of your packages configuration values are stored, and is in the following format:

<?xml version="1.0"?>
<PackageConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Settings>
    <Setting>
      <Id>testSetting1</Id>
      <Value>Test 1</Value>
    </Setting>
    <Setting>
      <Id>testSetting2</Id>
      <Value>Test 1 2 3</Value>
    </Setting>
    <Setting>
      <Id>testSetting3</Id>
      <Value>Test 3</Value>
    </Setting>
    <Setting>
      <Id>testSetting4</Id>
      <Value>false</Value>
    </Setting>
    <Setting>
      <Id>gender</Id>
      <Value>male</Value>
    </Setting>
    <Setting>
      <Id>testSetting5</Id>
      <Value>OptionVal3</Value>
    </Setting>
  </Settings>
</PackageConfiguration>

Note however, you do not need to create this file manually, unless you wish to define various default values.  Ensure that you follow this exact format, otherwise your package configuration will fail to load.

 

ScripterX.Config Context

So, what would be the use of configuration values if you couldn't manipulate them in your package javascript?  We've got that covered. 

To read or use a value from your package configuration, you need to make use of the ScripterX.Config context, available in your Package.js script.

Note: Editing your configuration file manually will *not* update your live, working configuration values.  The values must be manipulated using this context.   If you do wish to manually update your configuration file, you will need to click the 'reload package' button on your packages interface in order for the package to re-load your XML configuration.

Let's take a look at some examples.

In my configuration file, I have a value :-

<Setting>
  <Id>testSetting1</Id>
  <Value>Test 1</Value>
</Setting>

and I want to read it using javascript within my package.   This is a string value, so I want to make use of .StringValue(), and do so using the following syntax :-

var test_Setting_value = ScripterX.Config.Get("testSetting1").StringValue();

If this were an integer value, I could read the integer value as an integer object by replacing .StringValue() with .IntValue() and thus it would return the integer value for my configuration variable.

Current supported types are :-

StringValue String ScripterX.Config.Get("configId").StringValue()
IntValue Integer ScripterX.Config.Get("configId").IntValue()
LongValue Long ScripterX.Config.Get("configId").LongValue()
DoubleValue Double ScripterX.Config.Get("configId").DoubleValue()
FloatValue Float ScripterX.Config.Get("configId").FloatValue()

** Other types will be included as the packages code matures.

Let's see how to change this value in our javascript.

Any and all value updates accept two parameters, an Id and a Value.  Again, using the same configuration value in my XML file, I'd like to change the value for 'testSetting1' to 'My new value'.  To do so, I would use the following syntax:

ScripterX.Config.Set("testSetting1", "My new value");

Once I've called this function, ScripterX will update the value in my active, loaded package configuration, and then save the configuration back out to your XML file.  You don't need to manually call any save functions, as it will be automatically done for you.   This behavior could change in the future based on feedback and suggestions.