Share Page Creation Code

[ddraper]

Introduction

It's taken a little while due the convergence of Cloud and Enterprise code lines that has been ongoing for some time, but I can finally now release the source code for the drag-and-drop page creation tool that I demonstrated at Summit 2013. The recent updates to Alfresco in the Cloud marked the final step of the convergence process and allowed some code that had been on a private branch for many months to make its way to the main SVN trunk.

The code I'm providing is simply a couple of WebScripts that define pages made up of widgets that are now available in SVN. The code is packaged up as a JAR file that can be dropped into the 'webapps/share/WEB-INF/lib' folder of the web server that the Share application is running on and the pages will be available on the next server restart. You can download the JAR from here.

Pre-Requisites

NOTE: You need to have either built the latest Community code or have downloaded a nightly build - this will NOT work against any current Enterprise or Community release. The pages that you create will be stored on the Alfresco Repository and you will need to create a specific location in the Data Dictionary for them to be saved.

1. As 'admin' log into Share and click on the 'Repository' link in the header menu
2. Click on the 'Data Dictionary' folder
3. Select 'Folder' from the 'Create...' menu
4. Enter 'ShareResources' as the folder name (NOTE: no space, capital 'R') and click 'OK'
5. Click on the newly created 'ShareResources' folder and repeat steps 3-4 but create a folder called 'Pages' (NOTE: capital 'P')

The New Pages

The two pages provided are the JSON editor (http://<server>:<port>/share/page/hdp/ws/page-editor) and the Drag-and-drop Creator (http://<server>:<port>/share/page/hdp/ws/page-creator).  The JSON editor allows you to create pages by typing out the page model directly and the Drag-and-drop creator allows you to create pages using a simple GUI.

The JSON models for the pages themselves are defined in the following WebScript JavaScript controller files found in the JAR:

• alfresco/site-webscripts/org/alfresco/share/page-creation/dnd-creator.get.js
• alfresco/site-webscripts/org/alfresco/share/page-creation/json-page-editor.get.js

The JSON Editor

The actual editor used by the JSON Editor page is provided using the JSON Editor Online third party library. The 'alfresco/site-data/extensions/extension.xml' file in the JAR file shows an example of adding in a new AMD package into Share which was described in more detail in this previous blog post. The JSON Editor AMD modules are referenced from the 'alfresco/forms/controls/JsonEditor' widget that already exists in Share which is referenced by the 'json-page-editor.get.js' file.

Try the following simple example to get you started:

{
  'widgets': [
    {
      'name': 'alfresco/layout/ClassicWindow',
      'config': {
        'title': 'My Window',
        'widgets': [
          {
            'name': 'alfresco/logo/Logo',
            'config': {
              'logoClasses': 'surf-logo-large'
            }
          }
        ]
      }
    }
  ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

1. Copy and paste the JSON into the 'Page Definitions' field
2. Click on the 'Preview' button (the preview should be drawn at the top of the page)
3. Enter a name into the 'Page Name' field (e.g. 'FirstPage')
4. Click the 'Save' button
5. Go back to the 'Repository' page and check that the page definition has been created.
6. Open the following URL to view the page: http://<server>:<port>/share/page/hrp/p/FirstPage

You should see the following:

The DND Page Creator

The drag-and-drop page creator effectively does exactly the same as the JSON editor under the covers (e.g. it uses exactly the same Repository based REST API for saving the pages) but the key difference is that each widget that you drag from the 'palette' to the 'canvas' contains it's own configurable snippet of JSON.

I'd recommend watching both the Share Page Creation Live and Share Widget Library sessions from Summit 2013 to get a better understanding of how to use the page creator because it will be much simpler than trying to explain it in writing!

The Underlying Code

I'm not going to initially explain the underlying code but will rather rely on any questions in the comments section to provide assistance. You should be able to review the JSON page definitions and match the widget references to the corresponding source files in 'webapps/share/js/alfresco' (on the web server) or 'slingshot/source/web/js/alfresco' (in SVN).

What should be apparent though is that the pages that are used to create pages are defined using the exact same JSON structure as they themselves render. One file that is worth reviewing is the 'slingshot/config/alfresco/site-webscripts/org/alfresco/share/imports/widget-palette.lib.js' as this is contains all the JSON definitions for the items shown on the palette in the drag-and-drop page creator. The palette only contains a subset of the available widgets but hopefully should outline how it would be possible to define and include additional widgets for selection.

Summary

As I promised at Summit 2013 I've made the page creation code available as soon as possible. I appreciate that this blog post does not provide an in-depth discussion of the underlying code, but hopefully it is enough to whet people's appetite to prompt me with questions for further posts.