Editing the Web Template Files

Editing the Web Template Files 24-Sep-09

Editing the Web Template Files

This tutorial describes the process of editing the PHP files to make global changes to the layout, color, font, and text within the CONTENTdm Web templates. This documentation is not intended to take the place of having working knowledge of HTML, PHP, Java Script files, or framesets.

Before making changes to any CONTENTdm Web template files, be sure to make a backup copy so you can restore the original if needed. Keep in mind that even simple text changes could alter the layout of your Web templates.

The first step to customizing your site is to change the text of the Home page (index.php), About page (about.php), or Help page (help.php). To do this, edit the text in the files using a Web development tool or text editor such as TextPad. The files are located in the docs directory of the CONTENTdm server. About.php and help.php are located in the cdm4 subdirectory of the docs directory. Fundamental knowledge of HTML is recommended before changing these files.

Learn About:

Section I: Overview General Guidelines Variables

Section II: Editing the Style File Frequently Used Variables Color Changes to the Web Templates

Section III: Editing the Header File Changing the Header File Example

Section IV: Editing the Footer File Altering Footer Height

Section V: Editing the Localization File Changing Menu Options to Use Capitalization

Section I: Overview

This tutorial shows examples of changes you can make to your Web Templates. Modifying the files described in this guide enables you to change the appearance (color, layout, language or text) of the CONTENTdm Web templates. Changes made to global files and variables propagate throughout your Web template pages so the edits can be made once rather than on each Web page. Experienced Web developers can customize the existing templates as needed.

To edit HTML or the PHP files described in this tutorial, you must have access to the docs directory of the CONTENTdm server. If you do not have access to these files, contact your system administrator.

There are other tools within CONTENTdm that you can use to further customize your CONTENTdm site. To create queries or control the layout of the results displayed in your collection search results, see the Custom Queries and Results help files.

One of the most common changes that people wish to make are text changes to the index.php, about.php, and help.php files. Follow the general guidelines to make text changes to these files.

© 2009 OCLC Page 1 of 19

http://www.contentdm.org/help5/custom/cqr.asp


General Guidelines

Use the following guidelines when editing any PHP file:

1. Determine what changes in what files that you wish to make.

2. Make backup copies of all files that you plan to alter.

3. Open the file you wish to edit in your HTML editing software or in a text editor.

The CONTENTdm Web templates are Unicode compatible. When editing the files, be sure to use an editor that supports UTF-8 encoding. Some text editors, such as Notepad, add a Byte Order Mark to files saved as UTF-8. The Byte Order Mark is not recognized by all browsers and can alter the layout of the CONTENTdm Web templates. Notepad and other editors that add Byte Order Marks to UTF-8 files should not be used for editing the CONTENTdm Web templates.

4. Make changes and then save the file.

5. Check that the changes you make provide the expected results.

Generally, edit the:

• Global Style file to change color, font, and layout of the collection pages.

• Header file to make changes to the header on all Web template pages.

• Footer file to make changes to the footer on all Web template pages.

• Localization files to change navigational, button, and message text.

Variables

Most of the changes that we will make in this tutorial are done by changing variables within the PHP files. All variables that we will change in this tutorial have a specific format, shown below.

define("VARIABLE NAME", "VARIABLE VALUE"); // DEFAULT VALUE: COMMENT ABOUT THE VARIABLE

Make changes to the variable values by opening the PHP file in HTML editing software or a text editor.

When editing, do not change the variable name. Keep the quotation marks intact when editing the variable values. All text after the // is informational only.

An example of a PHP file is shown below. The editable variables are shown in blue and enclosed by double quotes. The green text shows comments that describe each variable.

Figure 1. Style file portion

Section II: Editing the Style File

The STY_global_style file contains over one hundred variables that can be changed to personalize your Web templates. Most of the variables in STY_global_style.php can be used to change colors, fonts, and other style parameters. In addition, the STY_global_style.php file provides variables for changing other options within the Web templates, including:



• Allowing a login link for each page

• Whether metadata is hyperlinked in the item and document viewers and the scope of the search when hyperlinks are activated

• Whether the site shows a bottom navigational menu

• How a date is displayed within a Date data type field

• At which number of collections do users see a select box instead of check boxes for each collection on the Advanced Search page

• Specifying which file types display with the Image Toolbar

• Enabling simultaneous multiple language support

• Specifying how the Advanced Search page behaves in a custom collection implementation

• Specifying which fields are used for facets

These variables, their description, and selection choices are described below.

Variable Description Selection Choices S_DATE_FORMAT A number between 0 and 6

that indicates the format of the date display for fields with the data type date.

