This project is read-only.

Creating Module Settings Form Using XsltDb.

settings_sample.PNG

Introduction

If you create a configuration that can be put on a number of pages on different portals you may want it to have different look on each portal and page. This can be done using mdo:setup tag that declares module setup form on module settings page. This means:
  • Values for settings are stored as module settings so they are different for the same configuration if you link a number of modules to single configuration.
  • However, if you put the same module on different pages they would share settings as it is the same DotNetNuke module instance.

Types of Settings

mdo:setup tag has the following structure:

<mdo:setup>
  <section control-width="..." label-width="..." >Module settings section title</section>
  <setting type="..." name="..." width="..." height="..." visible="...">
    <caption>setting control label</caption>
    <tooltip>setting control label tooltip</tooltip>
  </setting>
  <markup>
    Any HTML goes here.
  </markup>
</mdo:setup>
Currently XsltDb supports the following setting types:
  • date – date input field with calendar
  • text – single line text box
  • longtext – multiline text box.
  • richtext – formatted (HTML) text.
  • password – protected field for password processing
  • select – drop down list box
  • checkbox – checkbox.
  • file – file selection or upload
Besides <setting> you can put <markup> tag that allows you to put/generate free HTML inside :

Settings properties

Each type of setting (except <a/> and <new-group/>) has the following common properties:
  • name – name of setting in the database (ModuleSettings.SettingName column value). this name is also used by mdo:get-module-setting() function.
  • type – the type of setting and editing control. One of the types listed above.
  • width – control width (overrides secrion/@controls-width)
  • height – control height
  • visible – defines visibility of dependant setting (see Dependant Lists section)
    • True – to show setting control
    • False to hide setting control
  • auto-post-back – if "true" forces setting form to be rebuilt to reflect changes. (see Dependant Lists section)
Inside each setting we can put
  • <caption> tag with control label
  • <tooltip> tag with control label tooltip.
Settings of type "file" can have additional attribute "filter" that can contain a list of allowed extensions

Creating Lists

To create a drop down list we use setting of type "select". It can have <source> section where we can list available items:

<setting type="select" name="color">
  <source>
    <option value="#FF0000">Red</option>
    <option value="#00FF00">Green</option>
    <option value="#0000FF">Blue</option>
  </source>
</setting>
There’s no problem to fill options from database. Here’s an example with list of countries:

<setting name="country" type="select">
   <caption>Country</caption>
   <source>
     <xsl:variable name="sql-country">
       select EntryID, Text from {databaseOwner}[{objectQualifier}Lists]
       where ListName = 'Country' order by Text;
     </xsl:variable>
     <xsl:for-each select="mdo:sql($sql-country, 'country')//country">
       <option value="{EntryID}">{{Text}}</option>
     </xsl:for-each>
   </source>
 </setting>

Settings Form

Settings form is generated automatically by XsltDb but you can setup the following parameters
  • Section name – appears above settings form to the right of section expander.
  • Labels width – width of column with labels.
  • Controls width – width of column with settings controls.
Sample:

<section label-width="200px" control-width="200px">
   News Settings <!-- this is section name -->
 </section>

Validation

XsltDb settings mechanism supports the following validators:
  • Required Field
  • Regular Expression
  • Compare
  • Range

Required Field

No parameters. Example:

<validator type="required">This field cannot be blank</validator>

Regular Expression

Parameters:
  • regex – regular expression value should match.
Example:

   <validator type="regex" regex=".*\b[a-zA-Z0-9._%\-+]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]\{{2,4}}\b.*">
     Please, enter valid e-mail.
   </validator>

Compare

Parameters
  • compare-to – name of setting to compare
  • operator – type of comparison. Can be one of the following
    • Equal
    • NotEqual
    • GreaterThan
    • GreaterThanEqual
    • LessThan
    • LessThanEqual
    • DataTypeCheck
  • data-type – used to specify settings type for "DataTypeCheck" type of comparison.

Range

Parameters
  • min – minimum value for the setting
  • max – maximum value for the setting
  • data-type – data type of setting. Can be one of the following
    • String
    • Integer
    • Double
    • Date
    • Currency
Example:

   <validator type="range" min="01/01/2000" max="01/01/2020" data-type="Date">

Simple Settings Example

This is a complete example for the simple form with one setting of type date:

<mdo:setup>
<section label-width="200px" > News Settings </section>
<setting name="date" type="date">
   <caption>Begin date</caption>
   <tooltip>Service will be provided on and after this date.</tooltip>
   <validator type="range" min="01/01/2000" max="01/01/2020" data-type="Date">
     This must be a valid date.
   </validator>
</setting>
</mdo:setup>
It is useful to setup a range validator for date setting as it ensures date is well formed.

Localization

If you need you settings to be multilingual you can use any localization method available in XsltDb Localization example:

<mdo:setup>

<xsl:variable name="_strings">
  <caption>
    <value>News Settings</value>
    <value culture="ru-RU">Настройки новостей</value>
  </caption>
  <label>
    <value>Begin date</value>
    <value culture="ru-RU">Дата начала</value>
  </label>
  <label-tooltip>
    <value>Service will be provided on and after this date.</value>
    <value culture="ru-RU">Сервис будет предоставлен начиная с этой даты (включительно)</value>
  </label-tooltip>
  <error>
    <value>Service will be provided on and after this date.</value>
    <value culture="ru-RU">Сервис будет предоставлен начиная с этой даты (включительно)</value>
  </error>
</xsl:variable>
<xsl:variable name="strings" select="msxsl:node-set($_strings)"/>

<section label-width="200px" >{{#strings/caption#}}</section>
<setting name="date" type="date">
   <caption>{{#strings/label#}}</caption>
   <tooltip>{{#strings/label-tooltip#}}</tooltip>
   <validator type="range" min="01/01/2000" max="01/01/2020" data-type="Date">
     {{#strings/error#}}
   </validator>
</setting>
</mdo:setup>

Dependant Lists

Lists can be organized in hierarchical structure. When creating child list you have to use value of parent list to select items for child list. Parent list must have auto-post-back option set to True. It indicates that there are controls that depend on the value of this (parent) control.
To simplify hierarchy processing mdo:get-module-setting() function behaves as follows:
  • Being used in the settings form it returns current value of setting control instead of value.
  • In case of the first execution (when we just enter the form) it returns value stored in the ModuleSettings table.
So you just use it to reference parent values and XsltDb automatically chooses right value.

Complete Settings Example

Here is an example for Country / State selection. This example assumes that you are creating a news translation module that is capable to translate worldwide news or filtered by country or region. So you need a check-box "Show regional news". If it is ON – country and state selection boxes must appear.

<mdo:setup>
 <section label-width="200px" controls-width="200px;">
   News Settings
 </section>
 
 <setting name="regional-news" type="checkbox" auto-post-back="true">
   <caption>Show regional news</caption>
 </setting>

 <setting name="country" type="select" auto-post-back="true"
                                   visible="{mdo:get-module-setting('regional-news')='True'}">
   <caption>Country</caption>
   <source>
     <xsl:variable name="sql-country">
       select EntryID, Text
       from {databaseOwner}[{objectQualifier}Lists]
       where ListName = 'Country'
       order by Text;
     </xsl:variable>
     <xsl:for-each select="mdo:sql($sql-country, 'country')//country">
       <option value="{EntryID}">{{Text}}</option>
     </xsl:for-each>
   </source>
 </setting>

 <xsl:variable name="country" select="mdo:get-module-setting('country', -1)"/>
 <xsl:variable name="sql-region">
      select EntryID, Text
      from {databaseOwner}[{objectQualifier}Lists]
      where ListName = 'Region' and ParentID = @ParentID
      order by Text
 </xsl:variable>
 <xsl:variable name="regions" select="mdo:sql($sql-region, 'region', '@ParentID', $country)"/>
 <setting name="region" type="select"
       visible="{count($regions//region)!=0 and mdo:get-module-setting('regional-news')='True'}">
   <caption>Region</caption>
   <source>
     <xsl:for-each select="$regions//region">
       <option value="{EntryID}">{{Text}}</option>
     </xsl:for-each>
   </source>
 </setting>
 
</mdo:setup>
This script creates the following form:
settings_sample.PNG
As you see you can build your lists depending on any parent input field, not only list.

Future Roadmap

In future releases you will
  • be able to select setting storage (tab-module settings, module settings, portal settings or custom procedure)
  • have more default controls
  • be able to use XsltDb configuration to create Settings control
  • be able to create additional controls (not only View and Settings) using XsltDb configuration.

Last edited Aug 6, 2010 at 11:28 AM by findy, version 18

Comments

No comments yet.