Sun GlassFish Web Space Server 10.0 Administration Guide

Chapter 3 Customizing Sun GlassFish Web Space Server

This chapter describes some simple customization tasks, most of which can be done from the user interface of Web Space Server. For more serious changes to the product configuration, you need to make changes to the portal-ext.properties file. A simple example for making changes to the portal-ext.properties file, see Localization Support. For details of properties in the portal-ext.properties file, see Customizing Web Space Server Using the portal-ext.properties File. The following sections describes how to customize Web Space Server

Branding and Site Identity

You can use Web Space Server on your web site to customize the branding to establish your site identity.

To Change the Banner Logo

Choose Control Panel -> Portal -> Settings from the Welcome menu.

Click the Change link.

You are prompted to browse and select a new banner logo.

Select the file to use for the logo.

To Change the Address Bar and Browser Tab Icons

Navigate to the directory that contains the Web Space Server installation.

Change to the var/webspace/war-workspacedirectory.

cd ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace.

Change to the customs/webspace/html/themes/classic/images directory, and place liferay.ico image in the folder.

Note –
The default icon for the address bar and browser tabs is named liferay.ico. You can override the icon with an image with the same name.

After any customization you need to run ant -f synchronize.xml at the root of the customs folder.
1. Change to the ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace directory.
  
  cd ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace
2. Run ant -f synchronize.xml
  
  This will prompt for the war to synchronize, choose the default (which is webspace).

Restart the GlassFish server.

Clear the browser cache and reload the page.

Friendly URLs

Friendly URL is the part of the URL for a page on Web Space Server that can be customized as desired.

To Change the Friendly URL of a Page

Choose Manage Pages from the Welcome menu.

Figure 3–1 Manage Pages Page

The Friendly URL for the Welcome page in the Guest community is http://machine-name:8080/web/guest/home. You can directly access the PeopleSpace page by typing this URL. http://machine-name:8080/web/guest/home.

Change the value of the Friendly URL to the value you like.

For example, you can change it from home to my_home.

Click Save.

A message saying that the page is not found appears. For the changed URL to take effect, log out of Web Space Server and then log in again.

The changed URL for the PeopleSpace page is http://machine-name:8080/web/guest/my_home.

Site Layout and Navigation

Layout Templates enables you to choose how your portlets are arranged on a page. They make up the body of your page, the large area where you drag and drop your portlets to create your pages. Web Space Server comes with several built-in layout templates. However, if you have a complex page layout (especially for your home page), you might want to create a custom layout template of your own. See the development document in Liferay Documentation for the procedure to create a custom Layout Template.

To Change the Site Layout

Choose Layout Template from the Welcome menu.

The Layout page appears.

Select the layout you want to use and click Save.

Changing the Page Theme

Themes are hot deployable plugins that can completely transform the look and feel of the portal. Most organizations have their own look and feel standards for all the web sites and web applications in their infrastructure. Web Space Server enables site designers to create and install a theme plugin that can transform the portal to whatever look and feel is needed. See the development document in Liferay Documentation for the procedure to create a custom theme.

To Change the Page Theme

Log in to Sun GlassFish Web Space Server.

Any user can change themes, but only the admin user has access to all available themes, and has the privilege to install more themes.

Choose Manage Pages from the Welcome menu.

Click the Look and Feel tab.

The current theme for the page and its associated color schemes, and all the available themes, are displayed.

To change the theme, choose a theme from Available Themes.

The theme is applied to your page.

Click Save.

Using Bundled Web Space Server Portlets

A wide array of portlets is bundled with Web Space Server as part of its core and samples.

To Add Bundled Web Space Server Portlets

Choose Add Applications from the Welcome menu.

Locate the desired portlet.

You can search for a portlet by providing a search string for it or by expanding the portlet folder and clicking Add next to a selected portlet. For example, to add some social networking portlets to your page, expand the Social folder. You can add Activities and Requests portlets to your page by clicking the Add button corresponding to the portlet.

Add the required portlet to your page by clicking the Add button next to the portlet.

Look and Feel and Configuration of Portlets

You can customize the display name and look and feel of a portlet.

Changing the Name of a Portlet

You can change the display name of a portlet.

To Change the Name of a Portlet Located on a Private Page

Click the menu bar of a portlet.

For example, click the menu bar of the Languages portlet.

Figure 3–2 Changing the Display Name of a Portlet

Edit the name of the portlet, and click outside the name box for the change to take effect.

In this example, change the name of the portlet to Locales.

Figure 3–3 Changed Display Name

To Change the Name of a Portlet Located on a Public Page

Navigate to a public page of the user by choosing My Places on the Welcome menu.

Edit the portlet name.
1. Click the menu bar of a portlet
2. Edit its name.
3. Leave the menu bar

Customizing the Look and Feel and Configuration of a Portlet

You can customize the look and feel and configuration of a portlet. The menu bar of a portlet displays its name and the menu controls associated with it. All portlets have Look and Feel and Configuration menu controls, and some portlets have an additional menu control.

Note –

In order to access the menu controls of a portlet, Toggle Edit Controls must be set on. You can set Toggle Edit Controls from the Welcome menu.

Figure 3–4 Look and Feel and Configuration Menu Controls of a Portlet

Look and Feel Menu Control of a Portlet

Clicking the Look and Feel menu control button displays a window that provides options to customize the look and feel of the portlet.

Figure 3–5 Customizing the Look and Feel

This section describes the options in the Look and Feel window tabs.

Portlet Configuration Tab

The Use Custom Title option enables you to change the title of the Portlet. The Show Borders option enables or disables the display of borders.

Text Styles Tab

Using this tab, you can change the default settings for text such as font, size, color, alignment, bold, and italic.

Background Styles Tab

Using this tab, you can change the default background color for the portlet.

Border Styles Tab

Using this tab, you can change the border styles for the portlet. You can change the default settings for the border width, border style, and border color. You can set different width, style, and colors for different borders by disabling the Same for All option.

Margin and Padding Tab

Using this tab, you can change the default margin and padding settings. Be careful when changing the default margin and padding settings.

Advanced Styling Tab

Using this tab, you can define CSS rules for the portlet and all similar portlets.

WAP Styling tab

Using this tab, you can define the styling for mobile handsets.

Configuration Menu Control of a Portlet

Clicking the Customization button displays a window through which you can configure permissions for the portlet, can export or import the portlet data, and can enable sharing on the portlet or widget.

For a detailed example of using the Configuration button to enable sharing of portlets, see Enabling Sharing of a Portlet

Localization Support

Web Space Server is localized out-of-box in 22 languages. Sun provides localization support for Japanese (ja) and Simplified Chinese (zh_CN) but support for others is community driven.

The following sections describe how to perform localization:

Setting the User-Preferred Language in Web Space Server

Users can use Web Space Server in any of the supported languages.

To Set a User-Preferred Language

Choose My Account from the Welcome menu.

The Control Panel is displayed.

Choose Display Settings under Miscellaneous in the menu on the right.

Select a language from the Language drop-down list.

Click Save.

The user interface changes to the language selected.

Note –
You can use the same page to change the time zone and the greeting message.

Adding a New Language Support

You can add localization support for a language that is not supported by Web Space Server by default. This section describes how you can add localization support for a new language.

To Add New Language Support

This task describes how to create a portal-ext.properties file, and make changes to it to support localization.

Create a temporary folder. In this example, name the folder as test.

mkdir /tmp/test

Copy portal-impl.jar to the tmp folder.

The portal-impl.jar file contains resource bundles for Web Space Server. This JAR file is located in the GlassFish install-dir/domains/domain1/application/j2ee-modules/webspace/WEB-INF/lib/ directory.

cd GlassFish-install-dir/domains/domain1/application/j2ee-modules

cp webspace/WEB-INF/lib/portal-impl.jar /tmp/test

Change to the tmp directory.

cd /tmp/test

Extract the portal-impl.jar file.

jar -xvf portal-impl.jar

The portal.properties file will be placed in the current directory.

Open portal.properties and copy the locales property from the Languages and Time Zones section.

If a portal-ext.properties file does not already exist, create a text file with that name.

The default location of portal-ext.properties is GlassFish home/applications/j2ee-modules/webspace/WEB-INF/classes/portal-ext.properties.

Paste the locales property into the portal-ext.properties file.

