|
|
| (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> </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> </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, "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."</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, "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. </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, "HIT" 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 "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. </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><DlxsGlobals><?CHUNK filename="dlxsclassglobals.xml"?></DlxsGlobals></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><XslFallbackFileList><br>
| |
| - | <Filename><strong>bookbagitemsstring.xsl</strong></Filename><br>
| |
| - | <Filename><strong>search.xsl</strong></Filename><br>
| |
| - | <Filename><strong>htmlhead.xsl</strong></Filename><br>
| |
| - | <Filename><strong>navheader.xsl</strong></Filename><br>
| |
| - | <Filename><strong>footer.import.xsl</strong></Filename><br>
| |
| - | <Filename><strong>searchforms.xsl</strong></Filename><br>
| |
| - | <Filename><strong>xsl2htmlutils.xsl</strong></Filename><br>
| |
| - | <Filename><strong>globalvariables.xsl</strong></Filename><br>
| |
| - | <Filename><strong>searchheader.xsl</strong></Filename><br>
| |
| - | </XslFallbackFileList> </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><xsl:import href="<strong>/n1/web/t/text/bookbagitemsstring.xsl</strong>"/><br>
| |
| - | <xsl:import href="<strong>/n1/web/t/text/search.xsl</strong>"/><br>
| |
| - | <xsl:import href="<strong>/n1/web/t/text/htmlhead.xsl</strong>"/><br>
| |
| - | <xsl:import href="<strong>/n1/web/t/text/navheader.xsl</strong>"/><br>
| |
| - | <xsl:import href="<strong>/n1/web/t/text/footer.import.xsl</strong>"/><br>
| |
| - | <xsl:import href="<strong>/n1/web/t/text/searchforms.xsl</strong>"/><br>
| |
| - | <xsl:import href="<strong>/n1/web/lib/xsl2htmlutils.xsl</strong>"/><br>
| |
| - | <xsl:import href="<strong>/n1/web/t/text/globalvariables.xsl</strong>"/><br>
| |
| - | <xsl:import href="<strong>/n1/web/t/text/searchheader.xsl</strong>"/></p>
| |
| - | </blockquote>
| |
| - |
| |
| - | <p>The order of the import statements is significant. The <strong>first</strong> 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. <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 "login" to "sign in" for all Text
| |
| - | Class collections, do the following.</p>
| |
| - |
| |
| - | # 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. <br>
| |
| - | <br>
| |
| - | <span class="markupsnippet style1"><Item key="standardlogin.str"><strong>Login</strong>&#xa0;</Item><br>
| |
| - | <Item key="header.str.login"><strong>Login</strong> </Item><br>
| |
| - |
| |
| - | <Item key="results.str.9"><strong>Login</strong> for full access
| |
| - | to this item</Item> <br>
| |
| - | </span>
| |
| - | # Create a new file in the Text Class web directory called <strong>langmapextra.en.xml</strong> containing
| |
| - | the following text. The "Lookup id" value is arbitrary. "auth" is used here
| |
| - | just to be consistent with what appears in <strong>langmap.en.xml</strong>.
| |
| - | <span class="markupsnippet style1"><LookupTables><br>
| |
| - | <Lookup id="auth"> <br>
| |
| - | </span><span class="markupsnippet style1"><Item key="standardlogin.str"><strong>Sign
| |
| - | In</strong>&#xa0;</Item><br>
| |
| - |
| |
| - | <Item key="header.str.login"><strong>Sign In</strong> </Item><br>
| |
| - | <Item key="results.str.9"><strong>Sign In</strong> for full
| |
| - | access to this item</Item><br>
| |
| - | </Lookup><br>
| |
| - | </LookupTables>
| |
| - |
| |
| - | </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>
| |
