Disclaimer

Instructions for implementing a javascript/xslt user criteria saver for ENCompass. Use at your own risk. TCC is not responsible for damage or problems caused by the use of these scripts. No warranties or guarantees of any kind are implied or assumed.

ENCompass 3.5 User Criteria Saver

Version 3.5
Scripts by Jim Robinson
Tarrant County College South Campus
5301 Campus Dr.
Fort Worth, TX 76119
(817) 515-4310

Copyright 2005, Tarrant County College ("TCC"). All rights reserved.

For use with the ENCompass 3.5 product by Endeavor Systems, Inc.
"ENCompass" is a trademark of Endeavor Information Systems, Inc.

Purpose: Javascript and XSLT scripts allow user input to be retained in search forms when clicking the + or - buttons in childbrowse.xsl or childbrowseadvanced.xsl No warranties or guarantees of any kind or implied. use at your own risk. It works for us, so we thought we'd share... ;-)

By using this software the USER indicates that he or she has read, understood and and will comply with the following:

TCC hereby grants USER permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee, provided that:
  1. the above copyright notice appears in all copies of the software and its documentation, or portions thereof, and
  2. a full copy of this notice is included with the software and its documentation, or portions thereof, and
  3. neither the software nor its documentation, nor portions thereof, is sold for profit. Any commercial sale or license of this software, copies of the software, its associated documentation and/or modifications of either is strictly prohibited without the prior consent of TCC.
  4. Title to copyright to this software and its associated documentation shall at all times remain with TCC. No right is granted to use in advertising, publicity or otherwise any trademark, service mark, or the name of TCC.
  5. This software and any associated documentation are provided "as is," and TCC MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING THOSE OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR THAT USE OF THE SOFTWARE, MODIFICATIONS, OR ASSOCIATED DOCUMENTATION WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER INTELLECTUAL PROPERTY RIGHTS OF A THIRD PARTY. TCC, The University of Texas System, its Regents, officers, and employees shall not be liable under any circumstances for any direct, indirect, special, incidental, or consequential damages with respect to any claim by USER or any third party on account of or arising from the use, or inability to use, this software or its associated documentation, even if TCC has been advised of the possibility of those damages.
These scripts are meant to be used with the ENCompass product by Endeavor Information Systems, Inc.™ ENCompass has a nasty habit of losing all data input by a user if the "+" or "-" signs are used to open or close a collection. For example, if a user decided to perform a Subject Keyword search for "Navajo" OR "Hopi" As a Phrase returning 50 hits per page and entered this criteria, then decided to open a collection to choose a particular database to search, the user would have to re-enter "Subject Keyword", "Navajo", "Hopi", "As A Phrase", "NOT" and 50 hits per page (assuming none of these drop downs were the default).

The javascripts enclosed in encompass_criteria3.5.zip are meant to preserve the user's criteria when a collection hierarchy button ("+" or "-") is clicked. The scripts automatically check a child if the parent was checked when the parent was opened. All user choices are maintained. For example, if a parent is checked and a child of this parent is un-checked by the user, then a second collection is opened or closed, the integrity of the user's choice for the former collections remains intact.

