customizing display views - oclc · customizing these display views in the results.php or...

Customizing Display Views 11-Mar-10

© 2010 OCLC of 17

Customizing Display Views

This tutorial describes the process of customizing how search results and browse pages are displayed in CONTENTdm. This documentation is not intended to take the place of having working knowledge of HTML, PHP, or Java Script.

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

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 PHP and alters 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.

Learn About:

Section I: Overview

Section II: Before You Begin

Section III: Changing View Type

Section IV: Changing Display Views and Values using CQR

Creating a Custom Query

Pasting Results into browse.php

Checking Your Changes

Changing the results.php file

Section V: Default Viewing Parameters

Parameter Names and Values

Nicknames

Section VI: Editing Default Viewing Parameters Manually

Determining Field Nickname

Editing browse.php

Checking Your Changes

Changing the results.php file

Section I: Overview

When you browse a CONTENTdm collection or view search results, you most likely see the items in your collection in a grid view. Unless you change this view, the grid view displays the Thumbnail, the Title, the Subject, and Description fields. You can change the view from grid to another view by changing the CISOMODE value in the browse.php or the results.php files.

The browse.php file contains settings that affect how end users browse your collections. The results.php file settings affect what end users see after performing a search. In addition to changing the CISOMODE value, you can also change the values for the parameters that define


© 2010 OCLC of 17

the different views. These parameters include what fields are visible, how much data within the field is visible, which fields link to the item, how many items display on a page, and how the items are sorted. You can use Custom Queries and Results (CQR) to generate code to copy and paste into browse.php and results.php.

Customizing these display views in the results.php or browse.php files does not guarantee that this view is what the end user sees. The settings that you edit in these files can be overwritten by using predefined queries created using CQR. Additionally, an end user can overwrite both the default browse and search results displays and those defined by CQR queries by setting Preferences while viewing a CONTENTdm collection. In Preferences, an end user can select view option, sort order, and number of items per page but cannot change what fields are visible, how much data is visible, or which fields link to the item.

More information about CQR is available in the Help files at www.contentdm.com/help4/custom/cqr2.html.

Information about setting preferences is available in the Help files at www.contentdm.com/help4/using/preferences.html.

This tutorial leads you through the process of changing your PHP files to change the default settings for the browse and results pages. The tutorial will cover using Custom Queries and Results to generate code to copy and paste into browse.php and results.php. This tutorial also covers editing your settings manually.

Section II: Before You Begin

Both the browse.php file and the results.php file are located on the server in the \docs\cdm4 directory. You must have access to these files on the server in order to perform the steps within this tutorial. You must also have access to Collection Administration so that you can identify nicknames.

This tutorial involves editing your PHP files. This documentation is not intended to take the place of having working knowledge of HTML, PHP, or Java Script.

The customizations added to these pages will change the default settings of the browse.php and results.php file. These default settings can be overwritten by CQR queries and by the settings users define under preferences.

This tutorial does not cover changing the preferences page to match your new default display. This is considered advanced customization and is not supported.

Before you begin, make backup copies of your browse.php and results.php files so that you can easily change the web pages back to their original state if necessary.

Section III: Changing View Type Changing the default view from grid to another type is done by replacing “grid” (in quotes) in the default viewer parameters with one of the following:

bib Default displays title, which is hyperlinked, subject, and description. Does not include a thumbnail image. Default sorts by title.

thumb Default displays a thumbnail image and the title. Both are hyperlinked. Default sorts by title.

title Default displays title only, which is hyperlinked. Does not include a thumbnail image. Default sorts by title.

http://www.contentdm.com/help4/custom/cqr2.html

../../../Local%20Settings/Temporary%20Internet%20Files/OLK234/CQR

http://www.contentdm.com/help4/custom/cqr2.html

http://www.contentdm.com/help4/using/preferences.html

http://www.contentdm.com/help4/using/preferences.html


© 2010 OCLC of 17

hiera Default sorts and displays on subject and title. Does not include a thumbnail image.

The name of the variable to change is CISOMODE. When editing the CISOMODE variable, keep the semicolons and the quotation marks intact. Otherwise, your changes will not appear as expected. To keep the results displays consistent for both browse and search results, make the same changes to your default viewing parameters in both the browse.php and results.php files.

When a field is hyperlinked, it is a link to view the item in either the item viewer or the compound object viewer (if it is a compound object).

It is easy to make this change directly in your PHP files. Once you have made backup copies, edit the browse.php and results.php files using HTML editing software. If you do not have HTML editing software, open the files in a text editor that supports UTF-8 encoding. In this example, we will edit the browse.php and results.php files, changing the default view type from grid to thumbnail.

To change view type:

1. Make backup copies of browse.php and results.php, located in the \docs\cdm4 directory on your server.

2. Open browse.php in an HTML or text editor.

3. In the default viewer parameters section of the file, locate the variable named CISOMODE. This parameter defines the default viewing mode. Read Section V for more information about the default viewing parameters.

Figure 1. Locating CISOMODE

4. Locate the word “grid” next to CISOMODE. Replace the word grid with the word thumb, retaining the surrounding quotes. Other options are title, bib, and hiera, as noted in the comments within the file.

5. Save your changes.

6. Check that the changes you make provide the expected results. To preview your changes, enter the URL of your CONTENTdm server in your Web browser address bar.


© 2010 OCLC of 17

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. 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 file.

8. Open results.php and perform steps 3-7.

You have now changed the default view to thumbnail. If you wish to change the parameters within the view that you have selected, you must edit the default viewing parameter values, either by using CQR to generate new code, or manually.

Section IV: Changing Display Views and Values Using CQR

Many users want to change the default display view and sort field after adding a new field to their collection. For instance, if an organization adds a new field to their newspaper collection called Issue Number, they might want to change the grid view, hierarchical view, and bibliographic view to make the new field visible. They may also want to change the sort order so results are sorted on the new issue number.

Another reason you might want to change display views and values is to make more fields visible in the grid and bibliographic views.

You can change the default display and sort parameters in two different ways:

Generating a CQR query and then pasting the resulting code into browse.php and results.php

Editing the default viewer parameters in browse.php and results.php directly. This will be covered in Section VI.

To avoid errors caused by misplaced punctuation and unknown field nicknames, we recommend using CQR.

If you are not familiar with CQR, read Creating Custom Queries and Results at www.contentdm.com/USC/tutorials/cqr.pdf.

In this tutorial, we will change the default viewing mode from grid to bibliographic. Then, we will change the parameters within the bibliographic view type.

With this method, we will create a query using CQR to generate the code string that defines the view. We will copy the query result and paste it into browse.php. Once we check our changes, we will save them. Then, we will paste the same portion into results.php.

Step 1: Creating a Custom Query

This step will walk you through creating a query. For this tutorial, we are going to change the view from grid to bibliographic, and we are going to add a field to the list of visible fields.

1. Navigate to the CQR by typing the following URL in your Web browser address bar:

http://your.server.address/cdm4/cqr/cqr1.php

http://www.contentdm.com/usc/tutorials/cqr.pdf

http://www.contentdm.com/USC/tutorials/cqr.pdf


© 2010 OCLC of 17

Figure 2. Select Query Type

2. Select Generate the default view parameters for the browse or results page.

3. Click Next. The Results View page displays. What we choose will produce the code needed for changing the default viewing parameters.


© 2010 OCLC of 17

Figure 3. Define Results View

4. Change the following on the Results View page:

In Select the default viewing mode:

Select Bibliographic.

In Configure the bibliographic view:

For Field 4, select Format from the drop-down list. For Field 4 Display Options, select Show entire field from the drop-down list. For Field 4 Separator, select New Line from the drop-down list. Do not check Link to Item.

In Choose sort order:

For Priority 2, select Subject from the drop-down list.

Note: The Relevancy sort option only applies to the Results View page.


© 2010 OCLC of 17

In Define compound object results display: Choose Only show full compound object within search results.

