4. Portal Feature Examples

4.1. New portal page

This example explains how to create an new portal page with its own template and frame templates. We assume that your portal configuration already uses portal pages. If this is not the case please read the migration guide for portal pages.


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

  1. You can define new pages in the portal configuration file default.portal.xml of your server in the <pages-section>. Your portal page can use one or more positions that will contain the portlets. 
Show mypage <pages-section> within default.portal.xml configuration file.
Show mypage <pages-section> within default.portal.xml configuration file.
  2. In order to load a custom template you must define a template loader. This is done in the <template-section>. The default configuration has already a loader for portal page templates with the id "portalpage". It loads the template files from ${com.gentics.portalnode.confpath}/templates/portalpages (in your SDK this means Servers/<your-server>/gentics/templates/portalpages).
  3. We want our page "mypage" to use template file "mypagetemplate.vm". This is also configured in the template section: 
Show template loader within default.portal.xml configuration file.
Show template loader within default.portal.xml configuration file.
  4. Given the configuration above and the template loader "portalpage" you have to save your template to file "mypagetemplate.vm" in the folder ${com.gentics.portalnode.confpath}/templates/portalpages.
  5. The list of variables which can be used in the portal page template can be found in reference documentation of Gentics Portal.Node. You can also have a look at default template "demo.vm" in you SDK portal.
  6. Furthermore you can customize the portlet frames. Again you will need a template loader. The default configuration defines a template loader "portletframe" which loads the template files from ${com.gentics.portalnode.confpath}/templates/portletframes.
  7. The following code will cause the the portal to use the template "myframe.vm" for all portlets in "mypage" in windowstate normal: 
Show template loader within default.portal.xml configuration file.
Show template loader within default.portal.xml configuration file. You can also define a custom frame template for a specific portlet, position or style. See reference documentation for more information about how the matching algorithm for template selection works.

4.2. GenticsLoginModule

This example covers usage of the Gentics Login Module.


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

Though there may not be that much eyecandy on this example it demonstrates well how the <authentication-section> within the portal configuration file is used together with the GenticsLoginModule. User profiles stored in our sample HSQL database are able to authenticate using their firstname along with a default dummy password which is currently set to "password". Not that tricky. So try logging in using "Max" as login name. The PNAuthenticationManager will handle the rest for you, and authenticate according to the given loginrule.

4.3. URL Mapping Example

This example demonstrates the usage of the URL mappings.


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

The first thing to do when you want to make URLs beautiful, is to enable this feature in your portal configuration file by setting the portal parameter portal.urlmappings to true (the default is false ).


enable the feature in the portal configuration
enable the feature in the portal configuration

Normally most links in Gentics Portal.Node will have many GET parameters. This is neither beautiful nor very practical since such URLs tend to be quite long and unreadable. To avoid this you can configure your portal to use URL mapping. All relevant configuration options are stored in the portal configuration file:


open url mapping configuration
open url mapping configuration

In general the mappings affect all URLs rendered by Gentics Portal.Node including PLinks and URLs in GenticsContentModule. To keep things simple in this example we use the URL mappings to change the URLs for maximizing and minimizing the portlet.

Without the URL mappings the maximizing URL would look like http://localhost:42880/Portal.Node/portal?gentics.rm=URLMappingExample&gentics.ws=maximized&gentics.pb=right

  • The parameter gentics.rm=URLMappingExample specifies the portlet.
  • gentics.ws=maximized specifies the new window state
  • gentics.pb=right specifies the position

