Contents
The following sections explain how the most commonly used components of the reference website Geometrixx have been developed.
The Top Navigation Component displays the top level pages of the website. This navigation component is placed at the top of the content pages in the website.
There is no content to be handled by this component. Therefore there is no need for a dialog, only rendering.
Specification summary:
/libs/foundation/components/topnavDisplays level one pages (below Homepage).
Respects On/Off status and uses image rendering.
Displays as in the following screenshot:
The main function of a navigation component is to:
show the hierarchical page structure of a website
provide the possibility to access the pages within this structure.
To achieve this, functionality to “get the childpages” of a specific page is essential. Also required is the functionality to: get the path of the parent page of any page on a specific absolute level (start page of the navigation), check the validity of a page and of course get the path and title of a page.
The following are an introduction to the relevant functionality (API calls):
com.day.cq.wcm.core.PageManager.getPage(String path): get the page related to a pathcom.day.cq.wcm.core.Page.listChildren(): get the childpages of the pagecom.day.cq.wcm.core.Page.getPath()+.getTitle(): get the path or title of the page respectivelycom.day.cq.wcm.core.Page.isValid()+.isHideInNav(): checks if the page is valid or the hide in navigation property is set respectivelycom.day.cq.wcm.core.Page.getAbsoluteParent(int level): Get the the parent page on an absolute levelPageFilter(): The default CQ Page filter: checks if the page is valid (by checking that the property hideInNav is not set, performing checks on On-/Offtime etc); can be used instead ofisValid()andisHideInNav()
For more detailed information please have a look at the Javadoc provided with CQ5 WCM.
To be able to use image based navigation items, a mechanism is needed to request a page in an “image navigation item view”.
To achieve this a specific selector is added to the request
for the navigation item image of a page; for example,
/path/to/a/page.navimage.png. Requests with
such a selector have to be handled by an image processing mechanism.
Sling's request processing mechanism is used for this. To realize
this, an image processing script (or servlet) is added, this handles
all requests with the specific selector (for example,
/contentpage/navimage.png.jsp or
/contentpage/navimage.png.java).
For rendering text images the abstract servlet
AbstractImageServlet is very helpful. By overwriting the
createLayer() method, it is possible to
programmatically create a fully customized image.
The following lists the relevant functionalities (API calls):
com.day.cq.wcm.commons.AbstractImageServlet
com.day.cq.wcm.commons.WCMUtils
com.day.cq.wcm.foundation.ImageHelper
com.day.image.Font
com.day.image.Layer
For more detailed information please have a look at the Javadoc provided with CQ5 WCM.
The Top Navigation component renders graphical (image based) navigation items.
The images for the navigation items are requested from the page resources in a specific view. This means, the paths of the image tags for the navigation items are equivalent to the paths of the pages that the navigation items represent. To identify the view (kind of presentation) the resource (page) is rendered by, a specific URL selector ('navimage') is added.
The List Children component displays the child pages under a given root page. The root page can be configured for every instance of this component (for every paragraph which is rendered by this component). Therefore a dialog is needed to store the path of the root page as content in the corresponding paragraph resource. If no root page is set, the current page is taken as the root page. The component displays a list of links with title, description and date.
Specification summary:
Display a list of links with title, description and date, referring to pages which are below either the current page or a root page defined by the path provided in a dialog
/libs/foundation/components/listchildrenRespects the On/Off status of displayed pages
The following screenshot shows an example of how it displays:
The Dialog of a component is defined in a subtree of nodes below the component's root node. The root node of the dialog is of nodeType cq:Dialog and named dialog. Below this, root nodes for the individual tabs of the dialog are added. These tab nodes are of nodeType cq:WidgetCollection. Below the tab-nodes, the widget nodes are added; these are of nodeType cq:Widget.
Summary:
Location:
/apps/<myapp>/<mycomponent>/dialogRoot Node:
dialog (cq:Dialog) - node for the dialog
Vital Properties:
xtype=panel - Defines the dialog's xtype as panel; title sets the title of the dialog
Vital Child Nodes of Dialog Node:
items (cq:WidgetCollection) - tab nodes within the dialog
Vital Child Nodes of Tab Node:
<
mywidget> (cq:Widget) - widget nodes within the tabVital Properties:
name - Defines the name of the property where the content provided by this widget is stored (usually something like ./mypropertyname)
xtype - Defines the widget's xtype
fieldLabel - The text displayed in the dialog as a label for this widget
The Logo component displays the logo of the website Geometrixx. The logo image and the home link can be configured globally (same for every page of the website) so that every instance of this component is identical. Therefore a design dialog is needed to provide the image and path of the home link to the design of the corresponding Page. The Logo component is placed in the upper left corner of all pages on the website.
Specification summary:
/libs/foundation/components/logoDisplays a linked logo image in the upper left corner (spooled image, no rendering)
The path for the link is the path of a page on a defined absolute level
The logo image and the level are the same for all pages on the website; store the logo image and level in the design of geometrixx
Displays as in the following screenshot
The Designer is used to manage the look-and-feel of the global content; including the path to the tool-pages, image of the logo, design values such as text family, size and so on.
Summary:
Location:
/etc/designsRoot Node:
<
mydesign> (cq:Page) - Hierarchy node of the design pageVital Child Nodes:
jcr:content (cq:PageContent) - Content node for the design
Vital Properties of Child Node jcr:content:
sling:resourceType = “wcm/designer” - Reference to the designer rendering component
The Designer values can be accessed by the
currentStyle object provided in
global.jsp.
Design dialogs are structured in the same way as normal dialogs but are named design_dialog.
The Paragraph System is a key part of a website as it manages a list of paragraphs. It is used to structure the individual pieces of content on a website. You can create paragraphs inside the Paragraph System, move, copy and delete paragraphs and also use a column control to structure your content in columns.
The Paragraph System provided in CQ5 WCM foundations covers most of the variants needed and can also be configured by allowing you to select the components to be activated/deactivated within your current paragraph system.
The Image component displays images in the main paragraph system.
Specification summary:
/libs/foundation/components/imageDisplays an image in the main paragraph system.
The image and certain paragraph-related display properties (title, description, size) are stored in the paragraph resource by a dialog.
Some global design properties, valid for all paragraphs of this type (minimal size, maximal size), are stored in the design by a design dialog.
There is the possibility to crop, map etc the image.
The smartimage widget is an extended widget used to handle the most common aspects of image handling in a WCM system. It controls the upload of the image file and stores the reference to the media library. It also supports the cropping and mapping of images amongst other functions.
The most important properties of the smartimage widget are:
xtype - The type of widget ('smartimage').
name - The place to store the image file (binary), usually
./image/fileor./file.title - The title displayed in the dialog.
cropParameter - The place to store the crop coordinates, usually
./image/imageCropor./imageCrop.ddGroups - Groups in contentfinder from where assets can be dragged to this widget.
fileNameParameter - Specifies where the name of the image file will be stored, usually
./image/fileNameor./fileName.fileReferenceParameter - Location to store the image reference when an image from the media library is used, usually
./image/fileReferenceor./fileReference.mapParameter - Where to store the map data, usually
./image/imageMapor./imageMap.requestSuffix - The default suffix to be used when browsing for an image with this widget, usually
./image.img.pngor./img.png.rotateParameter - Where to store the rotation specification, usually
./image/imageRotateor./imageRotate.sizeLimit - Maximum size limit, i.e. 100.
uploadUrl - The path to be used when storing data temporarily, usually
/tmp/uploaded_test/*.
To be able to drag assets from the contentfinder to a
component there must be a drop target configuration
node called cq_dropTargets below
the edit configuration node
(cq:editConfig).
Summary:
Location:
/apps/<myapp>/components/<mycomponent>/cq:editConfig/cq:dropTargetsRoot node:
cq:dropTargets (cq:DropTargetConfig) - Hierarchy Node of the drop target configuration.
Below this node the following node tree (with vital properties) must be created for the smartimage:
image (nt:unstructured) with the following vital properties:
accept - The media types to be accepted; i.e.
image/gif,image/jpegorimage/png.groups - Groups in the contentfinder from where assets can be accepted, i.e. media
propertyName - Where the reference will be stored; usually
./image/fileReferenceor./fileReferenceIn the case that the image is stored in a separate image node in the content (for example, as with textimage, when the image is not the only data to be stored for the resource) the following two nodes must also be created:
parameters (nt:unstructured) below the image node
image (nt:unstructured) below the parameters node with the following vital properties:
sling:resourceType - The resource type to be stored in the case that a complete paragraph has to be created (as when dragging an asset to the paragraphsystem while pressing the
Altbutton).
This section lists the most relevant functionalities (API calls) for the programmatic manipulation of images:
com.day.cq.wcm.foundation.Image
addCssClass
loadStyleData
setSelector
setSuffix
draw
getDescription
com.day.cq.wcm.api.components.DropTarget
com.day.cq.wcm.api.components.EditConfig
com.day.cq.wcm.commons.WCMUtils
For more detailed information please look at the Javadoc provided with CQ5 WCM.
As for the Top Navigation component, the AbstractImageServlet is used to render the images. For an introduction to the AbstractImageServlet, see the section called “Image Rendering Essentials”.
As the request to the resource in the 'image view' has to be detected, a specific selector to the request of the image (i.e. /path/to/the/resource.img.png) needs to be added. Requests with such a selector are handled by the image processing servlet.
The Text & Image Component displays text and images in the main paragraphsystem.
Specification summary:
/libs/foundation/components/textimageDisplays a text and image in the main paragraphsystem.
The text and image together with specific paragraph related display properties (title, description, size) are stored in the paragraph resource (dialog).
There is the possibility to manipulate the image, including cropping and mapping amongst other functions.
For the image rendering use the servlet created for the image component (to inherit from the image component set resourceSuperType)
The richtext widget is an extended widget used to handle the most common aspects of text handling in a WCM system. It stores the text with the formatting information.
The most important properties of the richtext widget are:
xtype - The type of the widget ('richtext')
name - Where the text is stored, usually
./text.hideLabel - Defines whether the label should be displayed, usually false.
richFlag (xtype=hidden) with name ./textIsRich, ignoreData=true and value=true - Used to define that format is rich text format.
This section lists the most relevant functionalities (API calls) for the programmatic manipulation of texts and images:
com.day.cq.wcm.foundation.TextFormat
com.day.cq.wcm.api.WCMMode
For more detailed information please have a look at the Javadoc provided with CQ5 WCM.
The Search component can be placed in the paragraph system of any page. It searches the content of the site for a query provided in the request.
Specification summary:
/libs/foundation/components/searchDisplays a search form.
Displays the result of the search for a query provided in the request (if a query was provided).
Provides a dialog to define some properties
Search button text
No results text
Previous label
Next label
Provides pagination
This section lists the most relevant functionalities (API calls) for the programmatic manipulation of searches:
com.day.cq.wcm.foundation.Search - Search Class to be used for almost every aspect of the search. The query is expected in a request parameter named 'q'
getResult - Get the result object
com.day.cq.wcm.foundation.Search.Result
getResultPages
getPreviousPage
getNextPage
For more detailed information please have a look at the API documentation provided with CQ5 WCM.