Share Page Creation Code

cancel
Showing results for 
Search instead for 
Did you mean: 

Share Page Creation Code

ddraper
Intermediate II
0 16 7,328

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')


Screenshot showing the Repository page in Share

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


    Screenshot showing the JSON editor with page definition and preview

    You should see the following:

    Screen shot showing remotely loaded page

    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.

    16 Comments
    blog_commenter
    Active Member
    Hi Dave,

    I saw your sessions in Barcelona.

    I have a question: JSON files created with DND Page Creator are loaded only from 'Data Dictionary', or there is a way to load static JSON files from a context/config file (like share-config-custom.xml)?



    Thanks

    Federico Tarantino
    ddraper
    Intermediate II
    Hi Federico,



    At the moment this work is really only in the proof-of-concept phase and has yet to be truly 'productized'... if and when it does become a fully supported feature then obviously we'd make the persistence location configurable.



    At the moment the Data Dictionary path is hard-coded into the WebScripts for saving and retrieving the JSON models and can easily be modified (the code itself is very straightforward). I was very careful to intentionally that a number of hoops be jumped through in order for this to be used as is.



    If you just want to use static JSON files then the easiest way currently by defining them in a WebScript and using the 'page/hdp/' path, however I can see an argument for defining these as pure configuration files in the future.



    I hope that adequately answers your question?



    Regards,

    Dave
    blog_commenter
    Active Member
    Hello Dave,

    It's a really good enhancement for Share. I easily succeeded to use the PageCreator for generating basic widgets (logo, menu,...)

    As, at Summit, you also showed us a screen using 'documents' widgets, I tried to investigate further by trying to generate one document list but I did not yet succeeded to have something working. Is it because all of available widgets are not yet operational or probably because I don't know how to use them correctly ?

    If in this case, could you indicate us the steps to generate a simple document list (Just in some words, which widgets can be used and how to imbricate them together) ?

    Thank you.

    Joël
    ddraper
    Intermediate II
    @Joel - you need to make sure that you include the 'Document Service' (dropped into 'Services') and a 'Retrieve Documents' publication dropped into 'Page Load Publications' (start by configuring the 'Data Source' to be 'Well known node' and select 'Company home' as a starting point.



    Then drop a 'Document List' into the widgets and then the 'Simple Document List View' into it and hit the preview... I've just tried that locally (using the JAR) and it's working for me - but please let me know if you have any issues.



    For more advanced stuff (e.g. custom views) then follow along with the Summit video for a guide... but please ask if you have any further questions



    Regards,

    Dave
    blog_commenter
    Active Member
    Hello Dave,

    Following your indications, I succeeded to display the content of company home.

    Then I tried to adjust the parameters so to display the content of documentlibrary of the swsdp site that is provided with 4.3.a version but I currently get a strange issue. Rarely the document list is correcly displayed, and most of the time,  it is only displayed for less than a second and then is replaced by the content of company home.

    Could it be a bug or is it again due to a lack in my configuration ?

    Here is below a copy of the json that I use with the preview option in your page-editor (I don't know if this is the right place in your blog for this).

    Could anybody tell me if he reproduces the same effect or indicate the correction that i should make ?

    Thank you

    Joël





    {

        'widgets': [

            {

                'widgetsForDisplay': [

                    {

                        'name': 'alfresco/creation/DropZone',

                        'config': {

                            'horizontal': true,

                            'initialItems': [

                                {

                                    'defaultConfig': {

                                        'fieldId': '4e74593d-333c-49bb-86fe-5e34b18d35f0'

                                    },

                                    'widgetsForConfig': [],

                                    'module': 'alfresco/documentlibrary/views/AlfSimpleView',

                                    'widgetsForDisplay': [

                                        {

                                            'name': 'alfresco/html/Label',

                                            'config': {

                                                'label': 'Simple View'

                                            }

                                        }

                                    ],

                                    'previewWidget': false,

                                    'name': 'Simple Document List View',

                                    'type': [

                                        'widget'

                                    ]

                                }

                            ]

                        }

                    }

                ],

                'name': 'alfresco/documentlibrary/AlfDocumentList',

                'config': {

                    'site': 'swsdp',

                    'widgets': [

                        {

                            'widgetsForDisplay': [

                                {

                                    'name': 'alfresco/html/Label',

                                    'config': {

                                        'label': 'Simple View'

                                    }

                                }

                            ],

                            'name': 'alfresco/documentlibrary/views/AlfSimpleView',

                            'config': {

                                'fieldId': '4e74593d-333c-49bb-86fe-5e34b18d35f0'

                            }

                        }

                    ],

                    'sortField': 'cm:name',

                    'page': '1',

                    'container': 'documentlibrary',

                    'sortAscending': 'false',

                    'path': '/',

                    'pageSize': '4',

                    'fieldId': 'f50bd8a3-9d16-4f87-8c98-b0e4c3f1c0c7',

                    'type': 'all',

                    'filter': {

                        'filterData': '',

                        'filterId': 'path'

                    }

                }

            }

        ],

        'services': [

            {

                'widgetsForDisplay': [

                    {

                        'name': 'alfresco/html/Label',

                        'config': {

                            'label': 'Document Service'

                        }

                    }

                ],

                'name': 'alfresco/services/DocumentService',

                'config': {

                    'fieldId': 'f3332148-1dcb-411a-87d4-924a9a93ffce'

                }

            }

        ],

        'publishOnReady': [

            {

                'publishTopic': 'ALF_RETRIEVE_DOCUMENTS_REQUEST',

                'widgetsForDisplay': [

                    {

                        'name': 'alfresco/html/Label',

                        'config': {

                            'label': 'Retrieve Documents'

                        }

                    }

                ],

                'publishPayload': {

                    'site': 'swsdp',

                    'sortField': 'cm:name',

                    'page': '1',

                    'container': 'documentlibrary',

                    'sortAscending': 'true',

                    'pageSize': '5',

                    'type': 'all',

                    'filter': {

                        'filterData': '/',

                        'filterId': 'path'

                    }

                }

            }

        ]

    }

    ddraper
    Intermediate II
    @Joël - I'll try to find some time to look into this issue, however I would say that if you're configuring the 'alfresco/documentlibrary/AlfDocumentList' widget with details of the site and container then you shouldn't need the publishOnReady - this probably explains the reload effect that you're seeing. However, I'm not sure why the data isn't rendering correctly. The currently on the Community trunk is still a little way behind the latest code that we have so it could be that something is coming down the line that will fix the problem. 



    Also, please bear in mind that this isn't production ready code yet - we're just trying to get some interesting ideas out to the Community, and there are bound to be a few bugs! : )
    blog_commenter
    Active Member
    Hi Dave,



    I want to create a page having some fields with Save button to persist data into repository.

    I have used page-creator to create the same,I dragged the text and button widgets saved the page.

    But when i try to access and click save, nothing is happening.

    I guess i have to some services, in my requirement i have to use FormService but i don't see the FormService widget in the services section.

    Can you guide me?



    regards,

    Ashwini
    ddraper
    Intermediate II
    @Ashwini... first of all, it's worth bearing in mind that the Share creation code is more an example of what can be achieved by using Aikau rather than as a fully fledged page builder. There is no forms service as such within Aikau - I think you should probably work through some of my more recent blog posts with examples on creating and saving data via Aikau forms (I'd recommend starting here: https://www.alfresco.com/blogs/developer/2014/09/26/aikau-mini-examples-simple-form/ and working through all the subsequent blogs that I've written, reviewing the samples).



    Currently the page creation tools are not intended as a complete solution for creating pages for Share.
    blog_commenter
    Active Member
    Thanks Dave!

    I referred  the your example for datalist.

    Able to create a share page using Aikau to insert user defined values and stored in the document library.

    Now i need to read those values and display. But i couldn't achieve .



    I have used the following url to store the values, /slingshot/doclib/container/test/documentLibrary -- to insert data.

    Tried to fetch the stored values but i don't see the custom fields data, except title and description.



    slingshot/doclib/doclist/capa%3AcapaFolder/site/test/documentLibrary  -- to read data

    If i use the following share url,

    http://localhost:8080/share/service/components/documentlibrary/data/doclist/all/site/demo/documentLi...

    Am able to see the custom fields.Don't know which repository webscripts is it calling internally.



    Can you please tell me which webscript i have to call to read the data stored in the documentlibrary?
    blog_commenter
    Active Member
    Is it possible to call share services from the share side webscripts (Javascript).?

    If it is yes, can you please tell me how?
    blog_commenter
    Active Member
    How to add a Assignee using Aikau, any specific widgets do i need to use?

    I referred the datalist example, during the new item creation i want to add the assignee and persist in the repository.

    How i can achieve this?

    Thanks in advance.
    ddraper
    Intermediate II
    @Ashwani - this isn't really the write place for this sort of questions, it has nothing to do with the blog post. Try the IRC channel or the Alfresco forums.
    ddraper
    Intermediate II
    @Ashwani – this isn’t really the write place for this sort of questions, it has nothing to do with the blog post. Try the IRC channel or the Alfresco forums.
    ddraper
    Intermediate II
    @Ashwani - again, I'm happy to answer specific questions on the blog content, but this isn't a support channel Smiley Happy
    blog_commenter
    Active Member
    OK. Sorry for posting here in blog.

    I have posted few questions in the alfresco forum related to Aikau and am using Alfresco5.0c(community).

    Can you please guide me?
    blog_commenter
    Active Member
    […] A good example for Aikau is Share Page Creation Code […]