Content Comparison

In This Topic

...

Creating a Sidebar Widget

There is an archetype available in XperienCentral for generating Sidebar widgets. Executing the following command in a Command prompt to generate the "Hello World" sidebar widget using the sidebar widget archetype:

...

Related subjects: Plugins / Archetypes

Back to top

...

The Generated Files and Directories

After importing the contents of this directory in an IDE you will see a structure like this:

Activator and other Java code

The most interesting files for the Sidebar widget are the HTML, .CSS and JS files in the resources, since these are specific for widget plugins. The Activator class is the starting point of every plugin and defines the different parts the plugin consists of and what should happen next. For general information on XperienCentral plugins you can find information on the Plugins page and its subpages, such as the section about Authorization in Plugins. One part of the Activator is specific for widget plugins, namely how a DojoModule is defined. The DojoModule Java class is used to register the client-side component in XperienCentral to define where to find its client-side code when loading it and to access language-specific strings. Consider the following code snippet:

...

        // Add the sidebar widget
        widgetDefinition.setDojoModules(new DojoModule[]{getSidebarModule()});

languageResource.js Files

The languageResource.js files define the conversion from technical identifiers to easy readable texts in different languages. There is one file for each supported Workspace language. The default resource file is for English and the one in the NL directory is for Dutch. If other languages are supported, they are contained in a directory which is named after the ISO 639-1 standard langugae identifier codes (SP for Spanish, FR for French, DE for German, and so forth. The same identifiers are defined in all language resource files, but the strings they refer to are translated in the different languages. The language definitions are in JSON format which is very commonly used on the internet:

...

define({
	root : {
		title : "Title:",
		urlTitle : "URL Title:",
		save : "Save",
		savedSuccessfully : "Saved successfully",
	},
	'nl' : true
});

HelloWorld.html

<div class="helloworldsidebarwidget">
  <div class="divRow">
    <div class="propertiesLabel">${i18n.title}</div>
    <div class="propertiesValue" data-dojo-attach-point="_titleNode"></div>
  </div>
  <div class="divRow">
    <div class="propertiesLabel">${i18n.urlTitle}</div>
    <div class="propertiesValue">
      <input type="text" data-dojo-type="dijit/form/TextBox" data-dojo-props="trim:true" data-dojo-attach-point="_urlTitleNode" />
    </div>
  </div>
  <div class="divRow">
    <div class="buttonRow"></div>
    <div class="propertiesValue">
      <button data-dojo-type="dijit/form/Button" data-dojo-attach-point="_saveButton">${i18n.save}</button>
    </div>
  </div>
</div>

...

The above is an example of an HTML template which is partial HTML that defines the user interface of the Sidebar widget. This HTML file, together with HelloWorld.js defines a Dojo widget. If you're not familiar with the Dojo Toolkit, see the Sidebar Widgets topic.

There is always a tag, in most cases a <div>, surrounding the rest of the HTML.

• data-dojo-type - defines the type of widget to include, for example a textbox or a button.
• data-dojo-props - contains any configuration that needs to be passed to the constructor upon instantiation (more info).
• data-dojo-attach-point - is used to refer to a given element from the JavaScript code (see _saveButton in Event handling).
• class - is used for CSS styling and to look up groups of elements from the JavaScript code.

Labels like ${i18n.urlTitle} insert the language dependent texts defined in the languageResource.js files.

HelloWorld.css

Common CSS styling of the HTML is defined in HelloWorld.html. Note that every CSS selector starts with the identifier of the plugin (Artifact ID or WCB ID). This matches the class of the top level tag in the HTML. It is important to separate the CSS of different widgets from each other and from other CSS used within XperienCentral. When you start adding your own CSS selectors, remember to always start by matching this identifier. For example:

...

.helloworldsidebarwidget {
	margin: 8px;
}

.helloworldsidebarwidget .propertiesOverview {
	display: table;
    width: auto;
}

HelloWorld.js

The HTML and this JS together form a component which is styled by the CSS. Refer to the introduction if you are not familiar with the Dojo toolkit.

Basic Dojo Class Structure

The structure of the generated Sidebar widget code (the typical Dojo file structure) is shown below. It defines a widget, which is a Dojo class. The define part defines the dependent modules in AMD format. The modules, which are Dojo classes, are mapped to variables to allow access to them. This is done by adding the variables as arguments to the function statement following the define. These variables must be in the exact same order as the module references (this is a common source of errors).

...

Prefixing a function name with an underscore (_) is a convention for telling human readers of the code that a function is private. This encapsulation is not enforced by JavaScript interpreters. Never use properties and methods of other classes which are prefixed with an underscore.

Calling the Parent (super) Constructor

When overriding methods (functions) in Dojo, you should always call the parent method unless you explicitly want to prevent it from being executed. Simply use the arguments variable as in the example below to pass on the method arguments. This is variable is available in all JavaScript functions, not only in Dojo.

...

    postCreate: function () {
      // simple super call with the same arguments.
      this.inherited(arguments);
      ...
    }

Event Handling

The implementation of XperienCentral widgets is based on events. This means the JavaScript code subscribes to events to be able to listen to and react, for example, a button being clicked or that the page shown in the content area has changed. To listen to an event, you define an event handler, which is a normal JavaScript function. The function will be called every time the event occurs.

Subscribing to an Event

The code below, extracted from the archetype shows how to connect the event handler function _updateData to the event contentItemChange and the event handler _handleSave to the click event of the button called _saveButton:

...

Finding events available for subscription for standard Dojo widgets can be done in a similar way. In HelloWorld.html you can see that the full type of the button is dijit/form/TextBox. Look this class up in the Dojo API Documentation - expand the Event Summary to see all available events.

Back to top

...

Adding the Widget to XperienCentral

Generate, build and deploy the plugin containing the "Hello World" widget in XperienCentral. In the Workspace. The widget is now available to be added to a Sidebar. Click the (+) icon on one of the sidebars and click the [Add] button for the "Hello World" widget. The "Hello World" widget will be added to the Sidebar:

Back to top

...

JSDoc

JSDoc is comparable to JavaDoc, except that it is markup for JavaScript instead of Java code. Our JSDoc documents the client side API of XperienCentral. It is delivered with each release, but it is also available online: https://api.gxsoftware.com/jsdoc. It shows a tree view and is also searchable. To find the class mentioned above, perform the following steps: Search for the class SidebarContentItemWidget. (You need to click it in the tree view after searching.) Then, expand the Event Summary. Here you see: "Content item change event that published when the current content item changes in the editor". Further you can see that the event handler takes an argument called contentItemInfo. If you look it up you find out the argument has two properties, identifier and versionIdentifier which you can access in you event handler. Here you can see how the properties are used in the handler defined in the archetype:

...

    // get the information and update the view
    _updateData: function (contentItemInfo) {
      ContentManagement.getContentItemVersion(contentItemInfo.identifier, contentItemInfo.versionIdentifier).then(lang.hitch(this, function (version) {
        this.version = version;
        // update the title in the DOM
        this._titleNode.textContent = version.title;
        // update the Navigation title in the text box
        this._urlTitleNode.set("value", entities.encode(version.urlTitle));
      }));
    }

What have we learned?

We have seen how a Sidebar widget can be generated using a specialized archetype, how to build it and how to add it to the XperienCentral Workspace. Further we have examined the different files generated to get a good understanding on what they are for. After that we explored the JavaScript code containing the actual implementation of a Sidebar widget. This hopefully has imparted enough information to understand where to start adding your own code for your specific needs.

Back to top

...

Training Resources

GX Software offers courses in developing plugins for XperienCentral. These highly recommended courses put you on the fast track to developing plugins that add custom functionality to your XperienCentral installation. For complete information, see the Training Courses topic on our corporate website.

Back to top