Customizing the User interface

<p>Please read the [[User Interface Overview]] if you have

not yet. </p>

==Figuring Out How to Make a Change==

===Overview===

<p>Given the complexity of DLXS and the variety of options for making

interface customizations, it can be difficult to determine how to make a

change, let alone the the <em>best</em> way to make a change.</p>

<p>First of all, there are some [[Useful Tools|web development tools]] available that can greatly simplify

your effort. For now, get these three and keep the others in mind.</p>

<ol>

<li>Firefox web browser</li>

<li>Firebug extension for Firefox</li>

<li>Web Developer extension for Firefox</li>

</ol>

<p>Next, get a little more familiar with the potential places customizations

can be made. Listed below are the options, from simplest to most advanced.

It probably goes without saying that you want to choose a simple option

whenever possible. </p>

<table border="1">

<tr>

<th>&nbsp;</th>

<th >What can you do? </th>

<th>What do you need to know? </th>

</tr>

<tr>

<td>[[Working with the Collection Manager|Collection Manager]] </td>

<td>Change the most common interface elements such as collection title and field labels. Include or exclude certain functionality. Varies significantly by Class. </td>

<td>You need to know how to use your browser. There is contextual help in

Collection Manager for each field. </td>

</tr>

<tr>

<td>CSS</td>

<td>Change colors and font styles. Hide elements. Control positioning of

some elements in Image Class.</td>

<td>Requires knowledge of CSS and a basic understanding of Fallback.</td>

</tr>

<tr>

<td >Language Map </td>

<td >Change user interface text.</td>

<td >Requires basic knowledge of XSL, XML and Fallback. </td>

</tr>

<tr>

<td >XSL</td>

<td >Alter the structure/layout of the HTML including the application of CSS

styles.</td>

<td >Requires knowledge of XSL, HTML, and CSS and a very good understanding

of Fallback. </td>

</tr>

<tr>

<td >Javascript</td>

<td >Control dynamic interactions that occur in the browser. </td>

<td >Requires knowledge of Javascript and HTML and a basic understanding of

Fallback.</td>

</tr>

<tr>

<td >XML Template </td>

<td >Include/exclude Processing Instructions to control the availability of

data generated by the CGI. </td>

<td >Requires very good knowledge of all aspects of the user interface,

Fallback, and the role of the CGI in DLXS. </td>

</tr>

<tr>

<td >Perl</td>

<td >Control the data generated by the CGI. Alter Processing Instructions,

or create new ones. </td>

<td >Requires very good knowledge of object oriented Perl, the architecture of DLXS code, and all other aspects of the user interface. We recommend consulting with DLXS support before making Perl code changes. </td>

</tr>

</table>

<p>&nbsp;</p>

<p>Customization may require changes in more than one of the above areas. For

example, you may need to change the XSL to add a class to an element so that

you can change it's appearance in the browser using CSS. </p>

==Pointers for deciding how to approach a user interface customization task.===

====How to tell if the change can be made in [[Working with the Collection Manager|Collection Manager]]====

* Study the Collection Manager fields for the Class and Group, specifically looking for an option that would cause the desired change. Click the Collection Manager field labels for contextual help. Many fields apply to all classes, but each class has unique fields as well.

====How to tell if the change can be made with Cascading Style Sheets (CSS)====

