Configuration in WebApps

WebApp specific settings can be set in the configuration.

  • src/
    • config/
      • index.html
      • config.js
      • config.css

Configuration is retrieved in a WebApp server side context through the appData-object.

index.html

WebApp configuration is defined in index.html

<div class="panel panel-default">
   <div class="panel-heading">
      <h3 class="panel-title">WebApp Configuration</h3>
   </div>

   <div class="panel-body">
      <div class="form-group">
         <input class="form-control" data-component="page-selector" name="page">
      </div>

      <div class="form-group">
         <label>Text</label>
         <input class="form-control" type="text" name="text">
      </div>
   </div>
</div>

SiteVision components

SiteVision offers "native" components to select values from the SiteVision model. Values are retrieved using the appData-object in a server side script context.

Node selectors

In order to utilize SiteVision node selectors, simply add data-component="<type>" to an input/select element. The following types are supported.

// page-selector
<input class="form-control" data-component="page-selector" name="page">

// file-selector
<input class="form-control" data-component="file-selector" name="file">

// image-selector
<input class="form-control" data-component="image-selector" name="image">

// user-selector [@since 4.5.3]
<input class="form-control" data-component="user-selector" name="user">

// content-node-selector [@since 4.5.3]
<input class="form-control" data-component="content-node-selector" name="content">

// metadata-selector
<select data-component="metadata-selector" name="metadata"></select>

// template-selector
<select data-component="template-selector" name="template"></select>

Options

Options are passed to node selectors as data-attributes.

Attribute

Description

Since

data-removable

Makes it possible to clear a selected value

4.5.3

<input class="form-control" data-removable data-component="page-selector" name="page">
<select data-removable data-component="template-selector" name="template"></select>

List components

In order to utilize SiteVision list components, simply add data-component="<type>-list" to a hidden input element.

List component values are retrieved in a server side script context using the appData.getArray-method. 

The following types are supported.

// page-list [@since 4.5.3]
<input type="hidden" data-component="page-list" name="pages">

// file-list [@since 4.5.3]
<input type="hidden" data-component="file-list" name="files">

// image-list [@since 4.5.3]
<input type="hidden" data-component="image-list" name="images">

// user-list [@since 4.5.3]
<input type="hidden" data-component="user-list" name="users">

Adding SiteVision components dynamically [@since 4.5.2]

SiteVision components may be initialized dynamically by triggering 'setup-component' on the body with a selector targeting the component to initialize. See the following example:

 //config.js 
$(function() {
   $('#addComponentButton').on('click', function() {
      var el = 
         '<div class="form-group">' +
            '<label>Page</label>' +
            '<input id="myCustomId" class="form-control" data-component="page-selector" name="myCustomName">' +
         '</div>';
      
      $('.panel-body').append($(el));
      $('body').trigger('setup-component', '#myCustomId');
   });
});

A sv:loaded jQuery-event will be triggered for <select>-based components (template/metadata-selector) when the component has fetched its data (since 4.5.3).

HTML Components

Regular HTML elements may also be used to accept data from the user.

// Text
<div class="form-group">
   <label>Text</label>
   <input class="form-control" name="text">
</div>

// Email
<div class="form-group">
   <label>Email</label>
   <input type="email" class="form-control" name="email">
</div>

// Textarea
<div class="form-group">
   <label>Textarea</label>
    <textarea class="form-control" name="textarea"></textarea>
</div>

// Radiobuttons
<div class="form-group">
   <label><input type="radio" value="Value1" name="radio"/>Value 1</label>
   <label><input type="radio" value="Value2" name="radio"/>Value 2</label>
</div>

// Checkbox
<div class="form-group">
   <label><input type="checkbox" value="Checkbox1" name="checkbox"/>Checkbox1</label>
   <label><input type="checkbox" value="Checkbox2" name="checkbox"/>Checkbox2</label>
   <label><input type="checkbox" value="Checkbox3" name="checkbox"/>Checkbox3</label>
</div>

// Checkbox boolean
<div class="form-group">
   <label><input type="checkbox" name="checkboxBoolean" data-value-type="boolean"/>True/False</label>
</div>

// Single Selection
<div class="form-group">
   <select id="select" name="single" class="form-control">
      <option value="Value1">Value 1</option>
      <option value="Value2">Value 2</option>
      <option value="Value3">Value 3</option>
      <option value="Value4">Value 4</option>
   </select>
</div>