Default = "0" (choices are between 0-6) 0: yyyy-mm-dd 1: dd-mm-yyyy 2: mm-dd-yyyy 3: MONTH dd yyyy 4: dd MONTH yyyy 5: mm/dd/yyyy 6: dd/mm/yyy

S_THUMB_SIZE Thumbnail size in thumbnail view. Specify maximum dimension in pixels.

Default= "120" (choices are between 0-120)

S_GRID_SIZE Size of the thumbnail in grid view. Specify maximum dimension in pixels.

Default= "80" (choices are between 0-120)

S_ALLOW_LOGIN Provides a login link to your Web site. Necessary if you have restricted access to your collection by user. Allows report functionality within CONTENTdm to list usage identification.

Default = "0" 1 = YES 0 = NO

S_ALLOW_HYPERLINKING Allows hyperlinking of the metadata in the item and document viewers.


S_HYPERLINK_CISOROOT One of two variables that define the scope of search for metadata hyperlinks. Specify whether hyperlinks search across all collections or only the current collection.

Default = "1" 1 = Search all collections 0 = Search current collection

S_HYPERLINK_CISOFIELD One of two variables that define the scope of search for metadata hyperlinks. Specify whether hyperlinks

Default = "0" 1 = Search all fields 0 = Search current field



Variable Description Selection Choices search across all fields or only the current field.

S_HYPERLINK_LIMIT The maximum number of characters that can be hyperlinked and displayed in metadata fields. If the metadata is greater than this number, the metadata is displayed but not hyperlinked.

Default = 20,000 characters. Maximum character limit is 128,000.

S_FTS_DISPLAY The options for displaying full text field metadata in the item and document viewer. These values do not change the page and text view. If you do not wish to show full text metadata at all, including in the page & text view, hide the full text field by editing field properties.

Default ="1" 3 = Full text field is shown in full but does not hyperlink. 2 = Full text field is displayed, up to the character limit defined in S_TRUCATE_FTS_LIMIT. Provides a link to display the full text field in another window. 1 = Full text field is displayed and hyperlinked. 0 = Full text field is not displayed.

S_TRUNCATE_FTS_LIMIT The maximum number of characters that can be hyperlinked and displayed in full text field. A link is provided that displays the entire field in another window. Used when S_FTS DISPLAY is 2.

Default = "500"

S_SHOW_BOT_MENU View bottom navigational menu on Web pages.


S_CHECK_BOX_LIMIT Number of check boxes allowed before Advanced Search view switches to a select box.

Default= "20"

S_COLLECTION_LIMIT Total number of individual collections that can be searched at one time. It is limited to 100 in order to avoid exceeding the maximum URL string length in some browsers but may need to be adjusted lower depending on the length of collection aliases on your server. This value cannot be less than the value in the S_CHECK_BOX_LIMIT variable.

Default = "100" Maximum number is 100.


http://www.contentdm.com/help5/collection-admin/fields.asp

http://www.contentdm.com/help5/collection-admin/fields.asp


Variable Description Selection Choices S_FACETS Controls which fields

display in the Refine Your Search list in search results. To change the defaults, add, delete, or edit the list of field nicknames. A maximum of five fields can be displayed in the Refine Your Search list. Only searchable fields will display, if specified. Hidden fields will never display. For searches across multiple collections, the Refine Your Search list displays Dublin Core names. For single-collection searches, the field names are displayed. For more information about determining nicknames, see the Customizing Display Views tutorial (PDF).

Default= "subjec:creato:date:format:audien" None = Refine Your Search list does not display in search results

TD_META_WIDTH Controls the width of the metadata field name column in the item viewer.

Default = "0" Enter specific width

S_ALLOWED_ZOOM_IMAGE_TYPES Controls which file types are displayed with the Image Toolbar in all image viewers.

Default = "jpg, gif, tif, tiff, jp2, png " Remove file types from the list to disable the Image Toolbar for that file type. File types must be separated by a comma. Supported file types are jpg, gif, tif, tiff, jp2 and png.

S_SHOW_ITEMVIEW_PDF Controls whether single-item PDF files are displayed inline in the item viewer.

Default= "0" 1 = YES (display PDF inline) 0 = NO (do not display PDF inline)

S_CUST_DIR_ALIAS_LIST The collections that are searched in a custom collection interface. This variable only takes affect when custom collection interfaces are implemented.

Default = "all" All = Search all collections. Collection list is displayed on Advanced Search page. None = Search custom collection only. Collection list is not displayed on Advanced Search


http://www.contentdm.org/USC/tutorials/custom-results.pdf

http://www.contentdm.org/USC/tutorials/custom-results.pdf