Add the new locale at the end of the locales property in the format LanguageCode_CountryCode.

See the following links to find language and country codes:
- http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt for language codes.
- http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html for country codes.
For example, if you are adding support for Hindi, you need to add hi_IN at the end of locales property as follows:
```
locales=ar_SA,ca_AD,ca_ES,zh_CN,zh_TW,cs_CZ,nl_NL,en_US,fi_FI,fr_FR,de_DE,el_GR,hu_HU,
it_IT,ja_JP,ko_KR,nb_NO,fa_IR,pt_BR,ru_RU,es_ES,sv_SE,tr_TR,vi_VN,hi_IN
```

Save the portal-ext.properties file.

Navigate to the content folder and open the Language.properties file.

Note –
A folder named content was created when you extracted the portal-impl.jar file.

Translate all the strings you want to localize from temp/test/content/Language.properties to the new language.

Rename the translated Language.properties file to Language-ext_LanguageCode.properties.native.

Run the following command on the directories that contains the Language-ext_LanguageCode.properties.native file:

native2ascii -encoding UTF-8 Language-ext_LanguageCode.properties.native Language-ext_LanguageCode.properties

Create a directory structure webspace/WEB-INF/classes/ under ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace/customs, and copy portal-ext.properties file to it.

Create a directory structure webspace/WEB-INF/classes/content under ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace/customs, and copy Language-ext_LanguageCode.properties.native file to it.

Change to the ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace directory.

cd ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace

Run ant -f synchronize.xml.

Restart theGlassFish server.

To Verify the Localization of the Interface

Choose My Account from the Welcome menu.

The Control Panel is displayed.

Choose Display Settings under Miscellaneous.

The new language setting is reflected in the Language drop-down menu.

Select the language for the user and click Save.

The user interface is changed to the new language.

Removing Localization Support for Unwanted Languages

Generally, users don't require localization support for all languages that are supported by Web Space Server. This section describes how you can remove localization support for the languages that are not required.

To Remove Localization Support for Unwanted Languages

Create a temporary folder. In this example, name the folder as test.

mkdir /tmp/test

Copy portal-impl.jar to the tmp folder.

portal-impl.jar contains language resource bundles for Web Space Server. This JAR file is located in the GlassFish install-dir/domains/domain1/application/j2ee-modules/webspace/WEB-INF/lib/ directory.

cd GlassFish-install-dir/domains/domain1/application/j2ee-modules

cp webspace/WEB-INF/lib/portal-impl.jar /tmp/test

Change to the tmp directory.

cd /tmp/test

Extract the portal-impl.jar file.

jar -xvf portal-impl.jar

Open portal.properties and copy the locales property from the Languages and Time Zones section.

If portal-ext.properties does exist in Web Space Server then paste the locales property into it. Otherwise, create a text file (using any text editor) and name it as portal-ext.properties, and paste the locales property into it.

Default location of portal-ext.properties is GlassFish home/applications/j2ee-modules/webspace/WEB-INF/classes/portal-ext.properties.

Edit the locales property to include only the languages that are needed.

For example, if you want to support only English, German and Spanish, remove all the unwanted locales so that the locales value looks as follows:
```
locales=en_US,de_DE,es_ES
```

Save the portal-ext.properties file.

Create a directory structure webspace/WEB-INF/classes/ under ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace/customs, and copy the portal-ext.properties file to it.

Change to the ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace directory.

cd ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace

Run ant -f synchronize.xml.

Restart the GlassFish server.

The server will redeploy websynergy.war and update portal-ext.properties under applications/j2ee-modules/webspace/WEB-INF/classes.

Enabling the Guest Users to Select a Browser Language

Guest users can select their preferred browser language.

To Enable Guest Users to Select a Browser Language

Create a temporary folder, named test.

mkdir /tmp/test

Copy portal-impl.jar to the tmp folder.

portal-impl.jar contains language resource bundles for Web Space Server. This JAR file is located in the GlassFish install-dir/domains/domain1/application/j2ee-modules/webspace/WEB-INF/lib/ directory.

cd GlassFish-install-dir/domains/domain1/application/j2ee-modules

cp webspace/WEB-INF/lib/portal-impl.jar /tmp/test

