Skip navigation
All Places > Alfresco Content Services (ECM) > Blog > 2013 > November > 14

This blog is somewhat out of date - the new framework became Aikau and the JSDoc can be found here.

 

Introduction

Any new framework is going to live and die by the strength of it's documentation, so it's important that we try to ensure that we make as much information on the new Alfresco Share widget library available as possible. In an ideal world we'd have have a big team working on the widgets (and the supporting framework) that would include people dedicated to writing blogs, tutorials and documentation for it.  Sadly that's not the case at the moment but we're going to do the best we can to support the Alfresco Community in getting up to speed with this new approach for Alfresco Share development

 

 

Source Documentation

From the outset we wanted to ensure that we provided useful documentation within the source through commenting and JSDoc. Hopefully we've created well-commented code that is easy to read and understand but sometimes it's better to read and navigate comments via a browser through linked files rather than in the source itself. Therefore we've added comments using a JSDoc3 supported syntax that allows us to build a HTML representations of the source documentation.

We haven't included or published this documentation with the release of Alfresco Enterprise 4.2 for a few reasons:

    • We haven't had the time to put together an Alfresco specific template for the HTML output
    • Many of the widgets are still of beta quality (as explained at Alfresco Summit and mentioned briefly in my last post)
    • We're not completely satisfied with the current quality of the existing documentation


I also discovered whilst writing this post that there are still some syntax errors in the comments that prevents the released code from being used to generate the documentation. However, in the spirit of getting information out to the Community early I wanted to provide a sample of what to expect in future releases.

 

 

Writing Widgets Supporting JSDoc3

We encountered a few issues when initially trying to generate the JSDoc due to the AMD-style template that we were using for our source files. This means that we have had to adopt a specific use of the available tags to generate output that meets our needs.

You can browse the source files to get an idea of the tags that we've used, but if you are writing your own widgets and want to document them in a similar style then you should follow these broad guidelines:

    1. Use @module, @extends, @mixes and @author in the root comment block
    2. Use @instance for each function and variable
    3. Use @type and @default for each variable
    4. Use @param and @returns as appropriate for each function

 

Sample JS Doc

You can download a current snap-shot of the widget library documentation here. This was generated using the code currently on the Community SVN trunk (although I need to to fix a few tagging syntax errors that I will commit as soon as possible). Please bear in mind that this is very much a work in progress but as always we welcome your feedback. If you find any issues such as typos, missing links or specific areas where a better explanation is required then please let us know.

by Dave Draper

Introduction



Over the last couple of weeks I've presented a couple of sessions at the Alfresco Summit conferences in Barcelona and Boston. The purpose of these sessions were to socialise the new framework that we're going to be taking for developing the Alfresco Share application going forwards. The PowerPoint slides from these sessions are available at the Summit web site at the following links:


The sessions in Barcelona were also videoed and will be released at some point in the future if you were unable to attend either of the conferences.

Key Points



The key points to take away from the presentations are as follows:



  • It's now possible to create Share pages via a single WebScript that defines a JSON model of widgets and services to include in the page


  • We're going to be continuing to create new widgets for this framework and will be using them for all future Alfresco Share features


  • We're not going to be re-writing all of Share and it will still be possible to create pages using all the old development techniques


  • The majority of widgets that are currently in the Community source should be considered BETA and will be subsequent to change - but we wanted to get some code out to the Community as early as possible


  • Although the framework relies heavily on Dojo, it does not prevent you from developing widgets using any client-side JavaScript framework of your choosing (we've already built widgets using YUI 2, JQuery and ACE)



Page Creation Tools



I've demonstrated two page creation tools that are not included in Alfresco 4.2 - a JSON editor and a drag'n'drop GUI. The tools were created primarily as a means to better demonstrate the power of the widget framework but there have been subsequent requests for these tools to be released to the Community.



[vsw id='iMLk5p9Y9rA' source='youtube' width='425' height='344' autoplay='no']



[vsw id='CPzCFIGOzbM' source='youtube' width='425' height='344' autoplay='no']



Given that these tools are not production quality (they haven't been through our QA process, are not localized and are not accessible) and were not written to meet any specific Alfresco features I'm not going to commit the code to the Community SVN but will instead release them as standalone JAR files.



Unfortunately this won't happen for a few weeks until I can commit some of the supporting code back from development branch to the main Community trunk (otherwise the tools won't work properly). As soon as I make the tools available I'll announce it via the Alfresco Developer Blog and on Twitter.

We Want Your Feedback!



I always stress at the conference sessions how important the Community feedback is to us. This framework is still very much in its infancy and there is plenty of time to contribute to it's development. Our aim is to make it easier to develop and customise Share and we greatly value your comments and criticism and (if you feel we've earned it - your praise! ;) ).



We're aware that there isn't a great deal of documentation around this framework beyond these blogs but we'll endeavour to address this going forwards. If you're trying out the framework either by building page models or writing your own widgets and are struggling with any concepts or code then please start a topic on the forums, raise an issue in JIRA, add comments to this blog or ping me on twitter @_DaveDraper.

Filter Blog

By date: By tag: