== Widget settings ==


Every widget must have 3 necessary files: '''xml/main.xml''', '''xml/config.xml''' and '''xml/settings.xml''' and 2 or more optional files. If your widget provides different languages and skins it should contain '''xml/langs.xml''' and '''xml/skins.xml''' files respectively. They should be empty and will be overwritten after widget installation.

'''main.xml''' file should be empty. It will be overwritten after widget installation.

'''config.xml''' file contains current widget settings. These settings are used in Ray Admin panel in "Settings" section of the widget as current values. This file has the following structure:

{{{
<items>
<item key="some_key1"><![CDATA[some_value1]]></item>
<item key="some_key2"><![CDATA[some_value2]]></item>
...
<item key="some_keyN"><![CDATA[some_valueN]]></item>
</items>
}}}

Every item contains "'''key'''" and "'''value'''" attributes.

'''settings.xml''' file contains widget settings description and default values. These settings are used in the Ray Admin panel in the "'''Settings'''" section of the widget for respectively displaying settings controls. Settings that can't be changed through the "'''Settings'''" section in Ray Admin exist only in "'''config.xml'''". This file has the following structure:

{{{
<items>
<item type="string" key="some_key1" default="def_value1" range="20">
<caption><![CDATA[some_key1 caption]]></caption>
<comment><![CDATA[some_key1 description]]></comment>
</item>
<item type="number" key="some_key2" default="10" range="1:100">
<caption><![CDATA[some_key2 caption]]></caption>
<comment><![CDATA[some_key2 description]]></comment>
</item>
<item type="boolean" key="some_key3" default="false" range="">
<caption><![CDATA[some_key3 caption]]></caption>
<comment><![CDATA[some_key3 description]]></comment>
</item>
<item type="select" key="some_key4" default="value1" range="value1 value2 value3">
<caption><![CDATA[some_key4 caption]]></caption>
<comment><![CDATA[some_key4 description]]></comment>
</item>
<item type="select" key="some_key5" default="3" range="1:5 1">
<caption><![CDATA[some_key5 caption]]></caption>
<comment><![CDATA[some_key5 description]]></comment>
</item>
</items>
}}}

Every item contains "'''type'''", "'''key'''", "'''default'''" and "'''range'''" attributes and two child nodes "'''caption'''" and "'''comment'''". The "'''default'''" attribute contains a default value for this setting.

The "'''range'''" attribute defines the range of values that can be set for this setting. It depends on the type of setting.

The "'''type'''" attribute can be one of the following:

    '''string''' - any string value. Range - maximum string length.

    '''number''' - any number. Range - numbers range ([minimum]:[maximum]).

    '''boolean''' - logical value: true/false. Range should be empty.

    '''select''' - enumerable setting. Range - all possible values for this setting (" " - separator). If you want to show numbers as selection options you can use a structure like [minimum]:[maximum] [step] (see example above).

"'''caption'''" and "'''comment'''" nodes contain setting caption and comment as values respectively.