Variable Description Selection Choices page. /collection_alias = A comma separated list of collection aliases. Searches specified collections. Collection list is not displayed on Advanced Search page.

S_DMLANG Enables hyperlinks for localized versions to display in the site header. Localized versions of the LOC files in the /client directory and the index.php, about.php, and help.php files must be provided.

Default = empty Enter two character language designator followed by the language name in parenthesis. Multiple languages must be separated by a comma: "en(English),es(Español),fr(Français)" The two character language designator indicates the directory containing localized versions of the LOC files in the /cdm4/client directory. The language name is used as the text for the hyperlink in the header.

Two or more languages must be added to activate the language links in the header. Default language is the first language in the list.

Table 1. Style File Variables

To edit the Style file:

1. Navigate to the STY_global_style.php file located in the \docs\cdm4\client directory.

2. Make a copy of the STY_global_style.php file before making any changes.

3. Open STY_global_style.php in HTML editing software or a text editor such as Textpad.

4. Edit the variable selections that are enclosed in double quotes. Take care not to delete a double quote.

5. Save your changes. When you have entered new values in each of the variables, save the file.

6. To preview your changes, enter the URL of your CONTENTdm server in your Web browser address bar. If your changes are not visible, check that you have saved your file. You may need to refresh the Web page or delete your temporary Internet files to remove cached files. To refresh the Web page, press the F5 key. Or, to delete cached files when using Microsoft Internet Explorer, from the Tools menu, select Internet Options. Click Delete Files…. A dialog box confirms that you want to delete all files in Temporary Internet Files. Click Yes. When your cached files have been cleared, click OK. Refresh the Web page.



7. If you are satisfied with your changes, close the STY_global_style.php file.

Frequently Used Variables

Two frequently used variables are the ability to add a login link to the Web template header and the ability to add a bottom menu bar to the Web template footer. We will go through the process of editing each of these variables.

For the first example, edit the S_ALLOW_LOGIN variable when following the above instructions. In Step 5, edit one variable at a time, save it, and view the result before moving on to the next variable.

In the STY_global_style.php file, find the S_ALLOW_LOGIN variable. Notice that the variable and its value are enclosed in quotes. We also see from the explanatory text that the default value of this variable is “0” which does not display the login link. A value of “1” means the login link will be displayed. Change the value to “1,” keeping the quotes intact.

The image below shows the variable that has been changed within the STY_global_style.php.

Figure 2. Edited Login Variable

Figure 3 shows what happens to the home page after you change the S_ALLOW_LOGIN variable to 1. Notice the word login now appears in the upper right corner.

Figure 3. Login enabled

The next variable you are going to change is called S_SHOW_BOT_MENU. This allows a bottom menu to be visible within the Web templates page. Find this variable and change its value from the default of 0, which equals no, to 1, which equals yes.

Figure 4. S_SHOW_BOT_MENU Variable

Now, the footer displays with a navigational menu, as shown below:

Figure 5. View Bottom Menu

Color Changes to the Web Templates

In the following example we will customize the Web templates by changing a selection of variables within the STY_global_style.php file. When all our changes to variables within the



STY_global_style.php file are complete, the Web templates will look similar to images shown below.

Figure 6. Modified Web Templates

As you make changes to variables within the STY_global_style.php file, be sure to click through the Browse, Advanced Search, Preferences, and My Favorites pages to verify your changes. When editing the file, be careful to keep the quotes that surround each variable name and its value.

In the STY_global_style.php file, change the values for seven variables, in the order they appear within the file.

Variable Name New Value S_COPYRIGHT_COLOR #336699 S_GENMENU_BG #336699 S_GENMENU_COLOR #99CCCC S_HEADER_BG #CCFFFF S_HEADER_COLOR #737373 S_LINK_COLOR #003366 S_LINK_HOVER_COLOR #CC3366

Table 2. Initial Color Changes to STY_global_style.php

The images below show how the edited variables change the appearance of the Web templates when they are viewed through a browser. Note that not all pages of the Web templates are affected the same way.



Figure 7. CONTENTdm Index After Initial Changes

After clicking browse, we notice that the submenus need to be changed to match the new color scheme. The original submenu color is shown below.

Figure 8. Original Submenu Color

Now change the following variables that affect the submenus.

Variable Name New Value S_SUBMENU_BG #669999 S_SUBMENU_COLOR #FFFFCC

Table 3. Submenu Color Changes

After making the changes, the results page now appears similar to the image below.



Figure 9. Results Page with Changed Color

When navigating to the Advanced Search page, we notice that the color scheme is different than expected. The Advanced Search page contains FORM variables that aren’t shown on the Index or Browse pages.

