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
This example covers usage of the Gentics Login Module.
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.
This example demonstrates the usage of the URL mappings.
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
).
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:
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
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.
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).
gentics.ws
. In our case this would result in
/maximized/
gentics.pb
, thus resulting in /right/
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 |
---|---|
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. |
This example demonstrates how pages can be selected by a simple view.
This section walks you through all Ajax examples provided with the Gentics Portal.Node SDK.
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.
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.
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 |
---|---|
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.
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().
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
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
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
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.
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
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.
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.
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.
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.
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.
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
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
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
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:
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.
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
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
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
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
.
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).
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.
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-portletdragdrop.js
show gentics-portletreload.js
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).
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 .
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 |
---|---|
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 |
---|---|
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. |
The example consists of only the main class
com.gentics.portalnode.sdk.PCWSClientExample
and the runtime libraries
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.
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.
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.
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
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.
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
open com.gentics.portalnode.sdk.filter.StartsWith
open com.gentics.portalnode.sdk.filter.Sorter