In the urlmapping-section of the portal configuration we have defined a mapping to transform the URL. In our example there is only one configured mapping however more different mappings can be used.

  1. When a URL is rendered Gentics Portal.Node must decide whether a mapping should be applied. This is done using the hidden urlparameters. In our case we have defined, that the urlparameter gentics.rm must have the value URLMappingExample and will be hidden. This means that only URLs with the urlparameter gentics.rm=URLMappingExample will be transformed using this mapping (e.g. our URL for maximizing above).
  2. The pathtransformation defines how the transformed URL will look like. It consists of several segments.
    1. The first segment has a static value. Therefore the transformed result will always start /URLExample/
    2. The second segment is a dynamic one and uses the value of the urlparameter gentics.ws . In our case this would result in /maximized/
    3. The last segment is also dynamic and uses the value of gentics.pb , thus resulting in /right/
    The resulting transformed URL is created by simply putting the entries together - in our case http://localhost:42880/Portal.Node/portal/URLExample/maximized/right
  3. When you click on this URL then Gentics Portal.Node has to reconstruct the original URL with its urlparameters. So how can the original urlparameters be recognized? How does Gentics Portal.Node know that "maximized" is the value for the parameter gentics.ws The key is to recognize the mapping that was used to transform the URL. The static segment "URLExample" can be seen as a hint to the portal. It helps to determine which mapping was used to render the URL. Therefore it is recommended to embed a static segment in the transformed URL if your portal is configured to use multiple different mappings.

[Note]Note
The portlet itself and its implementation is the same as the “SimpleTemplateExample” (Section 3.1) but it uses a different template. The implementation of the portlet is not important. The only relevant part is the configuration of the URL mappings.

4.4. Page Selector Example

This example demonstrates how pages can be selected by a simple view.


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

4.5. AjaxExamples

This section walks you through all Ajax examples provided with the Gentics Portal.Node SDK.

4.5.1. Hello World

A very basic "Hello World" example incorporating Ajax functionality, which can be accessed via the Ajax portlet from the SDK portal. Believe it or not - the text which pops up after clicking the button is requested and delivered directly from the server, and not generated by the client, as one might expect. So at this time there's more under the hood than can be seen at first glance. When checking the helloworld.xml view file, you come to know that a CallableAction is in charge for delivering the highly anticipated "Hello World!"-string to you.


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

4.5.2. Autocomplete

The Autocomplete example features a typical Ajax usecase found in most Web 2.0 applications. When typing the portal will automagically be queried for matching contents from within our sample database, which are displayed in a box. Implementation is quite straightforward, which uses jQuery to invoke a CallableAction from the autocomplete view. Take a look at the custom template for the autocomplete input field, which takes care of querying the server and response handling all by itself, whilst keeping things easy with only very few lines of JavaScript.


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

4.5.3. Load & Store

The Load & Store example demonstrates a classical usecase for Ajax applications. Items can be loaded from a datasource by specifying their contentid. After changing some of the properties available, they might be stored back to the database, without reloading the page even just a single time.

[Tip]Tip
Try using contentid "1001.5" or "1001.6" to find database entries for your testing needs!

As one might expect this example relies heavily on usage of callable actions for both load and store operations. The form displayed itself is rendered using a custom template (loadandstore.vm) for both edit and query tasks. The load operation is implemented quite straightforward, and will also handle error cases like objects which could not be found or datasource errors from within the callable action itself. The store operation is not complicated either and works just as you'd implement a non-Ajax store operation. There is only one difference, as the object to be stored has to be built from request variables.


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

4.5.4. SimpleAjax Custom Form Example

This example demoes a very basic Ajax implementation, which does not rely on Gentics Portal.Node views. Instead the form is generated entirely from the SimpleAjax class, which delivers outputs on call of it's doView() method, and query result via serveResource().


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

4.5.5. AjaxAddRemovePortlet

This portlet allows you to add and remove portlets to your portal page. It is a ViewPortlet with three views. In order to add the portlets via AJAX without reloading the whole page you have to activate portlet reloading and replacing of links for this portlet. The SDK example portal has portlet reloading activated globally in the default.portal.xml. It can also be configured individually for each portlet in the portletentities.xml. 
open configuration
open configuration

The addportlet-View allows you to add new portlets. It consists of two simple select components where the user can choose the portlet and the position where the portlet will be placed. The [Add]-button reads the values of the select components and adds the portlet to the selected position of the current portal page by simply using the "+=" operator. Thanks to the portlet reloading your portal will take care of everything and no JavaScript programming is necessary in this example. 
Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

The removing of portlets is also very simple. To show the close button on portlets you have to define a new action. This is done in the portlet entities configuration file. 
open configuration
open configuration The reaction on the close event is also configured in the portlet entities file. It resolves the the portlet that caused the event, its position and the portal page and removes it from the list of portlets in that position using the "-=" operator.

4.5.6. Portlet Reloading

Portlet reloading means that all links and forms are replaced with ajax calls to Gentics Portal.Node which will only render and replace the affected portlets, not the whole portal page. This results in a much faster response time.

Procedure 4.1. Setting up Portlet Reloading

  1. Adding Javascript libraries to portlet application

    In the SDK SamplePortletapplication, you find our example implementations of the client-side scripting necessary for portletreloading. The Javascript files are all located in the path WebContent/ajax. To use those Javascript libraries in your own implementation, you can simply copy the following files into your own portlet application:

    • jquery-1.2.6.js contains the 3rd party jQuery library

    • jquery.form.js contains the form plugin for jQuery (needed to manipulate forms)

    • gentics-ajax.js contains the generic code to parse and interpret responses from the Gentics Portal.Node server to AJAX requests

    • gentics-portletreload.js contains the portletreloading specific code to substitute the portlets in the DOM tree with new rendered versions.

  2. Include Javascript libraries into the portal page template

    Of course, the javascript libraries need to be included in the html output for your pages. 
show in the portal page template.
show in the portal page template.

  3. Initialize the client-side javascript for portlet reloading

    The simple javascript code GENTICS.PortletReload.create(); will enable portlet reloading. 
show in the portal page template.
show in the portal page template.

  4. Add $portlet.portletreload to portlet frame templates

    The client-side javascript code will need special css classes in the outermost HTML tags of rendered portlets to identify the DOM parts, which have to be replaced by new rendered portlets. It is therefore necessary to add $portlet.portletreload to the class of the outermost HTML tag in all of your portlet frame templates. 
show in the portlet frame template.
show in the portlet frame template.

  5. Add css class to positions in portal page template

    Also the positions need to be indentified in the DOM tree by css classes, which need to be added manually. The css classes need to be named gentics-portletreload-position-[positionid]. 
show in the portal page template.
show in the portal page template.

  6. Enable portlet reloading in portal configuration

    Portlet Reloading must be activated by setting the parameter portal.portletreload to true in the portal configuration file default.portal.xml . 
open default.portal.xml
open default.portal.xml

It can then be deactivated for single portles by using the gentics.portletreload = false parameter as seen for example in the pnode of the LanguageSwitcher portlet ( portletentities.xml ). 
Open portletentities.xml
Open portletentities.xml

4.5.7. Drag'n'Drop

Our demo Drag'n'Drop implementation shows you what can be achieved with our new Ajax features by means of a pretty cool usecase. On every one of our example portal pages you are able to drag and drop each and every portlet from left and right portlet positions. Right after the drop occurs positions are stored back to the server, so the portal will remember your positioning, and apply it even after reloading the page. Furthermore your favoured positioning is put to the user object and stored back to the database. Therefore on your next login portlet positions will be restored.


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

4.5.7.1. JavaScript libraries needed for Drag'n'Drop

The following list contains all JavaScript libraries necessary for Drag'n'Drop. It consists of 3rd party libraries (jQuery) and demo libraries provided by Gentics.

  • jquery-1.2.6.min.js jQuery library. jQuery is an AJAX framework, which we use for all our AJAX examples. See http://jquery.com/ for details on jQuery.
  • jquery-ui-personalized-1.5.2.js jQuery UI plugin library. See http://ui.jquery.com/ for details about that. The personalized download contains the following Components:

    • UI Core
    • Draggable
    • Droppable
    • Resizable
    • Selectable
    • Sortable

  • gentics-ajax.js small library for decoding and interpreting server responses to AJAX calls. See the reference documentation (index term AJAX) for more details.
  • gentics-portletdragdrop.js encapsulation of the sortable features of jQuery to support Drag'n'Drop of portlets.
  • gentics-portletreload.js another small demo library to support portlet reloading. See “Portlet Reloading” (Section 4.5.6) for details about portlet reloading.

4.5.7.2. Enabling Drag'n'Drop for portlets
  1. For each position that should support Drag'n'Drop (in our case: left and right ), we embed the rendered portlets into a container tag (in this example: <ul>), which is identified by the class gentics-portletreload-position-[position_id] and the id col_[position_id]. 