* First of all, you need to have a basic understanding of what [[User Interface Overview#Cascading Stylesheets (CSS)|CSS]] is good for and how it works.

* Use the [[Useful Tools|Firebug]] extension to Firefox to <em>inspect</em> the structure of the page including element class and id attributes. Firebug also shows the styles that are currently affecting the element. In fact, you caneven experiment with style definitions in Firebug. This should give you

a very good idea of whether the change can be made with CSS, or not.

====How to tell if the change can be made with XSL====

* Add debug=xml to the URL to view the XML for the page. Take a close look at the XML to see if the the information needed is present in the XML and structured in a way amenable to use with XSL. If the right information is in the XML, then XSL modifications will probably bring the desired change.

====How to tell if a change can be made in an XML Template and/or Perl====

<p>At this point, things get quite a bit more complicated. Often, changing

the XML also means changing the Perl CGI and changing the XSL as well. In

the best case, it is only a matter of shifting existing code around a little.

For instance, the PI you need may exist already and you just need to add

it to the XML template for the page you are working on. </p>

<p>It would be appropriate at this point to contact DLXS Support with a question

such as, &quot;I'm thinking about doing X, and I'm wondering if it is reasonable

as well as what type of expertise would be needed to do the job.&quot;</p>

<p>However, if you are an experienced programmer, we encourage you to [[Installation Troubleshooting#Tools, checks and techniques|use

the Perl debugger to step through the code]] to see what you can figure

out on your own. If you think you see a solution, you might choose to contact

DLXS Support to say, &quot;I'm thinking about doing X, and this is how I propose

to do it. What do you think?&quot;. It is not that you need our blessing, but

perhaps we can make a suggestion that would save you a lot of time, or difficulty. </p>

<p>Basically, at this level, you need to be a programmer comfortable with using

the Perl debugger to step through a large body of object oriented code.</p>

<p>In general, it is not a bad idea to contact DLXS Support for

guidance. Tell us what you are trying to do and a we'll be able to suggest

the most reasonable approach. If you are not a programmer, you may need to

find one. </p>

==Finding the Correct Files: More about Fallback==

===XML Template===

<p>It can be difficult to locate the files that are directly involved in constructing

an HTML page. Add <strong>debug=tpl</strong> to any DLXS URL for a report

on the Fallback file selection process. The first file attempted will generally

be the XML template file. In the example below, taken from the debug output, &quot;HIT&quot; tells

us that the search.xml template was found in the class (t/text for Text Class)

level web directory. </p>

<b><font color="red">HIT</font>: standard template path: /n1/web/t/text/search.xml, xcollmode=singlecoll, on disk</b>

===XML Template Chunks===

<p>There is a special Processing Instruction called &quot;CHUNK&quot;. The CHUNK PI is

for inserting a &quot;chunk&quot; of XML into the XML Template. Chunks are helpful where

the same XML needs to occur in more than one XML Template. The best example

is dlxsclassglobals.xml. This is an XML chunk that is used in just about every

XML Template. When the chunk file is modified, all of the templates that use

it automatically take advantage of the change, making maintenance easy. Keep

in mind that chunks can contain PIs, including CHUNK PIs. </p>

<p>Fallback applies to CHUNKS too. A collection level chunk, if it exists and

the situation is right, will be used instead of class or group level chunk.</p>

&lt;DlxsGlobals&gt;&lt;?CHUNK filename=&quot;dlxsclassglobals.xml&quot;?&gt;&lt;/DlxsGlobals&gt;

===XSL Stylesheet===

<p>You will likely need to know which XSL files are being used. DLXS has a special

way of linking XSL Stylesheets to XML files that allows for a lot of flexibility.

The ability to make very specific customizations at the collection and group

levels is extremely useful, but also introduces the potential for lots of XML

and XSL to be duplicated needlessly. For example, you might be tempted to begin

customizing a collection by first copying all of the class level web files

to the collection's web directory (a very bad idea by the way). The best approach

is to copy as little code as possible and rely on Fallback to draw together

the proper set of files for a given situation.</p>

<p>Support for this principle required development of a special method for specifying,

locating, and importing one or more XSL Stylesheets for XML transformation

to HTML. The <strong>Virtual XSL Stylesheet</strong> serves this purpose.</p>

<p>Each primary XML Template includes an <strong>XSL Fallback File

List</strong> where XSL filenames are specified in import order. Paths are

not necessary, because the Fallback mechanism will find the file at the collection,

group or class level depending on the situation and the presence of files. </p>

<blockquote>

<p>&lt;XslFallbackFileList&gt;<br>

&lt;Filename&gt;<strong>bookbagitemsstring.xsl</strong>&lt;/Filename&gt;<br>

&lt;Filename&gt;<strong>search.xsl</strong>&lt;/Filename&gt;<br>

&lt;Filename&gt;<strong>htmlhead.xsl</strong>&lt;/Filename&gt;<br>

&lt;Filename&gt;<strong>navheader.xsl</strong>&lt;/Filename&gt;<br>

&lt;Filename&gt;<strong>footer.import.xsl</strong>&lt;/Filename&gt;<br>

&lt;Filename&gt;<strong>searchforms.xsl</strong>&lt;/Filename&gt;<br>

&lt;Filename&gt;<strong>xsl2htmlutils.xsl</strong>&lt;/Filename&gt;<br>

&lt;Filename&gt;<strong>globalvariables.xsl</strong>&lt;/Filename&gt;<br>

&lt;Filename&gt;<strong>searchheader.xsl</strong>&lt;/Filename&gt;<br>

&lt;/XslFallbackFileList&gt; </p>

</blockquote>

All Fallback is handled by the Perl CGI. To build the [http://www.dlxs.org/training/workshop200707/ui/search_virtualstylesheet.xml Virtual XSL Stylesheet (example)], the CGI parses the XSL Fallback File List, performs Fallback on each file, and assembles a list of XSL import statements.

<p>Here you can see the import statements from the Virtual XSL Stylesheet the

CGI builds. In this case, all of the files are in the class level web directory.</p>

<blockquote>

<p>&lt;xsl:import href=&quot;<strong>/n1/web/t/text/bookbagitemsstring.xsl</strong>&quot;/&gt;<br>

&lt;xsl:import href=&quot;<strong>/n1/web/t/text/search.xsl</strong>&quot;/&gt;<br>

&lt;xsl:import href=&quot;<strong>/n1/web/t/text/htmlhead.xsl</strong>&quot;/&gt;<br>

&lt;xsl:import href=&quot;<strong>/n1/web/t/text/navheader.xsl</strong>&quot;/&gt;<br>

&lt;xsl:import href=&quot;<strong>/n1/web/t/text/footer.import.xsl</strong>&quot;/&gt;<br>

&lt;xsl:import href=&quot;<strong>/n1/web/t/text/searchforms.xsl</strong>&quot;/&gt;<br>

&lt;xsl:import href=&quot;<strong>/n1/web/lib/xsl2htmlutils.xsl</strong>&quot;/&gt;<br>

&lt;xsl:import href=&quot;<strong>/n1/web/t/text/globalvariables.xsl</strong>&quot;/&gt;<br>

&lt;xsl:import href=&quot;<strong>/n1/web/t/text/searchheader.xsl</strong>&quot;/&gt;</p>

</blockquote>

<p>The order of the import statements is significant. The <strong>first</strong> import &quot;wins&quot; in

cases where an XSL template (don't confuse XSL templates with XML templates)

of the same name occurs in more than one file. This feature allows XSL template

overrides to occur in a logical fashion. <strong>This

is very important concept to understand. </strong>Imagine you want to customize

the search form for a single collection and that the change requires modification

to

<em>just one</em> of several XSL <em>templates</em> that exist in the Class level search.xsl

file. Here are the steps you should take.</p>

# Create a collection specific web directory, if one does not already exist.

# Create an XSL file called search.xsl in the collection specific web directory and include in it just the template(s) requiring modification. You probably want to copy the single template from the Class level XSL search.xsl file.

# Add an import statement to the collection level search.xsl file that imports the Class level file.

# Modify the collection level template to your liking.

<p>When the Virtual Stylesheet is assembled, Fallback will find the collection

level search.xsl file and import it. This will in-turn cause the Class level

search.xsl file to be imported too, <em>except</em> the modified collection level template

will be used since it was imported first. </p>

===Oxygen for Dissecting XML and XSL===

<p><strong>Oxygen</strong> is an application for editing and debugging XML and XSL (see also [[Useful Tools|web development tools]]).

It also does XSL transformations so you clearly see the relationship among

the XML, XSL and the resulting HTML. Oxygen enables you

to step through the transform, but even better, you can click on an element

in the HTML output and it will show you the XML and XSL that generated it.

What a powerful timesaver!</p>

<p>To make the most effective use of Oxygen, you should use an XWindows server

to run it remotely on the DLXS server. This provides direct access to all

of the XML and XSL files. Adding <strong>debug=xsltwrite</strong> to a DLXS

URL will cause the CGI to write the Virtual XSL Stylesheet and the populated

XML files to disk in <strong>$DLXSROOT/web/cache</strong>. Open these files in Oxygen, and transform

the Virtual XSL Stylesheet to the XML. Oxygen will find and open the imported

XSL files allowing you to make edits and rerun the transform. </p>

===Language Map===

<p>All text that appears as part of the user interface is stored in an XML file

per Class called <strong>langmap.en.xml</strong>. Phrases are assigned keys, and the keys are

used in the XSL to retrieve phrases. </p>

<p>Customization of the Language Map requires finding the key and phrase that

needs to be changed. There are a couple of ways to go at this. You can open

the Language Map file and search for the phrase, or you can locate the associated

key in the XSL and then look for the key in Language Map. Once the key and

phrase have been identified, it is recommended that you create a <strong>langmapextra.en.xml</strong> file and make your changes there. </p>

<p>For example, if you need to change the word &quot;login&quot; to &quot;sign in&quot; for all Text

Class collections, do the following.</p>

# Open $DLXSROOT/web/t/text/langmap.en.xml and locate the term &quot;login&quot;. There may be several occurrences, but you confirm three are relevant by grepping the XSL files for the keys. Here are the three. <br>

<Item key="standardlogin.str">Login&#xa0;</Item>

<Item key="header.str.login">Login </Item>

<Item key="results.str.9">Login for full access to this item</Item>

2. Create a new file in the Text Class web directory called langmapextra.en.xml containing the following text. The "Lookup id" value is arbitrary. "auth" is used here just to be consistent with what appears in langmap.en.xml.

<LookupTables>

<Lookup id="auth">

<Item key="standardlogin.str">Sign In&#xa0;</Item>

<Item key="header.str.login">Sign In </Item>

<Item key="results.str.9">Sign In for full access to this item</Item>

</Lookup>

</LookupTables>

<p>That's all it takes. The DlxsGlobals.xml chunk file already specifies that

<strong>langmapextra.en.xml</strong> be loaded if present. Item keys in it

trump items with the same keys in <strong>langmap.en.xml</strong>. To limit

the changes to a specific group or collection, place the <strong>langmapextra.en.xml</strong> file in the collection or group level web directory. </p>

<p>It is possible to use Language Maps to create a multi-lingual user

interface. </p>