Please read the User Interface Overview if you have not yet.
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.
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.
|What can you do?||What do you need to know?|
|Collection Manager||Change the most common interface elements such as collection title and field labels. Include or exclude certain functionality. Varies significantly by Class.||You need to know how to use your browser. There is contextual help in Collection Manager for each field.|
|CSS||Change colors and font styles. Hide elements. Control positioning of some elements in Image Class.||Requires knowledge of CSS and a basic understanding of Fallback.|
|Language Map||Change user interface text.||Requires basic knowledge of XSL, XML and Fallback.|
|XSL||Alter the structure/layout of the HTML including the application of CSS styles.||Requires knowledge of XSL, HTML, and CSS and a very good understanding of Fallback.|
|XML Template||Include/exclude Processing Instructions to control the availability of data generated by the CGI.||Requires very good knowledge of all aspects of the user interface, Fallback, and the role of the CGI in DLXS.|
|Configuration files||Various changes depending on class||Varies. In some cases simple changes can be made. For example to change the title of a section in the Findaid Class table of contents. Other chantes require 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.|
|Perl||Control the data generated by the CGI. Alter Processing Instructions, or create new ones.||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.|
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.
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.
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.
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.
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.
All Fallback is handled by the Perl CGI. To build the 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.
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.
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 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.
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.
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.