Configuration in WebApps
WebApp specific settings can be set in the configuration.
- src/
- config/
- index.html
- config.js
- config.css
- config/
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" placeholder="Select Page"
data-component="page-selector" name="page">
</div>
<div class="form-group">
<label>Text</label>
<input class="form-control" 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">
// 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, setValue and getValue).
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);
};
}());
setValue
setValue 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.setValue = 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));
getValue
getValue 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.