Development Guidelines

This topic provides guidelines and conventions for plugin development. The intention of these guidelines is to improve the overall quality of the plugin and to ensure that they are well designed, well-documented, consistent, compatible, Internationalization ready and migration ready. This topic can be used to validate plugins for plugin certification. A certified plugin must comply with many of the guidelines and conventions described. For each guideline or convention it is specified whether it is required eor recommended for a particular certification level

In This Topic

Terminology

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

Back to top

The Certification Process

The goal of certifying plugins is to improve the overall quality of all plugins, which makes it convenient for the customer, the developer of the plugin and any developer not familiar with the plugin who has to perform maintenance on it.

A summary of the plugin certification:

• Guarantees that the plugin will not conflict with other certified plugins.

• Guarantees a certain quality level in the sense of stability, compatibility, upgradability, security, performance and many other themes.

• Increases the ease of maintenance because the plugin’s source files are structured in a consistent way.

Certification Levels

For each guideline described in this document, a plugin certification level is defined. Plugin certification comes in three levels:

• Level 1 - Project specific. The plugin is fully functional for a specific XperienCentral installation but may lack documentation, localization and may require specific hardware or software. The plugin may not be suitable for running on other XperienCentral installations.

• Level 2 - Reusable. The plugin is fully functional, provides proper documentation but may require specific hardware or software as indicated in the packaged readme.md. It may lack support for localization and documentation in US English. The plugin is suitable to run on any XperienCentral installation of the version the certificate is valid for.

• Level 3 - Product ready. The plugin is fully functional, provides proper documentation and supports at least the hardware and software required by the XperienCentral platform itself. It supports localization and all documentation is available in at least US English. The plugin is of such high quality that it could be incorporated into the XperienCentral platform as is.

The table in the Guidelines Summary specifies for each guideline the plugin certification level for which the guideline is mandatory. The levels are cumulative. For certification of a particular level it is required that the plugin also conforms to all guidelines required for lower certification levels.

Guideline Versions

These plugin development guidelines are subject to change. Occasionally, new guidelines are added, old guidelines are removed or existing guidelines are updated for various reasons. Updates to these guidelines are always effective as of the next available version of XperienCentral. The guidelines are fixed for XperienCentral certification. A certificate will always mention the XperienCentral version for which the certificate has been granted, indicating the exact version of the guidelines against which it was verified. Note that the guidelines are also occasionally updated with textual improvements.

Plugin Version Updates

A plugin audit is performed on a particular version of a plugin, for example the 1.1.0 version. This version is referred to as the "plugin audit version". After the plugin audit, new versions of the plugin may become available.In a micro version update (for example from version 1.1.0 to 1.1.1), it is unlikely that a code change could lead to a guideline violation. If it did, that it would be a guideline violation since micro version updates should only contain micro software changes. The same partially applies to minor version updates. It would still be rather unlikely that a minor version update would violate a guideline. A major version update, however, could contain major refactoring or major functional enhancements which could mean that the plugin has to be recertified. For that reason GX Software stipulates that a plugin certification level is only valid until the next major version of the plugin . For example, if version 1.1.4 of a plugin has been certified at level 2, then each 1.1.x version, where x >= 4, as well as each 1.y.z version, where y >= 2, will also be certified at level 2. We refer to the range between the first certified version and the version from which the certificate will expire the "plugin certification range.

Preaudit

A plugin audit tool is available that automates and supports plugin audits. Running this tool to verify a plugin is called a pre-audit. Running a pre-audit is required before a plugin audit is requested. If the pre-audit results in one or more guideline violations which the developer of the plugin believes to be invalid, the developer should indicate this in the audit request.

Plugin audit report

A plugin audit report contains four important results:

• The version of the plugin that has been audited.

• The assigned certification level (if applicable) for the plugin (the plugin certification level).

• The XperienCentral version for which the certificate is valid.

• The range of plugin versions for which the certificate is valid (the plugin certification range).

For example:

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

1. GUI guidelines for the Editor - Guidelines to design consistent and user-friendly User Interfaces for the XperienCentral Editor. These guidelines do not apply to the GUI of the website environment.

2. Architecture - The architectural design patterns that the plugin should comply with. Design patterns contribute to software quality in many ways; future compatibility, plug ability, extendibility and synoptic code.

3. Migration - These guidelines deal with software upgrades. Conforming to these guidelines will guarantee a smooth migration from older to newer versions of the plugin.

4. Internationalization - All plugins must be ready for internationalization. This must be taken into account when designing the software. The XperienCentral platform offers support for internationalization.

5. Documentation - Since plugins are small software components that may be reused in other projects than they were originally intended for, it is important that proper user documentation is available.

6. Distribution - These guidelines define how a plugin should be packaged and distributed. They cover the contents of a plugin release and how they should be packaged.

7. Quality - These guidelines cover the stability and compatibility of the plugin with web browsers, web servers, application servers and databases.

8.  DTAP support - The plugin must be designed to support the DTAP model.

9. Security - The security guidelines define rules that must be followed in order to ensure that the plugin is a secure web application. This prevents common security errors like the enabling of SQL injection and cross-site scripting.

10. API - A plugin may expose an API in the form of implementation classes, interfaces and constants. These guidelines describe how such an API should be exposed by a plugin.

11. Coding conventions - Conforming to coding conventions contributes to readability of the software code. This makes it easy to read, easy to learn and will prevent bugs.

12. Javadoc - A proper Javadoc is very important for software developers coding against the API exposed by the plugin. If a plugin is extendable, it is very important that its API is well documented.

13. Naming conventions - For readability and maintainability of the software code, it is always a good idea to define the conventions used to name particular methods and classes.

Guidelines versus Conventions

Conventions are a specific type of guidelines: they describe proper naming or the way software code or documentation should be written. A convention is very specific and easy to validate against. A guideline is a more abstract definition and harder to validate.

Guideline Overview

This part contains an overview of all guidelines and conventions defined in this topic. The tables below define which guidelines and conventions are required for which plugin certification levels. The table also indicates a scope. The scope indicates to which part of the plugin the guideline applies. This may be only one particular component, a set of components or the plugin as a whole.

The following abbreviations are used in the table summary:

Back to top

Guidelines Summary

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.