Page History

...

...

Terminology

This topic uses the following acronyms. The meaning of each one is described below. 

...

Back to top 

...

The Certification Process

...

• Version of the audited plugin : 1.1.4
• Assigned plugin certification level: 2
• Certified on XperienCentral version: 10.8
• Plugin certification range: 1.1.4 to 2.0 (but not including 2.0)

...

Back to top 

...

Guidelines Overview

This document describes the guidelines and conventions for plugin development. These are divided into the following themes:

...

The following abbreviations are used in the table summary: 

Back to top 

...

...

The table below summarizes all the guidelines. Because the guidelines have evolved over time, some IDs have been removed, therefore the sequential order skips numbers in some places. If the column "Certification Level" is blank, this means that the guideline is not required for any certification level and is only a recommendation. Most of the guidelines are discussed in greater length following the table below. 

Back to top 

...

GUI Guidelines for the Editor

...

Developed plugins should apply this design pattern to be flexible, pluggable and extendable themselves. The figure below shows the abstraction layers in XperienCentral: 

In the approach depicted above, there is a very clean separation of responsibilities by the several application layers as also depicted below: 

The layers also conform to the MVC pattern in which a controller determines the model and returns the view to render the model.

...

• The business object is implemented as a POJO and does not contain any reference to a controller, form backing object or DAO. However, It may contain service references or references to other business objects [G007].
• The business object does not contain properties or logic whose only purpose is the view [G008]. An example violating this guideline would be defining a property like "selectedBook" that is not persisted but only temporarily stores the user selection in the view.
• The FormBackingObject is implemented as a POJO and does not have any reference to a controller, DAO or business object, unless the business object is a POJO itself. It may contain references to other FormBackingObjects. [G009].
• The FormBackingObject reflects the properties and logic to be rendered by the view and not the properties and logic of the business object from which it retrieves values. [G010].
• The FormBackingObject and the business object are not one and the same object [G011].
• Use the copyProperties() method of org.springframework.beans.BeanUtils to transfer values from the FormBackingObject to the business object and vice versa [G012].
• The controller is a separate class (not mixed with business object and/or FormBackingObject) and it implements all controller logic such as creating, updating and deleting FormBackingObjects, business objects and the views [G013].
• Persistence logic is not contained by the business object but is instead implemented in a separate DAO [G014]. It is recommended that you use the Entity Manager (a DAO implementation that currently supports only the JCR) available from XperienCentral.10.3 and later [G125]. Note that the current XperienCentral API does not yet support this for element business objects. For all other cases, this is the preferred way.
• JSPs do not contain SQL statements or other persistence implementation specific logic, except for those with scope Query or DatabaseEntity. If you have to use SQL in a JSP, separate it by including the SQL statement in a separate JSP tag [G015].

...

Plugin Completeness

A plugin is intended to be an individual component that contains all resources (like images, Java code and XML files) that contribute to the functionality of that plugin. If the proper working of a plugin requires, for example, a change to the web.xml of the web application, this breaks the one-click deployment concept of a plugin. A plugin must be capable of being deployed on any XperienCentral installation and work properly as long as all its dependencies are available [G016]. Note that the plugin may depend on presentation files contained by another plugin for level 1 certification, but for level 2 certification, it is required you add to add at least a working example presentation to the plugin [G153].

...

Writing readable code contributes to the maintainability of the software code and makes the software less error-prone since it easy to understand what the code does and/or is supposed to do. For determining an objective measurement of software complexity the so called Cyclomatic Complexity Number can be determined. A definition of the CMU-SEI interpretation of this number can be found at https://en.wikipedia.org/wiki/Cyclomatic_complexity. It is recommended that the CMU-SEI of the software does not exceed 15 [G107]. 

Back to top 

...

Migration Guidelines

Versioning

...

Plugins that use a service must define a service dependency with this service in the component definition in order to retrieve a reference to the service [G023]. For example:

ComponentDependencyImpl serviceDependency = new ComponentDependencyImpl();
serviceDependency.setServiceName(BookService.class.getName());
serviceDependency.setRequired(true);
elementDefinition.setDependencies(
  new ComponentDependency[]{serviceDependency});  

Back to top 

...

Internationalization Guidelines

...

Language labels should be defined in language resource files conforming to JavaI18N. The name of these language files conforms to the syntax [G026]: 

