` element with the text.
924 |
925 | `src/main/amp/web/js/example/widgets/RenderWidget.js`
926 |
927 | define(["dojo/_base/declare",
928 | "dijit/_WidgetBase",
929 | "alfresco/core/Core",
930 | "dojo/_base/lang",
931 | "alfresco/tutorial/_TopicsMixin",
932 | "dojo/dom-construct",
933 | "dijit/_TemplatedMixin",
934 | "dojo/text!./templates/RenderWidget.html"
935 | ],
936 | function(declare, _Widget, Core, lang, _TopicsMixin, domConstruct, _Templated, template) {
937 | return declare([_Widget, Core, _TopicsMixin, _Templated], {
938 |
939 | templateString: template,
940 | i18nRequirements: [ {i18nFile: "./i18n/PubSub.properties"} ],
941 |
942 | buildRendering: function example_widgets_renderWidget__buildRendering() {
943 | this.renderWidgetHeading = this.message('renderWidget.heading');
944 | this.inherited(arguments);
945 | },
946 |
947 | postCreate: function example_widget_renderWidget__postCreate() {
948 | this.alfSubscribe(this.TutorialTopic, lang.hitch(this, "_onPayloadReceive"));
949 | },
950 |
951 | _onPayloadReceive: function example_widgets_renderWidget__onPayloadReceive(payload) {
952 | var txt = domConstruct.create( "p", { innerHTML: payload }, this.payloadContainer );
953 | }
954 |
955 | });
956 | });
957 |
958 |
959 |
960 | For the final result, access the page on [http://localhost:8081/share/page/hdp/ws/pub-sub-example](http://localhost:8081/share/page/hdp/ws/pub-sub-example). There will be a textarea and a publish button. Enter something into the textarea, click the publish button, and the result will be rendered on the right side of the page:
961 |
962 | 
963 |
964 |
965 | # Part Three: Extending JSON models
966 |
967 | Now that we know a lot more about how to build pages and utilize the Aikau framework, let's back up and think about the JSON page definition. It's nice that we can define new pages, but what happens once Alfresco starts to really work the Aikau framework into Share? We still want to be able to extend it.
968 |
969 | As of 4.2.f, the only component that uses Aikau is the header. Now, what is the header component exactly?
970 |
971 | 
972 |
973 | The header component consists of the black top menu and the logo/title/buttons below it. It's defined in `WEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/header/share-header.get.js`.
974 | This file is pretty simple. It includes `WEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/imports/share-header.lib.js` which is where all the magic happens.
975 |
976 | Now, the header is a big component. It handles everything from the menu, user dashboard title, site title, buttons etc, so there is a lot of code there. In the end it ends up with a big JSON page model definition, but the definition is too big to go through all of it.
977 |
978 | Luckily, we have some very good options for extending a JSON model, instead of overwriting it. First of all, we need to create a Share module extension that will define which customizations we have and which files to target. This is done in an XML file in the `src/main/amp/config/alfresco/web-extension/site-data/extensions/` folder. Once it has been created, we need to create a javascript file where we can use a new root scoped object called `widgetUtils`, which allows us to find components in an existing JSON model and work with it.
979 |
980 | ## Creating an extension
981 |
982 | To extend any web script in Share, we need to define a custom extension module. Create a new XML file ending in `src/main/amp/config/alfresco/web-extension/site-data/extensions/` like this:
983 |
984 | This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/. Alfresco Share is a great front end for the Alfresco Repository. Out of the box it comes with full collaboration features, content management, and pretty much what you would expect for a full blown Enterprise Content Management System. Different users have different needs. Sometimes you'll want to add a few buttons and create a theme, but from time to time developers need to make significant user interface customizations to meet business requirements. Up until recent releases this would prove to be a challenge, and many developers chose to go down a different path and write a UI from scratch using a framework and language of their choosing. The new page and widget framework (Aikau) in Share provides a great way to create a complete custom interface, but keeps the code - and the users, within Share. This tutorial assumes knowledge of the Alfresco Maven SDK, or an existing development setup. All examples in this tutorial are available with full source which can be built with Maven. For a full tutorial on how to work with the Maven SDK, please see Jeff Potts' excellent tutorial on the subject. A few people have helped getting this article done: And of course all of the members of the Alfresco Community! To make sure everyone can understand and relate to the code in this tutorial, here is a description of the tools used for building these examples, and the file structure within the examples. While writing this tutorial the following tools have been used: All examples in this tutorial are available on GitHub. The Maven SDK will provide us with the initial directory structure, which contains some sample data. For all examples in this tutorial the sample data has been removed, and the Here are some notes on what goes where: Clone the code from GitHub, make sure you have an Alfresco instance running on port 8080, enter the This will build an AMP file, then apply the amp to the Share war-file, and startup an embedded Tomcat instance. Normally, Tomcat will run on the default port 8080, but since Alfresco is already running on that port, we need to change this. This can be done either by giving the port number as an argument to Maven, or defined in the The Tomcat port number is defined in With this in place, Tomcat will run on port 8081. Once Tomcat has started Share is accessible on http://localhost:8081/share. To shut down it down, simply hit CTRL+C. Share is a great frontend for Alfresco, but sometimes it doesn't meet a specific business requirement. A common use case is the need for a completely separate page to display custom metadata on a set of nodes, where the built in search or repository browser isn't enough. Many people end up writing separate applications outside Share to meet these requirements, because there is a lot of work involved in making a custom page in Share. If you have worked with Share in the past, you may be familiar with the Surf Framework. Defining a page using Surf requires template instances, regions, and components. Using the new widget framework, a single web script defines a page. This makes it much easier to develop custom pages that meets all business requirements, while still keeping the users inside the Share application. This chapter will focus on how to create a custom page in Share with a single web script and go through the JSON model that is used to setup the widgets on the page. Let's create a page named "Simple page", with a "Hello World" button. Create a new web script "simple-page", like this: Start up Share via Maven with this command: Navigate to Simple page with a widget The example above is the basic setup of a page with the new page model. Let's review what we just did. The web script defines a JSON model for a page. The JSON model consists of widgets, and their configuration. In this example we defined a single button-widget with a simple configuration which defines the label of the button. Widgets can be nested (if the widget supports it). This could be used to define the overall layout of the page, or define a simple widget to split widgets up into columns. Share provides a number of layout widgets, for example, sidebar container, left-and-right, tabs, vertical/horizontal etc. Since there is yet to be proper documentation on this, all widgets can be found in the source for Share. The freemarker template is really simple. It calls the After seeing the first example, the obvious question is how to add the Share header and footer. Luckily, this is not something you need to define manually. Share enables you to render pages in different contexts, which means the URL will determine how the page is rendered. Notice the URL The first part, "dp", defines that we want a dynamic page. This will render the page in a stand-alone manner, useful for embedding the page into other applications, or creating a complete custom interface for specific needs but, still in the Alfresco/Share ecosystem. The second part, "ws", means that we want to load the page from a web script. It's possible to remotely load the pages from the repository. That way we can create pages and store them within Alfresco and have them rendered. To add the Share header and footer simply switch the "dp" with "hdp": The result looks like this: Simple page with a widget rendered with header and footer The Share header widget is currently (as of 4.2.f) the only component in Share using the new Aikau framework. The header includes the menu bar, search, logo, and title. If we wish to add a title next to the logo, we'll need to define a title widget, which Share will take into account when rendering it with the header. If the page is rendered without the header, it simply ignores the widget. To add the title to our simple page, modify the JSON model and add the title: After restarting Share, the result looks like this: Simple page with a widget and title To add a simple horizontal layout we can use the The JSON model in The result looks like this: Simple page two widgets in a horizontal layout Notice how the widgets are nested inside each other. The As mentioned above, the only component in Share (as of 4.2.f) using the new Aikau framework is the header. However, this does not mean that we're limited to logo, buttons, and drop downs. The good folks at Alfresco are working hard on converting the Document Library to use the Aikau framework. This means that there is a lot of widgets in the library that can be used right now. Take a look at the Share source to see all the existing widgets. There are widgets for loading up nodes, rendering properties, buttons, menus, forms, dialogs, selectors for users, nodes, categories, and much, much more. Not all widgets are production ready, but they are excellent examples to look at, and to get inspiration from. Use them as a reference on good practises on writing good, and generic widgets. Using the existing widgets in Share provides a lot of features, but when developing a custom page, custom widgets are usually needed. To fully understand, use and extend the existing widgets we need to look at how widgets are created. This chapter will focus on how to write widgets, and will provide examples on how to utilize templates, i18n, css, and Ajax. Up until now, Share has been built on top of the YUI2 framework, and almost all of the current features in Share still use YUI2. Share will eventually move away from YUI2 as it is not being developed anymore, and since there is no clear upgrade path from YUI2 to YUI3, Alfresco had to make a decision and chose to go with Dojo's AMD Module system. The Aikau framework relies on Dojo's AMD Module system to provide features for loading and extending widgets. This does not mean that Alfresco is switching away from YUI and forcing users into Dojo. Most of Share's future core modules will be based on Dojo, but this does not mean developers needs to learn and use Dojo for everything. However a bit of AMD knowledge will be needed, which is what defines widget and their dependencies. That's it. Once AMD is in place, it's up to the developers to load up another framework or use vanilla Javascript. Let's create a really simple widget on a new page. The widget will not do much, other than do an alert with "Hello world". Let's start out with the code, see that it works and then go into the details. First we need to create the widget. Create this file: Once the widget is created, create a new web script to define the new page: Add a Freemarker template to render the page: Add the JSON file: The last thing that needs to be done is to tell Share about the path for the widget, otherwise it will not know where to look for it. This is done by creating an extension module for Share. Create the module in this file: Restart share and visit http://localhost:8081/share/page/dp/ws/simple-page to see the result. A lot of code was involved in creating the widget. We had to create a new web script, an extension module, and the widget. Let's look at each part to understand what's going on. If you have worked with Javascript in general, you'll notice a few things. We haven't included any Javascript files and there is no initialization of the widget object. This is because everything is handled by the Surf framework which powers Share. By defining our extension module, we told Share where to find the javascript files, and by defining our widget in the JSON model, it knows how to initialize it. When processing the JSON page model, Share will identify which widgets need to be included to render the page. It knows by the name attribute roughly where to look for it, but we didn't specify an absolute path or an extension to the file. Share registers a list of packages to include - a kind of namespace. This is done in The packages has a name and a location. So by referencing However, it is always good practise to create a custom namespace to avoid conflicts in the code. To do this, we added a new package in the extension module, which tells Share that when referencing Now that Share knows how to locate the widget files, it will run it through it's internal dependency aggregation and caching. Our widget might depend on other widgets, and those widgets might depend on other widgets. This will create a complex matrix of dependencies to load, but Surf is smart enough to only include the dependencies we need - and it will only include them once. The This is not an Alfresco specific thing - it's purely Dojo and AMD. Since Surf already pre-processed and initialized our widget, Share will already have taken care of loading all the resources we need. One less thing to worry about! The first lines of any widget consists of a definition of dependencies: This defines that we need to include the declare feature, WidgetBase and an Alfresco core widget. The next line returns a declaration of our widget: This might be a bit complex to read and understand, so let's spend some more time on it. We create a function, which will take "declare", "_Widget" and "Core" as arguments. The order of the arguments has to be the exact same as the definitions above, as they will be passed into this function. So, first we define our dependencies, then create a function which takes these dependencies in as arguments. Inside this function, we call the declare function, which is an AMD specific function. The declare function allows us to inherit and extend other AMD modules. In our case we extend the Dojo _WidgetBase and Alfresco's Core module. This will provide us with the basic framework, and after that we can start defining our widget object. So if we wanted to extend This way we can extend the standard button and modify it. Notice that the function definition and return statements are two different, separate things. The function arguments are the dependencies, we request with the define statement. The Notice that Now that we know a lot more about how a widget is written, let's look at some more examples. This example will feature the Dojo provides a template system for widgets, called Templated. This module will allow us to create HTML templates and manipulate them. We'll be able to bind events and elements directly to our widget for future reference. This way we can create the basic structure directly in HTML and hook into it from our widget. To use the Let's look at an example. Create a new file in Then a new widget in This widget will render the template, and replace the variable with the string "Hello". Notice that we're overriding the buildRendering method from the Templated module. This method is in charge of rendering the template and setting up the DOM correctly, so it's important to call the original method to ensure that everything will work out. This is done by calling The Templated module also takes care of binding together the variables, so once a variable has been defined in the template, like this This was a basic example of using the Templated module. We'll see more of this later. Let's add i18n and load a CSS file. i18n works exactly like you'd expect. We create properties files like you do for web scripts. Create the i18n file Let's move our greeting into the properties file: All that's left to do now, is to load up the i18n file by setting the With the translations done, let's add a CSS file Once the CSS file is in place, add the Add the widget to the Restart Share, and access http://localhost:8081/share/page/hdp/ws/custom-widget-page to see the result. Alfresco provides a CoreXhr module, which enables us to do Ajax calls. This module is fairly easy to use. We simply define Here is an example on how to use the If we want to do a POST operation, we usually want to provide some data to go along with it. The object we pass to the serviceXhr method takes in a few parameters, so we add a The callbacks will get two arguments: the response and the config object used for the request. Since this article is not about Dojo, we won't go in too much detail with this subject. Dojo comes with modules for manipulating DOM, which we will see in the later examples by using Attach points link nodes from our template into our widget, so we do not have to do queries for the nodes. Attach points are defined by setting a data attribute on the element we wish to attach to our widget, and after that we can access the DOM node directly like this Here is an example on how to use To get a full picture of working with DOM in Dojo, here is a list of recommended reading material: Let's build a widget that combines everything we've read so far. The advanced widget will use a template, it will have a CSS file, and use i18n. It will do an Ajax call to get all nodes in Company Home and use the All this example code can be found in the part-two directory of the tutorial source code. The template is pretty simple: we define a table, variables for column headers, and a We'll also need an i18n file to enable translations of our widget: Last but not least, the widget itself: Create a new web script The end result looks like this: Ajax example widget If we break it down a bit, there really is not much to it. We pull in the dependencies we need: The In the Now that we know how to setup a page, build a widget and do various basic things with it (templates, i18n, Ajax etc), the next step is to build a full blown page with lots of widgets. Having a page with single serving widgets is fine, but we will quickly need to have the widgets communicate with each other and trigger different actions across the whole page. But how can widgets communicate with each other? They're completely separate and decoupled, which is a good thing. The Aikau framework introduces a publication/subscription system which in many aspects works like the old YUI2 Bubbling system. The idea is that to have a "channel" where widgets broadcast information, and setup other widgets to subscribe to the channel and act upon the information. This allows us to create a navigation widget where nodes can be selected. The navigation widget is only responsible for fetching the node. The rendering of the node is handled by another widget. Think about the document library for a moment, where there is a left menu that allows us to navigate the folder structure, and the content area is responsible for rendering the contents of the folder. In the document library the left menu fetches and renders a list of folders, but once you click on a folder, it also broadcasts information to a channel. The content area subscribes on the channel, and renders the folder contents once it receives information on the channel. Let's skip the metaphor, because when we're looking at the code, the terminology is a bit different. The channels are called topics and the information being broadcast is a payload, which could be anything, but usually it will be a JSON object. Once we extend The payload can either be a plain string, or you can pass objects directly like this: To subscribe to a topic we use the Sometimes we don't want to have all our subscription logic inside a closure. In these cases we can use Dojo's One last thing to note, is that whenever we receive a JSON object as a payload, the topic will be added to the object as the key This is the very basic idea behind the pub/sub system. When it comes down to it, there really isn't much to it. However, this is what gives the widgets so much power Let's create a very simple page with two widgets. The first widget will have a textarea for inputting a payload and a button. Once the button is clicked, it publishes the value from the textarea to a topic. Next to the input widget there will be a widget that subscribes to the topic and puts it on the page. Create a new web script This example uses the We have to be careful when handling topics. If we hardcode the topic name into each file, things start to get messy. To solve this, we create a very simple object that defines a constant with the topic name. This way we can pull in the topic mixin and reference the constants instead. The topics mixin looks like this: To use the mixin we simply define and declare the object. This way we extend it, and we can reference the topic name with For a very simple example like this, it might seem a bit overkill. However, when developing a big and complex matrix of widgets, we'll be grateful to have this. For the InputWidget we'll use a few tricks to create a textarea and a button. First of all we need a simple template with a few attach points so we can place elements on the page: To create a widget ad-hoc from within our widget, we simple define the widgets and initialize them as normal objects: Once we have initialized the DojoTextArea widget, we can use the The code is straight forward. Create a For the render widget we also need a simple template with an attach point so we can display the value. The template looks like this: The widget itself is also easy, it pulls in TopicsMixin and setup the template with i18n. It also subscribes to the topic, and once it receives something, it uses For the final result, access the page on http://localhost:8081/share/page/hdp/ws/pub-sub-example. There will be a textarea and a publish button. Enter something into the textarea, click the publish button, and the result will be rendered on the right side of the page: Basic Pub/Sub example Now that we know a lot more about how to build pages and utilize the Aikau framework, let's back up and think about the JSON page definition. It's nice that we can define new pages, but what happens once Alfresco starts to really work the Aikau framework into Share? We still want to be able to extend it. As of 4.2.f, the only component that uses Aikau is the header. Now, what is the header component exactly? Share 4.2 Header The header component consists of the black top menu and the logo/title/buttons below it. It's defined in Now, the header is a big component. It handles everything from the menu, user dashboard title, site title, buttons etc, so there is a lot of code there. In the end it ends up with a big JSON page model definition, but the definition is too big to go through all of it. Luckily, we have some very good options for extending a JSON model, instead of overwriting it. First of all, we need to create a Share module extension that will define which customizations we have and which files to target. This is done in an XML file in the To extend any web script in Share, we need to define a custom extension module. Create a new XML file ending in Here we define a module, give it an ID, version and tell it to auto deploy. If you do not specify the auto deploy, you will have to manually go to the module deployment page on The The general idea behind this is that you can extend any web script in Share. Our script will run after Share's own. That way we can hook into the model object and modify as much as we want. We can extend/overwrite Freemarker templates using this same technique. On top of all of this, you can inject evaluators into the extension, so you can create custom evaluators or use the existing evaluators to only have your extension apply in certain situations. Now that we've defined an extension and told Share that the target is This is all that is required to extend an existing JSON model. We're using To figure out what ID's to target we have two options. First option is to go through the Bingo, Let's add a drop down menu with a custom link: In the context of a site, there is a menu to the right with links to Document Library, Members etc. How can we target this? Here is an example on how to add a widget to the user dashboard page: Now that we can add or change widgets, how about removing one? Unfortunately there is a bug in 4.2 that makes removing widgets fail. See the full details here: https://issues.alfresco.com/jira/browse/ALF-19930. This will be fixed in one of the next releases (4.2.2 Enterprise / 4.3 community). Until then we have to rely on a fix provided in the comments on the JIRA ticket. In the comments section we find a function that can be use to remove widgets: We simply have to copy this function into our code to use it. There is no way around it, until a later release, when it will be fixed. Let's remove the "Shared files" in the header: Combining all the examples, it will look like this: Header customizations This tutorial has shown how to build a complete page with the new JSON page definition and how to write widgets using templates, i18n, templates, Ajax, and much more. It also shows how to extend existing pages in Share. My closing thoughts on this tutorial is that the Aikau framework is really cool, and that it will provide a great framework for writing custom pages in Share. Unfortunately there is not that much documentation on the subject, so the best way to get help when things go wrong is to go to the source and dig in. Also, reading up on Dojo in general, especially Dojo's AMD Module system, is a great place to start.
1031 |
1032 | Bingo, `widgetid="HEADER_SEARCH_BOX"`, and there we go. We can use `widgetUtils` to find it and change it.
1033 |
1034 | Let's add a drop down menu with a custom link:
1035 |
1036 | `src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/header/share-header.get.js`
1037 |
1038 |
1039 | headerMenu.config.widgets.push({
1040 | id: "HEADER_CUSTOM_DROPDOWN",
1041 | name: "alfresco/header/AlfMenuBarPopup",
1042 | config: {
1043 | label: "Dropdown",
1044 | widgets: [
1045 | {
1046 | name: "alfresco/menu/AlfMenuBarItem",
1047 | config: {
1048 | label: "Link #1",
1049 | targetUrl: "/"
1050 | }
1051 | }
1052 | ]
1053 | }
1054 | });
1055 |
1056 |
1057 | ## Adding a link to the right of the title bar
1058 |
1059 | In the context of a site, there is a menu to the right with links to Document Library, Members etc. How can we target this?
1060 |
1061 | Here is an example on how to add a widget to the user dashboard page:
1062 |
1063 | `src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/header/share-header.get.js`
1064 |
1065 | /* Add link on user dashboard */
1066 | if (page.titleId == "page.userDashboard.title") {
1067 | var navMenu = widgetUtils.findObject(model.jsonModel, "id", "HEADER_NAVIGATION_MENU_BAR");
1068 | if (navMenu != null) {
1069 | navMenu.config.widgets.push({
1070 | name: "alfresco/menus/AlfMenuBarItem",
1071 | config: {
1072 | label: "Custom link"
1073 | }
1074 | });
1075 | }
1076 | }
1077 |
1078 |
1079 |
1080 | ## Removing widgets
1081 |
1082 | Now that we can add or change widgets, how about removing one?
1083 |
1084 | Unfortunately there is a bug in 4.2 that makes removing widgets fail. See the full details here: [https://issues.alfresco.com/jira/browse/ALF-19930](https://issues.alfresco.com/jira/browse/ALF-19930). This will be fixed in one of the next releases (4.2.2 Enterprise / 4.3 community). Until then we have to rely on a fix provided in the comments on the JIRA ticket.
1085 |
1086 | In the comments section we find a function that can be use to remove widgets:
1087 |
1088 | function findAndRemoveIn(obj, arrContext, arrIdx, id) {
1089 | var idx, max, key;
1090 | if (obj !== undefined && obj !== null) {
1091 | if (Object.prototype.toString.apply(obj) === "[object Object]") {
1092 | if (obj.hasOwnProperty("id") && obj.id === id) {
1093 | if (arrContext !== null && arrIdx !== null)
1094 | {
1095 | arrContext.splice(arrIdx, 1);
1096 | }
1097 | else
1098 | {
1099 | logger.debug("Unexpected match outside of array structure: " + jsonUtils.toJSONString(obj));
1100 | }
1101 | } else {
1102 | for (key in obj) {
1103 | if (obj.hasOwnProperty(key))
1104 | {
1105 | findAndRemoveIn(obj[key], null, null, id);
1106 | }
1107 | }
1108 | }
1109 | } else if (Object.prototype.toString.apply(obj) === "[object Array]") {
1110 | for (idx = 0, max = obj.length; idx < max; idx++)
1111 | {
1112 | findAndRemoveIn(obj[idx], obj, idx, id);
1113 | }
1114 | }
1115 | }
1116 | }
1117 |
1118 | We simply have to copy this function into our code to use it. There is no way around it, until a later release, when it will be fixed.
1119 |
1120 | Let's remove the "Shared files" in the header:
1121 |
1122 | `src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/header/share-header.get.js`
1123 |
1124 | findAndRemoveIn(model.jsonModel.widgets, null, null, "HEADER_SHARED_FILES");
1125 |
1126 | Combining all the examples, it will look like this:
1127 |
1128 | 
1129 |
1130 | # Closing thoughts
1131 |
1132 | This tutorial has shown how to build a complete page with the new JSON page definition and how to write widgets using templates, i18n, templates, Ajax, and much more. It also shows how to extend existing pages in Share.
1133 |
1134 | My closing thoughts on this tutorial is that the Aikau framework is really cool, and that it will provide a great framework for writing custom pages in Share. Unfortunately there is not that much documentation on the subject, so the best way to get help when things go wrong is to go to the source and dig in. Also, reading up on Dojo in general, especially [Dojo's AMD Module system](http://dojotoolkit.org/documentation/tutorials/1.9/modules/), is a great place to start.
1135 |
1136 | ## Where to Find More Information
1137 |
1138 | * [Dave Draper's Blog](http://blogs.alfresco.com/wp/developer/) provides great insights on everything related to Share and Surf
1139 | * [Alfresco Official Documentation](http://docs.alfresco.com) is improving every day and includes some examples for the Aikau framework
1140 | * [Dojo Toolkit Documentation](http://dojotoolkit.org/documentation/) has great documentation on the Dojo framework
1141 |
1142 |
1143 |
--------------------------------------------------------------------------------
/aikau/tutorial/tutorial.html:
--------------------------------------------------------------------------------
1 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
29 |
977 |
978 |
979 |
--------------------------------------------------------------------------------
30 |
960 |
31 |
959 |
32 |
958 |
33 |
957 |
34 |
956 |
35 |
39 | Working with the new Aikau framework in Alfresco Share 4.2
36 | Ole Hejlskov
37 | May 2014
38 |
40 |
89 |
41 |
88 |
43 |
46 |
52 |
53 |
56 |
62 |
65 |
69 |
75 |
79 |
85 |
License
90 | 
Introduction
92 | Credits
97 |
99 |
103 | Setup
105 | Tools
107 |
109 |
115 | Getting the code
116 | File structure
118 | src/main/amp/config/alfresco/web-extension folder has been added, as well as the src/main/amp/file-mapping.properties file.
121 |
122 |
150 |
123 |
126 |
127 |
128 | File
124 | Description
125 |
129 |
132 | src/main/amp/config/alfresco/web-extensionshare-config-custom.xml and other customization XML-files
131 |
133 |
136 | src/main/amp/config/alfresco/web-extension/site-webscriptsWeb scripts
135 |
137 |
140 | src/main/amp/webStatic assets, Javascript, CSS, Images etc
139 |
141 |
144 | src/main/javaJava classes
143 |
145 |
148 |
149 | src/testTest resources, Unit tests etc
147 | Running the examples
151 | aikau/aikau-tutorial-share/ folder and run the following command:
153 | mvn integration-test -Pamp-to-warpom.xml as the example in this tutorial.pom.xml with the following XML:
156 | <maven.tomcat.port>8081</maven.tomcat.port>Part One: Creating a page
160 | Create the page
164 | src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/simple-page.get.desc.xml
172 | <webscript>
167 | <shortname>Simple Page</shortname>
168 | <description>Simple page definition</description>
169 | <family>Share</family>
170 | <url>/simple-page</url>
171 | </webscript> src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/simple-page.get.html.ftl
174 | <@processJsonModel group="share"/>src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/simple-page.get.js
183 | model.jsonModel = {
176 | widgets: [{
177 | name: "alfresco/buttons/AlfButton",
178 | config: {
179 | label: "Hello world!"
180 | }
181 | }]
182 | };
185 | mvn integration-test -Pamp-to-warhttp://localhost:8081/share/page/dp/ws/simple-page to see the result, which looks like this:
187 |
189 | 
A closer look
190 | @processJsonModel macro, which takes care of rendering everything.Where is the Share header and footer?
195 | http://localhost:8081/share/page/dp/ws/simple-page. Notice /dp/ws/simple-page.http://localhost:8081/share/page/hdp/ws/simple-page
202 |
204 | 
Adding a title next to the logo
205 |
222 | model.jsonModel = {
208 | widgets: [{
209 | id: "SET_PAGE_TITLE",
210 | name: "alfresco/header/SetTitle",
211 | config: {
212 | title: "This is a simple page"
213 | }
214 | },
215 | {
216 | name: "alfresco/buttons/AlfButton",
217 | config: {
218 | label: "Hello world!"
219 | }
220 | }]
221 | };
224 |
226 | 
Adding a layout
227 | alfresco/layout/HorizontalWidgets widget, which makes it possible to horizontally align widgets and define their width in percentages.src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/simple-page.get.js should look like this:
259 | model.jsonModel = {
230 | widgets: [{
231 | id: "SET_PAGE_TITLE",
232 | name: "alfresco/header/SetTitle",
233 | config: {
234 | title: "This is a simple page"
235 | }
236 | },
237 | {
238 | id: "MY_HORIZONTAL_WIDGET_LAYOUT",
239 | name: "alfresco/layout/HorizontalWidgets",
240 | config: {
241 | widgetWidth: 50,
242 | widgets: [
243 | {
244 | name: "alfresco/logo/Logo",
245 | config: {
246 | logoClasses: "alfresco-logo-only"
247 | }
248 | },
249 | {
250 | name: "alfresco/buttons/AlfButton",
251 | config: {
252 | label: "Hello world"
253 | }
254 | }
255 | ]
256 | }
257 | }]
258 | };
261 |
263 | 
HorizontalWidgets has a config object with a list of widgets, each with their own peoperties. The configuration includes a parameter for the horizontal widget widgetWidth: 50 which defines the percentage width each widget should recieve.The built-in widgets
265 | Part Two: Introduction to widgets
271 | YUI, Dojo and AMD
274 | Creating a simple widget
280 | src/main/amp/web/js/example/widgets/MyWidget.js
297 | define(["dojo/_base/declare",
283 | "dijit/_WidgetBase",
284 | "alfresco/core/Core"
285 | ],
286 | function(declare, _Widget, Core) {
287 | return declare([_Widget, Core], {
288 |
289 | postCreate: function example_widgets_MyWidget__postCreate() {
290 | this.inherited(arguments);
291 | alert("Hello world!");
292 |
293 | }
294 |
295 | });
296 | });src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/custom-widget-page.get.desc.xml
305 | <webscript>
300 | <shortname>Custom Widget Page</shortname>
301 | <description>Page with custom widget</description>
302 | <family>Share</family>
303 | <url>/custom-widget-page</url>
304 | </webscript>src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/custom-widget-page.get.html.ftl
307 | <@processJsonModel group="share"/>src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/custom-widget-page.get.js
320 | model.jsonModel = {
309 | widgets: [{
310 | id: "SET_PAGE_TITLE",
311 | name: "alfresco/header/SetTitle",
312 | config: {
313 | title: "This is a simple page"
314 | }
315 | },
316 | {
317 | name: "example/widgets/MyWidget"
318 | }]
319 | };src/main/amp/config/alfresco/web-extension/site-data/extensions/widget-extension.xml
341 | <extension>
322 | <modules>
323 | <module>
324 | <id>Tutorial widgets</id>
325 | <version>1.0</version>
326 | <auto-deploy>true</auto-deploy>
327 | <configurations>
328 | <config evaluator="string-compare" condition="WebFramework" replace="false">
329 | <web-framework>
330 | <dojo-pages>
331 | <packages>
332 | <package name="example" location="js/example"/>
333 | </packages>
334 | </dojo-pages>
335 | </web-framework>
336 | </config>
337 | </configurations>
338 | </module>
339 | </modules>
340 | </extension>Breaking down the widget code
343 | Loading dependencies
345 | WEB-INF/surf.xml with this sniplet of XML:
355 | <packages>
349 | <package name="dojo" location="js/lib/dojo-1.9.0/dojo"/>
350 | <package name="dijit" location="js/lib/dojo-1.9.0/dijit"/>
351 | <package name="dojox" location="js/lib/dojo-1.9.0/dojox"/>
352 | <package name="alfresco" location="js/alfresco"/>
353 | </packages>
354 | alfresco/[folder]/[widget] in the JSON model, Share will look for the file in WEB-INF/js/alfresco/[folder]/[widget].js.example/[folder]/[widget] it will include WEB-INF/js/example/[folder]/[widget].js.<@processJsonModel group="share"/> macro in the Freemarker template triggers the process of resolving the dependencies and rendering everything from including the scripts to the initialization of the widget.Defining and declaring a widget
360 |
367 | define(["dojo/_base/declare",
363 | "dijit/_WidgetBase",
364 | "alfresco/core/Core"
365 | ]
366 |
373 | function(declare, _Widget, Core) {
370 | return declare([_Widget, Core], {
371 | });
372 | }alfresco/buttons/AlfButton, we would simply define the module, and add it to the list of modules, it can be extended like this:
390 | define(["dojo/_base/declare",
380 | "dijit/_WidgetBase",
381 | "alfresco/core/Core",
382 | "alfresco/buttons/AlfButton"
383 | ],
384 | function(declare, _Widget, Core, AlfButton) {
385 | return declare([_Widget, Core, AlfButton], {
386 | /* Our code goes here */
387 | });
388 | }
389 | }); return declare([]) defines which objects we want to extend. We do not always want to extend other objects, but only make them available in the object. One example of this could be if we wanted Dojo's array features. We would define them as a dependency, and make them available in the function, but we do not want to extend the object. This example shows how to include the array features:
406 | define(["dojo/_base/declare",
393 | "dijit/_WidgetBase",
394 | "alfresco/core/Core",
395 | "dojo/_base/array",
396 | ],
397 | function(declare, _Widget, Core, AlfButton, array) {
398 | return declare([_Widget, Core, AlfButton], {
399 | var list = [1,2,3];
400 | array.forEach( list, function(x) {
401 | console.log(x);
402 | });
403 | });
404 | }
405 | }); dojo/_base/array was only defined and passed in as an argument to our widget. We did not extend the array object.Beyond a "Hello world"
408 | Templated module, which enables you to specify a HTML template for your widget, bind values to it, and access it from within the widget. We'll also have a look at the basic DOM-operations Dojo supplies. Last but not least, we'll look at the CoreXhr module for doing Ajax as well as utilizing i18n and CSS.Templates, CSS, and I18N
410 | Templated module, the widget need to define the dijit/_TemplatedMixin module, and specify a path and name for the template, like this: dojo/text!./templates/TemplateWidget.html. The path is relative to the widget's location. The widget also needs to extend the Templated module with the declare feature discussed earlier.src/main/amp/web/js/example/widgets/templates/TemplateWidget.html with some HTML:
414 | <div class="my-template-widget">${greeting}</div>src/main/amp/web/js/example/widgets/TemplateWidget.js
430 | define(["dojo/_base/declare",
416 | "dijit/_WidgetBase",
417 | "alfresco/core/Core",
418 | "dijit/_TemplatedMixin",
419 | "dojo/text!./templates/TemplateWidget.html"
420 | ],
421 | function(declare, _Widget, Core, _Templated, template) {
422 | return declare([_Widget, Core, _Templated], {
423 | templateString: template,
424 | buildRendering: function example_widgets_TemplateWidget__buildRendering() {
425 | this.greeting = "Hello!";
426 | this.inherited(arguments);
427 | }
428 | });
429 | });this.inherited(arguments).${greeting}, it can accessed and modified directly in the widget within the buildRendering method. This is useful for setting up labels and headings with translations. Notice that the variables can only be modified from the buildRendering method.src/main/amp/web/js/example/widgets/templates/i18n/TemplateWidget.properties. Multiple languages can be supported by adding a prefix to the filename, like TemplateWidget_en.properties.
436 | hello-label=Hello from i18ni18nRequirements property and call this.message() to grab the label out of the translation system. Everything else is taken care of by the Aikau framework.src/main/amp/web/js/example/widgets/css/TemplateWidget.css
443 | .my-template-widget {
439 | border: 1px #000000 solid;
440 | padding: 1em;
441 | width: 100px;
442 | }cssRequirements property and point it to the CSS file. The final code looks like this:
462 | define(["dojo/_base/declare",
445 | "dijit/_WidgetBase",
446 | "alfresco/core/Core",
447 | "dijit/_TemplatedMixin",
448 | "dojo/text!./templates/TemplateWidget.html"
449 | ],
450 | function(declare, _Widget, Core, _Templated, template) {
451 | return declare([_Widget, Core, _Templated], {
452 | templateString: template,
453 | i18nRequirements: [ {i18nFile: "./i18n/TemplateWidget.properties"} ],
454 | cssRequirements: [{cssFile:"./css/TemplateWidget.css"}],
455 |
456 | buildRendering: function example_widgets_TemplateWidget__buildRendering() {
457 | this.greeting = this.message('hello-label');
458 | this.inherited(arguments);
459 | }
460 | });
461 | });custom-widget-page.get.js JSON model:
478 | model.jsonModel = {
464 | widgets: [{
465 | id: "SET_PAGE_TITLE",
466 | name: "alfresco/header/SetTitle",
467 | config: {
468 | title: "This is a simple page"
469 | }
470 | },
471 | {
472 | name: "example/widgets/MyWidget"
473 | },
474 | {
475 | name: "example/widgets/TemplateWidget"
476 | }]
477 | };Ajax
480 | alfresco/core/CoreXhr as a dependency and extend it, and then we can call this.serviceXhr to do GET/POST/PUT/DELETE operations against Alfresco. The serviceXhr method takes an object of parameters with parameters like URL, method (GET/POST etc), and callback methods for success/failure.CoreXhr module:
504 | define(["dojo/_base/declare",
483 | "dijit/_WidgetBase",
484 | "alfresco/core/Core",
485 | "alfresco/core/CoreXhr"
486 | ],
487 | function(declare, _Widget, Core, CoreXhr) {
488 | return declare([_Widget, Core, CoreXhr], {
489 |
490 | postCreate: function example_widgets_AjaxWidget__postCreate() {
491 | var url = Alfresco.constants.PROXY_URI + "slingshot/doclib/treenode/node/alfresco/company/home";
492 | this.serviceXhr({url : url,
493 | method: "GET",
494 | successCallback: this._onSuccessCallback,
495 | callbackScope: this});
496 | },
497 |
498 | _onSuccessCallback: function example_widgets_AjaxWidget__onSuccessCallback(response, config) {
499 | console.log(response);
500 | }
501 |
502 | });
503 | });data value in the object with our data for the POST operation. Unfortunately there is not much (if any) documentation on this just yet, but by looking at the code, the default options we can modify, look like this:
519 | var config = {
506 | handleAs: "text",
507 | method: "POST",
508 | data: null,
509 | query: null,
510 | headers: { "Content-Type": "application/json" },
511 | successCallbackScope: this,
512 | successCallback: this.defaultSuccessCallback,
513 | failureCallbackScope: this,
514 | failureCallback: this.defaultFailureCallback,
515 | progressCallbackScope: this,
516 | progressCallback: defaultProgressCallback,
517 | alfTopic: null
518 | };DOM helpers and modules
521 | domConstruct to create DOM nodes and attach them with attach points in our template.domConstruct enables us to create DOM nodes, and if we want, we can easily inject them into our templates with attach points.this.containerNode. The template would look like this:
525 | <div data-dojo-attach-point="containerNode"></div>domConstruct to create a new node inside containerNode with a text:
542 | define(["dojo/_base/declare",
527 | "dijit/_WidgetBase",
528 | "alfresco/core/Core",
529 | "dojo/dom-construct",
530 | "dijit/_TemplatedMixin",
531 | "dojo/text!./templates/TemplateWidget.html"
532 | ],
533 | function(declare, _Widget, Core, domConstruct, _Templated, template) {
534 | return declare([_Widget, Core, _Templated], {
535 | templateString: template,
536 |
537 | postCreate: function example_widgets_TemplateWidget__postCreate () {
538 | domConstruct.create( "div", { innerHTML: "Hello" }, this.containerNode );
539 | }
540 | });
541 | });
544 |
549 | Bringing it all together
550 | domConstruct module to populate a table with the data.tbody with an attach-point so we can access it from the widget:src/main/amp/web/js/example/widgets/templates/AjaxWidget.html
567 | <div class="ajax-widget">
555 | <h1>${widgetTitle}</h1>
556 |
557 | <table>
558 | <thead>
559 | <tr>
560 | <th>${columnName}</th>
561 | <th>${columnDescription}</th>
562 | </tr>
563 | </thead>
564 | <tbody data-dojo-attach-point="containerNode"></tbody>
565 | </table>
566 | </div>src/main/amp/web/js/example/widgets/i18n/AjaxWidget.properties
572 | widgetTitle=Nodes found in Company Home
570 | columnName=Name
571 | columnDescription=Descriptionsrc/main/amp/web/js/example/widgets/AjaxWidget.js
616 | define(["dojo/_base/declare",
575 | "dijit/_WidgetBase",
576 | "alfresco/core/Core",
577 | "alfresco/core/CoreXhr",
578 | "dojo/dom-construct",
579 | "dojo/_base/array",
580 | "dijit/_TemplatedMixin",
581 | "dojo/text!./templates/AjaxWidget.html"
582 | ],
583 | function(declare, _Widget, Core, AlfCoreXhr, domConstruct, array, _Templated, template) {
584 | return declare([_Widget, Core, AlfCoreXhr, _Templated], {
585 | templateString: template,
586 | cssRequirements: [{cssFile:"./css/AjaxWidget.css"}],
587 | i18nRequirements: [ {i18nFile: "./i18n/AjaxWidget.properties"} ],
588 |
589 | buildRendering: function example_widgets_AjaxWidget__buildRendering() {
590 | this.widgetTitle = this.message('widgetTitle');
591 | this.columnName = this.message('columnName');
592 | this.columnDescription = this.message('columnDescription');
593 | this.inherited(arguments);
594 | },
595 |
596 | postCreate: function example_widgets_AjaxWidget__postCreate() {
597 | var url = Alfresco.constants.PROXY_URI + "slingshot/doclib/treenode/node/alfresco/company/home";
598 | this.serviceXhr({url : url,
599 | method: "GET",
600 | successCallback: this._onSuccessCallback,
601 | callbackScope: this});
602 | },
603 |
604 | _onSuccessCallback: function example_widgets_AjaxWidget__onSuccessCallback(response, config) {
605 | if (response.totalResults != undefined && response.totalResults > 0) {
606 | var parentNode = this.containerNode;
607 | array.forEach( response.items, function(item) {
608 | var row = domConstruct.create( "tr", {}, parentNode );
609 | domConstruct.create( "td", { innerHTML: item.name }, row);
610 | domConstruct.create( "td", { innerHTML: item.description }, row);
611 | });
612 | }
613 | }
614 | });
615 | });ajax-page that defines a page with the widget:src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/ajax-page.get.desc.xml
624 | <webscript>
619 | <shortname>Ajax Page</shortname>
620 | <description>Ajax page with a bit of DOM</description>
621 | <family>Share</family>
622 | <url>/ajax-page</url>
623 | </webscript>src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/ajax-page.get.html.ftl
626 | <@processJsonModel group="share"/>src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/ajax-page.get.js
639 | model.jsonModel = {
628 | widgets: [{
629 | id: "SET_PAGE_TITLE",
630 | name: "alfresco/header/SetTitle",
631 | config: {
632 | title: "This is an advanced page with Ajax and DOM operations"
633 | }
634 | },
635 | {
636 | name: "example/widgets/AjaxWidget"
637 | }]
638 | };
641 |
643 | 
CoreXhr, dom-construct, array, and TemplatedMixin. We also specify the template, css, and i18n files.buildRendering method sets up the template with i18n, postCreate does an Ajax call to Alfresco.constants.PROXY_URI + "slingshot/doclib/treenode/node/alfresco/company/home" to get a list of all nodes in "Company Home", and uses the _onSuccessCallback method to do the actual rendering._onSuccessCallback method we check that we actually got results, then catch the containerNode attach-point from the template, loop the reulsts, and construct a row with two columns for each result.Inter-widget communication
647 | alfresco/core/Core, we inherit two methods: alfPublish and alfSubscribe, which allows us to publish and subscribe to a topic. A topic is simply a string, which gives us something to identify it by. The alfPublish method takes the topic as the first argument, followed by the payload like this:
652 | this.alfPublish("MY_TOPIC", "my payload");
654 | this.alfPublish("MY_TOPIC", {nodes: [{name:"node1"}, {name: "node2"}]});alfSubscribe method, which takes the topic as the first argument, followed by a callback to act on the payload:
658 | this.alfSubscribe(this.TutorialTopic, function(payload) {
656 | console.log(payload);
657 | });lang.hitch method to connect the subscription with a method on our object:
677 | define(["dojo/_base/declare",
660 | "dijit/_WidgetBase",
661 | "alfresco/core/Core",
662 | "dojo/_base/lang",
663 | ],
664 | function(declare, _Widget, Core, lang) {
665 | return declare([_Widget, Core], {
666 |
667 | postCreate: function () {
668 | this.alfSubscribe("MY_TOPIC", lang.hitch(this, "_onPayloadReceive"));
669 | },
670 |
671 | _onPayloadReceive: function (payload) {
672 | console.log(payload);
673 | }
674 |
675 | });
676 | });alfTopic. A simple JSON object like {nodes: []} published to "MY_TOPIC" will become {alfTopic: "MY_TOPIC", nodes: []}. This is useful in identifying where the payload originated from.A basic pub/sub example
680 | pub-sub that defines a page with the widget:src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/pub-sub.get.desc.xml
689 | <webscript>
684 | <shortname>Publish-Subscription page</shortname>
685 | <description>Example on using pub/sub with widgets</description>
686 | <family>Share</family>
687 | <url>/pub-sub-example</url>
688 | </webscript>src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/pub-sub.get.html.ftl
691 | <@processJsonModel group="share"/>src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/pages/pub-sub.get.js
715 | model.jsonModel = {
693 | widgets: [{
694 | id: "SET_PAGE_TITLE",
695 | name: "alfresco/header/SetTitle",
696 | config: {
697 | title: "Pub/sub example"
698 | }
699 | },
700 | {
701 | name: "alfresco/layout/HorizontalWidgets",
702 | config: {
703 | widgetWidth: 50,
704 | widgets: [
705 | {
706 | name: "example/widgets/InputWidget"
707 | },
708 | {
709 | name: "example/widgets/RenderWidget"
710 | }
711 | ]
712 | }
713 | }]
714 | };alfresco/layout/HorizontalWidgets layout widget to put the two widgets next to each other.A simple Mixin for constants
717 | src/main/amp/web/js/example/widgets/_TopicsMixin.js
726 | define(["dojo/_base/declare"],
720 | function(declare) {
721 |
722 | return declare(null, {
723 | TutorialTopic: "ALFRESCO_TUTORIAL_TOPIC"
724 | });
725 | });this.TutorialTopic instead of hardcoding the topic into each file.InputWidget
729 | src/main/amp/web/js/example/widgets/templates/InputWidget.html
735 | <div class="tutorial-input-widget-container">
732 | <span data-dojo-attach-point="inputTopicNode"></span>
733 | <span data-dojo-attach-point="publishTopicNode"></span>
734 | </div>
739 | this.textArea = new DojoTextarea({
737 | label: this.message("inputWidget.inputLabel")
738 | });placeAt method to have the widget rendered at an attach point in the template. The complete InputWidget looks like this:src/main/amp/web/js/example/widgets/InputWidget.js
779 | define(["dojo/_base/declare",
742 | "dijit/_WidgetBase",
743 | "alfresco/core/Core",
744 | "dojo/_base/lang",
745 | "alfresco/buttons/AlfButton",
746 | "alfresco/forms/controls/DojoTextarea",
747 | "alfresco/tutorial/_TopicsMixin",
748 | "dijit/_TemplatedMixin",
749 | "dojo/text!./templates/InputWidget.html"
750 | ],
751 | function(declare, _Widget, Core, lang, AlfButton, DojoTextarea, _TopicsMixin, _Templated, template) {
752 | return declare([_Widget, Core, _Templated, _TopicsMixin], {
753 |
754 | templateString: template,
755 | i18nRequirements: [ {i18nFile: "./i18n/PubSub.properties"} ],
756 |
757 | postCreate: function example_widgets_InputWidget__postCreate() {
758 | this.inherited(arguments);
759 |
760 | this.textArea = new DojoTextarea({
761 | label: this.message("inputWidget.inputLabel")
762 | });
763 | this.textArea.placeAt(this.inputTopicNode);
764 |
765 | var btn = new AlfButton({
766 | label: "Publish",
767 | onClick: lang.hitch(this, '_onPublish')
768 | });
769 | btn.placeAt(this.publishTopicNode);
770 |
771 | },
772 |
773 | _onPublish: function example_widgets_InputWidget__onPublish() {
774 | this.alfPublish(this.TutorialTopic, this.textArea.getValue());
775 | }
776 |
777 | });
778 | });DojoTextarea and a AlfButton. Hitch the _onPublish method to the onClick event on the button, and place them in the template. Once the button is clicked, we publish the value of the textarea to the topic.RenderWidget
781 | src/main/amp/web/js/example/widgets/templates/RenderWidget.html
787 | <div class="tutorial-input-widget-container">
784 | <b>${renderWidgetHeading}</b>
785 | <span data-dojo-attach-point="payloadContainer"></span>
786 | </div>domConstruct to create a <p> element with the text.src/main/amp/web/js/example/widgets/RenderWidget.js
819 | define(["dojo/_base/declare",
790 | "dijit/_WidgetBase",
791 | "alfresco/core/Core",
792 | "dojo/_base/lang",
793 | "alfresco/tutorial/_TopicsMixin",
794 | "dojo/dom-construct",
795 | "dijit/_TemplatedMixin",
796 | "dojo/text!./templates/RenderWidget.html"
797 | ],
798 | function(declare, _Widget, Core, lang, _TopicsMixin, domConstruct, _Templated, template) {
799 | return declare([_Widget, Core, _TopicsMixin, _Templated], {
800 |
801 | templateString: template,
802 | i18nRequirements: [ {i18nFile: "./i18n/PubSub.properties"} ],
803 |
804 | buildRendering: function example_widgets_renderWidget__buildRendering() {
805 | this.renderWidgetHeading = this.message('renderWidget.heading');
806 | this.inherited(arguments);
807 | },
808 |
809 | postCreate: function example_widget_renderWidget__postCreate() {
810 | this.alfSubscribe(this.TutorialTopic, lang.hitch(this, "_onPayloadReceive"));
811 | },
812 |
813 | _onPayloadReceive: function example_widgets_renderWidget__onPayloadReceive(payload) {
814 | var txt = domConstruct.create( "p", { innerHTML: payload }, this.payloadContainer );
815 | }
816 |
817 | });
818 | });
821 |
823 | 
Part Three: Extending JSON models
824 |
827 |
829 | 
WEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/header/share-header.get.js. This file is pretty simple. It includes WEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/imports/share-header.lib.js which is where all the magic happens.src/main/amp/config/alfresco/web-extension/site-data/extensions/ folder. Once it has been created, we need to create a javascript file where we can use a new root scoped object called widgetUtils, which allows us to find components in an existing JSON model and work with it.Creating an extension
833 | src/main/amp/config/alfresco/web-extension/site-data/extensions/ like this:
849 | <extension>
835 | <modules>
836 | <module>
837 | <id>Add custom menu item to header</id>
838 | <version>1.0</version>
839 | <auto-deploy>true</auto-deploy>
840 | <customizations>
841 | <customization>
842 | <targetPackageRoot>org.alfresco.share.header</targetPackageRoot>
843 | <sourcePackageRoot>com.example.header</sourcePackageRoot>
844 | </customization>
845 | </customizations>
846 | </module>
847 | </modules>
848 | </extension>http://localhost:8081/share/page/modules/deploy to deploy it.<customizations> section is used to tell Share which folder we want to target, and where it can find the source for the customizations. This is not specific to the Aikau framework, as it's been in Share for a while, and it's the best way to do clean extensions of Share's own files. We're targeting org.alfresco.share.header which translates into WEB-INF/classes/alfresco/site-webscripts/org/alfresco/share/header. Anything in this folder can be extended in our own folder in src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/header/header.Adding a menu item to the header
854 | org.alfresco.share.header, create a web script controller called share-header.get.js in src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/tutorial/header. Let's find the menu and add our own menu item that links to the user's profile:src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/header/share-header.get.js
867 | var headerMenu = widgetUtils.findObject(model.jsonModel, "id", "HEADER_APP_MENU_BAR");
857 | if (headerMenu != null) {
858 | headerMenu.config.widgets.push({
859 | id: "HEADER_CUSTOM_PROFILE_LINK",
860 | name: "alfresco/menus/AlfMenuBarItem",
861 | config: {
862 | label: "My profile",
863 | targetUrl: "user/" + encodeURIComponent(user.name) + "/profile"
864 | }
865 | });
866 | }widgetUtils to find the HEADER_APP_MENU_BAR widget. Once we have it, we simply push a widget into it. We can push any widget we want, but since we're in the header, we should probably limit it to smaller things. Here we could remove, add or change any of the things in the header. Want a new search box? Find the HEADER_SEARCH_BOX widget and replace it with a new one.share-header.lib.js file, which defines the whole header. The problem with this file is that it's very big and confusing to dig into. The alternative is to use a tool like Firebug/Developer tools in Chrome and inspect the elements from the browser. If we look at the search box, we'll see that its markup looks like this:
870 | <div id="HEADER_SEARCH_BOX" class="alf-search-box" widgetid="HEADER_SEARCH_BOX">widgetid="HEADER_SEARCH_BOX", and there we go. We can use widgetUtils to find it and change it.src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/header/share-header.get.js
889 | headerMenu.config.widgets.push({
874 | id: "HEADER_CUSTOM_DROPDOWN",
875 | name: "alfresco/header/AlfMenuBarPopup",
876 | config: {
877 | label: "Dropdown",
878 | widgets: [
879 | {
880 | name: "alfresco/menu/AlfMenuBarItem",
881 | config: {
882 | label: "Link #1",
883 | targetUrl: "/"
884 | }
885 | }
886 | ]
887 | }
888 | });Adding a link to the right of the title bar
890 | src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/header/share-header.get.js
905 | /* Add link on user dashboard */
894 | if (page.titleId == "page.userDashboard.title") {
895 | var navMenu = widgetUtils.findObject(model.jsonModel, "id", "HEADER_NAVIGATION_MENU_BAR");
896 | if (navMenu != null) {
897 | navMenu.config.widgets.push({
898 | name: "alfresco/menus/AlfMenuBarItem",
899 | config: {
900 | label: "Custom link"
901 | }
902 | });
903 | }
904 | }Removing widgets
906 |
938 | function findAndRemoveIn(obj, arrContext, arrIdx, id) {
910 | var idx, max, key;
911 | if (obj !== undefined && obj !== null) {
912 | if (Object.prototype.toString.apply(obj) === "[object Object]") {
913 | if (obj.hasOwnProperty("id") && obj.id === id) {
914 | if (arrContext !== null && arrIdx !== null)
915 | {
916 | arrContext.splice(arrIdx, 1);
917 | }
918 | else
919 | {
920 | logger.debug("Unexpected match outside of array structure: " + jsonUtils.toJSONString(obj));
921 | }
922 | } else {
923 | for (key in obj) {
924 | if (obj.hasOwnProperty(key))
925 | {
926 | findAndRemoveIn(obj[key], null, null, id);
927 | }
928 | }
929 | }
930 | } else if (Object.prototype.toString.apply(obj) === "[object Array]") {
931 | for (idx = 0, max = obj.length; idx < max; idx++)
932 | {
933 | findAndRemoveIn(obj[idx], obj, idx, id);
934 | }
935 | }
936 | }
937 | }src/main/amp/config/alfresco/web-extension/site-webscripts/com/example/header/share-header.get.js
942 | findAndRemoveIn(model.jsonModel.widgets, null, null, "HEADER_SHARED_FILES");
944 |
946 | 
Closing thoughts
947 | Where to Find More Information
950 |
951 |
955 |
961 |
971 |
962 |
970 |
963 |
966 |
967 |
969 |
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
968 |
972 |
976 |
973 | Fork me on GitHub
974 |
975 |