Note: The compound object option only applies to the results page.

5. Select Next. The Finish page is shown.

Figure 4. CQR Results

Step 2: Pasting Results into browse.php

In this step, copy the results in the text box on the Finish CQR page and then paste it into browse.php.

1. Copy the code from the text box of the CQR page. Many Web browser support Ctrl C as a shortcut.

2. Navigate to \server\docs\cdm4 and make backup copies of browse.php and results.php if you have not already done so.

3. Open browse.php.

4. Find the default viewer parameters within the file. There are comments above and below the parameters that indicate their location.


© 2010 OCLC of 17

Figure 5. browse.php File

5. Highlight and delete the default viewer parameters.

6. Paste the section that you copied from the Web page into browse.php.

7. Save browse.php.

Note: The CQR finish page adds a command to suppress compound objects in search results. This code does not change the functionality of the browse.php page. If desired, you can remove this code from the file.

Step 3: Checking Your Changes

Before you close your file, check your changes to make sure that this new view is what you want.

To preview your changes, enter the URL of your CONTENTdm server in your Web browser address bar and navigate to the Browse page.


© 2010 OCLC of 17

Figure 6. Check the Browse page within your Web browser

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.

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. 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.

You have now successfully changed the browse.php file.

Step 4: Changing the results.php File

Once you have successfully changed the browse.php file, you are now ready to change the results.php file. At this point, you still have the finish page of Custom Queries and Results open and you have made a back up copy of your results.php file.

1. Copy the code from the CQR text box. (If you know that you have the default parameters in the clipboard, you can skip this step.)

2. Navigate to \server\docs\cdm4 and make backup copies of results.php if you have not already done so.

3. Open results.php.

4. Find the default viewer parameters within the file. There are comments above and below the parameters that indicate their location.

5. Highlight and delete the default viewer parameters.

6. Paste the section that you copied from the Web page into results.php.

7. Save results.php.


© 2010 OCLC of 17

Check your work as before. After entering the URL of your CONTENTdm server in your Web browser address bar, perform a search.

If your changes were successful, you will see all results in a bibliographic view.

Section V: Default Viewing Parameters This section provides you with information about the default viewing parameters in case you wish to edit your files without using Custom Query and Results.

The default viewer parameters appear in both the browse.php and results.php files. They are in the format of:

define("parameter name", "variable value"); //comments

The results and the browse.php files have almost identical default viewer parameters. However the parameter CISOSUPPRESS, shown below, has no effect within the browse.php file since individual pages of compound objects are automatically suppressed in browse mode. Also, three of the parameters in results.php contain sorting by relevancy.

Figure 7. Default Viewer Parameters

Parameter Names and Values

The table below explains the default viewer parameter values. The first three parameters define results, viewer, and default viewing formats. The final five define the views. By editing the parameter options that define the views, you can change the number of items displayed per results page and the sort order. For the grid view and the bibliographic view, you can choose which fields to display, whether displayed fields are hyperlinked to the viewer, and how much content of a field is shown.

When editing these views, keep in mind that the end user can change the view type, number of items per page and sort order in Preferences. The end user does not have the ability to change what fields are visible, except in the hierarchical view. For the hierarchical view, the fields displayed and the sort order are the same. CONTENTdm supports the ability to view up to 100 items per results page.

Parameter Name

Explanation

CISORESTMP Defines which file is used to display search results. If you wish, you can create a custom results page for each collection. For information on how to customize multiple collections, read Customizing Multiple Collections at www.contentdm.com/help4/custom/Custom_Coll.pdf

http://www.contentdm.com/help4/custom/Custom_Coll.pdf




© 2010 OCLC of 17

Parameter Name

Explanation

The default parameters are: define (DEF_CISORESTMP”, “results.php”);

CISOVIEWTMP Defines which file is used to display items. If you wish, you can create a custom item viewer for each collection. For information on how to customize multiple collections read Customizing Multiple Collections at www.contentdm.com/help4/custom/Custom_Coll.pdf The default parameters are: define (DEF_CISOVIEWTMP”, “item_viewer.php”);