messages_<language>_<country>_<variant>.properties

The language file contains the language labels used throughout the entire plugin but its scope is limited to that plugin. Using the same language labels in different plugins will not cause conflicts. It is recommended that you use only lower case letters for the label ID [G027] and that you group the language labels per component and prefix them with at least the ID of the component [G028]. All labels with an ID prefixed by panel.button are reserved by the framework for retrieving language labels for panel buttons - it is recommended that you group these labels separately [G127].

For example, if a plugin has three components with IDs reviewelement, reviewmediaitem and maintenancepanel, the US English resource file might look like this: 

// Framework labels
panel.button.apply=Apply
panel.button.close=Close
panel.button.ok=OK

// Labels for review element
reviewelement.menuitem=Books review element
reviewelement.headertitle=Books review element
reviewelement.title=Title
reviewelement.frontcover=Front cover

// Labels for review media item
reviewmediaitem.bookreview=Book review
reviewmediaitem.metadata=Metadata
reviewmediaitem.quote=Review quote
reviewmediaitem.select=Select

// Labels for maintenance panel
maintenancepanel.books=Books
maintenancepanel.reviewers=Reviewers
maintenancepanel.genres=Genres

Back to top 

...

Documentation Guidelines

This part provides guidelines for documentation to be distributed among with the plugin.

...

Documentation should be available in at least US English [G034]. 

Back to top 

...

Distribution Guidelines

A plugin is distributed as a single ZIP file, called a WCA (WebManager Component Archive) which can also contains other related plugins [G035]. The WCA contains the compiled plugins as JAR files, corresponding documentation and (optionally) the source code. The WCA contains the following directory structure [G036]:

...

/configuration - Contains configuration files like metatype files for Configuration Management. 

...

Back to top 

...

Quality Guidelines

In order for GX Software to be able to effectively monitor adherence to the quality guidelines, a quality assurance report must accompany a plugin that is submitted to GX Software for certification. This report must detail various subjects in order for certification to be able to take place. Please note that the discussion of the plugin quality guidelines will be kept in relatively general terms because an exhaustive treatment thereof would not be practical given the goal of this part. Similarly, the methods for validating adherence to the quality guidelines will also only be discussed in general terms.

...

Each plugin should come with a unit test or test bundle that has a code coverage of at least 10% [G120]. 

Back to top 

...

DTAP Guidelines

DTAP is an abbreviation of Development, Test, Acceptance and Production. These terms refer to the environments on which the software will be installed, starting on a development environment it will be installed next onto the test environment. When development and bug fixing is finished it is installed onto an acceptance environment to be tested by the customer. Finally if the software component is accepted, it will be installed onto the production environment.

...

For persisting preferences for a plugin, use the Preferences Service offered by the XperienCentral platform [G047]. This ensures a proper distribution and maintenance of preferences in multiple environments as applicable for the DTAP model. Note that preferences are properties that are maintained by the software and are read-only for the end-user.

Back to top 

...

Security Guidelines

Web applications such as XperienCentral operate in a hostile environment. Over the last few years many powerful and extremely common types of security flaws have been found in web applications. It is an unfortunate truth that security flaws are very easy to introduce into an application. This part provides some basic guidelines for avoiding some common security errors when developing plugins. It is advised that every web developer at least be aware of the Open Web Application Security Project (OWASP) and its top ten list of security vulnerabilities for web applications. The list is updated each year and is located here: https://www.owasp.org/index.php/OWASP_Top_10. 

...

Escape Input from the User

Outputting user supplied data without correctly escaping it for HTML or XML can be exploited for Cross Site Scripting (XSS) attacks. Use the output-html-encoded-quotes XSLT template to properly HTML escape strings in the output when using XSLT [G048].

<xsl:call-template name="output-html-encoded-quotes">
<xsl:with-param name="text" select="$mystring"/>
</xsl:call-template>

...

In JSP, use standard JSTL functions (like escapeXML()) to properly escape strings in the HTML output [G123]:

<%@ taglib uri="http://java.sun.com/jsp/jstl/functions" prefix="fn" %>
${fn:escapeXml(user.name)}

...

Use SQL Prepared Statements

SQL injection is a way to abuse poorly programmed SQL statements in order to execute statements that the developer did not foresee. Consider the following example of a badly programmed SQL query: 

