...
Term | Description |
---|---|
POJO | A Plain Old Java Object. This refers to a basic Java class not implementing or extending any special class(es). |
MVC | Model-View-Controller. A design pattern used to separate the business model, business logic and UI logic. |
Spring MVC | The web application framework used by XperienCentral to render the Editor. |
DAO | Data Access Object. An object that encapsulates all access to a particular data source. It is used to prevent a business object from having dependencies with a particular persistence implementation. |
DTAP | Development Test Acceptance and Production. |
JCR | Java Content Repository. |
RBAC | Role Based Access Control. |
FBO | A FormBackingObject , which is an object that represents the data contained by an HTML form. |
Plugin audit | The process of verifying a plugin against the plugin development guidelines and granting a particular certification level. |
Plugin certification level | A level that indicates the extent to which the plugin conforms to the plugin development guidelines. The higher the certification level, the more the plugin conforms to the defined guidelines. |
Plugin certification range | The range from the first certified plugin version to the first major version of the plugin for which the current plugin certification level will not be valid anymore and a new plugin audit will be required. |
Guideline scope | The software component(s) or component type(s) to which the guideline applies. |
Pre-audit | The act of running the plugin guideline audit tool to verify your plugin against a basic subset of guidelines. |
...
The Certification Process
...
- 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.txtmd
. 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.
...
- 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)
...
Guidelines Overview
This document describes the guidelines and conventions for plugin development. These are divided into the following themes:
...
Scope | Description |
---|---|
A | The guideline applies to all component types or to the plugin or WCA as a whole. |
P | The guideline applies to panel components. |
E | The guideline applies to element components. |
M | The guideline applies to media item components. |
C | The guideline applies to service components. |
D | The guideline applies to page metadata components. |
L | The guideline applies to servlet components. |
R | The guideline applies to presentation components. |
F | The guideline applies to form components. |
V | The guideline applies to profile provider components. |
...
Anchor | ||||
---|---|---|---|---|
|
...
Guideline ID | Description | Certification Level | Scope | ||||||
---|---|---|---|---|---|---|---|---|---|
G001
| The HTML rendering the UI conforms to the basic layout using a table of class | 1 | PEMDV | ||||||
G002
| The HTML rendering the UI uses only the defined CSS classes. | 3 | PEMDV | ||||||
G003
| The UI conforms to the basic guidelines. | 2 | PEMDV | ||||||
G004
| The UI uses the widgets supported by the XperienCentral platform. | 2 | PEMDV | ||||||
G005
| The JSPs that render the HTML use the JSTL tags and JSP tags offered by the XperienCentral platform as often as possible. | 2 | PEMDV | ||||||
G006
| The UI conforms to the defined UI interaction patterns. | 2 | PEMDV | ||||||
G007
| The business object is implemented as a POJO and does not contain any reference to a controller, form backing object or DAO. | 1 | PEMDV | ||||||
G008
| The business object does not contain properties or logic whose sole purpose is the view. | 1 | PDV | ||||||
G009
| The | 1 | PEMDV | ||||||
G010
| The | 1 | PEMDV | ||||||
G011
| The | 1 | PEMDV | ||||||
G012
| The | 3 | PMDV | ||||||
G013
| The controller is a separate class and implements all controller logic. | 1 | PEMD | ||||||
G014
| Persistence logic is not contained by the business object but implemented in a separate DAO. | 1 | PEMDV | ||||||
G015
| JSPs do not contain SQL statements or other persistence implementation-specific logic unless they are contained by a separate JSP tag. | 1 | PEMDRV | ||||||
G016
| The plugin contains all resources not provided by dependencies or other presentation plugins and is capable of being deployed and functioning properly on any XperienCentral installation, as long as all its defined dependencies are available. | 1 | A | ||||||
G017
| The version number of a plugin conforms to the syntax "major.minor.micro". | 1 | A | ||||||
G019
| The version numbers of the plugin are independent of the XperienCentral release they were developed for. | 1 | A | ||||||
G020
| If the data model of the plugin has been changed in a newer version of the plugin , the plugin must properly handle data model updates. | 2 | PEMDV | ||||||
G021
| The API that XperienCentral provides is used to access the data model XperienCentral exposes. | 1 | A | ||||||
G022
| XperienCentral features and API functions are used where possible instead of implementing custom functions. | 1 | A | ||||||
G023
| When the plugin uses a service, a dependency with that service is defined in the component definition in order to retrieve a reference to the service. | 1 | A | ||||||
G024
| Text, images and other GUI components are suitable for translation. | 3 | PEMCDV | ||||||
G025
| Multilingual content that can be created using the plugin is translatable. | PEMCDLFV | |||||||
G026
| Language labels are defined in language resource files conforming to JavaI18N and the filename meets the syntax | 1 | PEMCDLFV | ||||||
G027
| Label IDs in the language resource files use only lower case letters. | 1 | PEMCDLFV | ||||||
G028
| Language labels in language resource files are grouped per component and prefixed with at least the ID of the component. | PEMCDLFV | |||||||
G034
| Documentation is available in at least the US English language. | 3 | PEMDFV | ||||||
G035
| A plugin is distributed as a single ZIP file known as a WCA (WebManager Component Archive) which can also contain other related plugins. | 1 | A | ||||||
G036
| The contents of the WCA conforms to the defined directory structure. | 2 | A | ||||||
G037
| The WCA contains a | 1 | A | ||||||
G038
| The layout of the | 1 | A | ||||||
G039
| The plugin JAR file containing the software follows the defined directory structure. | 1 | A | ||||||
G042
| The HTML generated by the JSPs for rendering the Editor is XHTML 1.0 transitional compliant. | 3 | PEMDV | ||||||
G045
| All content generated by the plugin is stored in the JCR or in an external database if there is an obvious need for it. | 1 | PEMCDLFV | ||||||
G046
| The configuration management service is used to store configuration options. No hard-coded web IDs, paths or URLs are used in the software. | 1 | PEMCDLFV | ||||||
G047
| The preferences service is used to store all preferences. | 1 | PEMCDLFV | ||||||
G048
| The | 1 | PEMDRV | ||||||
G049
| SQL-prepared statements are used for all SQL queries. | 1 | A | ||||||
G050
| At least one RBAC category is defined for each component which has a GUI representation which contains one or more RBAC permissions for the component. | 2 | PEDV | ||||||
G051
| A permission category defines and implements at least the RBAC permissions as defined. | 2 | PEV | ||||||
G052
| The implementation of RBAC permission handling is mainly programmed in a controller or service, not in the business object itself. The check is only performed in the business object itself if the permission defines authorization to retrieve or update that particular property only. | 2 | PEMDV | ||||||
G053
| The definition of all RBAC permissions is positive. Permissions are defined in a way that assigning the permission to a role grants the role particular rights and it never denies rights. | 1 | PEMDV | ||||||
G055
| Coding conventions: the coding conventions that Sun publishes as the standard for the Java programming language are followed. | A | |||||||
G056
| Coding conventions: Java language features are used where applicable (Java version 5 and higher). | 3 | A | ||||||
G057
| Coding conventions: | 1 | A | ||||||
G058
| Coding conventions: Java concurrency utilities are used where applicable (Java version 5 and higher). | 3 | A | ||||||
G059
| Coding conventions: old collections like | 1 | A | ||||||
G060
| Coding conventions: the | A | |||||||
G061
| Coding conventions: The basic variant of the Hungarian notation is used. | A | |||||||
G063
| Coding conventions: The source code does not contain blank spaces before and after method arguments, however, spaces are used after Java keywords and commas. | A | |||||||
G064
| Coding conventions: Declare variables and methods in the following order: Class (static) variables, instance variables, constructors, methods. | A | |||||||
G067
| The FIXME comment is used to indicate that code snippets are incorrect during development and do not appear in a released plugin. | A | |||||||
G068
| The TODO comment is used to indicate that code snippets are incomplete during development and do not appear in a released plugin. | A | |||||||
G069
| Coding conventions: Spaces are used instead of tabs for trailing white space in the source code. | A | |||||||
G070
| Coding conventions: The size of one line in the software code is limited to 120 characters. | A | |||||||
G071
| Coding conventions: Start brackets are added on the same line as the statement to which they apply but ending brackets appear on a new line. | A | |||||||
G072
| Coding conventions: Brackets are used in all cases, even for single line statements. | A | |||||||
G073
| Coding conventions: The source code conforms to Javadoc conventions defined by Sun. | 2 | A | ||||||
G074
| Coding conventions: Public and protected classes, interfaces, variables and methods are tagged with Javadoc. | 2 | A | ||||||
G075
| The Javadoc does not contain references to documents that might not be accessible by external developers. | 3 | A | ||||||
G076
| General plugin classes conform to the defined naming conventions. | 1 | A | ||||||
G077
| Element component classes conform to the defined naming conventions. | 1 | E | ||||||
G078
| Element component classes conform to the defined hierarchy. | 1 | E | ||||||
G079
| Media Item component classes conform to the defined naming conventions. | 1 | M | ||||||
G080
| Media Item component classes conform to the defined hierarchy. | 1 | M | ||||||
G081
| Panel component classes conform to the defined naming conventions. | 1 | P | ||||||
G082
| Panel component classes conform to the defined hierarchy. | 1 | P | ||||||
G083
| The domain used for naming is returned by | 1 | A | ||||||
G084
| The plugin ID is returned by | 1 | A | ||||||
G087
| The prefix equals the plugin ID. | 1 | A | ||||||
G089
| Package names used in the source code of the plugin conform to the package naming guidelines as defined by the Sun coding conventions. | 1 | A | ||||||
G090
| Top level Java package names follow the syntax | 1 | A | ||||||
G095
| The artifact ID in the | 1 | A | ||||||
G096
| The group ID in the | 1 | A | ||||||
G097
| The ID of the component bundle definition defined in the activator of the plugin conforms to the defined syntax. | 1 | A | ||||||
G098
| 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, matches the component name and consists of lower case alphanumeric characters in the range [a-z]. This does not include the media item component definition. | 1 | A | ||||||
G099
| All IDs and properties defined use only lower case letters. | 1 | A | ||||||
G101
| The name of the RBAC category conforms to the syntax | 1 | PEMCDLFV | ||||||
G102
| The technical name of each RBAC permission is prefixed with the technical name of the RBAC category, followed by a dot. | 1 | PEMCDLFV | ||||||
G103
| Technical names of categories and permissions are in lower case, do not contain spaces and separate words are separated by a dot. | 1 | PEMCDLFV | ||||||
G104
| For CRUD actions, the defined naming conventions are used. | 2 | PEMCDLFV | ||||||
G105
| In user documentation, the defined naming conventions are used for XperienCentral assets. | 3 | A | ||||||
G106
| All names of labels, Java classes, methods, properties, etc. are in US English unless they represent translatable labels presented to the end user. | 1 | A | ||||||
G107
| The CMU-SEI (https://en.wikipedia.org/wiki/Cyclomatic_complexity) does not exceed 15. | 3 | PEMCDLFV | ||||||
G108
| Online help covering the visible components contained by the plugin is available. | 2 | PEMDV | ||||||
G109
| An API is exposed by a domain object interface when it consists of getters and setters for properties of that domain object. | 1 | PEMCDLFV | ||||||
G110
| Implementations of a domain object interface is postfixed with "Impl". | 2 | PEMCDLFV | ||||||
G111
| An API is exposed as a service when the API creates or deletes domain objects or operates on multiple domain objects. | 2 | PEMCDLFV | ||||||
G112
| An API service managing entities is preferably postfixed with "ManagementService". | 3 | CV | ||||||
G113
| A method handles an exception internally if it is recoverable. | 2 | A | ||||||
G114
| A method throws a checked exception if it is unrecoverable and occurs in an area outside the immediate control of the program. | A | |||||||
G116
| Identifiers used by a plugin are defined in one class as public static final fields of that class. | 3 | A | ||||||
G117
| A plugin exposes its identifiers by exposing the class as defined by guideline G116. | 3 | A | ||||||
G118
| Any class or interface that is exposed by a plugin as API should be contained by a package called "api" directly under the plugin's root package, or by a sub package of this package. | 2 | A | ||||||
G119
| If content is stored in an internal relational database, the SQL scripts to create those database tables should be contained by the plugin in a | 2 | A | ||||||
G120
| Each plugin should come with a unit test or test bundle that has a code coverage of at least 10%. | 3 | PEMCDLFV | ||||||
G121
| The plugin ID only contains alphanumeric characters in the range [a-z]. | 1 | A | ||||||
G122
| The domain only contains alphanumeric characters in the range [a-z] separated by dots. | 1 | A | ||||||
G123
| In the JSPs, properly escaped strings in the HTML are output using standard JSTL functions. | 1 | PEMDRV | ||||||
G124
| The | 1 | M | ||||||
G125
| Use the Entity Manager as the DAO implementation to store entities in the JCR when possible. | PEMCDLF | |||||||
G126
| Creating and removing resources on which a plugin depends should be done automatically upon installation and purging the plugin if possible. | 1 | A | ||||||
G127
| Framework labels are grouped separately in the language resource files. | PEMCDLFV | |||||||
G128
| Language files are at least available in US English. | 2 | PEMCDLFV | ||||||
G129
| A method should not catch an unchecked exception if it is unrecoverable and occurs in an area inside the immediate control of the program. | 1 | A | ||||||
G131
| A new checked exception type is used as the wrapper for multiple checked exceptions if the amount of thrown checked exception exceeds five. | 2 | A | ||||||
G132
| The Javadoc clearly explains how the class or interface should be used, preferably by providing code examples. | 2 | A | ||||||
G133
| For each package contained by the plugin, a | A | |||||||
G134
| HTML generated by the JSPs for rendering the website environment should be XHTML 1.0 transitional compliant. | 3 | R | ||||||
G135
| If a method of a class implements a method of an interface, refer to the Javadoc of the interface using the | 2 | A | ||||||
G136
| The | 1 | A | ||||||
G137
| The presentation plugin is self-sufficient and does not depend on any resource provided by another plugin unless it is another presentation plugin . | 1 | R | ||||||
G138
| JSPs copied from the original XperienCentral platform presentation are copied to the specified directory. | 1 | R | ||||||
G139
| The value of the name attribute in the descriptor of a JSP is prefixed by the plugin ID. | 1 | R | ||||||
G140
| Static files used by the presentation plugin are located in a subdirectory that equals the plugin ID. | 1 | R | ||||||
G141
| The software does not contain code snippets that are commented out, not used or that duplicates of other code snippets in the same plugin . | 2 | A | ||||||
G142
| Media item JSPs that display the content of a media item contain a check to see whether the media item has not already been rendered before within the same request. | 1 | MR | ||||||
G143
| Use the | 1 | PEMDRV | ||||||
G144
| Implement caching properly by providing SSIs. | 1 | PEMDRV | ||||||
G145
| A plugin contains only those components that logically belong to each other. | 1 | R | ||||||
G147
| The plugin does not contain the empty online help that was generated by the archetype. | 1 | A | ||||||
G148
| Do not use public or protected instance variables. Use private instance variables with getters and setters instead. | 1 | A | ||||||
G149
| The plugin ID and domain are approved by GX and the plugin (of this version) is registered. | 1 | A | ||||||
G151
| The name of a scheduled job is prefixed by the plugin ID. | 1 | C | ||||||
G152
| The ID of each configuration set defined by the plugin is prefixed by or equals the plugin ID. | 1 | A | ||||||
G153
| The plugin contains an example frontend presentation if it requires such a presentation to work properly. | 2 | EMDFV | ||||||
G154
| The plugin supports the software and hardware as described in Hardware and Software Requirements. | 2 | A |
...
GUI Guidelines for the Editor
...
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].
...
Migration Guidelines
Versioning
...
- The plugin supports automatic data model conversion.
- The plugin states specifically in the
thatreadme.txt
that the data model has been changed and that the new version of the plugin is not compatible with the previous version.md
...
Code Block | ||
---|---|---|
| ||
ComponentDependencyImpl serviceDependency = new ComponentDependencyImpl(); serviceDependency.setServiceName(BookService.class.getName()); serviceDependency.setRequired(true); elementDefinition.setDependencies( new ComponentDependency[]{serviceDependency}); |
...
Internationalization Guidelines
...
Code Block | ||
---|---|---|
| ||
// 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 |
...
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].
...
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]:
...
/content
- Contains all content needed by the plugin.
- A text file without markup that contains a full history of all issues that have been fixed after the first release of the WCA (stored in the root of the WCA [G035]) It should be properly filled in..changelog.txtmd
- A text file without markup that contains list of new features in the latest version of the WCA, list of hardware & software requirements, license statement and known issues (stored in the root of the WCA [G035]) It should be properly filled in.readme.txtmd
...
Note |
---|
A plugin should contain only components that logically belong to each other [G145]. |
...
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.
...
For each XperienCentral release, the Hard and Software Requirements is updated which describes the hardware and software on which XperienCentral is supported. The plugin should be compliant with these requirements [G154].
...
Each plugin should come with a unit test or test bundle that has a code coverage of at least 10% [G120].
...
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.
...
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.
...
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.
...
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.
...
Code Block | ||
---|---|---|
| ||
<domain>.<plugin ID>.api |
...
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].
...
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.
...
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.
...
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].
...
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.
...
Java class name | Extends | Implements |
---|---|---|
<name>Panel |
| |
| SimplePanelComponent | |
<name>PanelController |
|
...
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.
...
Property | Example |
---|---|
Editor | The XperienCentral application in which editors maintain the content to be published on the website or another medium. |
Website environment | A presentation of (a part of) the content maintained by XperienCentral, usually a website. |
Standalone | The mode in which XperienCentral content is served from only one application server. |
Clustered | The mode in which XperienCentral content is served from at least two application servers. |
MasterRead/write | The application server on which the Editor can be used to maintain the content. In standalone mode, there is only one masterread/write node. In clustered mode, there is one master and read/write node and one or more slavesread-only nodes. |
SlaveRead-only | The application server which only serves content (the website environment) but cannot be used to maintain the content because it is read-only. In standalone mode, there is no slaveread-only. In clustered mode, there are one or more slavesread-only nodes. |
External server name | The public hostname of the application server accessible from the internet. The website environment is accessible from this hostname. |
Internal server name | The hostname of the application server that exists only in the local network. The Editor is accessible only from this host name. |
...
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.