Customizing the User interface

From DLXS Documentation

(Difference between revisions)
Jump to: navigation, search
Current revision (18:20, 10 August 2007) (edit) (undo)
 
(8 intermediate revisions not shown.)
Line 1: Line 1:
-
<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 width="100%" 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 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====
 
- 
-
<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>
 
- 
-
====<font color="red">HIT</font>: standard template path: /n1/web/t/text/search.xml,
 
-
xcollmode=singlecoll, on disk====
 
- 
-
===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>
 
- 
-
<p>&lt;DlxsGlobals&gt;&lt;?CHUNK filename=&quot;dlxsclassglobals.xml&quot;?&gt;&lt;/DlxsGlobals&gt;</p>
 
- 
-
===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>
 
- 
-
<p>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>
 
- 
-
<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>
 
-
<br>
 
-
<span class="markupsnippet style1">&lt;Item key=&quot;standardlogin.str&quot;&gt;<strong>Login</strong>&amp;#xa0;&lt;/Item&gt;<br>
 
-
&lt;Item key=&quot;header.str.login&quot;&gt;<strong>Login</strong> &lt;/Item&gt;<br>
 
- 
-
&lt;Item key=&quot;results.str.9&quot;&gt;<strong>Login</strong> for full access
 
-
to this item&lt;/Item&gt; <br>
 
-
</span>
 
-
# Create a new file in the Text Class web directory called <strong>langmapextra.en.xml</strong> containing
 
-
the following text. The &quot;Lookup id&quot; value is arbitrary. &quot;auth&quot; is used here
 
-
just to be consistent with what appears in <strong>langmap.en.xml</strong>.
 
-
<span class="markupsnippet style1">&lt;LookupTables&gt;<br>
 
-
&lt;Lookup id=&quot;auth&quot;&gt; <br>
 
-
</span><span class="markupsnippet style1">&lt;Item key=&quot;standardlogin.str&quot;&gt;<strong>Sign
 
-
In</strong>&amp;#xa0;&lt;/Item&gt;<br>
 
- 
-
&lt;Item key=&quot;header.str.login&quot;&gt;<strong>Sign In</strong> &lt;/Item&gt;<br>
 
-
&lt;Item key=&quot;results.str.9&quot;&gt;<strong>Sign In</strong> for full
 
-
access to this item&lt;/Item&gt;<br>
 
-
&lt;/Lookup&gt;<br>
 
-
&lt;/LookupTables&gt;
 
- 
-
</span>
 
-
<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>
 

Current revision

Personal tools