Figure 10. Advanced Search Page Contains FORM Elements

Now change two of the FORM variables to continue the pastel color scheme.

Variable Name New Value S_FORM_FIELDS_BG #FFFFCC S_FORMS_BG #FFFFFF

Table 4. Forms Variables

The Advanced Search page now has a form that matches the rest of the color page, as shown below.



Figure 11. Advanced Search Page with Changed Colors

The next page to browse to is the Preferences page. Within the STY_global_style.php file, you can change the color of the choices provided to the end-user from which they can select color schemes for My Favorites, Compare, and Slideshow.

Figure 12. End User Palette Choices within Preferences

There are eight different options provided. The My Favorites alternate colors are not displayed in the same order as they are listed in the STY_global_style.php file. From left to right, the options are displayed as:

ALT 5, ALT 2, ALT 3, ALT4, ALT 1, ALT 6, ALT 7, ALT 8

ALT 5 uses the site’s current background color, font color and link color as an option. In this example, you will change the three variables associated with ALT 1. By default, the ALT 1 background color is black, the text color is maroon, and the link color is blue.

Variable Name New Value S_ALT_BG_1 #CCFFFF S_ALT_FONT_COLOR_1 #006699 S_ALT_LINK_COLOR_1 #009999

Table 5. My Favorites Preferences Changes

Once the changes are made to the STY_global_style.php file, view the preferences page to see the new color option.



Figure 13. End User Pallet Choices With Changes

Select the new color option and click Apply changes. Then navigate to the My Favorites page to see the new background color.

Figure 14. My Favorites with New Selection

Changing the alternate colors is optional and you can easily change the My Favorites background color back to yellow by returning to preferences and selecting the appropriate color.

Figure 15. My Favorites with Yellow Background



To finish customizing the color scheme, change the button color and font color of all the pages. Change the button variables in STY_global_style.php to the new values specified below.

Variable Name New Value S_BUTTON_BG #CCFFFF S_BUTTON_FONT_COLOR #336699

Table 6. Button Variable Changes

The buttons display colors similar to below.

Figure 16. Button Display Colors

The STY_global_style file can be used in conjunction with other files to make even more advanced changes to the Web templates.

For additional information, see CONTENTdm Web templates within the Help files.

Section III: Editing the Header File

The code in the Header file (global_header.php) and in the STY_global_style.php can be changed to make modifications to all headers within the Web templates. More advanced structural modifications, such as changing the logo, logo placement, or placement of the navigational menu are done in the global_header.php file, whereas text and color changes are done in the STY_global_style.php file. After changing the logo, you may need to adjust header height in the STY_global_style.php file.

The global header file (global_header.php) is located within Server\docs\cdm4\includes. The global header file is included within all other PHP files (except pop-up windows) and governs the header in all template pages.

Each Web template is constructed using a series of embedded tables, with the customizable global header file called into each page using the following syntax:

<? include($includeHeader); ?>

The unedited global header file displays as:

Figure 17. CONTENTdm Global Header


http://www.contentdm.com/help5/custom/templates.asp


The default header code is shown below:

Figure 18. Global Header File



Changing the Header File Example

In this example, you can change the header so that the navigational menu is located below the CONTENTdm logo by rearranging the table structure, as shown below.

Figure 19. Changed Header Script File



To edit the Global Header:

1. Navigate to the global_header.php file located in the \docs\cdm4\includes directory.

2. Make a copy of the global_header.php file before making any changes.

3. Open global_header.php in HTML editing software or a text editor such as Textpad.

4. Edit the code you wish to change and save your changes.

In this example: Delete the following lines beginning on line 21 (including the ending and beginning row tags):

<td colspan="3" valign="top">

<? include($includeMenu); ?>

</td>

</tr>

<tr>

5. Add the following new row at line 68 (making it the last row before the second to last ending table tag):

<tr>

<td colspace ="2" valign="top">

<? include($includeMenu); ?>

</td>

</tr> When you have finished changing the code, save the file.

To preview your changes, enter the URL of your CONTENTdm server in your Web browser address bar. If your changes are not visible, you may need to refresh the Web page or delete your temporary Internet files to remove cached files. To refresh the Web page, press the F5 key. Or, to delete cached files when using Microsoft Internet Explorer, from the Tools menu, select Internet Options. Click Delete Files…. A dialog box confirms that you want to delete all files in Temporary Internet Files. Click Yes. When your cached files have been cleared, click OK. Refresh the Web page.

If you are satisfied with your changes, close the file.

Note: If your header differs in size from the default design, you may need to modify the S_HEADER_HEIGHT variable in the global style file.

