Packt+ | Advance your knowledge in tech

You're reading from Alfresco One 5.x Developer???s Guide - Second Edition

Product type Book

Published in Feb 2017

Publisher Packt

ISBN-13 9781787128163

Pages 528 pages

Edition 2nd Edition

Languages

Java

Concepts

CMS

Authors (2):

Benjamin Chevallereau

Jeff Potts

View More author details

Table of Contents (17) Chapters

Alfresco One 5.x Developer’s Guide - Second Edition

Credits

About the Authors

About the Reviewer

www.PacktPub.com

Customer Feedback

Preface

1. The Alfresco Platform

2. Getting Started with Alfresco

3. Working with Content Models

4. Handling Content Automatically with Actions, Behaviors, Transformers, and Extractors

5. Customizing Alfresco Share

6. Creating an Angular Application

7. Exposing Content through a RESTful API with Web Scripts

8. Advanced Workflow

9. Amazing Extensions

10. Security

Chapter 5. Customizing Alfresco Share

Alfresco Share is an all-purpose user interface for general document management. As such, it may not be specific enough for the solution you are trying to implement. Or, you may have the opposite problem-too many choices can confuse the users. The good news is that Alfresco Share is easily configurable and can be extended.

By the end of this chapter, you will know how to:

Add new action items to the Alfresco Share
Show/hide menu items based on things such as permissions or arbitrary logic
Create custom metadata template to change how Alfresco Share shows repository data
Create custom dialogs to gather information from a user
Create new pages into Alfresco Share
Create new dashlets into Alfresco Share
Assess whether the solution you are building should be based on a custom version of Alfresco Share or would be more appropriate as a custom application

Note

It is important to note that with the 4.2 release (and expanded with the 5.1 release), Alfresco introduced...

Knowing when to customize Alfresco Share and when to write your own

Before you set off on that big Alfresco Share customization project you've been dreaming of, it is important to ask yourself if the Alfresco Share is the right place for your customizations. The key consideration is how closely does your solution resemble the generic "document management" use case? If the answer is that it is quite close such that the list of substantial customizations is fairly small, then proceed. SomeCo's internal rollout is a good example of this. So far, everything SomeCo is looking to do with Alfresco has been about managing documents. The customizations have been small tweaks aimed at streamlining certain tasks for the end users.

However, if your solution is radically different from document management or is composed of several significant customizations, you should think twice about customizing Share. Instead, consider building a custom application loosely coupled to the repository through services...

Adding new menu items

Probably the simplest form of UI customization is adding new menu item in the header. In our use case, we'll add external URL.

Step-by-step - adding a simple menu item

Suppose SomeCo wanted to add a set of links to the Alfresco user interface. In this case, Alfresco Share is using the Aikauto display the header of the page. If you want to modify it, you'll need to use Aikau (and not Surf). To know where Aikau is used in Alfresco Share, you can check the following page http://docs.alfresco.com/5.1/concepts/aikau-intro.html and scroll to the section Aikau use in Share.

Let's discover a bit more about Aikau. The main goal of the Aikau framework is to provide a library of widgets that can be re-used and assembled into a web application. Aikau won't replace Alfresco Share, but will be used more and more to move from its original Surf implementation. The main objectives of Aikau are:

Maximize code re-use
Build user interfaces faster
Simplify greatly the customization of page

Don...

Adding new action items

In the previous example, we just added some generic links in the header but there was no repository action behind that. In the previous chapter, we created some repository actions and we had to use some tricks to be able to test them. And now, in this section, we'll explain how to add a UI action related to the web flag on documents.

Step-by-step - adding an action item to set the web flag

Recall that a subset of SomeCo's Whitepapers will be available on the Web. Whitepapers that need to be published to the Web are identified by the sc:webable aspect, which contains an isActive flag. SomeCo employees can add or remove a Whitepaper to or from the Web by setting the flag to true or false. But SomeCo doesn't want just anybody to be able to set that flag. Alfresco doesn't have field-level security out of the box. So how can this be implemented?

