...
Some settings for Grouper UI customization are described here. Look in grouper-ui-ng.base.properties for more settings in the UI.
| Table of Contents |
|---|
Adding Custom CSS Files
Grouper has its own CSS stylesheets, but provides a mechanism for site-specific stylesheets to be loaded after the Grouper stylesheets. This allows sites to override/extend existing styles and to add new styles. Such changes can alter the position of screen elements, fonts, colors, etc.
...
Since pages in the UI have the base UI /grouperUi/app/UiV2Main.index, you can reference the root of the webapp with "../../".
Changing the Internet2 Logo
The grouper-ui property image.organisation-logo is the path to the organization logo that appears in the banner. The default value is grouperExternal/public/assets/images/organisation-logo.gif. To change this to your own image you can either:
...
Note that the default template in Grouper only supports an image in the banner, not additional text.
Changing the Institution Name
The institution name that appears on the main page and in the footer is defined in the text resource bundle (grouperText/grouper.textNg.en.us.base.properties), property institutionName. You will likely want to change this from its default "Institute of Higher Education". This can be configured in overlay file grouperText/grouper.text.en.us.properties, or in the database configuration for config file "grouper.text.en.us.properties".
Changing the browser title
Set an env name in grouper.properties and use this in externalized text (v4.9.0+)
| Code Block |
|---|
grouperAppName = PennGroups
browserTitleSuffix = , $$grouperAppName$$ ${edu.internet2.middleware.grouper.cfg.GrouperConfig.retrieveConfig().propertyValueString("grouper.env.name")} |
Changing the Default Language
The Grouper UI supports internationalization for all navigational text and instructions. Text strings in UI templates are keyword pointers to the actual text in Java ResourceBundle files, which are property files stored in WEB-INF/classes/grouperText/grouper.textNg.<language>.<country>.base.properties. The default language is English (en_us), but a set of French translations (fr_fr) is packaged with Grouper.
...
| Panel |
|---|
grouper.text.defaultBundleIndex = 0 grouper.text.bundle.0.language = en |
Changing UI Text
In the standard UI, all navigational text and instructions are derived from a Java ResourceBundle grouperText/grouper.textNg.en.us.base.properties (or other language equivalent). Custom properties to override default values can be added to overlay property file grouperText/grouper.text.en.us.properties, or a database configuration entry can be added to configuration "grouper.text.en.us.properties". Note that in the UI configuration, only overrides will be shown, not the large list of default values from the base properties file.
If you create your own JSP templates or Java classes, you are not under any obligation to use ResourceBundles instead of directly entering hard-coded text. However, if you wish to contribute code back to Grouper, such a contribution would be more useful if it used externalized text.
Legacy Settings Invalid for Grouper 2.5+
| Warning |
|---|
Information below this point is primarily relevant for the older "Admin UI" or "Lite UI", and generally will not apply to Grouper 2.5+ |
...
Some configuration that you generally will not need to change in upgrading to Grouper 2.2 is in media.properties.
Using Custom Templates Instead of the Standard Templates
The Grouper UI uses Strut's Tiles to define core page components. In the standard UI these are defined in grouper-qs/grouper-ui/webapp/WEB-INF/tiles-def.xml. In the custom UI some definitions are modified and another added in the filegrouper-qs/custom-grouper-ui/webapp/WEB-INF/tiles-def-custom.xml. New definitions for headerDef and footerDef allow site specific branding. groupStuffDef defines a template which is included in the Group Summary page of the UI.
EasyLoginFormDef defines a new page (see Customising Authentication).
Defining Custom Dynamic Templates
Grouper recognises some core entities such as Groups, Stems, Subjects and Collections. The Grouper UI dynamically chooses the appropriate template for an entity at runtime based on its type and the UI context. The default templates for an entity and view are defined in grouper-qs/grouper-ui/resources/grouper/media.properties. When a specific entity-view key is not found, a default is used. Key-value pairs can be overridden, or more specific keys added to grouper-qs/custom-grouper-ui/resources/grouper/media.properties. The algorithms used to choose appropriate keys are described in the Javadoc for DefaultTemplateResolverImpl. This class can be extended to add support for other entity types, or a completely new implementation plugged in (see Javadoc for the TemplateResolver interface.
...
defines a specific template for subjects whose source has an ID of personQS. In the UI examples the name Keith Benson is followed by (kebe) in the custom UI due to the use of /WEB-INF/jsp/custom/customPersonSubjectView.jsp as a template. Subjects and groups may have any number of site specific attributes, so dynamic templates allow sites to create templates which have access to these custom attributes.
See Determining How a Grouper UI Page is Constructed for determining which template was chosen for an entity-view on a page in the UI.
| Anchor | ||||
|---|---|---|---|---|
|
Modifying Existing Structs Actions, Adding new Actions, and Making New Tiles Definitions Available
The Grouper UI is based on Struts and the standard Struts configuration is through grouper-qs/grouper-ui/webapp/WEB-INF/struts-config.xml. Existing actions can be replaced and new ones added to grouper-qs/custom-grouper-ui/webapp/WEB-INF/struts-config-custom.xml.
...
Even if you don't need to change/add any actions, a Tiles plugin must be configured in order to make custom templates available (see Using Custom Templates instead of the standard templates):
...
Note that the order of files in the definitions-config property is important as the last Tile definition with a particular name loaded is used.
| Anchor | ||||
|---|---|---|---|---|
|
Customising Authentication
The standard UI uses basic HTTP authentication configured through Tomcat and the web application web.xml file. A Filter LoginCheckFilter checks if you are logged in before allowing access to the application. It checks the javax.servlet.http.HttpServletRequest.getRemoteUser(). If not set the user is redirected to the splash page, otherwise, access is granted, and if necessary, the user session initialised.
...
In order to configure new Filters, it is necessary to modify the web application web.xml file. How to do this is described in Customising web.xml.
Note: The standard UI does not have a logout link, because it is not possible to safely logout of basic HTTP authentication. Other authentication schemes will generally work by setting an HttpSession attribute - which is cleared when an HttpSession is invalidated, so a logout link is provided.
...
| Anchor | ||||
|---|---|---|---|---|
|
Customising group authorizations
As of v1.3.0 it is possible to override how the UI decides what the current user can do with a group. The primary motivation for this feature is to allow some UI features to be turned off i.e. when the feature should be maintained by a loader. Customization is achieved by implementing the UIGroupPrivilegeResolver interface, and configuring it through media.properties e.g.
| No Format |
|---|
edu.internet2.middleware.grouper.ui.UIGroupPrivilegeResolver=uk.ac.bris.is.grouper.ui.UoBUIGroupPrivilegeResolver |
| Anchor | ||||
|---|---|---|---|---|
|
Customising the Root Node of the Grouper Repository
*see also Customizing Browsing and Searching
The Grouper API defines a root stem. In the standard UI the Current location begins with Root whereas in the custom UI it starts with QS University of Bristol. Both screen shots are views of the same Grouper repository. Three scenarios are possible
...
| Anchor | ||||
|---|---|---|---|---|
|
Creating an InitialStems View
*see also Customizing Browsing and Searching
This feature is not implemented in either the standard or custom UIs; however, it provides an alternative starting point for browsing, by allowing sites to provide a customised list of stems or quick links. The list of stems can come from any part of the hierarchy, and so may provide a better starting point for users, i.e., for GrouperSystem the default view is:
...
As of Grouper 0.9 it is possible to define a different InitialStems implementation for each browse mode; see AbstractRepositoryBrowser.getInitialStems()
| Anchor | ||||
|---|---|---|---|---|
|
Customising Browsing and Searching
As of version 0.9 of Grouper it is possible to customise existing browse modes and add new browse modes. It is also possible to specify root nodes and InitialStem implementations on a mode by mode basis.
...
Alternatively, new browse modes can be implemented and configured. In general you will also need to implement a top level Strut's action and page for any new browse mode, and provide links as appropriate. See Customising the Menu\ for details on how to change the default menu.
| Anchor | ||||
|---|---|---|---|---|
|
Customising the Menu
As of version 0.9 of Grouper the menu is configurable. PrepareMenuActionreads resources/grouper/menu-items.xml to obtain a list of known menu items. A media.properties key, menu.order, determines the order in which items are rendered.
...
| Anchor | ||||
|---|---|---|---|---|
|
Personal Groups
Grouper has no specific support for personal groups, however, by implementing the PersonalStem interface, the Grouper UI will create a 'personal stem' for a user (if one does not exist) at login. An implementation of PersonalStem is provided at grouper-qs/custom-grouper-ui/java/src/edu/internet2/middleware/grouper/customqs/ui/CustomQSPresonalStem.java. This implementation creates a stem (extension=subject id) as a child of /qsuob/personal. Currently any user who is logged in can see personal stems. Whether they can see groups in the personal stem will depend upon Access privileges. Sites could use custom implementations of RepositoryBrowsers to implement their own business rules around personal stems and groups.
| Anchor | ||||
|---|---|---|---|---|
|
Displaying subjects, groups, and stems
Prior to Grouper v1.2.0 it was necessary to use custom dynamic tiles to change how subjects, groups and stems are displayed. This still remains the most flexible approach, especially if you need to show more than one attribute.
...
You could use this feature to create virtual attributes as composites of other attributes.
| Anchor | ||||
|---|---|---|---|---|
|
Sort order of lists
As of Grouper v1.2.0 various lists may be sorted alphabetically.
...
In principle, the sort algorithm should use exactly what is displayed on screen to sort lists, and, by default, this is what it does. The sort algorithm, therefore, takes account of the configuration for Displaying subjects, groups and stems. On the other hand, Grouper allows the use of dynamic tiles and so it is possible to override the defaults in a way that the sort algorithm cannot work out. If a site does use dynamic tiles to display subjects, groups or stems, it is possible to configure Grouper to use alternate configuration for sorting, but it is the responsibility of the administrator to ensure that the sort configuration is appropriate for what is displayed on screen. For maximum flexibility, it is also possible to configure different attribute(s) to sort on for different contexts*. The 'search' order for keys is documented for each implementation of GrouperComparatorHelper.
...
| Anchor | ||||
|---|---|---|---|---|
|
Enabling import / export of group memberships
As of Grouper v1.2.0 it is possible to configure the UI to enable import / export of group memberships. Simple implementation classes are provided for dealing with tab or comma delimited files. In general, the formats for import or export vary for different sites. By default import / export is not enabled. Import is controlled by MembershipImportManager and a DefaultMembershipImporter class is provided. Export is controlled by MembershipExporter.
...
If a user does not select a file to import, the user is presented with a text area where they can type or paste data.
| Anchor | ||||
|---|---|---|---|---|
|
Customising the Build Process
The Grouper UI uses the grouper-qs/grouper-ui/build.xml ant script to build the web application. This script is configured throughgrouper-qs/grouper-ui/build.properties, which has a key additional.build. In the custom UI this is set to \${basedir}/../custom-grouper-ui/additional-build.xml. It is the responsibility of this script, which is called by the standard script, to compile any Java source files and to copy to the build area any other necessary files. If you wish to incorporate any contributed code, calls to the relevant build scripts should be placed here. In the custom-grouper-ui/additional-build.xml script, the struts-patch build script is called.
| Anchor | ||||
|---|---|---|---|---|
|
Customising web.xml
A web application web.xml file is a key configuration file and any site wishing to customise the Grouper UI will need to modify it. The web.xml is a J2EE deployment descriptor which configures the Servlets (how URLs are mapped to Java classes), the filters (pre/post logic around servlets), j2ee security (if not done in apache or somewhere else), listeners (for j2ee events), custom tag libraries (how some tags in JSPs map to java classes), etc. Things you might need to customize are filters (e.g. a new way to do authentication / authorization), security (do you want the servlet container to manage authentication / authorization?), custom tag libraries (are you using a new library in JSP extensions?), etc.
The default deployment descriptor is found at grouper-qs/grouper-ui/webapp/WEB-INF/web.core.xml. The UI provies a mechanism for merging fragments of different web.xml files into a final deployment file. In your additional build script (see Customising the Build Process copy any web.xml fragments into \${temp.dir}. Typically files should be prefixed with a 2 digit number e.g. 20 (90 is used for web.core.ml). The merging process merges in name order of the files.
The custom UI includes two web.xml fragments which, when copied, are prefixed with 00 and 95 so the former is merged with web.core.xml and the latter is merged with the result of the first merge.
...
| Anchor | ||||
|---|---|---|---|---|
|
Running the standard UI at the same time as the custom UI
By applying the struts-patch contribution (see Customising the Build Process), and configuring the Struts action servlet with more than one module see (config/i2mi parameter in Customising web.xml), it is possible to have both the standard and custom UIs available at the same time.
...
| Anchor | ||||
|---|---|---|---|---|
|
Determining How a Grouper UI Page Was Constructed
Since a Grouper UI page may be constructed from many templates, including dynamic templates, and it may not be easy to determine which ResourceBundle key was used to render text, a mechanism has been created to display debug information. Go to the URl /grouper/populateDebugPrefs.do. You should see a form:
...
*These fields are only required if you wish to link template names to a JSP editor.
| Anchor | ||||
|---|---|---|---|---|
|
Providing Feedback and Getting Help
The Grouper UI is intended to be extensible and not to force unnecessary constraints, however, it is only as sites try to make their own customisations that the true extensibility can be tested. If while customising the Grouper UI you find yourself forced to modify standard Grouper UI sources (of any kind), or find that you cannot easily do what you want to, please offer feedback to, or request help via the grouper-users mailing list.