Creating Aikau Site Pages for Share

[ddraper]

Introduction

The Aikau framework provides a simpler way of creating pages in Share where a page can be declaratively defined as a JSON model in a WebScript. This avoids the necessity to create the XML and FreeMarker files for Surf Pages, Templates and Components.

I've been asked how you would create an Aikau page such that it is available as a site page in Share (e.g. a page that can be added via the Site Customization tooling in Share). So thought it would be worth capturing this information in a blog post. This is one of those interesting use cases where the old and new approaches of Share development intersect...

Background

In Share we use 'pre-sets' configuration to provide default User and Site dashboards. These are XML configurations that define the Surf objects that can be used to 'cookie-cut' new page instances (which are then stored on the Alfresco Repository).

The pre-sets can be found in in this file and the 'site-dashboard' pre-set contains a property ('sitePages') that defines the initial set of pages for each site. Once the site is created a new Surf Page instance is created on the Repository and when you add or remove pages from the site it is this property that is updated (in the instance, not the pre-set).

The 'Customize Site' page lists both the available 'Site Pages' and the 'Current Site Pages' and the list of pages to choose from is defined in the 'share-config.xml' file under the 'SitePages' condition, e.g:

<config evaluator='string-compare' condition='SitePages'>
  <pages>
    <page id='calendar'>calendar</page>
    <page id='wiki-page'>wiki-page?title=Main_Page</page>
    <page id='documentlibrary'>documentlibrary</page>
    <page id='discussions-topiclist'>discussions-topiclist</page>
    <page id='blog-postlist'>blog-postlist</page>
    <page id='links'>links</page>
    <page id='data-lists'>data-lists</page>
  </pages>
</config>‍‍‍‍‍‍‍‍‍‍‍

It's possible to extend this configuration to include additional pages, however the underlying code currently assumes that each page is mapped to a Surf object. This means that if you want to add in an Aikau page to this list then you need to create a Surf Page object (even though it won't actually be used to render the page at all).

Example

Say you want to add in a new Aikau page called 'Example'. You need to create a Share configuration extension that defines the new page (one way of doing this would be to create a 'share-config-custom.xml' file that you place in the 'alfresco/web-extension' classpath).

The file would contain the following XML:

<alfresco-config>
  <config evaluator='string-compare' condition='SitePages' replace='false'>
    <pages>
      <page id='example'>dp/ws/example</page>
    </pages>
  </config>
</alfresco-config>‍‍‍‍‍‍‍

But you'd also need to create a Surf Page XML file (placed in the  'alfresco/site-data/pages' classpath) containing:

<?xml version='1.0' encoding='UTF-8'?>
<page>
  <title>Example Site Page</title>
  <description>Example of adding a new site page</description>
</page>‍‍‍‍‍

Which would result in the following being shown when customizing a site: