Customizing the User interface

From DLXS Documentation

Revision as of 12:57, 10 August 2007

Please read the User Interface Overview if you have not yet.

Figuring Out How to Make a Change

Overview

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 best way to make a change.

First of all, there are some web development tools available that can greatly simplify your effort. For now, get these three and keep the others in mind.

1. Firefox web browser
2. Firebug extension for Firefox
3. Web Developer extension for Firefox

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.

     field labels. Include or exclude certain functionality. Varies significantly

     of DLXS code, and all other aspects of the user interface. We recommend

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.

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

How to tell if the change can be made in 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 CSS is good for and how it works.

• Use the Firebug extension to Firefox to inspect 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 can
   even 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

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.

It would be appropriate at this point to contact DLXS Support with a question such as, "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."

However, if you are an experienced programmer, we encourage you to 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, "I'm thinking about doing X, and this is how I propose to do it. What do you think?". 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.

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.

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.

Finding the Correct Files: More about Fallback

XML Template

It can be difficult to locate the files that are directly involved in constructing an HTML page. Add debug=tpl 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, "HIT" tells us that the search.xml template was found in the class (t/text for Text Class) level web directory.

====HIT: standard template path: /n1/web/t/text/search.xml,

 xcollmode=singlecoll, on disk====

XML Template Chunks

There is a special Processing Instruction called "CHUNK". The CHUNK PI is for inserting a "chunk" 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.

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.

<DlxsGlobals><?CHUNK filename="dlxsclassglobals.xml"?></DlxsGlobals>

XSL Stylesheet

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.

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 Virtual XSL Stylesheet serves this purpose.

Each primary XML Template includes an XSL Fallback File List 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.

<XslFallbackFileList>
<Filename>bookbagitemsstring.xsl</Filename>
<Filename>search.xsl</Filename>
<Filename>htmlhead.xsl</Filename>
<Filename>navheader.xsl</Filename>
<Filename>footer.import.xsl</Filename>
<Filename>searchforms.xsl</Filename>
<Filename>xsl2htmlutils.xsl</Filename>
<Filename>globalvariables.xsl</Filename>
<Filename>searchheader.xsl</Filename>
</XslFallbackFileList>

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.

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.

<xsl:import href="/n1/web/t/text/bookbagitemsstring.xsl"/>
<xsl:import href="/n1/web/t/text/search.xsl"/>
<xsl:import href="/n1/web/t/text/htmlhead.xsl"/>
<xsl:import href="/n1/web/t/text/navheader.xsl"/>
<xsl:import href="/n1/web/t/text/footer.import.xsl"/>
<xsl:import href="/n1/web/t/text/searchforms.xsl"/>
<xsl:import href="/n1/web/lib/xsl2htmlutils.xsl"/>
<xsl:import href="/n1/web/t/text/globalvariables.xsl"/>
<xsl:import href="/n1/web/t/text/searchheader.xsl"/>

The order of the import statements is significant. The first import "wins" 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. This is very important concept to understand. Imagine you want to customize the search form for a single collection and that the change requires modification to just one of several XSL templates that exist in the Class level search.xsl file. Here are the steps you should take.

1. Create a collection specific web directory, if one does not already exist.
2. 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. 

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

   the Class level file. 

1. Modify the collection level template to your liking.

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, except the modified collection level template will be used since it was imported first.

Oxygen for Dissecting XML and XSL

Oxygen is an application for editing and debugging XML and XSL (see also 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!

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 debug=xsltwrite to a DLXS URL will cause the CGI to write the Virtual XSL Stylesheet and the populated XML files to disk in $DLXSROOT/web/cache. 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.

Language Map

All text that appears as part of the user interface is stored in an XML file per Class called langmap.en.xml. Phrases are assigned keys, and the keys are used in the XSL to retrieve phrases.

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 langmapextra.en.xml file and make your changes there.

For example, if you need to change the word "login" to "sign in" for all Text Class collections, do the following.

1. Open $DLXSROOT/web/t/text/langmap.en.xml and locate the term "login". There

   may be several occurrences, but you confirm three are relevant by grepping
   the XSL files for the keys. Here are the three. 

   

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

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

That's all it takes. The DlxsGlobals.xml chunk file already specifies that langmapextra.en.xml be loaded if present. Item keys in it trump items with the same keys in langmap.en.xml. To limit the changes to a specific group or collection, place the langmapextra.en.xml file in the collection or group level web directory.

It is possible to use Language Maps to create a multi-lingual user interface.