This topic provides extra information and tasks you must perform when upgrading your XperienCentral installation to a specific version. The modifications per version are not cumulative which means that you need to apply the changes for all versions between your current version and the one you are upgrading to. For example, if you upgrade from XperienCentral 10.14.0 to 10.21.1, you need to apply the changes described in this topic for all versions from 10.14.1 up to and including 10.21.1. For general upgrade information, see Upgrading a Linux Installation or Upgrading a Windows Installation.
XperienCentral 10.9.0
- The GetText servlet has been deleted. If you are using a modified web.xml file then be sure to remove any references to the GetText servlet.
- From now on the 3.0 servlet API is supported only. To enable this the dependencies to the related artifacts need to be changed in custom poms that refer to these artifacts:
javax.servlet:servlet-api
andjavax.servlet:jsp-api
. The
web.xml
deployment descriptor header should be changed to the 3.0 format:<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"version="3.0"> </web-app>
Maven 3.X does not support file URLs like "file:./maven-repository" in the settings.xml anymore, therefore the "localRepository" setting must be a real file path from now on and this should be updated in your custom Maven settings if needed. An absolute path is preferred for referring to the same repository (for example in subprojects) because the settings are relative to the current project directory (see https://maven.apache.org/plugin-developers/common-bugs.html#Resolving_Relative_Paths).
Maven 3.X discourages using expressions for the groupId, artifactId and version settings in POMs and other descriptors. These have been replaced by constant values and, as a result, the webmanager.project.groupId, webmanager.project.artifactId and webmanager.project.version settings from the settings.xml no longer serve a purpose and thus have been removed from the settings.xml. As a result of this it may be necessary to update the values of your project specific webmanager.staticbasedir, webmanager.backendbasedir and webmanager.cleansitelocation settings.
Because the Maven plugin for OSGI bundles has been replaced in Maven 3.X, the following adjustments are needed in the
pom.xml
of custom plugins.
PACKAGING:
Maven 2:
<project ...>
<packaging>osgi-bundle</packaging>
...
Replacement in Maven 3:
<project ...>
<packaging>bundle</packaging>
...
MAVEN OSGI PLUGIN: Note especially that the <explicitImportPackage> tag is not needed any more.
Previously this tag was used to make exported local packages available within the plugin code.
Maven 2:
<plugin>
<groupId>org.apache.felix.plugins</groupId>
<artifactId>maven-osgi-plugin</artifactId>
<configuration>
<osgiManifest>
<bundleActivator>...</bundleActivator>
<exportPackage>...</exportPackage>
<explicitImportPackage>...</explicitImportPackage>
</osgiManifest>
<configuration>
...
Replacement in Maven 3:
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<configuration>
<instructions>
<Bundle-Activator>...</Bundle-Activator>
<Export-Package>...</Export-Package>
<!-- REMOVED! explicitImportPackage -->
</instructions>
<configuration>
...
If a custom parent pom.xml is used in place of the one delivered in the XperienCentral SDK ZIP (
nl.gx.webmanager.wcbs:webmanager-wcbs
), then you need to make the following changes in the parentpom.xml
. Some of these tags can also be used directly in the pom.xml of a plugin. In that case, the same "translation" should be used there.Maven 2:
<plugin>
<groupId>org.apache.felix.plugins</groupId>
<artifactId>maven-osgi-plugin</artifactId>
<version>...</version>
<configuration>
<manifestFile>...</manifestFile>
<osgiManifest>
<bundleVendor>...</bundleVendor>
<bundleSymbolicName>...</bundleSymbolicName>
<bundleName>...</bundleName>
<bundleDescription>...</bundleDescription>
<bundleSource>...</bundleSource>
<bundleDate>...</bundleDate>
<bundleManifestVersion>${webmanager.manifestversion}</bundleManifestVersion>
</osgiManifest>
<configuration>
...
Replacement in Maven 3:
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>2.5.3</version>
<configuration>
<archive>
<manifestFile>...</manifestFile>
</archive>
<instructions>
<Embed-Dependency>*;scope=compile</Embed-Dependency> <!-- NEW! -->
<Embed-Transitive>true</Embed-Transitive> <!-- NEW! -->
<Export-Package/> <!-- NEW! -->
<Bundle-Vendor>...</Bundle-Vendor>
<Bundle-SymbolicName>...</Bundle-SymbolicName>
<Bundle-Name>...</Bundle-Name>
<Bundle-Description>...</Bundle-Description>
<Bundle-Source>...</Bundle-Source>
<Bundle-Date>...</Bundle-Date>
<!-- REMOVED: bundleManifestVersion -->
</instructions>
<configuration>
...
The maven-bundle-plugin adds version information to the Manifest file for its dependencies. This information is checked at runtime in order to ensure that an accepted version of the referred plugin is installed on the system, otherwise the plugin will fail to start. The default runtime version requirements are sensible, but when dealing with 3rd party components you might need to overrule these default requirements. This can be done as follows to allow v1.x.x - v5.x.x:
<Import-Package>com.gxwebmanager.tests.testservice.*;version="[1,6)",*</Import-Package>
.
XperienCentral 10.7.1
XperienCentral 10.7.1 provides an oEmbed service to embed XC content in external oEmbed consumers. The presentation of this content is provided by some XC presentation files. An example implementation can be found in the wmpcommunityeditionstyle
WCB (provided in the edition-bundles
directory of the release) that contains presentations with the following names: "WM page embed", "WM page embed ssi", "WM contentpart embedded" that are used to render the oEmbed presentation. "WM content" and "WM databasepage" are invoked but not modified.
XperienCentral 10.7.0
- The manner in which the active version of a form or form section is determined has been changed. It no longer makes use of a predefined set of states, but uses the XperienCentral Workflow functionality instead. As a result of this the getActiveVersion and setActiveVersion methods on the Form and FormSection class have been deprecated. The getActiveVersion method now invokes the newly introduced getCurrent method to determine which version is returned as the "active" version. The setActiveVersion no longer executes any logic at all.
- The behavior of the Session#getWrapper method has been altered when retrieving Content Items (instances of MediaItem). Previously this method would return an object even if none could be found for the requested identifier while now it will return null in this situation.
- 10.7.0 introduces support for Workflow in Interactive Forms. In order for this to work properly, WebManager sets up a new Workflow Repository Model called "Interactive Forms Workflow". You may want to review whether the permissions assigned to each activity suit your needs. You can find Workflow Repository Model configuration in the "Workflow" menu. The following permissions have been introduced in WebManager 10.7.0: Copy forms, create forms, create versions of forms, delete forms and edit forms.
XperienCentral 10.5.0
The model in order to store personalizations has been refactored. As a result, export files created using the content export functionality in the setup tool of older XperienCentral versions containing personalizations or references to personalizations cannot be imported on XperienCentral 10.5.0 and vice versa.
XperienCentral 10.4.1
- In 10.4.1 the logic which adds anchors and back to top links to elements has been moved from the
content.jspf
, which loops over and renders all elements, to two separate presentation JSPs, one with scope ElementAnchor, which prepends the anchors to an element if applicable and one with scope ElementBackToTop, which adds the back to top links to an element if applicable. - All element related logic should be removed from your project specific presentation JSPs which currently loop over and render the elements, like the
content.jspf
in the webmanager-cestyle-wcb and add two new presentation JSPs based on the elementAnchor.jspf andelementBackToTop.jspf
in the webmanager-cestyle-wcb.
XperienCentral 10.4.0
In 10.4.0 all default database connections are merged to one database connection named WebManagerDb which by default is accessed through JNDI lookups. Therefore it is necessary that before deploying the application the WebManagerDb datasource is configured to be available on the application server. For Apache Tomcat edit the server.xml and add this resource to the context of the backend webapp:
Resource name="jdbc/WebManagerDb" auth="Container" type="javax.sql.DataSource" username="${webmanager.externaldb.dbuser}" password="${webmanager.externaldb.dbpassword}" driverClassName="${webmanager.externaldb.dbdriver}" url="${webmanager.externaldb.dburl}" maxActive="100" maxIdle="10" maxWait="10000" testWhileIdle="true" timeBetweenEvictionRunsMillis="900000" removeAbandoned="true" removeAbandonedTimeout="30" logAbandoned="true" validationQuery="${webmanager.externaldb.validationquery}"/>>
Note that you still have to fill in the correct values for the username, password, driverClassName, URL and validationQuery attributes. Examples of these can be found in the settings.xml.
For Jboss edit the standalone.xml and add this datasource to datasources subsystem:<datasource jndi-name="java:jboss/jdbc/WebManagerDb" pool-name="WebManagerDb" enabled="true" use-java-context="true"> <connection-url>${webmanager.externaldb.dburl}</connection-url> <driver>${driverName}</driver> <security> <user-name>${webmanager.externaldb.dbuser}</user-name> <password>${webmanager.externaldb.dbpassword}</password> </security> </datasource>
Note that you still have to fill in the correct values for the connection-url, driver, user-name and password. Examples for the connection-url, driver and user-name can be found in the settings.xml. The driver value has to correspond with the name attribute of the driver you wish to use as defined in the drivers tag in the datasources subsystem. Furthermore, the driver for your database must be copied to the lib directory of your Tomcat or JBoss installation. Supported drivers can be found in the ext-directory in the root of the SDK distribution.
It is advised to generate a new repository.xml using the maven configure-jcr-repository profile to make sure the jcr also accesses the database using JNDI and uses the WebManagerDb database connection. When you place this newly generated repository.xml you need to completely rebuild the JCR-index and thus stop the application server, remove the current repository directory and then start the application server again. If your installation contains custom database connections, you have to manually configure those to make use of JNDI, which includes adding the datasource to the application server configuration and updating the database connection set in the [Database configuration] tab of the setup tool.
If you don't want to use JNDI, you have to fill in the old settings in the dbcbmanager sets in the dpcbmanager_defaults.xml which are generated in the WEB-INF folder of the webmanager-backend-webapp based on the settings.xml before executing the upgrade. You cannot generate non-JNDI dbcpmanager_defaults.xml using a maven command you always have to do this manually.The secure form signer used to protect forms against tampering has been changed. All dumped pages which contain interactive forms or advanced forms will need to be regenerated or flushed from the cache. Any old pre-upgrade forms submitted by browsers to the website after the upgrade will be rejected by the secure forms checking filter.
PageVersionEvent.getTargetPageVersion() is deprecated; use .getPageVersion() instead. This change is relevant only for event handlers that use the deprecated method on a COPY event.
PageVersionEvent.getEntity() no longer returns the original page version, it now returns the target page version. The same holds for .getPageVersion(). This change is relevant only for event handlers that use one of these methods on a COPY event.
ElementEvent.getElement() now returns the target element, instead of the old element. This change is relevant only for event handlers that use this method on a COPY event.
ElementEvent.getOriginalElement() now returns the original element. This change is relevant only for handlers that use this method on a COPY event.
Subscription to interface scopes is possible; this might cause issues if a handler is subscribed to both Foo.class and FooParent.class.
The PageManagementService no longer publishes UPDATE events, WCBs that rely on such an event being published after calling either .addLeadText(PageVersion), .addRedirect(PageVersion), or.reorderElements(PageVersion, Element[]) should now publish UPDATE events themselves.
HistoryEvent.TOUCH is deprecated (and no longer published), please replace this with EntityEvent.UPDATE (both PRE and POST).
Saving page metadata no longer publishes an MediaItemVersionEvent, but a PageVersionEvent instead.
Apache Commons FileUpload has been updated to v1.3.1 (from 1.2.2), any implementation of FileItem now should implement both setHeaders(FileUploadHeaders) and getHeaders(). See http://commons.apache.org/proper/commons-fileupload/changes-report.html for other changes.
XperienCentral 10.2.x or older to 10.3.0
- In 10.2.1 or higher the XML parser factories of JBoss are boot delegated. Therefore, bundles that use XML parsing must import involved packages from javax.xml.* of the system bundle. Bundles cannot include a jar that provides javax.xml interfaces, or a ClassCastException occurs in combination with JBoss. This situation differs from 9.20.x as javax.xml.* packages were boot delegated. This breaks modularity of these packages leading to the problem the other way around: bundles cannot provide an implementation of a javax.xml.* package.
- In 10.3.0 or higher the hidden fields with name formid and clientsideRouting for Interactive Forms no longer have the id attributes with respective values formid and clientsiteRouting. Custom javascript code which depends on these iID attributes has to be updated.
- In 10.3.0 or higher, the divs with id attributes starting with "info_" and "errors_" have been extended with an identifier for the form to which they belong. Custom javascript code which depends on these id attributes has to be updated.
- In 10.3.0 or higher add the "Create versions of content items" permission explicitly to the "Create object" activity of all workflow repository models being used, in order to be able to create content versions of content repository related types.
GX WebManager 9.18.x, 9.19.x and 9.20.x to XperienCentral 10.x.x
- The "javax.servlet:servlet" artifact name has been changed to "javax.servlet:servlet-api". This
may require changes to dependencies in WCB pom.xml files. However, most (if not all) WCBs
"inherit" this setting from XperienCentral and won't require changes.
NOTE: From 10.9.0 the 3.0 servlet API is supported, so see below for 10.9.0 related changes to
support this version of the servlet API.
- Create pages as a display on page for page sections and the image, download, flash and multimedia
and configure these special pages at "Website configuration" -> "Special pages".
- Choose a page part that will display page sections that do not yet have a page section label
assigned and configure it as such by checking the "Show page sections without label" checkbox at
"Design templates" -> "Page parts". Make sure this page part is visible on the page section
display on page configured in the previous step. Also see Online Help in XperienCentral.
- Rebuild the search index
- Update customized wmasolrsearch configuration
- Presentation: Update xslStyleSheet.jspf in the "website" folder of your custom presentation WCB to
check for "mode=incontext" instead of "mode=preview". This is needed for Read Access to work on
the backend.
- Tweak presentations to work seamlessly with Inline Editing. For more on this, see section 3
"Preparing presentation WCBs for use with the Inline Editor" below.
- From GX WebManager 10.1 XperienCentral, Interactive Forms has become integral part of the platform.
As a result, the Interactive Forms bundles are not upgraded automatically, and therefore, all
Interactive Forms bundles with the version 2.x.y need to be stopped and uninstalled manually.
Optional changes:
- It is suggested to disable adds in the incontext mode of XperienCentral.
- Remove or update maximum platform version in pom.xml. Note that as of GX WebManager 10 XperienCentral
this property is no longer honored as the GX WebManager 10 XperienCentral API will remain backwards
compatible with GX WebManager 9.
- If a WCB uses dependency manager api directly it should switch to the new dependency manager 3 API
- Updating icons for Custom Media Items may be preferred; existing icons may typically not fit that
well in the new UI. Deleting them and falling back to the default may be a valid solution in many
cases. New sizes are 20x20 and 180x180 with Sprite support. Icons for Elements will probably need
to be updated as well.
- Make sure empty content items have a non-zero size (in mode=incontext) in order to be able to
doubleclick on it in the Inline Editor. The same goes for elements.
- The menu has been reordered and target menu settings in WCB component definitions are now ignored.
In order to place a menu item in a specific category, use
"PanelComponentDefinitionImpl.setMenuCategory()" to set the category to one of the constants
defined in PanelComponentDefinition.
GX WebManager Versions older than 9.18.0 to XperienCentral 10.x.x
When upgrading from a version older than GX WebManager 9.18.0, it is strongly advised to upgrade to
GX WebManager 9.20.x before performing an upgrade to GX WebManager 10.x XperienCentral.
General Notes for all Versions
---------------------------------------------------------------------------------------------------
-3- Preparing presentation WCBs for use with the Inline Editor
---------------------------------------------------------------------------------------------------
In order for your presentations to properly interact with the Inline Editor, some changes need to
be made: all editable areas must be wrapped by wm:editable tags and some other changes may be
required. More information can be found at:
https://api.gxsoftware.com/javadoc/nl/gx/webmanager/taglib/EditableTag.html (Javadoc)
and
https://wiki.gxsoftware.com/wiki/display/PD/Taglib+Reference#TaglibReference-editable (documentation)
Below are some additional tips and tricks.
HTML 5 Mode
-----------
GX WebManager 10 XperienCentral requires that web site presentations and pages run in HTML 5
standards mode. This is most important for Internet Explorer which by default doesn't run in
standards mode. To engage standards mode on Internet Explorer, pages need to start with the
"<!DOCTYPE html>" doctype. Firefox and Google Chrome run in standards mode by default.
Displaying Text (CSS styling)
-----------------------------
The Inline Editing functionality in GX WebManager 10 XperienCentral features an advanced
rich text or WYSIWYG editor built into the browser using the standard web technologies like
JavaScript and CSS. For the editor to really be "What You See Is What You Get" there needs
to be some basic agreements in place between the front-end presentation (JSP and CSS) and the
rich text editor with regard to how HTML content should be rendered.
The following rules should be followed:
- Whitespace is significant. Multiple spaces show more space on the screen and don't
collapse to just one space.
- <p> tags are inserted automatically as soon as a paragraph exceeds the length of a line or
becomes more complex than a very simple line of text. In order for this not to have a visual
effect, text in <p> tags should have similar style as the text directly placed in the content
area.
- Empty <p> tags should display a blank line and not collapse - a user will expect 3 empty
lines when they press enter 3 times in a row. This is best done by adding a CSS rule such
as: <p> { min-height: 1em; }
Identifying Content
-------------------
Use the editable tag to mark where your content items appear on the page
(whether they're editable or not!), otherwise GX WebManager 10 XperienCentral can't
find them and make them editable or update context-sensitive sidebar widgets based on them.
For example, use this to show the title of a page in H1 tag:
<wm:editable tag="h1" contentholder="${pageversion}" area="title">${title}</wm:editable>
The wm:editable tag documentation in the XperienCentral Javadoc contains much more information.
Tips:
- Be sure to only include editable content inside the editable tag. Don't hard-code any
extra content in your JSP inside the editable tag, otherwise the extra content will be seen
as having come from WM and will be saved when the user edits the page. This also applies to
whitespace, comments and additional DIVs. The application server will sometimes strip some
whitespace out of JSP code (e.g. tabs for tag indenting) but it is much safer to ensure that
there is no extra whitespace in between the start/end of the editable tag and the content
itself. Also, do not modify or enhance the HTML content from WM when printing it off in the
JSP. These extra bits of HTML will also be saved when editing the page.
- Always print out an editable tag even if there is no content or elements, otherwise the user
won't be able to add any content there.
- The areaend parameter (when content spans a range of separator elements) must have a
sensible value because XC creates separators for each area if missing. E.g. area=3 and
areaend=1000 creates 9993 separators.
Floating HTML elements
----------------------
The float CSS property specifies that an element should be taken from the normal flow and
placed along the left or right side of its container, where text and inline elements will
wrap around it. A floating element is one where the computed value of float is not none.
A common problem with float-based layouts is that the floats' container doesn't want to
stretch up to accomodate the floats. If you want to add, say, a border around all floats
(ie. a border around the container) you'll have to command the browsers somehow to stretch
up the container all the way.
This also applies for the page flow of an XPC content item: to make sure the next XPC
content item element is rendered properly and will not be positioned within the block flow
of the previous XPC content item element the floating must be cleared to make it possible to
stretch the element container div to it's full content and draw the container borders
correctly.