One way to do this is to configure the property to be read-only in the interface and then use two actions, available only to the...

Writing action evaluators to show/hide UI actions

In the previous example, you set up two action items to enable and disable the isActive flag for a webable piece of content. The actions only show up if a user has the appropriate permissions. But what if SomeCo wants to give several different people or groups Write permission, but only wants a subset of those folks to be able to publish documents to the Web? Not only that, but isn't it a bit sloppy to show the Enable link when the isActive flag is already set to True (and Disable when it is already set to False)?

Both of these issues are easily addressed using Spring beans and out-of-the-box Alfresco Share evaluators. Evaluators are used to control if an action item should be displayed or not. If you don't find what you need in the standard evaluators, you can as well create your own evaluator coded in Java (more information here http://docs.alfresco.com/5.1/tasks/dev-extensions-share-tutorials-custom-evaluator.html).

Step-by-step - evaluating...

Changing how Share renders forms

The majority of the forms configuration are located in the share-config-custom.xml file. Alfresco provides form controls for most of the data types, but sometimes you want to customize it. A form control is implemented as a Freemarker template.

Let's look at a couple of basic examples that can at least get you pointed in the right direction. Suppose that SomeCo's Operations department wants to track status reports in Alfresco. Status reports will be written as documents and uploaded to the Operations space. Two properties will help the Operations team get a feel for the project's status: statusSummary will be a text property meant to capture a couple of sentences summarizing the status report, and statusIndicator will be a single-value select box consisting of color-coded statuses that are Red, Yellow, or Green.

Rather than creating a "status report" type, you will model the two status-related properties as part of a "status-able" aspect that will be applied...

How to use indicators

The manager that asked to use traffic lights to have a quick understanding of the status complained that he/she has to click on each document to be able to see the status. To be more efficient, it seems that the indicator should be displayed directly in the document list. Hopefully, Alfresco provides the concept of indicators. A content in Alfresco can have one or more indicators and are used to reflect certain states. This will involve:

Create three evaluators to be able to differentiate the different states
Create three indicators for each possible state.

Step-by-step - creating indicators for the status indicator

The first step is to create indicators, as we do for the actions. Update the file share-slingshot-application-context.xml where you already created all indicators. We need to create one evaluator for each color of the traffic light:
```
<bean id="evaluator.doclib.action.statusIsGreen"  parent="evaluator.doclib.metadata.value"> 
    <property name="accessor...
```

How to create metadata template

You just received a call from the same manager that works with the Operations document. The indicator is very useful; you can have a quick overview of the status of all documents. However, when the status is Red, the only way to get the status summary is to open the document details page. It would be very helpful if we can see the status summary directly in the document list. And this manger is proposing that we replace the documentation field, by the sc:statusSummaryfield. Hopefully again, Alfresco provides the concept of metadata template. You can define the list of metadata that you want to display depending of the content type.

Step-by-step - create a metadata template for Operations document

This configuration may be the easiest one in this book. We decided that we'll remove the description line and we'll replace it with the status summary. We are lucky, we already created the evaluator used to identify if the document is an Operation document.

This time...

Creating custom dialogs

For the moment, the manager handling operational documents seems pretty satisfied by the solution that we implemented. We can work and satisfy another manager. If you remember our work on Whitepapers, we create two actions to enable and disable the Web flag. Each UI action calls the same action that we defined in the repository. Moreover, when we enable the Web flag, we update automatically the publish date with the current date. We want to improve this behavior. We want to be able to set the Web flag to true and to specify when should be the publish date. This feature will be very useful to plan the publication of the Whitepapers.

In this section, we'll:

Update the Alfresco action to receive the publication date as parameter;
Create a new form in Alfresco Share with an input field for the publication date;
Update the action definition in Alfresco Share to use the new form.

Step-by-step - creating a dialog to publish Whitepapers

To develop the custom dialog, follow these...

Creating custom dashlets

Alfresco Share includes two special pages called Dashboard, which contains windows (think Portlets) of content called Dashlets. In the current version, most of these Dashlets are Spring Surf Dashlets. As I explained in the introduction, Alfresco Share provides two platforms or technologies to accomplish that: Surf and Aikau. But we'll use only Surf in this book (except for the menu customization because it's implemented using Aikau and we don't have other options).

As explained above, Alfresco provides two dashboard: user and site dashboard. Each dashboard can be customized by selecting a layout and add only the relevant dashlets. The user dashboard is customizable by each user, and the site dashboard available for each site is customizable by all Site managers.

The following list displays all available dashlets by default in Alfresco.

Create custom pages

You discovered in the Chapter 2, Getting Started with Alfresco, that Alfresco Share is based on the concept of pages. In each site, you can add or remove pages depending of the use of this site. Alfresco Share already provides out-of-the-box pages like Document Library, Calendar, Wiki, Discussions, Blog, Links or Data Lists. In the previous section, we discovered how to create new dashlets to your different dashboards to be able to display custom content. Sometimes, the use of dahslets is not sufficient, and you want to display more information and more features. In this case, you need to create a new Surf page.

In this section, we'll:

Create a new page that you'll be able to add to any Share site;
Use the CMIS 1.1 API directly from Alfresco Share;
Create a simple Angular page to display all webable documents in a site.

Step-by-step - create a new page to list all Webable documents

In this section, we'll create a new Surf page addable to any Share site where the users will...

Summary

In this chapter, you learned that the Alfresco Share is an all-purpose user interface for general document management. It can be easily extended using approaches that range from making XML configuration file changes to writing new Surf dashlets or pages.

Specifically, you learned how to:

Add new menu items to the top bar menu
Create new actions items using dialogs or not
Show/hide action items based on things such as permissions or arbitrary logic
Create custom metadata template to change how Share shows repository data
Implement indicators in Share to reflect a status or an information on documents
Create a new form control to interact differently with metadata
Assess whether the solution you are building should be based on a custom version of Alfresco Share, or would be more appropriate as a custom application

We discovered in this chapter how you can configure and customize Alfresco Share for your use case. In the next chapter, we'll discover more about the new Alfresco Development Framework...

The rest of the chapter is locked

You have been reading a chapter from

Alfresco One 5.x Developer???s Guide - Second Edition

Published in: Feb 2017 Publisher: Packt ISBN-13: 9781787128163

A free Packt account unlocks extra newsletters, articles, discounted offers, and much more. Start advancing your knowledge today.

Unlock this book and the full library FREE for 7 days

Get unlimited access to 7000+ expert-authored eBooks and videos courses covering every tech area you can think of

Start free trial

Renews at $15.99/month. Cancel anytime}

Authors (2)

Benjamin Chevallereau

Benjamin Chevallereau is a French software architect, based in London, who has been working on Alfresco projects for the last 8 years and Ephesoft projects for the last 3 years. He implemented solutions for small companies and global organizations in different domains such as transport, finance, and government. He has worked for different Alfresco-recognized partners in France, the UK, and USA, including Armedia LLC, Zaizi, Michelin / Wipro, and BlueXML. He is also one of the committers and PMC members of the Apache CMIS Chemistry project.

See other products by Benjamin Chevallereau

Jeff Potts

Jeff Potts is the founder of Metaversant Group, Inc., a consulting firm focused on content management, search, and workflow. Jeff brings over 20 years of Enterprise Content Management implementation experience to organizations of all sizes including the Fortune 500. Throughout his consulting career he has worked on a number of projects for clients across the media and entertainment, airline, consumer packaged goods, and retail sectors. Jeff began working with and blogging about Alfresco in November of 2005. In 2006 and 2007, he published a series of Alfresco tutorials and published them on his blog, ecmarchitect.com. That work, together with other Community activity in Alfresco's forum, Wiki site, and JIRA earned him Alfresco's 2007 Community Contributor of the Year Award. In the past, Mr. Potts has worked for Alfresco Software, Inc. as Chief Community Officer, Optaros as Senior Practice Director, and Hitachi Consulting as Vice President where he ran the ECM practice.

See other products by Jeff Potts