Instructions

  • Always back up a file before making changes!!!
  • Just to be safe, comment out, don't delete, existing code before you make changes to your copy.
  • Instructions are in bold
  • Explanations are italicized.
  • Enough with the warnings, here are the instructions.

  1. Download the JavaScripts from http://lib-serv.tccd.edu/code/encompass/encompass_criteria3.5.zip

  2. Drop the file "tcc.js" in your html directory.
    (by default, the html directory for ENCompass 3.5 is located at /m1/encompass/yourcollection/tomcat/default/context/logicrouter/html)
    These are the javascripts that do all the work.

  3. In childbrowse.xsl find:

    <script LANGUAGE="JavaScript1.2" type="text/javascript">
       document.write("&lt;script LANGUAGE='JavaScript1.2' SRC='/html/validate.js'&gt;&lt;\/script&gt;");
    </script>


    Below it, add this line:

    <script type="text/javascript" src="/html/tcc.js"/>

    This allows the javascripts to be used from childbrowse.xsl

  4. In childbrowseadvanced.xsl find:

    <script type="text/javascript" src="/html/validate.js"/>
    <script type="text/javascript" src="/html/getcheck.js"/>

    Below it, add this line:

    <script type="text/javascript" src="/html/tcc.js"/>

    This allows the javascripts to be used from childbrowseadvanced.xsl

  5. In childbrowse.xsl and childbrowseadvanced.xsl find:

    </body>

    ABOVE the </body> tag, add:

    <script language="Javascript">
       setChecks();
       removeHierCookie();
    </script>

    This reads the cookies once the page has loaded and sets the input fields based on the cookies.

  6. In child_logic.xsl find the last two (2) instances of:

    <img src="/images/mns.gif" alt="collapse thread" border="1" class="hidden"/>
    and
    <img src="/images/pls.gif" alt="collapse thread" border="1" class="hidden"/>

    DO NOT change the instance under <xsl:template name="DoChildGroupLogic">
    The first instance is under <xsl:template name="DoThreadLogic">
    The second instance is under <xsl:template name="DoPubThreadLogic">

    Replace them to read:

    <img src="/images/mns.gif" alt="collapse thread" border="1" class="hidden" onclick="getChecks()"/>
    <xsl:call-template name="FormatHierCookies">
       <xsl:with-param name="hier_val" select="@hier"/>
       <xsl:with-param name="object_id">
          <xsl:value-of select="*[name()=$object_ID]"/>
       </xsl:with-param>
    </xsl:call-template>

    and


    <img src="/images/pls.gif" alt="collapse thread" border="1" class="hidden" onclick="getChecks()"/>
    <xsl:call-template name="FormatHierCookies">
       <xsl:with-param name="hier_val" select="@hier"/>
       <xsl:with-param name="object_id">
          <xsl:value-of select="*[name()=$object_ID]"/>
       </xsl:with-param>
    </xsl:call-template>

    This runs the scripts when the user clicks a "+" or "-" that collects all the current data and stores it in a cookie.

  7. In misctools.xsl, find:

    <!-- ############################################################################ -->

       <xsl:template name="FormatHier">
          <xsl:param name="hier_val"/>
          <script language="javascript">jsIndent("<xsl:value-of select="$hier_val"/>")</script>
       </xsl:template>

    <!-- ############################################################################ -->

    Below this, add:

       <xsl:template name="FormatHierCookies">
          <xsl:param name="hier_val"/>
          <xsl:param name="object_id"/>
          <script language="javascript">hierCookie("<xsl:value-of select="$hier_val"/>", "<xsl:value-of select="$object_id"/>")</script>
       </xsl:template>

    <!-- ############################################################################ -->

    This takes information sent from the xsl:call-template added in step 6 above and calls a javascript that creates a cookie with hierarchy information.

    That should do it for saving criteria when users click the "+" and "-" buttons.

    There are a couple of other features and scripts included that you may want to take advantage of:
  • To set default collections,
    1. Open your default ENCompass search page in your web browser.
    2. Click the View XML button.
    3. Make note of the <OI>#</OI> numbers associated with the collections you wish to be defaults.
    4. Now open tcc.js and find Set Default Collections Here
    5. Follow the instructions you find there.
  • To set default search types (Global, Subject, Name, Title) in childbrowseadvanced.xsl:
    1. Open tcc.js.
    2. Find Set default search types.
    3. Follow the examples.
  • To add a "Set All Checks" button:
    • In childbrowse.xsl or childbrowseadvanced.xsl where you would like the button to appear, add:

      <input type="button" value="Set All" onclick="setAllChecks(true);" />

      (Note that this button must be between the <form></form> tags)

  • To add a "Clear All Checks" button:
    • In childbrowse.xsl or childbrowseadvanced.xsl where you would like the button to appear, add:

      <input type="button" value="Clear All" onclick="setAllChecks(false);" />

      (Note that this button must be between the <form></form> tags)

  • To add a "Reset All To Defaults" button:
    • In childbrowse.xsl or childbrowseadvanced.xsl where you would like the button to appear, add:

      <input type="button" name="Reset" value="Reset" onclick="clearChecks();"/>

      (Note that this button must be between the <form></form> tags)

How It Works

When the user clicks a "+" or "-" to open or close a collection, the getChecks() javascript and the FormatHierCookies.xsl template are called. These scripts gather the values of each input field, checkbox, and hierarchy name and value and create name-value strings, which it stores as cookies on the user's browser.

The page then reloads with the altered state of the collection (open or closed.) After the page loads (or near the end of the load), the setChecks() javascript is called. This script reads and parses the cookies, then sets all the values to the state before the page refreshed.

With these scripts, we can also set default values for the user's first visit to the page. We can also make it easy for the user to set every checkbox, to clear every checkbox, and to reset the forms to the default states.

Troubleshooting

Questions can be sent to Jim Robinson at Tarrant County College, but the help I can provide is limited due to time constraints and lack of access to your system for debugging... ;-)

Some hints about debugging javascripts:

  • If a script isn't working as you'd expect, try putting an alert message in the function to see if the code is being reached and that it is returning what you expect. For example:
    function testFunction() {
       var myForm = document.forms['myForm'];
       alert("myForm="+myForm);
       other code...;
    }
  • If the code isn't being called, check the syntax, the path to the javascript source, and your objects. Don't be afraid to stick an object in an alert message to make sure it's an object.
  • Download a free Firefox browser Get Firefox! and choose Tools->JavaScript Console.
  • Download an Opera browser (http://www.opera.com) and turn on "Report JavaScript Errors".
  • Remember: browser detection is poor coding...object detection will serve you much better.