Embed Size (px)
DESCRIPTION
Many Alfresco projects require customizations to the Share user interface that go beyond the normal configuration. This usually involves changing/overriding Repository Web Scripts and Surf Web Scripts, updating JavaScript and CSS files, coding with the Yahoo UI Library, etc. This session will customize the Alfresco Share Upload File(s) dialog and show you how to: Add Widgets to the Upload File(s) dialog, Override Surf Web Scripts, Override/Update JavaScript and CSS files, Write Repository Web Scripts, Call Web Scripts from Yahoo UI Library code, and Setup a build project for these customizations. This session will present the advanced customization concepts via hands-on tutorial and slides.
Citation preview
Customizing the Upload File(s) Dialog in Share!
Martin Bergljung, Principal ECM Architect, Ixxus (twitter: gravitonian, blog:[email protected], Alfresco 3 Business Solutions)!
Table of Contents!
• What is it that we want to customize?!• What files are involved? !!• How do we update/customize these files?!• Debugging client side JavaScript!• Updating Share UI to show custom types, aspects, and
associations !
Hereʼs what we want to do!
Original Upload File(s) Dialog!
Customized Upload File(s) Dialog! Customized !Metadata Screen!
What client side files are involved?!
So what files do we need to update? • Start by using Firebug in Firefox to see what JavaScript files are
involved!• Start Firebug and then click Upload in the !!Share doc lib toolbar!
• Now click Script in the Firebug toolbar!• To see all loaded JS click combo box at the top!• To see what Flash file is used for !!uploading multiple files click Net | Flash !
What client side files are involved continued?!
So flash-upload-min.js is involved in the Upload File(s) dialog? • We need to find out where this file is located!
• A clue can be found in Firebug:!
• Client side resource files are directly under /webapps/share!• So if we navigate into /webapps/share/components/upload we will find the
files we are looking for!• Here we will also find a non-minified (i.e. not compressed) JS file called flash-
upload.js!
What client side files are involved continued?!
Looking inside flash-upload.js • Looking inside this file reveals what class is used and later created in the page!
• The YUI Library is used to create the widgets used in the dialog!
What client side files are involved continued?!
Looking inside flash-upload.js continued • We can also see how the Flash Uploader component is hooked up to the JS!
What server side files are involved?!
Where is the HTML page that loads flash-upload.js? • If we can find this out then we will also know more about what files
that are involved on the server side!• We can find the template/page by looking for files that reference flash-
upload.js, thereʼs got to be some file loading this JS!• Searching in the Alfresco source code gives us a couple of hits:!
• We are not interesting in the RM files so there is just one Web Script flash-upload.get.* left that we can focus on!
Some more about the client side files!
Why didn't we look for flash-upload-min.js, how is it loaded? • If we open up the Web Script file flash-upload.get.head.ftl we can see
how it loads <head> content:!
• It just refers to the non-minified version of the JS file, which is normally loaded with the <script> element!
• However, here we can see that the <@script> FreeMarker macro is used instead!
• This macro will expand to load the minimized version instead (i.e. flash-upload-min.js), if debug mode is off!
• This is also where we can add YUI libraries that are not included in our page, for example, to use the tab view control include:!
• <@script type="text/javascript" src="${page.url.context}/res/yui/tabview/tabview.js"></@script>
Generating compressed client side files?!
How to compress/minify JS and CSS files? • Itʼs best to include this in the build at the very start!• Download the YUI Compressor lib!• Then create ant targets:!
What server side files are involved continued?!
We know how the header is loaded, what about the page body? • If we open up the Web Script file called flash-upload.get.html.ftl we will
get the answer to that!• We can see that several markup element ids are linked to the JS code
in the flash-upload.js file!webapps/share/WEB-INF/classes/alfresco/!site-webscripts/org/alfresco/components/!upload flash-upload.get.html.ftl!
/webapps/share/components/upload/flash-upload.js!
What server side files are involved continued?!
And how does the page load the Alfresco.FlashUpload class? • At the end off the flash-upload.get.html.ftl file we will find the creation
of this class:!
How do we update the involved files?!
We know what files we need to update, how do we do that? • Spring Surf Web Scripts can be overridden and we can then also pick
up updated and new JS and CSS files!• The Web Script files that we will update are copied over to the build
project and into the web-extension directory !• We create new JS and CSS files for our customizations and put into
the META-INF directory!
Loading custom JS and CSS?!
We need to make sure our custom JS and CSS files are loaded • We add them in the flash-upload.get.head.ftl file that we just copied
into our development project:!
Adding markup for new dialog widgets?!
Start customizing by updating the page/dialog template? • We do that in the flash-upload.get.html.ftl file that we just copied
into our development project:!
• If we build the extension then the dialog !!would now look something like this:!
Populating the existing files list!
First create a Web Script to return existing files? • This is going to be an Alfresco Repo Web Script so we add it as
follows to the directory structure:!
• Could use CMIS call but will require a lot of processing, make sure also that XML parsing works in all browsers!
• CMIS 1.1 with Browser binding will help out in the future!
Populating the existing files list continued!
Testing the existing files Web Script • Use curl to try out the new Web Script:!
• It will return a JSON result looking something like this:!
Populating the existing files list continued!
Adding a YUI Data table for the existing files • Next step is to add a YUI Data table that will be populated with the
output from the existing files Web Script, this is done in flash-upload-custom.js:!
Populating the existing files list continued!
• Now we can implement the method that will create and populate the existing files list, we add it at the end of the flash-upload-custom.js file:!
Populating the existing files list continued!
Authenticating AJAX calls • Important is to use the proxy URL:!
• Alfresco.constants.PROXY_URI = http://localhost:8080/share/proxy/alfresco/
• This URL is mapped to a Surf end point controller:!• /proxy/**=endpointController
• The End Point http proxy controller (Servlet) provides the ability to submit a URL request via a configured end point, such as a remote Alfresco Server, the URL template looks like this:!
• /proxy/<endpointid>[/uri]*[?[<argName>=<argValue>]*] • The endpointid is the ID of a configured EndPoint model object to
make a request against, such as:!
Populating the existing files list continued!
Authenticating AJAX calls continued • The Connector framework is used so that appropriate
authentication is automatically applied to the proxied request!• The full URL looks like this:!
• http://localhost:8080/share/proxy/alfresco/mycompany/existingfiles?folderNodeRef={noderef} !
• Note that the /service URL path element is not present as when you normally call Web Scripts, it is already part of the <endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>!
• http://localhost:8080/alfresco/service/mycompany/existingfiles?folderNodeRef={noderef} !
Populating the existing files list continued!
The Upload File(s) dialog now looks something like this:
Debugging if things go wrong!
Not looking like you expected, time for some debugging • Check that there are no obvious errors like for example:!
• Then turn on JS debug mode in Share configuration:!
• Now check that the flash-upload-custom-min.js is up-to-date, open up the file in Firebug!
Debugging if things go wrong continued!
Debugging the JS code • In Firebug you can now debug the JavaScript code:!
Logging from JavaScript!
Use Alfresco specific methods for logging • Alfresco.logger.debug/info/warn/error/fatal() • For example, to do some debug logging do:!
• And enable log4javascript console to show up:!
Styling the custom widgets!
The existing files data table needs some styling • We can do that by defining the CSS classes we used in the divs!• This is done in the flash-upload-custom.css file:!
Setting up derived work association & comment!
Custom content model for derived work • We are going to need a custom content model for the derived
work association and comment!
Setting up derived work association & comment!
A Web Script to setup the derived work association • This is going to be an Alfresco Repo Web Script so I add it as
follows to the directory structure:!
Setting up derived work association & comment!
A Web Script to setup the derived work comment • This too is going to be an Alfresco Repo Web Script so I add it as
follows to the directory structure:!
Setting up derived work association & comment continued!Update Java Script code to hold derived comment
• For this we open up the flash-upload-custom.js file and add the following property to hold the derived comment:!
Setting up derived work association & comment continued!Update Java Script code to setup derived work association
• In flash-upload-custom.js we override the onUploadCompleteData function, which will be called when a file has been uploaded successfully!
• In this function we add a new function call:!
• The fileInfo object has some useful properties for the file being uploaded such as:!
• contentType • nodeRef • fileName • state
Setting up derived work association & comment continued!
• Now we can implement the method that will setup associations between uploaded files and existing files, we add it at the end of the flash-upload-custom.js file:!
Using our new MyCompany.FlashUpload object!
We have now created and completed the MyCompany.FlashUpload object, but how is it loaded?
• To actually load this new FlashUpload customization we need to update the flash-upload.get.html.ftl file:!
Setting up derived work association & comment continued!Fixing so Share UI displays associations and comment
• The Share UI will not display the new association and comment for a node that has it, we need to configure it !
• In share-config-custom.xml add the following form configuration:!
Setting up derived work association & comment continued!Fixing so Share UI displays the rest of the properties
• The Share UI will not display the standard properties if the node have one of our custom types, for this we need to configure forms for the custom types:!
Setting custom types during upload!
Updating the flash-upload Web Script to set Type during upload • In flash-upload.get.js add the 2 custom types defined in the content
model:!
• And fix the labels for the types!
• Now we will have a choice of selecting type during upload:!