Show portal page template
Show portal page template

  2. All portlet frames must have their outermost html tag have the class sortable (which marks the DOM element as being draggable) and the id ${portlet.id} (which will render the portlet's id). 
show portlet frame template
show portlet frame template

  3. Calling the JavaScript method GENTICS.DragDrop.create() in the portal pages template binds the necessary jQuery functions to all sortable items inside the specified Drag'n'Drop containers. 
Show portal page template
Show portal page template The method accepts an array of JavaScript objects to specify the sortable positions and the url for the server call to store back the new portlet positions. The sortable positions can have the following attributes:

    • position : id of the position (e.g. left )
    • id : id of the html container tag of the position (e.g. col_left )
    • accept : jQuery selector to identify all sortable elements (here: .sortable , which finds all elements with class sortable )
    • connectWith : array of jQuery selectors of other containers (e.g. #col_right to connect the position left with the position right, which means that portlets can be moved from left to right)
    • helperclass : Name of the class which the drop target "helper" will get (such that the user can see, where he/she is about to drop a portlet)
    • handle : jQuery selector to identify the "drag-handle" (the part of a portlet, which allows dragging the portlet, e.g. div.head to make the portlets draggable when clicked onto the headline)

    The url for the server call is accessible as $portal.portletpositionchange.

4.5.7.3. How does the portlet Drag'n'Drop actually work

  • The source code of the JavaScript function can be found in the library file gentics-portletdragdrop.js . It enables sorting for all specified positions and binds the function GENTICS.DragDrop.updatePositions() (which is defined in the same file) as callback function when portlets have been dragged to different positions (or reordered in one position).
  • The method GENTICS.DragDrop.updatePositions() constructs the parameter list for the portal server request to store back the new portlet positioning and finally issues the AJAX request.
  • In the callback method of the AJAX call, the method GENTICS.processResult() (which can be found in the file gentics-ajax.js ) is called. This method decodes and interprets the server response. As a result, all portlets that need to be re-rendered due to the portlet position changes will be replaced on the page by means of jQuery DOM manipulation methods.


open gentics-ajax.js
open gentics-ajax.js 
open gentics-portletdragdrop.js
open gentics-portletdragdrop.js 
show gentics-portletreload.js
show gentics-portletreload.js

4.6. Gentics .Node PortalConnector Examples

The update file and installation CD contains a file named 'gentics-portalconnector-3-example.zip' which contains simple Gentics .Node PortalConnector examples (Read/Write as well as a JSP usage example).

4.7. PCWSClientExample

This example demonstrates the usage of the Gentics .Node PortalConnector WebService to access datasources from Java client programs. The example is a very simple commandline program that uses Apache Axis .


open PCWSClientExample.java
open PCWSClientExample.java

4.7.1. Prerequisites

In order to access a WebService you may examine the *.wsdl file that defines the services, methods and objects. The *.wsdl for Gentics .Node PortalConnector WebService can be obtained via web access using the URL http://localhost:42880/Portal.Node/ws/services/datasource?wsdl .

[Note]Note
Please note that you need a valid Gentics Portal Connector Webservice License to use this feature. In the default configuration of your SDK installation, the web service access is disabled for security reasons. Configure a user and passwort in ${com.gentics.portalnode.confpath}/users.properties . You also need to enable the user within the webservice configuration: ${com.gentics.portalnode.confpath}/webservices/configuration.properties Take a look at the reference documentation for further information.

With axis, you could auto-generate client classes with the command

java -cp mailapi.jar:activation.jar:saaj.jar:wsdl4j-1.5.1.jar:jaxrpc-1.2.1.jar:commons-discovery-0.2.jar:commons-logging-1.0.4.jar:axis.jar org.apache.axis.wsdl.WSDL2Java -p com.gentics.portalnode.pcws.example -U admin -P secret http://localhost:42880/Portal.Node/ws/services/datasource?wsdl

These classes have already been generated and packaged in the archive SamplePortletapplication/WEB-INF/lib/pcws-clientexample.jar .

[Note]Note
Although the access to a specific datasource is done through an URL that contains the datasource id, the client classes have been generated without datasource id and can be used to access all datasources that are exposed via web service.

4.7.2. Running the Example

The example consists of only the main class com.gentics.portalnode.sdk.PCWSClientExample and the runtime libraries

  • pcws-clientexample.jar (containing the auto-generated client classes)
  • axis.jar
  • commons-logging-1.0.4.jar
  • commons-discovery-0.2.jar
  • jaxrpc.jar
  • wsdl4j-1.5.1.jar
  • saaj.jar

To run the example, start Tomcat (if not already done before) and then simply right click on the *.java file in the package explorer and choose "Run as..." and then "Java Application". Whatch the Console view in your SDK for the program's output.

4.8. CsvImportExample

This example covers a standalone commandline program, which uses the CsvDataImportAction to import a csv file into a datasource, and a simple view using the same pluggable action. The example csv file can be found within your SDK installation. Please use WebContent/WEB-INF/examples/com/gentics/portalnode/sdk/cmdline/csvdata.csv in your SDK SamplePortletapplication Project.

For a detailed description of the csv file header format and the action parameters, see the CsvDataImportAction documentation in the Gentics Portal.Node reference.

4.8.1. Commandline example

The datasource to a contentrepository is created using the connection settings specified in the jdbc-handle.properties file. The cache.ccf file is used by the contentrepository cache. Before the commandline program can be used, the jdbc connection must be set to an existing contentrepository, which contains the objecttypes from the sdk sample database.

The implementation uses the PortalConnectorFactory to create a datasource, using the settings from the properties file. Then, a new instance of the pluggable action is created, as well as a request object, which holds all request parameters, and a response object, which stores the feedback message the response from the action.

After the action has been executed, the response messages and the ids of all new objects are printed. If the import fails (i.e. any error occurs), all created objects are deleted while the ids are printed.

The example can be run by selecting 'Run As' 'Java Application' or 'Debug As' 'Java Application' from the context menu.

4.8.2. View example

The view example can be accessed by the ExampleSelector-portlet. The view contains some simple input fields for the input parameter of the action, a button which triggers the action and a feedback- and a labelcomponent, to display the results of the import.


Show example in
Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK

The uploadcomponent provides the uploaded content as data stream without encoding. Therefore, the BinaryToTextAction is used to convert it into text, which uses the given encoding setting to handle special characters. The encoding of the sample csv file is ASCII. If the specified encoding does not match the format of the file, the resulting text may be corrupted.

After the text is successfully transformed, the action imports the content using the given settings. The result messages are then displayed using a labelcomponent.

To import the sample csv file, the object type must be set to 1001, the file encoding to ASCII and the file path prefix must be set to the directory containing the binary files. All other fields can be left empty.

4.9. PostProcessor Example

This example shows how the implementation of the interface com.gentics.api.lib.expressionparser.filtergenerator.PostProcessor instances can be used in conjunction with the filter() function to move contentrepository filter logic from the database into Java code.

The implementation of the portlet com.gentics.portalnode.sdk.filter.PostProcessorExample fetches data from a ContentRepository datasource with four different filter rules:

  • object.obj_type == 1001 is a normal filter to get all objects with a given type.
  • filter(object.obj_type == 1001, 'com.gentics.portalnode.sdk.filter.StartsWith', ['firstname', 'B']) also fetches all objects, but then removes all objects with firstnames not starting with 'B' by letting an instance of com.gentics.portalnode.sdk.filter.StartsWith process the intermediary result.
  • filter(object.obj_type == 1001, 'com.gentics.portalnode.sdk.filter.Sorter', 'surname') fetches all objects and in uses an instance of com.gentics.portalnode.sdk.filter.Sorter to sort them by surname.
  • filter(filter(object.obj_type == 1001, 'com.gentics.portalnode.sdk.filter.StartsWith', ['firstname', 'B']), 'com.gentics.portalnode.sdk.filter.Sorter', 'surname') finally combines the two filters from the previous examples to get a filtered and sorted result.


Show example in Gentics Portal.Node SDK
Show example in Gentics Portal.Node SDK 
open com.gentics.portalnode.sdk.filter.StartsWith
open com.gentics.portalnode.sdk.filter.StartsWith 
open com.gentics.portalnode.sdk.filter.Sorter
open com.gentics.portalnode.sdk.filter.Sorter