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 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

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>

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');
   });
});

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 a true or false value.

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

In config.css, contains 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'), tentatively in index.js.

Using AppData for HTML Component selectors

// 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 Component selectors

// index.html
<div class="form-group">
   <input class="form-control" data-component="page-selector" name="page">
</div>
<div class="form-group">
   <input class="form-control" data-component="file-selector" name="file">
</div>
<div class="form-group">
   <input class="form-control" data-component="image-selector" name="image">
</div>
<div class="form-group">
   <select class="form-control" data-component="template-selector" name="template"></select>
</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');

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.