// Multiple selection
<div class="form-group">
   <select id="multiple-select" multiple name="multiple" class="form-control">
      <option value="Value1">Value 1</option>
      <option value="Value2">Value 2</option>
      <option value="Value3">Value 3</option>
      <option value="Value4">Value 4</option>
   </select>
</div>

Checkbox boolean

For checkboxes you can use the data attribute data-value-type="boolean" to make it return true or false.

Hide settings for editors

By adding the data attribute "data-global-setting" to a config element, it will only be visible in the addons area in the SiteVision editor.

config.js

In config.js, custom JavaScript may be added, that will be executed in the configuration panel. It is also possible to overwrite default functions (validate, setValues and getValues).

Validate

By default, elements with the required attribute are validated. To add custom validation, overwrite the default validation function.

(function() {
   // overwrite default validate function
   window.validate = function() {
      var emailInput = document.querySelector('input[name=email]');

      return isValidEmail(emailInput.value);
   };
}());

setValues

setValues populates elements with data when configuration is loaded. To handle custom components this function should be overridden.

(function($) {
   // populate inputs when configuration is loaded
   window.setValues = function(values) {
      var inputs = document.querySelectorAll('input');

      inputs.forEach(function(input) {
         var name = input.name;

         if (name) {
            var value = values && values[name],
               $input = $(input);

            $input.val(value);
            $input.trigger('change');
         }
      });
   };
}(jQuery));

getValues

getValues retrieves values from elements that will be sent to the server. To handle custom components this function should be overridden.

(function($) {
   // retrieve values that will be sent to the server
   window.getValues = function() {
      var values = {},
         inputs = document.querySelectorAll('input');

         inputs.forEach(function(input) {
            var name = input.name;

            if (name) {
               var inputValue = input.value;
               values[name] = inputValue;
            }
         });
         
      return values;
   };
}(jQuery));

config.css

Add custom CSS for the configuration panel.

// index.html
<div class="form-group">
   <label>Text</label>
   <input class="form-control amazing-class" name="text">
</div>   

// config.css
.amazing-class {
	color: blue;
}

AppData

To access configuration, use require('appData')in a server side script context.

Using AppData for HTML input elements

// index.html
<div class="form-group">
   <label>Text</label>
   <input class="form-control amazing-class" name="theTextField">
</div>   

// index.js
var appData = require('appData');
...
// returns the text value from the input field
text = appData.get('theTextField');

Using AppData for SiteVision components

// index.html
<div class="form-group">
   <label>Page</label>
   <input class="form-control" data-component="page-selector" name="page">
</div>
<div class="form-group">
   <label>Pages</label>
   <input type="hidden" data-component="page-list" name="pages">
</div>

// index.js
var appData = require('appData');
...
// returns the JCR Node
page = appData.getNode('page');

// returns the JCR Node identifier i.e: '4.540818ed12a6539aa3f80001645'
pageId = appData.get('page');

/*
 * returns an object with given properties of the JCR Node i.e:
 *
 *   {
 *      URI: '/4.540818ed12a6539aa3f80001645.html',
 *      displayName: 'Home',
 *      published: true,
 *      publishDate: 1227618333142
 *   }
 */
pageData = appData.get('page', 'URI', 'displayName', 'published', 'publishDate');

/* getArray [@since 4.5.3]
 *
 * returns value as an array
 * - an array of JCR Nodes for list components
 * - value wrapped in an array for single type components
 */
pages = appData.getArray('pages');

AppData for the SiteVision metadata selector

The metadata selector manages a metadata definition. Though, in many cases the metadata value is of interest.

Tip! The metadata value for a specific node can be resolved using the name of the metadata definition.

// index.html
<div class="form-group">
   <select class="form-control" data-component="metadata-selector" name="metadef"></select>
</div>

// index.js
var appData = require('appData'),
   portletContextUtil = require('PortletContextUtil'),
   propertyUtil = require('PropertyUtil'),
...

// Get the metadata definition JCR Node
metadataDefinition = appData.getNode('metadef');

// Get the name of the metadata definition and the Node of interest
nameOfTheMetadata = metadataDefinition.getName();
currentPage = portletContextUtil.getCurrentPage();

// ...and resolve the metadata value
metadataValue = propertyUtil.getString(currentPage, nameOfTheMetadata, '');

SiteVision node types

Refer to the node types documentation to see what properties are available for different node types. Values retrieved from appData.get() are JavaScript compatible.

  • PropertyType.DATE returns a timestamp
  • PropertyType.WEAKREFERENCE returns an ID

Config Example App

A WebApp demonstrating configuration is available in SiteVision's GitHub repository.