Creating an editor widget

This topic describes how to extend the Episerver editing user interface through widgets. 

Table of contents

• Editor widget properties
• Editor widget methods
• Creating a simple widget
• Validation
• Dealing with child dialog boxes

Editor widget properties

Episerver page editing is based on the Dojo client JavaScript toolkit. Each property or block that you edit consists of one or more widgets. A widget is a Dojo JavaScript class creates a user interface. Widget methods are used by the wrapper that displays the widget.

• intermediateChanges. Indicates whether the onChange method is used for each value change or only on demand.
• label. Title of the property to be edited.
• value. Value of the widget.
• required. Indicates whether this widget requires a value.

Note: You can add properties for a particular widget by using a PropertyEditorDescriptor.

Editor widget methods

• onChange. Callback event that should be raise from within the widget when the value has changed. The wrapper displaying this widget will listen to this event and update the UI when it occurs.
• focus. Called when the widget is displayed, should give focus to the start element in the widget.
• isValid. Called during validation when item is saving, true if the current value is valid.

Creating a simple editor widget

The following example shows the basic structure of a widget class and creates a simple widget for entering a valid e-mail address. To create a widget for a dialog editor, you must inherit from the dijit._widget class.

define("acme.widget.EmailTextbox", [
  "dojo/_base/declare",
  "dijit/_Widget",
  "dijit/_TemplatedMixin"
], function (
  declare,
  _Widget,
  _TemplatedMixin) {

  declare("acme.widget.EmailTextbox", [_Widget, _TemplatedMixin], {

    // templateString: [protected] String
    //    A string that represents the default widget template.
    templateString: '<div> \
                      <input type="email" data-dojo-attach-point="email" data-dojo-attach-event="onchange:_onChange" /> \
                     </div>'
  })
});

Note: The code snippet inherits from the dijit._TemplatedMixin class, which lets you to create a template for the user interface of the widget in either a local string or an external HTML file. You can attach to elements in the template, giving you a programmatic reference to that node in the widget, and you also can attach events to event handlers in our widget.

When you create this widget, the initial value is passed in as a constructor argument with the property name value, which is automatically mixed into the widget by the constructor in the dijit._widget class. To make sure you update the value in the text box when it is set on the widget, declare a _setValueAttr method, which is called with set('value', value).

postCreate: function () {
  // summary:
  //    Set the value to the textbox after the DOM fragment is created.
  // tags:
  //    protected

  this.set('value', this.value);

  if (this.intermediateChanges) {
    this.connect(this.email, 'onkeydown', this._onIntermediateChange);
    this.connect(this.email, 'onkeyup', this._onIntermediateChange);
  }
},

_setValueAttr: function (value) {
  // summary:
  //    Sets the value of the widget to "value" and updates the value displayed in the textbox.
  // tags:
  //    private

    this._set('value', value);
    this.email.value = this.value || '';
}

This example adds a postCreate method to pass the value to set, which ensures the widget updates correctly with the initial value (because the widget constructor uses a mixin which does not call set).

The set method also references a variable named email, which is the textbox DOM node; it is automatically assigned to this variable name by the dijit._Templated class when it parses the data-dojo-attach-point in the template code.

When you need to populate the changes made in the widget, call the onChange method and pass a new value to it. You should call onChange as often as necessary during editing to provide an accurate preview of changes.

_onChange: function (event) {
  // summary:
  //    Handles the textbox change event and populates this to the onChange method.
  // tags:
  //    private

  this._set('value', event.target.value);
  this.onChange(this.value);
}

The _onChange method is a private event handler that is triggered when a change is made on the text box. It is configured in the template using the data-dojo-attach-event syntax. After it updates the value it calls the onChange method which in turn causes a page to update.

onIntermediateChange: function (event) {
  // summary:
  //    Handles the textbox key press events event and populates this to the onChange method.
  // tags:
  //    private
 
  if (this.intermediateChanges) {
    this._set('value', event.target.value);
    this.onChange(this.value);
  }
}

focus: function () {
  // summary:
  //    Put focus on this widget.
  // tags:
  //    public

  dijit.focus(this.email);
}

isValid: function () {
  // summary:
  //    Indicates whether the current value is valid.
  // tags:
  //    public

  var emailRegex = '[a-zA-Z0-9_.-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+';
  if (!this.required) {
    emailRegex = '(' + emailRegex + ')?';
  }
  var regex = newRegExp('^' + emailRegex + '$');
  return regex.test(this.value);
}

_showChildDialog: function () {
  var dialog = dijit.Dialog({
    title: 'Child Dialog'
  });
  this.connect(dialog, 'onHide', this._onHide);

  this.isShowingChildDialog = true;

  dialog.show();
},

_onHide: function () {
  this.isShowingChildDialog = false;
}