Quickly Customizing Alfresco


Published on

Find out how easy it is to brand a Share installation. We will create a custom theme using CSS and a Tag cloud dashlet implemented as a simple WebScript that you can later add to the dashboard.

Published in: Technology, Design
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Applicable for any Share JS module, not just dashletsObjects created are namespaced within Alfresco.dashlet scopeVariables and functions are scoped by enclosing within functions (variable scope in JavaScript is function-wide)Aliases declared at start of module – keeps code shorterConstructor sets up the object – unique object ID is passed inoptions property used to set parameters for a particular instance of the object (as we could have more than one on a page)onReady() function called by YUI when the parent element is available for scripting, usually used to add further listeners to particular Dom elements and set up YUI widgetsOther functions may define additional behaviour and be called by onReady()Other functions will define event handlers that are attached to objects
  • Client-side JS source/web/components/dashlets/site-tags.jsAlias Dom and Event YUI classes which are used heavily within the moduleAlias html() and combine() Alfresco util functionsDeclare preference key values used as constantsConstructor is standardOptions holds max number of tags to show, plus parameters for sizing each tag displayed (use fixed font-sizes for the least-occurring and most-occurring tags, with a linear algorithm for tags in-between)Container <div> Dom element that is frequently used is cached as tagsContaineronReady() initialisestagsContainer, Adds event listeners to form controls, initialises YUI widgets and fires off loading of tags via XHRonRefresh() provides event handler when a user clicks the refresh buttonrefreshTags() does the work of refreshing the tags, loading data via Alfresco.util.Ajax.jsonGet() onTagsSuccess() and onTagsFailed() provide the async call-backs for the JSON callgetUriTemplate() is a convenience method to return the URL that a tag should be hyperlinked to in the UIupdateFilterUI() sets the active filter highlight in the UIsetActiveFilter() persists the new active filter (using prefs as well as local option val), calls updateFilterUI() and refreshes the list of tagsonAllCheckedChanged(), onFilterClicked() and onFilterChanged() provides event handlers for when users change the tag filters in the UIWeb script config/alfresco/site-webscripts/org/alfresco/components/dashlets/site-tags.getThe Tag Cloud dashlet. Renders a container for the tag cloud and instantiates the JS object to start doing the real work.
  • Client-side JS source/web/components/dashlets/twitter-user-timeline.jsAlias Dom and Event YUI classes which are used heavily within the moduleAlias html() and combine() Alfresco util functionsConstructor is standardOptions holds the currently-configured Twitter username, plus a default username if the user clears the current configurationContainer <div> Dom element that contains the Twitter stream, plus the dashlet title Dom element are cached as timeline and title.onReady() initialisestimeline and title, calls refreshTimeline() and adds event listener to the ‘Configure’ link in the UIonRefresh() provides event handler when a user clicks the refresh buttonrefreshTimeline() does the work of refreshing the twitter stream, making an AJAX request to the second ‘data’ web script via Alfresco.util.Ajax.request() onTimelineLoaded() and onTimelineLoadFailed () provide the async call-backs for the JSON callonConfigClick() does the work of attaching the config dialogue to the ‘Configure’ link. All behaviour of the dialogue is programmed in here declaratively, including loading the config dialogue web script and persisting the configuration when the ‘OK’ button is clicked.Web script config/alfresco/site-webscripts/org/alfresco/components/dashlets/twitter-user-timeline.getThe Twitter User dashlet. Really just acts as a container for the Twitter stream and instantiates the JS object.Web script config/alfresco/site-webscripts/org/alfresco/components/dashlets/twitter-user-timeline-list.getReturns the actual user timeline of a specific Twitter user in HTML formatWeb script config/alfresco/site-webscripts/org/alfresco/modules/dashlets/config-twitter-user-timeline.getRenders the config dialogue UI for configuring the Twitter User dashlet
  • Directory source/web/themes/redThemeAll your theme assets live here – CSS and imagesThese can be copied over from existing themes (But if copying from the default theme several files and directories will be missing from the ‘yui’ directory. Other themes have these already.)Style sheet source/web/themes/redTheme/presentation.cssMost styles defined by the theme are in here. Note many style classes are defined within a container .yui-skin-redTheme. If you create your own theme based on another, you will need to do a find-and-replace to change this class name throughout the file, e.g. to .yui-skin-myCustomTheme.Line 881 – set background of main title bar.theme-bg-color-1,div.theme-bg-color-1{ background-color: #ef1216;}Line 456 – background of buttons displayed on main title bar.yui-skin-redTheme .title-button .yui-button{ background: transparent url(images/title-button-bg.png) repeat-x 0 0;}Line 311 – set colour/background of site navigation barPick a lighter colour than the main navigation bar - Around 50% opacity of main colour works well.site-navigation{ background-color: #f7898b; /*background-image: url(../../components/images/navigation-bg.png);*/ border-bottom: 1px solid #f34d50; border-top: 1px solid #b50e11;color: white;}Colour of navigation links set following thisLine 109 – Dashlet title bars background.dashlet .title{ background-color: #d7e0e7; background-image: url(images/dashlet-title-bg.png); background-repeat: repeat-x; border-bottom: 1px dashed #bababa;color: #262d35;}Stylesheet source/web/themes/redTheme/yui/skin.cssOther YUI-specific style definitions. Again, developers must perform a find-and-replace based on the theme name in this file, if copied from elsewhere.Images in source/web/themes/redTheme/imagestitle-bg.png – Background for the title bar (not used in red theme)title-button-bg.png – buttons appearing on the title bar – 1x48 gradient imagedashlet-title-bg.png – Dashlet title bar background (not customised)app-logo.png – Application logo used in the main application (not customised)logo.png – Logo used on login page (not customised)loginbg.png – Background of login page (not customised)
  • Quickly Customizing Alfresco

    1. 1. Quickly Customizing Alfresco Share<br />2<br />AingaranPillai<br />Founder, Zazi<br />twitter: @apillaiz<br />
    2. 2. Use case: Adding Simple Extensions<br />3<br /><ul><li>Based on Alfresco Share v3.3
    3. 3. Simple Extensions
    4. 4. Practical Examples – Tag Cloud, Twitter Feed, Red Theme</li></li></ul><li>What’s an Extension?<br />4<br />Anything utilising a general Share extension point<br />Custom Dashlets<br />Custom Themes<br />Document Library actions<br />Custom page components (see Advanced Customizationpresentation)<br />Share Header (new in 3.4)<br />Scriptable, templatable<br />No Java involved!<br />Easily deployable (JARs/AMPs)<br />
    5. 5. Tag Cloud Dashlet<br />5<br />Site Dashlet<br />Displays dynamic data<br />Tags associated with the current site, as a tag cloud<br />Loads data from repository via existingRESTful API<br />GET /alfresco/service/api/tagscopes/site/{site}/tags<br />GET /alfresco/service/api/tagscopes/site/{site}/{container}/tags<br />Business logic could be implemented entirely in the web tier<br />But better using client-side JavaScript<br />Allows ‘refreshing’ of data<br />Deploy as a JAR<br />
    6. 6. 6<br />
    7. 7. Typical Dashlet Pattern<br />7<br />(function()<br />{<br /> ...<br />Alfresco.dashlet.SiteTags = functionSiteTags_constructor(htmlId)<br /> {<br />returnAlfresco.dashlet.SiteTags.superclass.constructor.call(this, "Alfresco.dashlet.SiteTags", htmlId);<br />};<br />YAHOO.extend(Alfresco.dashlet.SiteTags, Alfresco.component.Base,<br />{<br /> options:<br /> {<br /> ...<br /> },<br />onReady: function SiteTags_onReady()<br />{<br /> ...<br /> },<br /> ...<br /> }<br />}<br />
    8. 8. Code Walk Though<br />8<br />Client-side JS source/web/components/dashlets/site-tags.js<br />Web script config/alfresco/site-webscripts/org/alfresco/components/dashlets/site-tags.get<br />
    9. 9. Twitter Feed Dashlet<br />9<br />Generic Dashlet (User or Site dashboards)<br />Displays last ten tweets of a specific user<br />Loads data from Twitter JSON API<br />GET /alfresco/service/api/tagscopes/site/{site}/tags<br />GET /alfresco/service/api/tagscopes/site/{site}/{container}/tags<br />Data loading performed by a second ‘list’ web script<br />Dashlet web script just acts as a container<br />Allows simple refreshing of data<br />Configuration dialogue UI to set Twitter username<br />Yet another web script!<br />Glue it all together using client-side JavaScript<br />Deploy as a JAR<br />
    10. 10. 10<br />
    11. 11. Code Walk Though<br />11<br />Client-side JS source/web/components/dashlets/twitter-user-timeline.js<br />Web script config/alfresco/site-webscripts/org/alfresco/components/dashlets/twitter-user-timeline.get<br />Web script config/alfresco/site-webscripts/org/alfresco/components/dashlets/twitter-user-timeline-list.get<br />Web script config/alfresco/site-webscripts/org/alfresco/modules/dashlets/config-twitter-user-timeline.get<br />
    12. 12. Dashlet Development Considerations<br />12<br />How should I load my data?<br />Web tier only for simple dashlets<br />Complement with client-side JavaScript where needed<br />More client-side JS allows richer user experience and shifts processing burden onto the clients<br />What format? JSON, XML or direct HTML?<br />What configuration parameters can be applied?<br />e.g. Number of tags, default Twitter user<br />Configuration dialogue allows users to change it<br />Store default values in .config.xmlfile<br />Are any user preferences required?<br />
    13. 13. Custom Red Theme<br />13<br />Custom Theme for Alfresco Share<br />Provides custom CSS plus (optional) images<br />Allow selection of theme in Admin Console<br />Deploy as an AMP (not a JAR)<br />
    14. 14. Custom Theme Walk-Through<br />14<br />Changing the title bar colour/background<br />Changing the site navigation bar<br />Changing the hyperlink colour<br />Changing the default logos<br />YUI Controls<br />YUI Tree controls<br />YUI Buttons<br />YUI Menus<br />
    15. 15. 15<br />
    16. 16. Code Walk Though<br />16<br />
    17. 17. Packaging Extensions<br />17<br />Always package simple extensions in JAR format where possible<br />Share Extras uses a standard source structure and Ant built script to acheivethis<br />Some extensions (e.g. Custom themes) cannot be packaged as JARs - use AMP files instead<br />Use a build process to do the hard work<br />Create directory structures<br />Create JAR/AMP files<br />JavaScript compression<br />See example in Share Extras projects<br />
    18. 18. Tools<br />18<br />Use whatever tools you like, BUT<br />Separate your source from your deployment<br />Do not develop inside the webapp!<br />Use a source code management tool<br />Use a standard project structure<br />Build tools (e.g. Ant) can help you<br />JavaScript/FreeMarker code completion/syntax checking will save you a LOT of time<br />Eclipse can do all of this<br />Test across different browsers<br />Firefox/Firebug and Google Chrome are best for debugging<br />
    19. 19. General Points<br />19<br />Share is a powerful platform<br />But modularity leads to a lot of files<br />You may want to copy/paste from similar areas of functionality<br />Don’t forget to document!<br />
    20. 20. More Information<br />20<br />Share Extras project - http://code.google.com/p/share-extras/<br />Advanced Share Customisation<br />Using Forms in Share<br />