Composum Pages is providing a CMS framework on top of the powerful Apache Sling framework to create your own Content Management System. The CMS implementation is driven by components which are the placeable pieces of a content page. Pages are also implemented as components and provided as preconfigured page templates. A page is referencing client libraries (clientlibs) which are containing the component styles and the necessary client code (Javascript).

For the component development the Composum Pages edit frame can be used in the 'develop' mode. A developer can switch to this mode using the 'logo tools menu' in the left corner or by requesting the edit frame with the additional URL parameter pages.mode=develop.

Components

Composum Pages components are Sling components which ere rendered by the Apache Sling scripting services. A Pages Component consists of

a set of rendering scripts (JSP, HTL, ...) which are using Java models (Sling or Pages models or other Java objects) to access the repository resources and generate the HTML markup
a component structure description for the generic tools of the Pages edit frame
a dialog component to edit the components properties
a set of action declarations for the various contexts in the Composum Pages edit frame
a component help content page which describes the components features

A set of useful components to start quickly is delivered with the Pages Components module. The examples below are references to these components.

Component Declaration

In Apache Sling everything is a resource; a component also. A components resource describes the components type and declares a resource type (the path in the repository). The components resource describes also the property and element structure of the component:

the 'iFrame' component declaration xml

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:cpp="http://sling.composum.com/pages/1.0"
        xmlns:jcr="http://www.jcp.org/jcr/1.0"
        xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
        xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
        jcr:primaryType="cpp:Component"
        sling:resourceSuperType="composum/pages/components/element"
        jcr:description="an iFrame to embed rendered content"
        jcr:title="iFrame"
        category="[General,Blueprint]">
    <jcr:content
            jcr:primaryType="nt:unstructured">
        <properties
                jcr:primaryType="nt:unstructured">
            <src
                    jcr:primaryType="nt:unstructured"/>
            <title
                    jcr:primaryType="nt:unstructured"
                    i18n="{Boolean}true"
                    text="plain"/>
            <serviceUri
                    jcr:primaryType="nt:unstructured"/>
            <copyright
                    jcr:primaryType="nt:unstructured"
                    i18n="{Boolean}true"
                    text="plain"/>
            <style
                    jcr:primaryType="nt:unstructured"/>
            <mode
                    jcr:primaryType="nt:unstructured"/>
            <height
                    jcr:primaryType="nt:unstructured"/>
            <expandable
                    jcr:primaryType="nt:unstructured"
                    type="Boolean"/>
        </properties>
    </jcr:content>
</jcr:root>

/libs/composum/pages/components/element/iframe

The necessary property of such a component declaration are:

jcr:primaryType
must be 'cpp:Component' if you want to select this component type for insertion in a container otherwise 'sling:Folder' or 'nt:unstructured' are possible also
componentType or sling:resourceSuperType
a component must declare its general Type - Element, Container or Page; if a resource super type is specified this type declaration is inherited
category (multi)
the set of categories to present the component type in the designated group of the Pages edit frame tools
jcr:title and jcr:description
useful to find the component in the component selection tools

The jcr:content subnode of the component declaration resource contains the component structure describing meta data of the component - the set of properties and the set of embedded elements. This meta data are used by generic editing tools such as the content comparator to use the instances of the content component.

Scripting

Edit Dialogs

Edit dialogs are 'subcomponents' of a content component. They are placed at the edit/dialog path of the content component and they are itself also a Sling component (not of type 'cpp:Component' !). Such a dialog can be derived from a dialog super type, e.g. from a dialog component of the components super type. The dialog template is a JSP script which is using the edit widget JSP tags of theComposum Pages taglib to render the HTML markup edit dialog.

Dialog example jsp

<%@page session="false" pageEncoding="utf-8" %>
<%@taglib prefix="cpp" uri="http://sling.composum.com/cppl/1.0" %>
<cpp:defineFrameObjects/>
<cpp:editDialog title="@{dialog.selector=='create'?'Create an iFrame':'Edit iFrame'}">
    <cpp:widget label="Title" property="title" type="textfield" i18n="true"
                hint="the optional title shown as the frames header"/>
    <cpp:widget label="Frame Source" property="src" type="pathfield"
                hint="the 'src' of the iframe - an external URL or a path in the repository"/>
    <cpp:widget label="Service URI" property="serviceUri" type="textfield"
                hint="an optional URI of a servlet prepended to the path in 'src'"/>
    <cpp:widget label="Copyright" property="copyright" type="textfield" i18n="true"
                hint="copyright notice if necessary or useful"/>
    <div class="row">
        <div class="col col-xs-3">
            <cpp:widget label="Style" property="style" type="select"
                        options="simple,bordered,panel" default="simple"/>
        </div>
        <div class="col col-xs-3">
            <cpp:widget label="Auto Height" property="mode" type="select" hint="calc rule"
                        options="body,elements" default="body"/>
        </div>
        <div class="col col-xs-3">
            <cpp:widget label="Collapsed Height" property="height" type="textfield"/>
        </div>
        <div class="col col-xs-3">
            <cpp:widget label="Expandable" property="expandable" type="checkbox"/>
        </div>
    </div>
</cpp:editDialog>

the dialog of the 'iFrame' component

Edit Actions & Tile

Context Tools and the Help Page

Pages and Templates

Page Components

A content page is also rendered by a Sling component. Such a component must be of component type cpp:Page.

the Pages Components base page component xml

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:cpp="http://sling.composum.com/pages/1.0"
        xmlns:jcr="http://www.jcp.org/jcr/1.0"
        xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
        jcr:primaryType="cpp:Component"
        jcr:title="Page"
        componentType="cpp:Page">
    <jcr:content
            jcr:primaryType="nt:unstructured">
        <properties
                jcr:primaryType="nt:unstructured">
            <jcr:title
                    jcr:primaryType="nt:unstructured"
                    i18n="{Boolean}true"
                    text="plain"/>
            <subtitle
                    jcr:primaryType="nt:unstructured"
                    i18n="{Boolean}true"
                    text="plain"/>
            <jcr:description
                    jcr:primaryType="nt:unstructured"
                    i18n="{Boolean}true"
                    text="rich"/>
            <search
                    jcr:primaryType="nt:unstructured">
                <ignoreInSearch
                        jcr:primaryType="nt:unstructured"
                        type="Boolean"/>
            </search>
            <navigation
                    jcr:primaryType="nt:unstructured">
                <title
                        jcr:primaryType="nt:unstructured"
                        i18n="{Boolean}true"
                        text="plain"/>
                <hideInNav
                        jcr:primaryType="nt:unstructured"
                        type="Boolean"/>
            </navigation>
            <style
                    jcr:primaryType="nt:unstructured">
                <category.theme
                        jcr:primaryType="nt:unstructured"/>
                <category.view
                        jcr:primaryType="nt:unstructured"/>
                <category.edit
                        jcr:primaryType="nt:unstructured"/>
            </style>
        </properties>
        <elements
                jcr:primaryType="nt:unstructured">
            <top
                    jcr:primaryType="nt:unstructured"
                    type="composum/pages/components/container/parsys"/>
            <main
                    jcr:primaryType="nt:unstructured"
                    type="composum/pages/components/container/parsys"/>
            <bottom
                    jcr:primaryType="nt:unstructured"
                    type="composum/pages/components/container/parsys"/>
        </elements>
    </jcr:content>
</jcr:root>

/libs/composum/pages/components/page

A page is declaring a set of elements and containers to construct the page content. These elements are arranged by the pages rendering scripts and normally static included. This and all the other aspects of a page component are similar to a content component.

A page components must render a complete HTML page including the 'head' and 'body'. To support the page editing for these both elements a JSP tag is available - see the base page 'main' script of the Pages Components:

a page 'main' script example jsp