CISOMODE Defines the default viewing mode. Changing this value in browse.php changes the default viewing mode when browsing. Changing this value in results.php changes the default viewing mode for search results. Choose from the following values shown commented in the code: grid, title, thumb, bib; hiera. The default parameters are: define("DEF_CISOMODE", "grid"); //grid; title; thumb; bib; hiera

The following parameters define what is displayed for the viewing modes. If you have changed the default viewing mode in CISOMODE, confirm that it displays as you wish. Also, check the values of the other modes, especially the fields that are visible in the grid and bibliographic views. Changing these values does not affect what the end user sees on the preferences page.

Parameter Name

Explanation

DEF_CISOGRID The grid view shows the items separated by a rule, with information about each item (the fields) in columns. Column headings contain the field names. Up to five fields can be viewed or four fields and a thumbnail image. Parameter values are: “fieldnickname1,a,b;fieldnickname2,a,b;fieldnickname3,a,b;fieldnickname4,a,b; fieldnickname5,a,b; number of items per page;c,d,e,f,g” where: fieldnickname is the nickname of the field. a is how much of the metadata within the field is shown. (A = all of the metadata is shown, K = show search keywords in context. Or, indicate the number of characters to show: 20, 40, 60, 80, 100 or 200.) b determines if the field is hyperlinked to the item viewer (1 = the field will be hyperlinked to the viewer, 0 = the field will not be hyperlinked to the viewer.) number of items per page is a numeric value that defines the number of items displayed per page (10, 20, 30, 40, 50, 60, 70, 80, 90 or 100). and c,d,e,f,g (except when relevancy is used in the first position in results.php), this shows field nicknames in the desired sort order. If you do not want to view





© 2010 OCLC of 17

Parameter Name

Explanation

or sort on all five fields, use “none” instead of a field name. The default parameters are: define("DEF_CISOGRID", "thumbnail,A,1;title,A,1;subjec,A,0;descri,200,0;none,A,0;20;relevancy,none,none,none,none"); In the default grid view, the thumbnail will be shown on the left, followed by the Title, Subject, and Description fields. The Thumbnail and the Title fields are hyperlinked to the item viewer. The Description and Title field are not. The entire Title and Subject fields are shown. Up to 200 characters of the Description field will be displayed. There will be 20 items on each page. The items will be sorted by title only.

CISOBIB The biblographic view displays text from up to five fields without thumbnails. Each item is separated by a rule. Choose whether the fields describing the item are separated by new line, comma, period or space. Choose up to five fields to use to sort the items. Parameter values are: “fieldnickname1,a,b,c;fieldnickname2,a,b,c;fieldnickname3,a,b,c; fieldnickname4,a,b,c;fieldnickname5,a,b,c; number of items per page; d,e,f,g,h” where fieldnickname is the nickname of the field. a is how much of the metadata within the field is shown. (A = all of the metadata is shown, K = show search keywords in context. Or, indicate the number of characters to show: 20, 40, 60, 80, 100 or 200.) b determines if the field is hyperlinked to the item viewer (1 = the field will be hyperlinked to the viewer, 0 = the field will not be hyperlinked to the viewer.) c determines how the different fields are separated (N = new line, C = comma, P = period, S = space). number of items per page is a numeric value that defines the number of items displayed per page (10, 20, 30, 40, 50, 60, 70, 80, 90 or 100). and d,e,f,g,h are field names in the desired sort order. and c,d,e,f,g (except when relevancy is used in the first position in results.php), this shows field nicknames in the desired sort order. If you do not want to view or sort on all five fields use “none” instead of a field name The default parameters are: define("DEF_CISOBIB","title,A,1,N;subjec,A,0,N;descri,200,0,N;none,A,0,N;none,A,0,N;20;relevancy,none,none,none,none") In the default bibliographic view, the entire Title and Subject fields are shown, followed by the Description field. The title is hyperlinked to the item viewer. Up to 200 characters of the Description field will be displayed. The items will be sorted by title only.

