Customizing the Document Library

1. Customizing the Document Library1Mike HatfieldSenior Software Engineer, Alfrescotwitter: @mikehatfield

2. Customizing the Document Library2What We’ll Cover Architecture

3. Challenges to customization and extensionPlans for improvement Case Study: the DoD 5015.2 Extensions

4. Extension Example Status Indicators Custom Actions Custom Metadata Filters

5. Architecture3

6. Architecture4Heavy Use of YUI for “Web 2.0” ExperienceMany JavaScript frameworks evaluatedOnly YUI had a full-time staff, full API documentation, supported UI widgetsMany YUI widgets and modules usedDataTableTreeviewButtons, Menus, ContainersHistory Manager for “AJAX back button” supportXHR wrappers, JSON parserMost HTML rendering performed client-side

7. yuilibrary.com is your friend!Architecture5Initial Page LoadCreate all YUI controls

8. Register event handlers

9. Extract URL arguments

10. Bubbling Event  “changeFilter”

11. onChangeFilter: updateDocList()

12. Webscript URL (via proxy)  YUI DataSource

13. Repository webscripts execute for given filter & params

14. Bubbling Event  “filterChanged”

15. Render JSON response using DataTable cell renderersArchitecture6Subsequent Navigations (e.g Folder)Bubbling Event  “changeFilter” [new filter params]

16. onChangeFilter: Build data webscript URL

17. History Manager  multiNavigate()

18. onHistoryManagerFilterChanged: updateDocList()

19. Webscript URL (via proxy)  YUI DataSource

20. Repository webscripts execute for given filter & params

21. Bubbling Event  “filterChanged”

22. Render JSON response using DataTable cell renderersArchitecture7YUI DataTable RenderersOne renderer per data columnSelected file / folderStatus indicatorThumbnail / iconMetadata descriptionActionsRender XSS-safe HTML from parsed JSONelCell.innerHTML = “<div>…</div>”YUI wraps output in <table><tr><td> tagsArchitecture8ActionsCurrently defined in webscript config xml filesSeparate configs for browse page, details pagesAction Sets based on repository business logicevaluator.lib.js“document”, “folder”, “locked”, “workingCopyOwner”, etc.Two action types“simple-link” URL via getActionUrls(){downloadUrl}, {viewUrl}, {folderDetailsUrl}“action-link” JavaScript function  “id” attributeID attribute defines action icon and JavaScript functionArchitecture9ActionsPermissionsComma-separated listUser AND asset must have ALL permissions for action to appear“Virtual” permissions as well as role-basedcreate, edit, delete, permissions, cancel-checkoutinline-edit, simple-approve, googledocs-editNegative permission via tilde (~)~filter-path, ~portlet, ~googledocs-editLabel attribute for I18N messageCurrent Extension Points10Custom UINew FiltersNew ActionsCustom UINew FiltersNew ActionsCustom UINew ActionsNew ActionsNew Filters

23. Plans for Improvements11 Consolidate scattered action configurationshare-config-custom.xml instead of webscriptconfigStill possible to restrict & specialise actions on details pages New actions via configuration where practicablejar file for client-side UI assets, I18NCSS and JS dependencies via config (see Forms & Header) Leverage Repository Actions & scripts

24. Custom ViewsWeb-tier renderingOpen CMIS

25. Case Study: DoD 5015.2 Extensions12

26. Case Study: DoD 5015.2 Extensions13Custom ActionsNumerous new and overridden actions to support the DoD requirements specification.

27. Case Study: DoD 5015.2 Extensions14Custom ToolbarSensitive to current folder type. New and overridden actions.Custom FiltersRemoved unsuitable filters (user filters, tags). One static, one dynamic (populated from list of saved searches on the Repository).

28. Case Study: DoD 5015.2 Extensions15“documentLibrary” container type determines components

29. Case Study: DoD 5015.2 Extensions16

30. Template: documentlibrary17documentlibrary.jsconnector.get("/slingshot/doclib/container/" + siteId + "/" + containerId);"dod:filePlan"model.doclibType = fromRepoType("dod:filePlan");“dod5015”documentlibrary.ftl<@region id=doclibType+ "documentlist" scope="template" protected=true />Surf Component Bindingtemplate.dod5015-documentlist.documentlibrary.xml<url>/components/documentlibrary/dod5015/documentlist</url>