Change to the tmpdirectory.

cd /tmp/test

Extract the portal-impl.jar file.

jar -xvf portal-impl.jar

The portal.properties file will be placed in the current directory.

Open portal.properties and copy the locale.default.request property from the Languages and Time Zones section.

If portal-ext.properties does exist in Web Space Server then paste the locale.default.request property into it. Otherwise, create a text file (using any text editor) and name it as portal-ext.properties, and paste the locale.default.request property into it.

Default location of portal-ext.properties is GlassFish home/applications/j2ee-modules/webspace/WEB-INF/classes/portal-ext.properties.

Set the property to locale.default.request=true.

Save the portal-ext.properties file.

Create a directory structure webspace/WEB-INF/classes/ under ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace/customs, and copy the portal-ext.properties file to it.

Change to the ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspacedirectory.

cd ZIP_ROOT/webspace-for-gfv2/var/webspace/war-workspace

Run ant -f synchronize.xml.

Restart the GlassFish server.

It will redeploy websynergy.war and update portal-ext.properties under applications/j2ee-modules/webspace/WEB-INF/classes. Clear browser cookies before accessing Web Space Server interface to allow the changes to take effect.

Precedence Hierarchy for `Language.properties` Files

Language and display information is defined in the Language.properties, as well as various other Language_LanguageCode.properties files for foreign languages. When you extract the portal-impl.jar file, these files are placed in the content folder. Language.properties is the primary and default language definition file, but definitions in that file may be overridden by language-specific definitions. For example, the file Language_en.properties contains the English versions of most of the definitions, the file Language_fr.properties contains the French version, and so on.

Language files can further have locale-specific definitions. The Language_en_US.properties file contains English phrase variations further defined for the United States. Other languages can also have locale-specific definitions.

Rules of Precedence

The hierarchy of precedence for different Language.properties files is:

Language-ext.properties takes precedence over Language.properties.
Language-specific versions take precedence over the non language-specific versions. For example, Language_en.properties takes precedence over Language.properties.
Location-specific versions take precedence over the non location-specific versions. For example, Language_en_US.properties takes precedence over Language_en.properties.

For the Language.properties file for English, Language-ext_en_US.properties has the highest precedence and the Language.properties file has the least precedence. The hierarchy is:

Language-ext_en_US.properties
Language_en_US.properties
Language-ext_en.properties
Language_en.properties
Language-ext.properties
Language.properties

Changing the Existing Language Entries

You can easily change existing English and foreign languages entries in Web Space Server. Consider the example of changing the name of a portlet from Message Boards to Forums. To do this when English is the default language, you would create the Language-ext_en.properties to override the Language_en.properties file. In Language-ext_en.properties, duplicate the content in the Language_en.properties file, and replace the entry javax.portlet.title.19=Message Boards with javax.portlet.title.19=Forums. The portlet Message Boards is renamed to Forums.

You can also add new language entries for customization or for new portlets. For example, you can create an entry similar to javax.portlet.title.EXT_1=Reports to add the name of a new portlet named Reports.

Customizing Portlet Names While Localizing

You can customize the name of a ported for any language by using the Look and Feel button on the portlet. Consider the example of localizing Web Space Server to French. In this case, the name of the Admin portlet translates as Administration du portail. You might prefer to have a customized name for the Admin portlet when Web Space Server is localized to French.

To Customize the Name of a Portlet While Localizing the User Interface

Click the Look and Feel button on a portlet.

In this example, click the Look and Feel button on the Admin portlet.

Select the Use Custom Title option.

Select a language from the language list.

In this example, select French.

Type a title for the portlet in the selected language in the Portlet Title box.

In this example, type the name Administration.

Click Save.

Note –
For the changes to take effect, you may have to save twice: once with the Use Custom Title option deselected and again with selected. Some times the portlet name in the default language too may have changed. You need to verify this.

Choose My Account from the Welcome menu.

Choose Display Settings under Miscellaneous.

Select a language from the Language list that is the same as the language selected previously.

For example, select French.

Click Save and navigate back to the community page.

You can see the changed name of the portlet in the localized version. In this example, the name of the Admin portlet localized to French is changed from Administration du portail to Administration.