CISOTHUMB In the thumbnail view, the Title field is displayed along with a Thumbnail image in columns and rows. Both the Thumbnail and Title field are automatically


© 2010 OCLC of 17

Parameter Name

Explanation

hyperlinked to the viewer. Parameter values are: “number of items per page (number of columns x number of rows); a,b,c,d,e” where number of items per page is a numeric value that defines the number of items displayed per page (10, 12, 15, 16, 20 (4x5), 20 (5x4), 24, 25, 28, 30, 32, 35, 36, 40 (4x5), 40 (5x4), 50, 60 (4x5), 60 (5x4), 70, 80 (4x5), 80 (5x4), 90, 100 (4x5) or 100 (5x4)). Numbers that are divisible by both 4 and 5 require you to select whether want your items displayed 4 items across or 5 items across. and c,d,e,f,g (except when relevancy is used in the first position in results.php), this shows field nicknames in the desired sort order. If you do not want to sort on all five fields, use “none” instead of a field name. The default parameters are: define (“DEF_CISOTHUMB”, “20 (4x5); relevancy, none,none,none,none”); In the default thumbnail view, up to 20 items are displayed on a page. The Thumbnail and Title fields are hyperlinked to the item viewer. The items will be sorted by title only.

CISOTITLE In the title view, only the titles of the images are displayed. Parameter values are: “number of items per page; a,b,c,d,e” where number of items per page is a numeric value that defines the number of items displayed per page (10, 20, 30, 40, 50, 60, 70, 80, 90 or 100). a,b,c,d,e are field names in the desired sort order. If you do not want to sort on all five fields, use “none” instead of a field name. The default parameters are: define("DEF_CISOTITLE", "20;title,none,none,none,none"); In the default title view, the items will be sorted by title only. Up to 20 items are displayed on a page.

CISOHIERA In the hierarchical view, the items are sorted and displayed by the fields that you select. The field titles are arranged in rows across the page. A separate entry for each field is provided on each row. Parameter values are: “number of items per page; a,b,c,d,e” where number of items per page is a numeric value that defines the number of items displayed per page (10, 20, 30, 40, 50, 60, 70, 80, 90 or 100). a,b,c,d,e are field names in the desired view and sort order. If you do not want to view and sort on all five fields, use “none” instead of a field names. The default parameters are: define("DEF_CISOHIERA", "20;subjec,title,none,none,none");


© 2010 OCLC of 17

Parameter Name

Explanation

In the default hierarchical view, the items are sorted by the Subject field and then by the Title field. The Subject and Title fields are the only fields that will be shown. Up to 20 items are displayed on a page.

CISOSUPPRESS This parameter suppresses pages in compound objects in search results. The two values you can choose are: 0 or 1. 0 = Do not suppress compound object pages within search results. This means that the individual pages that make up the compound object will display in search results as well as the compound object itself. 1 = Suppress compound object pages within search results. The individual pages that make up the compound object will not display in search results. Only the compound object will display.

Nicknames

As shown in the variable name and value table, you must know the field nickname if you edit values for some of the default viewer parameters. Enter field nicknames to specify viewing and sorting information. If you use CQR (the recommended method) to change the default viewing parameters, you won’t need to determine field nicknames.

If you do not use CQR and choose to alter the default viewing parameters code directly, taking care to keep quotations, semicolon, and commas intact, you must determine field nicknames.

Note that CONTENTdm uses field nicknames when searching or browsing within a single collection. Dublin Core Mapping is used when searching across multiple collections.

To determine field nicknames:

1. Open CONTENTdm Administration using your Project Client or by navigating to:

http://your.server.address/cgi-bin/admin/start.exe

2. Enter your user name and password if prompted.

3. Click the Collections tab. Then, click Fields to arrive at the field properties page.

4. On the Field Properties page, click Edit in the row of the field for which you wish to find the field. The Edit Field page opens.

5. Check the URL of the page. The field nickname, is after the parameter CISONICK.