// Bad SQL query vulnerable to SQL injection
String query = "select count(*) from users where name=' + name + "' and password='" + password + "'";

...

If the name and password are directly passed from the posted form onto this query, the query will be vulnerable to SQL injection. If the user would enter username and password: 

username=’ or 1=1 or name='
password=’ or 1=1 or password='

...

The query would always return 1. SQL injection can be easily prevented by using prepared statements instead. Prepared statements prevent SQL injection by automatically escaping the input. For this reason it is recommended that you use prepared statements in all cases. See java.sql.PreparedStatement [G049].

...

All content must be stored in the JCR [G045]. This of course also applies to files. Files can be stored in the JCR in two ways; public and non-public. Public files are copied to all web servers in the production environment and are thus accessible by anyone who visits the website. Non-public files are handled by the application server only and support custom authorization on file downloads. 

Back to top 

...

API

A plugin may expose an API containing interfaces, implementation classes, constants, etc. To ensure consistency over all APIs exposed by all plugins, this part describes which guidelines to which such an API should conform.

...

Any class or interface that is exposed by a plugin as API should be contained by a package called "api” directly under the plugins root package or by a sub package of this package [G118]. Because of guideline [G090], the full package name of this API package will be: 

<domain>.<plugin ID>.api

...

Back to top

...

Presentation Plugins

Presentation plugins differ in in many ways from other plugins. They contain the actual representation of the website as a whole and thus presentations (in JSP) of several components deployed from several plugins. They overrule presentations defined by the plugins themselves, which should be considered example presentations. A presentation plugin usually is customer-specific - it contains the presentation of that customer’s website. For that reason, separate guidelines are applicable for presentation plugins. A presentation plugin must be self-sufficient - it should not depend on any resource (JSP, CSS, etc.) provided by another plugin unless this presentation is a plugin itself [G137]. If a presentation plugin depends on presentation JSPs that are part of the original XperienCentral platform, these JSPs should be copied to the presentation plugin in the directory /src/main/resources/presentationtype/jsp/wm [G138]. Note that the guidelines mentioned in the remainder of this part do not apply to these JSPs.

...

Finally, implement caching properly by providing SSIs [G144]. 

Back to top 

...

Coding Conventions

This part describes the recommended coding conventions for XperienCentral development. These conventions are based on Sun’s coding conventions but additional XperienCentral specific conventions apply. G055 covers Sun’s coding conventions, all other conventions in this chapter are XperienCentral specific.

...

The use of a basic variant of the Hungarian notation is encouraged. It is recommended that you prefix instance variables with “my”. For example: 

// Correct
private String myTitle;

// Incorrect
private String title;

...

Use of blank space is discouraged before and after a method argument but it is mandatory after Java keywords and commas. For example:

// Correct
public void makeItSo(String action, String expression){
    if (check(expression)) {
        makeItSo(action);
    }
}

// Incorrect
public void makeItSo( String action , String expression ) {
    if(check(expression)) {
        makeItSo(action);
    }
}

...

It is recommended that you use the comment “FIXME” in the source code to indicate that the implementation is incorrect. It may be used, for example, to indicate that the code snippet fails in some cases or that it is a workaround for another issue. It is also recommended that you add the name of the developer that added the FIXME to the code.  For example: 

// FIXME (ivol): this won't work if myNumber equals 0
public String getProperty();
    return 1/myNumber;
}

...

It is recommended that you use a TODO in the code if the code snippet works but is not yet finalized. It is also recommended that you add the name of the developer that added the TODO to the code. For example:

public int doComplexCalculation();
    // TODO (ivol): must be implemented, return 0 for now
    return 0;
}

...

It is recommended that you add start brackets on the same line as the statement to which they apply and to add ending bracket on a new line. For example:

...

// Correct
public void makeItSo() {
    if (isTrue) {
        doSomething();
    }
}

// Incorrect
Public void makeItSo() 
{
    if (isTrue) 
    {
        doSomething();
    }
}

...

It is recommended that you use brackets in all cases, even for single line statements. For example:

...

// Correct
if (expression) {
    doSomething();
}

// Incorrect
if (expression) doSomething();
if (expression) 
    doSomething();

...

Instance Variable Access [G148]

Instance variables should always be private and provided by accessor methods (getter and setter). Using private instead of public and protected instance variables prevents tight code coupling between the class and classes from other plugins that use this class. 