31. Creating the Container18DoD 5015.2 Methodpresets.xml<preset id="rm-site-dashboard"> <page id="site/${siteid}/dashboard"> <properties> <pageMetadata>{"documentlibrary":{…, "type":"dod5015"}}</pageMetadata> documentlibrary.jspage = sitedata.getPage("site/" + siteId + "/dashboard");pageMeta = eval('(' + p.properties.pageMetadata + ')');contentType = doclibMeta.type;connector.get("/slingshot/doclib/container/" + siteId + "/" + containerId+ “?type=“ + toRepoType(contentType));”dod:filePlan”

32. Creating the Container19Web QuickStart Methoddashletconnector.get("/api/loadwebsitedata?site=" + siteId);LoadWebSiteDataGet.javaNodeRefdocLib = siteService.getContainer(siteId, COMPONENT_DOCUMENT_LIBRARY);siteService.createContainer(siteId, COMPONENT_DOCUMENT_LIBRARY, WebSiteModel.TYPE_WEBSITE_CONTAINER, null);ornodeService.setType(docLib, WebSiteModel.TYPE_WEBSITE_CONTAINER);

33. Case Study: DoD 5015.2 Extensions20YUI HelpsYUI developers added a number of helper functions to allow OO-style JavaScript modules. Notice:constructorsuperclassextendaugmentetc…

34. Component Replacement Approach21Full override / replacement control on all tiers.Your code can be almost completely independent of Alfresco’s.ProsMandatory component mapping , even for “native” components.Still have to copy/paste where <include> cannot be used, e.g. I18N.Repository folder type to component prefix issue.Not a 100% “clean” override mechanism.Cons

35. Mandatory Component Mapping22Big Development Overheadtemplate.dod5015-actions-common.documentlibrary.xmltemplate.dod5015-documentlist.documentlibrary.xmltemplate.dod5015-file-upload.documentlibrary.xmltemplate.dod5015-fileplan.documentlibrary.xmltemplate.dod5015-flash-upload.documentlibrary.xmltemplate.dod5015-html-upload.documentlibrary.xmltemplate.dod5015-navigation.documentlibrary.xmltemplate.dod5015-savedsearch.documentlibrary.xmltemplate.dod5015-title.documentlibrary.xmltemplate.dod5015-toolbar.documentlibrary.xmltemplate.dod5015-tree.documentlibrary.xml…And that’s just the browse page!

36. Extension Example23 Overview

37. Customisations Status IndicatorsCustom MetadataNew FiltersCustom Action Based on Alfresco Community 3.4.b

38. Need to use AMP on the Repository until refactoring work is complete

39. Share extensions via .jar and web-extension folderExtension Example: Photography24Overview

40. DemoOut-of-the-box Share25

41. Extension: Status Indicators 26Provide the user a quick indication of the current status of a folder or document, e.g. aspects applied.Calculated in evaluator.lib.jsRepository

42. evaluator.lib.js

43. Share

44. I18N messages

45. Indicator imagesRepository: Override evaluator.lib.js27/* Exif metadata */if (node.hasAspect("exif:exif")){status["exif"] = true;}/* Geographic */if (node.hasAspect("cm:geographic")){status["geographic"] = true;}

