Portal Administration Guide : Xinet Portal Themes : Theme Configuration

Theme Configuration
This chapter explains some ways to configure your Portal themes. To begin, we review the contents of the folders provided with the base installation.
In this chapter:
Exhibit Folder Overview
The Exhibit folder is provided with your base installation. This same folder is duplicated when you create a new site via the PORTALADMIN GUI. This folder includes several files that are critical to Xinet Portal. It is very important to maintain the integrity of the file and folder structure within each Xinet Portal site folder.
The Exhibit folder looks like this:
FIGURE 1. Contents of the Exhibit folder
At the top level you have three php files: index.php, startup.php and config.inc.php, as well as a templates folder. These files and this folder must remain nested at the top level of your site folder. You cannot rename these files nor this folder.
Within the templates folder you have many different types of files: HTML files, local.inc.php, portal.css, and portal.js as well as a few folders for plug-ins and images. Once again, these files and folders must remain nested within the templates folder of site’s folder. You cannot rename these files or folders.
Here’s what some of the files do:
The startup.php file, located at the top level of your site folder, is responsible for starting Xinet Portal. This file controls the post-login process. Do not edit it. (You can change the look and feel of the login process using the PORTALADMIN Theme Editor or by editing the login.html file.)
The index.php file, also located at the top level of your site folder, can be customized by advanced administrators who want the user experience to begin with a splash screen, for example, instead of the Xinet Portal authentication process. In its default state, as shipped, this file simply calls the startup.php file.
The config.inc.php file contains php variables for your Xinet Portal site. These attributes are most-easily edited using the Site Manager, Edit Site, Configuration page in the PORTALADMIN GUI. Descriptions of them appear in Server Defaults Pages.
The local.inc.php file, inside the templates folder, contains php. If you have php programmers at your disposal, they can add additional php scripting in this file for enhanced site functionality. This file is read after the config.inc.php file and after modules (if any).
The portal.css file is a cascading style sheet for each Xinet Portal theme. Use the Theme Editor, described beginning on The Theme Editor (for Exhibit Sites) to edit an Exhibit theme only. It controls visual attributes of sites using the Exhibit theme. For sites using a Marquee theme, see Create a new Marquee Theme Template.
The portal.js file contains the JavaScript specific to Xinet Portal. Once again, if you have programmers, they can add additional JavaScript to this file for enhanced site functionality.
The basketplugins folder houses the plug-ins responsible for the Collection functionality of Xinet Portal, including Asset Fulfillment Request and One-click Download. Appendix: Asset Timer (Exhibit Only) provides more information about these plug-ins.
The images folder contains all of the image files specific to your site. You can replace these with your own custom images. The easiest way is through the Theme Editor. If you don’t use the PORTALADMIN Theme Editor to replace these files (i.e., you replace them by hand) you should not change the name of these files you replace unless you also make the appropriate change within the config.inc.php file. The Theme Editor will take care of this for you automatically.
Templates, tag domains, tags, tag families and arrays
This section presents the relationship between Xinet Portal templates, domains, tags and arrays, along with some examples that show what each controls.
Vocabulary and relationships
Template
A template is a file, always ending the suffix .tmpl.html, which always resides within the site’s templates directory or subdirectory. The file contains HTML code and tags.
Tag domain
A tag domain is a designated block of HTML within a template that has variable portions called tags.You can recognize a tag domain in Xinet Portal templates because a domain always begins with <styles:tmpl name= ...> and ends with </styles:tmpl>. The base tag domain for every Xinet Portal page is PortalPage. Other domains may be nested within it.
Tag
A tag presents variable data, stored in an array, depending on when and where it is called. Examples: {UN} and {KW_HTML}.
Tag families
A tag family is a group of tags that must be used together in a template in order to present button functionality. Here’s an example of the four tags used to present the Custom Order button in Short View inside the file_table_short.tmpl.html template:
{FILE_ORDER_ICON} {FILE_ORDER_DISPLAY}{FILE_ORDER_LINK}{LANG_CUST}
Each of the tags in the family has its own function, but all four tags must be used together to offer the Custom Order button. Other buttons that appear in Xinet Portal templates have similar tag families associated with them.
The four parts of this family include:
a. A tag that presents the Custom Image Order icon, as defined in portal.css file (.icon_order)
b. A tag that applies logic to the HTML template, allowing Xinet Portal to only present the Custom Image Order button under certain conditions.
c. A link to a CGI, for Custom Order, it's the IMAGEORDER.php call.
d. A tag that refers to the user’s language style, which will be filled in automatically from an entry in the language.js file.
If you look in the file_table_short.tmpl.html file you'll find examples of buttons which use tag families in this way. It is easy to customize new buttons by copying an existing one and substituting specific HTML for a tag. You don’t need to write fancy scripts if you follow this technique. Please refer to Xinet Technote 330 for further information about customizing buttons.
Array
Each tag domain has an array of tags associated with it. Turn to Looking at Xinet Portal arrays for some examples. You may also want to consult a PHP manual for explanations on the working of associate arrays.
The following subsections explore the relationship between these components.
Inside a template
Here’s the passwordcntl.tmpl.html file from a site using the Exhibit theme.
.
All Xinet Portal templates begin with <styles:tmpl name="PortalPage">, the beginning of the PortalPage tag domain, and close with </styles:tmpl>. The passwordcntl template, above, uses the {LANG_CHANGEPASSFOR}, {UN}, and {RESULT_MESSAGE} tags, which are stored by the $tmpl->variables['PORTALPAGE'] array.
Figure 2 shows the passwdctl.tmpl.html page as rendered, first, by Dreamweaver, and then, by Xinet Portal (by pointing a browser at /localhost/PORTAL/PASSWORDDCNTL.php).
FIGURE 2. The passwdctl.tmpl.html template viewed through a browser.
Templates interact with arrays
Xinet Portal employs three types of arrays:
Built-in php arrays
Built-in php arrays, such as $_SESSION, $_SERVER, are not used in templates. You can gain access to them using the local.inc.php file.
PORTALPAGE array of $tmpl ($tmp ->variables['PORTALPAGE']) which contains basic PORTALPAGE tags and is stored as an array within the $tmpl object.
Iterative arrays
Iterative arrays are composed of sub-arrays, one for each item. For example, $volume_info, $keyword_info, $files_info. As a tag domain iterates through each item, one cell in a template becomes one cell for each item in the array in the page the browser displays. The tag domain includes _table, _row, _cell for each _info array. For example, the $file_info array has tag domains file_table, file_row, file_cell.
Let’s examine an Exhibit theme site file_table_short.tmpl.html for its iterative array tags and tag domains. The browseshort.tmpl.html template calls upon the file_table_short.tmpl.html template whenever a user browses in Short View.
<div id="filewrap">
/* */
/* Designate beginning of the file_table tag domain */
/* */
<styles:tmpl name="file_table" visibility="hidden">
<div id="filescroll">
<div id="filelist">
/* */
/* Designate beginning of the file_row tag domain */
/* */
<styles:tmpl name="file_row">
/* */
/* Designate beginning of the file_cell tag domain */
/* */
<styles:tmpl name="file_cell" type="SIMPLECONDITION"
requiredvars="FILE_NAME">
/**/
/* Begin display of preview’s outer box */
/* */
<div class="preview_outerbox">
<div class="{PREVIEW_PAD_COLOR} allcorners">
/* */
/* Include tag that shows archive status */
/* */
<span class="archivestatus">{AS}</span>
<div class="previewPadColor allcorners">
/* */
/* Include tags to display file icon*/
/* and page count (for multipage documents) */
/* */
<div class="preview_info">
{I16} {FILE_PAGE_COUNT}
</div>
<div class="clearblock">&nbsp;</div>
/* */
/* Begin display of inner box surrounding */
/* preview */
/* */
<div class="preview_innerbox">
/* */
/* Include tags that display arrows for */
/* paging backwards in multipage documents */
/* */
<a class="_img_pad button_container
{FILE_PAGE_LEFT_ICON}
{FILE_PAGE_LEFT_DISPLAY}"
href="{FILE_PAGE_LEFT_LINK}"
onclick="{FILE_PAGE_LEFT_ACTION}"
/* */
/* Language Tag for ‘View File’ rollover */
/* */
title="{LANG_VIEWPREV}">
<label class="button_label">
{LANG_VIEWPREV}</label>
</a>
/* */
/* Include tag to display the Small Preview */
/* */
{SP}
/* */
/* Tags for arrow to page forward in */
/* multipage documents */
/* */
<a class="_img_pad button_container
{FILE_PAGE_RIGHT_ICON}
{FILE_PAGE_RIGHT_DISPLAY}"
href="{FILE_PAGE_RIGHT_LINK}"
onclick="{FILE_PAGE_RIGHT_ACTION}"
title="{LANG_VIEWNEXT}">
<label class="button_label">
{LANG_VIEWNEXT}</label>
</a>
/* */
/* Tags for Asset Timer usage */
/* */
<a class="_img_pad button_container
{FILE_AT_DISPLAY} {FILE_LOCKED_ICON}"
href="{FILE_AT_LINK}"
onclick="doFmgrTools('atrequest',
'{FILE_AT_LINK}',event);return false;"
title="{LANG_ATUSAGEREQUEST}">
<label class="button_label">
{LANG_ATUSAGELOCKED}</label>
</a>
</div>
</div>
/* */
/* Begin displaying tool tags (and their language */
/* rollovers) */
/* */
<ul class="preview_tools">
/* Include tag for file name */
<li><span class="filename"
title="{FILE_LONG_NAME}">
{FILE_NAME}</span>
</li>
<li class="fileactions">
/* Include tags for downloading hi res */
<a class="_img_pad button_container
{FILE_HIGH_ICON} {FILE_HIGH_DISPLAY}"
href="{FILE_HIGH_LINK}"
title="{LANG_HIGH}"><label
class="button_label">{LANG_HIGH}</label>
</a>
/* Include tags for downloading FPO */
<a class="_img_pad button_container
{FILE_FPO_ICON} {FILE_FPO_DISPLAY}"
href="{FILE_FPO_LINK}"
title="{LANG_FPO}">
<label class="button_label">
{LANG_FPO}</label>
</a>
/* Include tags for File Info */
<a class="_img_pad button_container
{FILE_II_ICON} {FILE_II_DISPLAY}"
href="{FILE_II_LINK}"
title="{LANG_DVIEW}">
<label class="button_label">
{LANG_DVIEW}</label>
</a>
/* Include tags for downloading File Manager */
<a class="_img_pad button_container
{FILE_FILEMGR_ICON} {FILE_FILEMGR_DISPLAY}"
href="{FILE_FILEMGR_LINK}"
title="{LANG_MANF}">
<label class="button_label">
{LANG_MANF}</label>
</a>
/* Include tags for Custom Order */
<a class="_img_pad button_container
{FILE_ORDER_ICON} {FILE_ORDER_DISPLAY}"
href="{FILE_ORDER_LINK}"
title="{LANG_CUST}">
<label class="button_label">
{LANG_CUST}</label>
</a>
/* Include tags for Collection */
<a class="_img_pad button_container
{FILE_BASKET_ICON} {FILE_BASKET_DISPLAY}"
href="{FILE_BASKET_LINK}"
onclick="updateBasket
('{FILE_BASKET_PATH}',event);return false;"
title="{LANG_BASKETSTATUS}">
<label class="button_label">
{LANG_BASKETSTATUS}</label>
</a>
/* Include tags for mview display */
<a class="_img_pad button_container
{FILE_MVIEW_ICON} {FILE_MVIEW_DISPLAY}"
href="{FILE_MVIEW_LINK}" id="APL_{FILE_ID}"
title="{LANG_AVIEW}">
<label class="button_label">{LANG_AVIEW}
</label>
</a>
/* Include tags for streaming file*/
<a class="_img_pad button_container
{FILE_STREAM_ICON} {FILE_STREAM_DISPLAY}"
href="{FILE_STREAM_LINK}"
title="{LANG_STREAM}">
<label class="button_label">
{LANG_STREAM}</label>
</a>
/* Include tags for showing file versions */
<a class="_img_pad button_container
{FILE_VERSIONS_ICON}
{FILE_VERSIONS_DISPLAY}"
href="{FILE_VERSIONS_LINK}"
title="{LANG_SHOWVERSIONS}">
<label class="button_label">
{LANG_SHOWVERSIONS}</label>
</a>
/* Include tags for browsing directory */
<a class="_img_pad button_container
{FILE_BROWSE_ICON} {FILE_BROWSE_DISPLAY}"
href="{FILE_BROWSE_LINK}"
title="{LANG_IBROWSE}">
<label class="button_label">
{LANG_IBROWSE}</label>
</a>
/* Include tags for revealing annotations */
<a class="_img_pad button_container
{FILE_OPENFILEANNOTATIONS_ICON}
{FILE_OPENFILEANNOTATIONS_DISPLAY}"
href="{FILE_OPENFILEANNOTATIONS_LINK}"
onclick="{FILE_OPENFILEANNOTATIONS_ONCLICK}"
title="{LANG_OPENFILEANNOTATIONS}">
<label class="button_label">
{LANG_OPENFILEANNOTATIONS}</label>
</a>
/* Include tags for opening the hires image */
/* when using Exhibit*/
<a class="_img_pad button_container
{FILE_OPENHIGH_ICON}
{FILE_OPENHIGH_DISPLAY}"
href="{FILE_OPENHIGH_LINK}"
onclick="{FILE_OPENHIGH_ONCLICK}"
title="{LANG_OPENHIGH}">
<label class="button_label">
{LANG_OPENHIGH}</label>
</a>
/* Include tags for revealing location of */
/* hires image when using Exhibit*/
<a class="_img_pad button_container
{FILE_REVEALHIGH_ICON}
{FILE_REVEALHIGH_DISPLAY}"
href="{FILE_REVEALHIGH_LINK}"
onclick="{FILE_REVEALHIGH_ONCLICK}"
title="{LANG_REVEALHIGH}">
<label class="button_label">
{LANG_REVEALHIGH}</label>
</a>
</li>
<li class="fileactions filemgrtools">
/* Include tags for file manager tools */
<a class="_img_pad button_container
{FILE_MOVE_ICON} {FILE_MOVE_DISPLAY}"
href="{FILE_MOVE_LINK}"
onclick="doFmgrNavigator('{LANG_MOVE}
{FILE_LONG_NAME}','{FILE_MOVE_LINK}',event);
return false;" title="{LANG_MOVE}
{FILE_LONG_NAME}">
<label class="button_label">
{LANG_MOVE}</label>
</a>
<a class="_img_pad button_container
{FILE_COPY_ICON} {FILE_COPY_DISPLAY}"
href="{FILE_COPY_LINK}"
onclick="doFmgrNavigator('{LANG_COPY}
{FILE_LONG_NAME}','{FILE_COPY_LINK}',event);
return false;" title="{LANG_COPY}
{FILE_LONG_NAME}">
<label class="button_label">
{LANG_COPY}</label>
</a>
<a class="_img_pad button_container
{FILE_RENAME_ICON} {FILE_RENAME_DISPLAY}"
href="{FILE_RENAME_LINK}"
onclick="doFmgrDialogue('{LANG_RENAME}
{FILE_LONG_NAME}',
'{FILE_RENAME_LINK}',event);
return false;" title="{LANG_RENAME}
{FILE_LONG_NAME}">
<label class="button_label">
{LANG_RENAME}</label>
</a>
<a class="_img_pad button_container
{FILE_TRASH_ICON} {FILE_TRASH_DISPLAY}"
href="{FILE_TRASH_LINK}"
onclick="doFmgrDialogue('{LANG_REMOVE}
{FILE_LONG_NAME}','{FILE_TRASH_LINK}',
event);return false;" title="{LANG_REMOVE}
{FILE_LONG_NAME}">
<label class="button_label">
{LANG_REMOVE}</label>
</a>
<a class="_img_pad button_container
icon_filemgr_cancel"
href="{FILE_CANCEL_LINK}"
title="{LANG_CANCEL}">
<label class="button_label">
{LANG_CANCEL}</label>
</a>
</li>
</ul>
</div>
</styles:tmpl>
/* */
/* End of the file_cell tag domain */
/* */
</styles:tmpl>
/* */
/* End of the file_row tag domain */
/* */
<div class="clearblock">&nbsp;</div>
<div id="filecontrols">
/* */
/* Include tag that shows list of additional pages */
/* to display */
/* */
<span class="pagelist">{LIST_PAGES}</span>
</div>
/* */
/* End display of preview’s outer box */
/* */
</div>
</div>
</styles:tmpl>
/* */
/* End of the file_table tag domain */
/* */
</div>
The figure below shows how a browser renders file_table_short.tmpl.html when called through browseshort.tmpl.html.
FIGURE 3. Exhibit site Short View
For more information about arrays, including a complete list, turn to Looking at Xinet Portal arrays.
Customizing with arrays
Let’s look at an example of how you might make use of Xinet Portal arrays when customizing sites. We’re going to change a copy of the Exhibit site so that file-modification date shows in Short View:
1.
First, check that the [MD] entry actually appears in the Short View $files_info array. Figure 4 shows that it does:
FIGURE 4. The [MD] entry within the file_info array
The presence of [MD] tells us that it is possible to display {MD} tag information in Short View. (Looking at Xinet Portal arrays provides information about displaying an array, as we’ve done above.)
2.
Open an Exhibit-style site’s file_table_short.tmpl.html in an editor and locate the template’s file_cell tags shown in the snippet below.
<styles:tmpl name="file_cell" type="SIMPLECONDITION"
requiredvars="FILE_NAME">
<div class="preview_outerbox">
<span class="archivestatus">{AS}</span>
<div class="previewPadColor allcorners">
<div class="preview_info">
{I16} {FILE_PAGE_COUNT}
</div>
<div class="clearblock">&nbsp;</div>
<div class="preview_innerbox">
<a class="_img_pad button_container {FILE_PAGE_LEFT_ICON}
{FILE_PAGE_LEFT_DISPLAY}" href="{FILE_PAGE_LEFT_LINK}"
onclick="{FILE_PAGE_LEFT_ACTION}"
title="{LANG_VIEWPREV}">
<label class="button_label">{LANG_VIEWPREV}</label>
</a>
{SP}
<a class="_img_pad button_container
{FILE_PAGE_RIGHT_ICON} {FILE_PAGE_RIGHT_DISPLAY}"
href="{FILE_PAGE_RIGHT_LINK}"
onclick="{FILE_PAGE_RIGHT_ACTION}"
title="{LANG_VIEWNEXT}">
<label class="button_label">{LANG_VIEWNEXT}</label>
</a>
<a class="_img_pad button_container {FILE_AT_DISPLAY}
{FILE_LOCKED_ICON}" href="{FILE_AT_LINK}"
onclick="doFmgrTools('atrequest','{FILE_AT_LINK}',event);
return false;" title="{LANG_ATUSAGEREQUEST}">
<label class="button_label">{LANG_ATUSAGELOCKED}</label>
</a>
</div>
</div>
<ul class="preview_tools">
<li><span class="filename" title="{FILE_LONG_NAME}"
>{FILE_NAME}</span></li>
<tr>
<li class="fileactions">
3.
Insert <li><span class="moddate" title="{FILE_MOD_DATE}">Mod: {MD}</span></li> into the file_cell just after the {FILE_NAME} tag, highlighted with bold type above, and save the file.
4.
Load a Short View page in your browser to view the results. You should see modification times displayed.
Further reference
Xinet Portal Templates
Xinet Portal comes with a base set of templates that correspond to basic views. Located in your site’s templates folder, the base set of templates includes the following files.
Before you begin to customize your site you should be aware that these templates have been built using forms, tables and nested tables. You should also be familiar with the various tags utilized in Xinet Portal as well.
 
Settings within the site’s portal.css file will override those in the base_portal.css when in conflict.
File manager subwindow— copy asset
Primary view for File Manager
File Manager subwindow — move asset
Stores page-specific CSS for mview which isn’t useful to other Portal operations.
The main mview template file
Portal mview presents a preview on the right side of the screen and with a menu of functions on the left side. When a user clicks one of the menu items on the left side, the menu slides away to the left and exposes a panel with the requested functionality. Each of the mview_ files contains the HTML code necessary to build those panels, with the name of the files indicating the panel to which it pertains.
Cascading Style Sheet for global customizing. The PORTALADMIN Theme Editor provides a GUI for making changes to the elements contained within the portal.css file.
Display large preview of image in a new window. (Also includes small previews of SWF and FLV flash streams.) Can be customized for WebNative Portal.
Display of Quick Filters in sub-Searches.
Controls the Quick Search options (as opposed to the More Options).
File Manager subwindow — rename asset
Controls Search, More Options display.
Search view
File Manager subwindow — delete asset
Controls Top Level