Back to top 

...

Javadoc Conventions

This part describes the recommended Javadoc conventions for XperienCentral development. These conventions are based on Sun’s Javadoc conventions. Additional XperienCentral specific conventions are also explained below.

...

The Javadoc should clearly explain how the class or interface should be used, preferably by using code examples [G132]. For each package contained by the plugin, a package.html should be provided that clarifies the purpose and contents of the package [G133]. 

Back to top 

...

Class Name Conventions

For consistency of the source code of all plugins, it is important to define naming conventions. This makes the plugin easy to read and maintain for developers since the same classes will be named the same way in each plugin. This part defines naming conventions for Java classes.

...

For general classes (classes that are not directly related to a particular component implementation) used in plugins, the following naming convention for the Java classes are recommended [G076]. Note that <name> indicates a custom name defined by the developer. 

Element Components

For element components, the following naming convention for the Java classes are recommended [G077]. Note that <name> indicates a custom name defined by the developer like ‘review’ or ‘webshop’. 

...

To properly use the API for element components offered by the XperienCentral platform, it is recommended that you use the following hierarchy for the classes contained by an element component [G078]: 

...

Media Item Components

For media item components, the following naming convention for the Java classes are recommended [G079]. Note that the difference between a media item and a media item version is that a media item has one or more versions. The implementation of the media item itself is not contained by a media item component but by the implementation of the media item version. Again, <name> indicates a custom name defined by the developer like "article" or "movie". 

...

To properly use the API for element components offered by the XperienCentral platform, it is recommended that you use the following hierarchy for the classes contained by a media item component [G080]: 

...

Panel Components

For panel components, the following naming convention for the Java classes are recommended [G081]. In the table below, <name> indicates the name of the panel as a whole while <tab> indicates the name of one particular (horizontal, vertical or sub) tab within that panel. 

To properly use the API for element components offered by the XperienCentral platform, it is recommended that you use the following hierarchy for the classes contained by a panel component [G082]: 

Back to top 

...

ID Naming Conventions

Because the ecosystem of plugins will cause a rapidly increasing number of available plugins developed by many different companies, unique identifiers are necessary to prevent conflicts between plugins. This part describes the guidelines for which identifiers defined by a plugin should conform to in order to prevent such conflicts.

...

A plugin consists of one or more components. The activator of a plugin defines what component a plugin contains by defining one component bundle definition which registers one or more component definitions. The ID of the component bundle definition defined in the activator of the plugin must follow the following syntax [G097]:

<domain>.<plugin ID>

...

The ID of each component definition contained by the plugin must be prefixed with the component bundle definition ID followed by an ID that is unique within the plugin and must match the component name and consist of lowercase alphanumeric characters in the range [a-z] [G098]. We refer to this unique ID within the plugin as the component ID and the component definition ID conforms to the syntax: 

<domain>.<plugin ID>.<Component ID>

...

For media Item components, the content type (defined by the @ContentType annotation in the media Item version implementation class) must equal the plugin ID or be prefixed by the plugin ID and may only contain alphanumeric characters in the range [a-z] [G124].

...

The package names used by the plugin must conform to the Java standard as also stated in the Java coding conventions by SUN [G089]. The top level package name must meet the following syntax [G090]: 

<domain>.<plugin ID>

...

This part provides an overview of the recommended naming conventions as described above. An additional guideline is that all these properties may use only lowercase letters [G099]: 

...

RBAC Naming

Each plugin defines at least one RBAC category which may contain one or more RBAC permissions. The technical naming of all RBAC categories and permissions must be unique in order to avoid collisions across multiple plugins. For this reason, the technical name of each RBAC category must conform to the syntax <domain>.<plugin ID>.<Component ID> [G101]. Furthermore, the technical name of each RBAC permission must be prefixed with the technical name of the RBAC category, followed by a dot [G102]. All technical names of categories and permissions must be lowercase, may not contain spaces and separate words must be separated by a dot [G103].

...

This part provides an example for using proper naming conventions: 

...

When writing documentation or online help for plugins, it is recommended that you use the following guidelines regarding naming of XperienCentral assets [G105]: 

...

The language to be used for all names, codes, Java classes, methods, properties, etc. is US English [G106]. A different language may only be used if, and only if, it represents a piece of text that is displayed to the end user and may require translation.

Back to top