The default header height is 89 pixels in STY_global_style.php. You can increase this height or decrease this height. Subtract the larger number from the smaller and alter the header height. For example, if the default header is 89 pixels high and your new header is 110 pixels high, you would need to increase the header height variable by 21 pixels to ensure that Web templates containing frames render without additional scrollbars.



Section IV: Editing the Footer File

The Footer file can be used in conjunction with the Style file to make changes to all footers within all Web templates. While you can make some changes to the footer with the Style Script file, you are limited to such changes as adjusting colors, selecting text face, adding a duplicate menu bar, and adjusting spacing height. Use global_footer.php to make more advanced changes.

The global footer file (global_footer.php) is located within Server\docs\cdm4\includes. The global footer file is included within all other PHP files (except pop-up windows) and governs the footer in all template pages.

Each Web template is constructed using a series of embedded tables, with the customizable global footer file called into each page using the following syntax:

<? include($includeFooter); ?>

The unedited global footer file displays as:

Figure 20. CONTENTdm Global Footer

The default footer code is included below:

Figure 21. Global Footer File

To edit the Global Footer File:

1. Navigate to the global_footer.php file located in the \docs\cdm4\includesdirectory.

2. Make a copy of the global_footer.php file before making any changes.

3. Open global_footer.php in HTML editing software or a text editor such as Textpad.

4. Edit the code you wish to change. Save your changes.

Altering Footer Height

If your footer differs in size from the default design, you may need to modify the height in the style file.

Increase the value of the S_HEADER_HEIGHT variable to ensure that Web templates containing frames render without additional scrollbars. Decrease the value to maximize available browser space.



For example, if the default footer is 89 pixels high and your new footer is 110 pixels high, you would need to increase S_HEADER_HEIGHT by 21 pixels to ensure that Web templates containing frames render without additional scrollbars.

Note: The S_HEADER_HEIGHT variable tracks the differential in size of both the header and footer from the original sizes. Changes made to one or both should be combined when computing the necessary value for S_HEADER_HEIGHT.

The default value of the S_HEADER_HEIGHT variable is shown below.

define("S_HEADER_HEIGHT", "89"); // 89: allows for correct browser height specs // change accordingly to avoid browser scrollbars in parent window

Section V: Editing the Localization Files

The Localization files contain variables that control the text that appears on buttons, forms, and pages throughout the Web templates. To change text within the Templates or to use a language other than English in the Web templates (usually referred to as localization), you must edit seven files in the Server\docs\cdm4\client directory:

• LOC_document.php. Specifies the navigational and function wording within the compound object viewer.

• LOC_favorites.php. Specifies the navigational and function wording within My Favorites, Slideshow, and Compare views.

• LOC_global.php. Specifies the navigational and function wording for terms used in all pages. This includes changing the e-mail address and company name.

• LOC_preferences.php. Specifies the navigational and function wording within My Preferences.

• LOC_results.php. Specifies the navigational and function wording within Browse and Results pages.

• LOC_search.php. Specifies the navigational and function wording within Search pages.

• LOC_viewer.php. Specifies the navigational and function wording within the Item viewer.

The localization files do not control the text that appears on the home page (index.php), about page (about.php), and help page (help.php). These files must be edited separately.

See Editing CONTENTdm Web templates for more information.

To edit the localization files:

1. Navigate to the localization files, located in the \docs\cdm4\client directory.

2. Make a copy of all files before making any changes.

3. Edit the variable selections that are enclosed in double quotes. Take care not to delete a double quote. Tip: If you need to use double quotes for punctuation, use the special HTML character entity to represent quotes, "

4. Save your changes.


http://www.contentdm.com/help5/custom/templates2.asp


Changing Menu Options to Use Capitalization

In this example, we are going to edit the localization files to change the menu options from being all lower case to upper case.

Follow the instructions above to open the LOC_global.php file. This file changes options within the headers, footers and error messages.

Change the following variables, keeping the quotations on either side

Variable Current Text Change To L_ABOUT_US about About L_ADVANCED_SEARCH advanced search Advanced Search L_BROWSE browse Browse L_CLOSE close Close L_GO go Go L_HELP help Help L_HOME home Home L_LOGIN login Login L_MAX max Max L_MIN min Min L_MY_FAVORITES my favorites Favorites L_PREFERENCES preferences Preferences L_PRINT print Print L_SAVE save Save L_SEARCH search Search L_TO_TOP to top To Top

Figure 20 shows the changed home page.

Figure 22. Capitalized Menu

If you are satisfied with the look of these changes, continue editing the other localization files to make the capitalization consistent throughout the results page, my favorites page, and the viewers.


Documents

Editing the Web Template Files