Share Header

Document created by resplin Employee on Jun 6, 2015Last modified by alfresco-archivist on Aug 31, 2016
Version 6Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com



Alfresco Share3.4


Overview


The 3.4a release introduces the ability to customize the main header bar in the Share application via the share-config-custom.xml mechanism. The following describes what customizations are available and how to achieve them.

The default Share header for a non-admin user looks like:

frame|c|none|Default user header

...an admin user also has access to the individual tools within the Share Admin Console:

frame|c|none|Default admin menu

Previously, these two different configurations were accomplished using some logic within the Freemarker template, which was tricky to find and extend. Version 3.4.a introduces a configuration-based header which is much easier to extend.

The header config reader is defined at the top of share-config.xml as:


<element-reader element-name='header' class='org.alfresco.web.config.header.HeaderElementReader'/>




Header Structure


The header bar in Share is constructed from four parts:


  • the logo
  • the application items (icon above, text below)
  • the user items (text only, positioned above the search area)
  • the search area

Application and User items can be static links, dynamic links or menus (more on those later). The configuration structure for these two types is exactly the same, but Share renders them differently. By default they are logically split into those items referring to the application (Sites, People, etc.) and the user (Profile, Change Password, etc.). This distinction is not enforced by the implementation, but is more a guide for a better user experience.




Logo


The logo is both themeable and replaceable via the i18n mechanism.


Alfresco Share

  • {theme} is the current application theme, e.g. default, yellowTheme, etc.
  • {logo} is the resolved i18n message header.logo, e.g. header.logo=app-logo.png in slingshot.properties




Application and User Items


Application header items refer to those to the left of the header area consisting of an icon and text, whereas User items are positioned above the search bar and are text only (due to the compressed spacing of user items, they do not support icons).

frame|c|left|Link item frame|c|none|Menu item




Search Area


The search box and dropdown are rendered as part of the header, but are not currently configurable.

frame|c|none|Search area


Configuration


A default header has been defined in share-config.xml. In order to customise to your own needs, you need to replace the default structure in a share-config-custom.xml file in the Tomcat/shared/classes/alfresco/web-extension. See the notes in Install Tomcat6 to ensure extensions will be picked up.

Copy the entire <header>...</header> XML structure as follows, noting the replace='true' attribute:



<alfresco-config>
   <config replace='true'>
      <header>
         ...
      </header>
   </config>
</alfresco-config>

There are three sections to the header configuration:


  • <app-items> and <user-items> to define each header section respectively.
  • <dependencies> declares required client-side JavaScript and Stylesheet includes (e.g. for Sites menu)

In terms of configuration, there is no difference between the application and user items.




Item Config


An item is declared using an <item> node.


















Attribute
Mandatory
Description
type yes Item type. Can be one of:
  • link
  • external-link
  • container
  • js
  • user
id yes Used to uniquely define the header item. Only needs to be unique within it's container.
icon no Image URL, relative to components/images/header/.

If not supplied, an image named components/images/header/{id}.png will be rendered.
For no icon, use icon=''. A user item must not define an icon.

label no Label text or i18n property.

If not supplied, an i18n message header.{id}.label will be rendered.
For no label, use label=''.

description no Description (hover state) text or i18n property.

If not supplied, an i18n message header.{id}.description will be rendered.
For no description, use description=''.

permission no Currently only admin supported, which restricts the visibility of the link to members of the Administrators group.
condition no Any Freemarker expression that results in a boolean true or false value.

The item will only be rendered if the condition is true.





'link' and 'external-link' types


These, as their name would suggest, generate internal and external links (the difference being the external link type is rendered with target='_blank'). The link is specified within the node value and can be one of the following formats:


  • Share page. Relative to the /page servlet, e.g. /my-tasks, /site/marketing/documentlibrary
  • Full URL, e.g. http://www.google.co.uk/
  • Share URI template or Help page, e.g. {userdashboardpage}, {share-help}

Examples:


<item type='link' id='marketing-doclib' label='Marketing' description='Marketing Document Library' icon='../filetypes/generic-folder-16.png'>/site/marketing/documentlibrary</item>

<item type='external-link' id='bbc' label='BBC News' description='' icon='../info-16.png'>http://news.bbc.co.uk/</item>

<item type='link' id='help'>{share-help}</item>




'container' type


Must contain only <container-group> nodes. Container groups support the permission and condition attributes which are cascaded to all contained items.












Attribute
Mandatory
Description
id yes Used to uniquely define the container group. Only needs to be unique within it's item parent.
label no Label text or i18n property.

If not supplied, an i18n message header.{id}.label will be rendered.
For no label, use label=''.

permission no Currently only admin supported, which restricts the visibility of the contained items to members of the Administrators group.
condition no Any Freemarker expression that results in a boolean true or false value.

The container will only be rendered if the condition is true.


Examples:


<container-group id='tools' permission='admin'>
   <item type='link' id='application'>/console/admin-console/application</item>
   <item type='link' id='groups'>/console/admin-console/groups</item>
   <item type='link' id='replication-jobs'>/console/admin-console/replication-jobs</item>
   <item type='link' id='users'>/console/admin-console/users</item>
</container-group>

<container-group id='blogs' label='Blogs...'>
   <item type='external-link' id='mike' label='Mike Hatfield' description='' icon='../comment-16.png'>http://blogs.alfresco.com/wp/mikeh/</item>
   <item type='external-link' id='kev' label='Kevin Roast' description='' icon='../comment-16.png'>http://blogs.alfresco.com/wp/kevinr/</item>
   <item type='external-link' id='will' label='Will Abson' description='' icon='../comment-16.png'>http://blogs.alfresco.com/wp/wabson/</item>
</container-group>




'js' type


Renders a placeholder button which can then be 'taken over' by some client-side JavaScript implementation. The JavaScript class is specified in the node's value, e.g. Alfresco.module.Sites and its implementation must be declared via the <dependencies> tag (see below).

Example:



      <item type='js' id='sites'>Alfresco.module.Sites</item>
   ...
   <dependencies>
      <css src='/modules/create-site.css' />
      <css src='/modules/header/sites.css' />
      <js src='/modules/create-site.js' />
      <js src='/modules/header/sites.js' />
   </dependencies>

A header module is very similar to a standard Share module, but doesn't render it's own initial HTML mark-up. Upon instantiation, it's given the DOM ID of the element created as the placeholder. It's entirely up to the module to decide what to do with this existing element, but it's strongly recommended that it be rendered as a YUI Button widget to maintain consistency within the header.

See the Alfresco.module.Sites implementation in modules/header/sites.js for example code.




'user' type


The user type is a special case used to render the avatar and status update UI. It is intended to be used once as a sub-item of the user items menu. Any other use is unsupported at this time.




Dependency Config


The <dependencies> section supports the JavaScript item type. Client-side JavaScript and Stylesheet links should be defined here, which will be loaded as part of the header rendering sequence.

Outcomes