© 2010 OCLC of 17

Figure 8. Nickname in URL

Note: If your status bar is active in your Web browser, you can also see the field nickname by hovering over the edit link in all field rows on the Field Properties page.

Figure 9. Nickname in Status bar

Section VI: Editing Default Viewing Parameters Manually

Now we will make the same changes to the browse.php and results.php files without using code generated by CQR, using an unedited copy of your browse and results files. This requires that you edit, with Web editing software or a text editor, the browse.php and results.php files.

Before we begin, confirm that you have a back up copy of both files. If you have edited the files, as in the previous section, ensure that you retain unedited copies of the files. This may require that you make additional copies of the unedited files.

In this example, we will:

Change default view to bibliographic.

Add the Format field to the view, separated by a new line.

Add an additional field to the sort options.

We will apply these changes to both results.php and browse.php.

The general steps are:

1. Determine field nickname for the field that we are adding to the bibliographic view.

2. Edit the browse.php file.

3. Check your changes.

4. Edit the results.php file.


© 2010 OCLC of 17

Step 1: Determining Field Nickname

In order to add another field to any default viewer parameters, we must know the field nickname. We are going to go to Collection Administration to determine field nickname.

1. Open CONTENTdm Administration. Do this by navigating to:

http://your.server.address/cgi-bin/admin/start.exe

2. Enter your user name and password if prompted.

3. Click the Collections tab. Then, click Fields to arrive at the Field Properties page.

4. In the Field Properties page, find the Format field.

5. Click Edit for that field. The Edit Field page opens.

6. Check the URL of the page. The field nickname, after the parameter CISONICK, is format.

Figure 10. Format nickname

Step 2: Editing browse.php

Now that we know the nickname, we are ready to edit the browse.php file. In this step, open the browse.php file and edit the values to reflect the changes that we wish to make:

1. Navigate to \server\docs\cdm4 and make copies of browse.php and results.php.

2. Open browse.php using Web editing software or a text editor.

3. Find CISOMODE in the browse.php file. Change “grid” to “bib”. This changes the default view to bibliographic.

The following shows the change to DEF_CISOMODE.

Figure 11. Changing CISOMODE

4. Now find CISOBIB. Make the following changes to the fourth field in the view parameters.

Find the fourth field, currently set at none, and change to format. Keep the A, as we want to show all fields.


© 2010 OCLC of 17

Keep the 0, as we do not want this term hyperlinked to the viewer. Keep the N, as we want this field separated with a new line.

5. Make the following changes to the sort view:

Find the second value, currently set at none, and change it to subjec. This is the field nickname.

6. Save browse.php.

Step 3: Checking Your Changes

Before you close your file, check your changes to make sure that this new view is what you want to display.

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, as shown in the previous section.

To refresh the Web page, press the F5 key.

Step 4: Changing the results.php File

Once you have successfully changed the browse.php file, you are now ready to change the results.php file. At this point, you’ve made a copy of your results.php file.

1. Open results.php using Web editing software or a text editor.

2. Find CISOMODE in the results.php file. Change “grid” to “bib”. This changes the default view to bibliographic. Now we are ready to make the change to the CISOBIB values.

3. Find CISOBIB. Make the following changes to the fourth field in the view parameters.

Find the fourth field, currently set at none, and change to format. Keep the A, as we want to show all fields. Keep the 0, as we do not want this term hyperlinked to the viewer. Keep the N, as we want this field separated with a new line.

4. Make the following changes to the sort view:

Find the first value, currently set at relevancy, and change it to title. This is the field nickname.

5. Save results.php.

Check your changes in this file, exactly as you did in Step 3.

You have now successfully changed both the results and browse pages to bibliographic view. Follow these general steps to make other changes to these files. If you want to revert back to the default values, rename your existing edited PHP files to something other than browse.php or results.php (such as editedbrowse.php or editedbrowse.php). Then, rename the copies that you made of browse.php and results.php files back to browse.php and results.php.

customizing display views - oclc · customizing these display views in the results.php or...

Documents