The Share Widget Library 5th November 2013 Dave Draper (@_DaveDraper)

A Brief History… Alfresco Surf used in Share 3.0, 3.1 & 3.2 Alfresco Surf becomes Spring Surf (first used in Share 3.3) Initial extensibility features added in 4.0 Dynamic configuration added for 4.1 WebScript refactor for Share 4.2

Share Customization Information http://www.youtube.com/watch?v=rx-uaKTc8xs

The Annual Spring Surf Question… 2 years ago: “Leaving where it is” Last year: “Bringing back” Sept. this year Spring Source had spring clean Currently hosted on Alfresco SVN (private) May branch for first time (if Alfresco goes full Maven)

Why Change? YUI 2 is no longer being developed Creating pages in Share is too hard Accessibility Performance (reduce HTTP requests) Improve re-usability Improve extensibility

What’s Changed? Simple page creation Dynamic dependency analysis in Surf New widget library New customization tools CSS token substitution by Themes

Introducing the new “Widget Library” Over 100 new widgets Most should be considered BETA Will be used for all new Share projects

What is a Widget? JavaScript HTML CSS i18n

Old Widget Granularity

New Widget Granularity

Page Models Introduce the concept of single WebScript pages that define a JSON model comprised of services and nested widgets

JSON Structure Example ID of the definition in the model ID of the root element in the resulting DOM Assigns to a variable of the enclosing widget The widget to instantiate The instantiation arguments Used by the enclosing widget Passed as an argument during instantiation

Single WebScript Pages Can create a page via single WebScript JavaScript controller defined page model

Updated Surf Object Hierarchy Page model WebScript WEBSCRIPT Template Template XML Template is WebScript (NOT Freemarker) Dynamically created Component for WebScript (guarantees binding) Multiple Page/Template definitions (e.g. hybrid, remote, etc) Page XML

URL Tokens

/{pageid}/ws/{webscript} /{pageid}/p/{pagename} Matches URL in WebScript Descriptor /{pageid}/ws/{webscript} /{pageid}/p/{pagename} Matches document name /Data Dictionary/ShareResources/Pages

http://localhost:8081/share/page/hrp/p/LogoPage http://localhost:8081/share/page/rp/p/LogoPage

How Does it Work? Built around the concept of AMD

What is AMD? “Asynchronous module definition (AMD) is a JavaScript API for defining modules such that the module and its dependencies can be asynchronously loaded. It is useful in improving the performance of websites by bypassing synchronous loading of modules along with the rest of the site content. In addition to loading multiple JavaScript files at runtime, AMD can be used during development to keep JavaScript files encapsulated in many different files. This is similar to other programming languages, for example java, which support keywords such as import, package, and class for this purpose. It is then possible to concatenate and minify all the source JavaScript into one small file used for production deployment.” - Wikipedia “It is then possible to concatenate and minify all the source JavaScript into one small file used for production deployment”

<@processJsonModel> This is the single custom Freemarker directive that is used to convert a JSON model into all the resources required to build a page Each widget is an AMD module Resources derived from module

<@processJsonModel> (includes i18n object) JavaScript Bootstrap Surf <@processJsonModel> JavaScript Modules Page Model (includes HTML fragments) CSS Resource (can includes Base64 encoded images)

Dynamic Dependency Analysis “So, how does Surf know what resources are required?”

Dependency Example A B C E D Requesting A results in B, C, D & E being loaded C is only loaded once (despite being depended on twice)

JavaScript “bootstrap” resource JavaScript dependency layer Resource Goals JavaScript “bootstrap” resource JavaScript dependency layer CSS dependencies Image Sprite * These are the optimum resources that will be loaded Image sprites will be in next release (4.2 features CSS encoded images)

What About Performance? Module dependencies cached Minified resources cached Aggregated resources cached Page definitions cached Resources check summed (with infinite expiry) for safe browser caching

Decoupling Widgets for presentation, Services for data/actions Communication via pub/sub or custom event bubbling

“Wait, so you’re NOT using Angular.js ?!?” Nothing against Angular per se

Why Dojo? AMD Accessibility Widget templating Unit testing Inheritence DOES have a healthy Community Backed by BIG companies Same age as Alfresco (8 years old)

(but it’s not just Dojo) All widgets in the library start with the Dojo widget template base Some widgets wrap existing Share widgets Some new widgets use YUI resources (Sidebar container) Some widgets use JQuery (new previewer) Widgets exist that use other 3rd party libraries (ACE/JSON editors)

(and it’s better than just AMD) Surf supports non-AMD dependencies It’s possible for a widget to declare a dependency on any JavaScript resource Surf prevents duplicate resources being loaded multiple times

What Widgets are Available?

Menu Widgets

Form Widgets NOT JUST DOJO

Layout Widgets NOT JUST DOJO

Document Widgets

HTML5 Previewer NOT JUST DOJO

Where are the Widgets?

tomcat/webapps/share/js/alfresco (server) slingshot/source/web/js/alfresco (SVN)

Where is this in Share 4.2?

What Does This Mean for Customization? Use current customization patterns Extension modules targeting JS controllers More tooling Explain broken “delete widget” issue

alfresco/menus/AlfMenuBar alfresco/menus/AlfMenuBarItem third/party/MenuBarItem alfresco/menus/AlfMenuBarItem alfresco/menus/AlfMenuBarItem Can also reconfigure widgets

http://blogs. alfresco http://blogs.alfresco.com/wp/developer/2013/09/04/customizing-the-share-header-menu-part-1/

CSS Theme Tokens

alfresco-dialog-AlfDialog .alfresco-dialog-AlfDialog.dijitDialog { border: $theme-border-1; border-radius: 6px 6px 6px 6px; box-shadow: $theme-box-shadow; font-family: $theme-font-family-2; font-size: $theme-font-size-1; }

<. xml version='1. 0' encoding='UTF-8' <?xml version='1.0' encoding='UTF-8'?> <theme> <title>Light Theme</title> <title-id>theme.lightTheme</title-id> <css-tokens> <theme-font-family-1>Open Sans Condensed,Arial,sans-serif</theme-font-family-1> <theme-font-family-2>Open Sans,Arial,sans-serif</theme-font-family-2> <theme-font-family-3>Open Sans Bold,Arial,sans-serif</theme-font-family-3> <theme-font-size-1>13px</theme-font-size-1> <theme-color-1>#333</theme-color-1> <theme-color-2>#333</theme-color-2> <theme-color-3>#333</theme-color-3> <theme-color-4>#333</theme-color-4> <theme-color-5>#ccc</theme-color-5> share/WEB-INF/classes/alfresco/site-data/themes/lightTheme.xml

So, What’s Next? New UI features will be written using this framework More widgets added (with full unit tests) Accessibility testing Document Library refresh

What Does This Mean For You? Use our widgets to extend Easier to customize our pages Easier to build new pages Easier to contribute to Community

Any Questions? If there’s any time left, open up for Q&A