<%@page session="false" pageEncoding="utf-8" %>
<%@taglib prefix="sling" uri="http://sling.apache.org/taglibs/sling/1.2" %>
<%@taglib prefix="cpp" uri="http://sling.composum.com/cppl/1.0" %>
<cpp:defineObjects/>
<!DOCTYPE html>
<html ${currentPage.htmlLangAttribute} ${currentPage.htmlDirAttribute} class="${currentPage.htmlClasses}"
                                                                       data-context-path="${slingRequest.contextPath}"
                                                                       data-locale="${currentPage.locale}">
<cpp:head>
    <sling:call script="head.jsp"/>
</cpp:head>
<cpp:body cssAdd="composum-pages-components-page">
    <sling:call script="body.jsp"/>
</cpp:body>
</html>

/libs/composum/pages/components/page/page.jsp

The base page implementation in the Pages Components is using a lot of scripts for the various aspects of a page to support changing of this aspects selective by base page subtypes.

Page Templates

A new page is created by applying a predefined page template.

The page templates are declaring the component type of the page and their initial content structure. They specify also the structure policies of the page.

the Pages Components 'content' page template xml

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:cpp="http://sling.composum.com/pages/1.0"
        xmlns:jcr="http://www.jcp.org/jcr/1.0"
        xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
        xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
        jcr:primaryType="cpp:Page">
    <jcr:content
            jcr:primaryType="cpp:PageContent"
            sling:resourceType="composum/pages/components/page"
            jcr:description="A multi purpose content page with only one 'main' container to arrange content of all general element types including rows and columns."
            jcr:title="Pages Components Content Page"
            allowedChildTemplates="[
                ^(.*/)?pages/components/templates/page/([^/]+|subsite/root)$,
                ^(.*/)?pages/options/.*/template(s(/page)?(/.+)?)?$
            ]">
        <main
                jcr:primaryType="cpp:Container"
                sling:resourceType="composum/pages/components/container/parsys">
            <cpp:design
                    jcr:primaryType="nt:unstructured"
                    sling:resourceType="composum/pages/stage/edit/page/design"
                    allowedElements="[
                        ^(/[^/]+/)?composum/pages/components/container/(row)$,
                        ^(/[^/]+/)?composum/pages/components/element/title$
                    ]"
                    typePatterns="[
                        ^(/[^/]+/)?composum/pages/components/container/parsys$
                    ]">
                <column
                        jcr:primaryType="nt:unstructured"
                        allowedElements="[
                            ^(/[^/]+/)?composum/pages/components/(element|composed|search)/.*$,
                            ^(/[^/]+/)?composum/pages/components/container/(section)$,
                            ^(/[^/]+/)?composum/prototype/pages/.*$
                        ]"
                        typePatterns="[
                            ^(/[^/]+/)?composum/pages/components/container/row/column$
                        ]"/>
            </cpp:design>
        </main>
        <bottom
                jcr:primaryType="cpp:Container"
                sling:resourceType="composum/pages/components/container/iparsys">
            <cpp:design
                    jcr:primaryType="nt:unstructured"
                    sling:resourceType="composum/pages/stage/edit/page/design"
                    allowedElements="[
                        ^(/[^/]+/)?composum/pages/components/navigation/siblings$,
                        ^(/[^/]+/)?composum/pages/components/element/text$
                    ]"
                    typePatterns="[
                        ^(/[^/]+/)?composum/pages/components/container/iparsys$
                    ]"/>
        </bottom>
        <cpp:design
                jcr:primaryType="nt:unstructured"
                sling:resourceType="composum/pages/stage/edit/page/design">
            <container
                    jcr:primaryType="nt:unstructured"
                    allowedElements="[
                        ^(/[^/]+/)?composum/pages/components/(element|composed|search)/.*$,
                        ^(/[^/]+/)?composum/pages/components/container/(section)$
                    ]"
                    typePatterns="[
                        ^(/[^/]+/)?composum/pages/components/container/.*$
                    ]"/>
        </cpp:design>
    </jcr:content>
</jcr:root>

/libs/composum/pages/components/templates/page/content

Each content page in the resource resolvers search path is a page template (if not marked with isTemplate=false). The known Sling overlay mechanism is also effective here - a template in the '/apps' folder hides the template at the same path in the '/libs' folder.

Development