46. Share: Indicator images28status[”exif"] = true;status["geographic"] = true;share.jar!/META-INF/components/documentlibrary/imagesexif-indicator-16.pnggeographic-indicator-16.png

47. Share: Add I18N messages29share.jar!/org/springframework/extensions/surf/custom-slingshot-geographic-context.xml<bean id="geographic.custom.resources" class="org.springframework.extensions.surf.util.ResourceBundleBootstrapComponent"> <property name="resourceBundles"> <list> <value>alfresco.messages.geographic</value> </list> </property></bean>share.jar!/alfresco/messages/geographic.propertiestip.geographic=Geo Locationtip.exif=EXIF Metadata

48. Extension: Custom Metadata30Rendered entirely by the web browser from JSON data.Repository

49. item.lib.ftl

50. Maybe also JavaScript logic

51. Share

52. I18N messages

53. Override cell rendererRepository: Override item.lib.ftl31alfresco.amp!/WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/slingshot/documentlibrary/item.lib.ftl<#if node.hasAspect("cm:geographic")>“geolocation”:{ "latitude": ${(node.properties["cm:latitude"]!0)?c}, "longitude": ${(node.properties["cm:longitude"]!0)?c}},</#if><#if node.hasAspect(”exif:exif")>“exif”:{ …},</#if>

54. Share: Reference extension JavaScript32shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/components/documentlibrary/actions-common.get.head.ftl<@script type="text/javascript" src="${page.url.context}/res/components/geographic/geographic-extension.js"></@script>

55. Share: Override cell renderer33Override fnRenderCellDescriptionshare.jar!/META-INF/components/geographic/geographic-extension.jsYAHOO.util.Event.onContentReady("alf-hd", function(){ if (Alfresco.DocumentList) {Alfresco.DocumentList.prototype.fnRenderCellDescription = function DL_fnRenderCellDescription() { … if (record.exif) {desc += scope.msg(“detail.exposure”) + record.exif.exposureTime; } … } }}

56. Extension: New Filter34Allow easy filtering by any Repository logic, most commonly a Lucene or Alfresco FTS search query.Repository

57. filters.lib.js

58. Share

59. I18N messages

60. Filter webscriptconfigShare: Filter webscriptconfig35shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/components/documentlibrary/filter.get.config.xml<filters> … <filter id="geo" label="link.geo-located" /> <filter id="exif" label="link.exif" /> …</filters>

61. Repository: Filter webscript override36alfresco.amp!/WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/slingshot/documentlibrary/filters.lib.jscase "geo":filterQuery = "+PATH:\"" +parsedArgs.rootNode.qnamePath + "//*\"";filterQuery += "+ASPECT:\"cm:geographic\"";filterParams.query = filterQuery break;case "exif":filterQuery = "+PATH:\"" +parsedArgs.rootNode.qnamePath + "//*\"";filterQuery += "+ASPECT:\"exif:exif\"";filterParams.query = filterQuery break;

62. Extension: Custom Action37Can be configured to only appear if a folder or document is in a particular state and/or the user has the correct permission(s) and/or the page is within a Site context and/or the action is on the browse or details page.Repository

63. evaluator.lib.js

64. Action processing (optional)

65. Share

66. I18N messages

67. Action configuration

68. Client-side logic & imagesRepository: Override evaluator.lib.js38/* Geographic */if (node.hasAspect("cm:geographic")){status["geographic"] = true;permissions["geographic"] = true;}

69. Share: Action configuration39shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/components/documentlibrary/documentlist.get.config.xmlshared/classes/alfresco/web-extension/site-webscripts/org/alfresco/components/document-details/document-actions.get.config.xmletc…<actionSet id="document"> … <action type="simple-link" id="onActionGeographic" permission="geographic" href="{geographicUrl}" label="actions.document.geographic" /></actionSet>

70. Share: CSS and JS dependencies40shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/components/documentlibrary/actions-common.get.head.ftl<@link rel="stylesheet" type="text/css" href="${page.url.context}/res/components/geographic/geographic-extension.css" />share.jar!/META-INF/components/geographic/geographic-extension.css.doclist .onActionGeographica{ background-image: url(pin.png) !important;}

71. Share: Proxy JavaScript function41var override = Alfresco.DocumentList || Alfresco.DocumentActions;// Store reference to getActionUrls() function to allow extension.vargetActionUrls_geo = override.prototype.getActionUrls;override.prototype.getActionUrls = function(recordData){varactionUrls = getActionUrls_geo.apply(this, arguments);actionUrls["geographicUrl"] = Alfresco.util.siteURL( "geographic-map?nodeRef=" + recordData.nodeRef); return actionUrls;};

72. DemoNew Extensions42

73. The End Result43

74. Roadmap44 Consolidate scattered action configuration

75. New actions via configuration where practicable

76. Remove references to non-core Share code

77. Leverage Repository Actions & scripts

78. Custom ViewsQ & A45FeedbackLearn More46wiki.alfresco.com/wiki/Shareblogs.alfresco.com/wp/mikeh/

Customizing the Document Library

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to Customizing the Document Library (20)

More from Alfresco Software (20)

Recently uploaded (20)

Customizing the Document Library

Editor's Notes