home *** CD-ROM | disk | FTP | other *** search
/ CD Actual Thematic 7: Programming / CDAT7.iso / Share / Java / ScriptBuilder / NOSB30_TRIAL.exe / data1.cab / Program_Files / CompLib / historyNav.js < prev    next >
Encoding:
Text File  |  1998-10-05  |  13.6 KB  |  351 lines
  1.  
  2. /* ******************* BEGIN HistoryNav Object ******************** */
  3.  
  4. /* ======================================================================
  5. OBJECT:        HistoryNav
  6.  
  7. PROPERTIES:    The following properties should be considered public, and
  8.                 can be set by the outside world.
  9.                 ---
  10.                 domain (string)    : the domain name being accessed (e.g. "netobjects.com")
  11.                 firstLabel (string): the label that appears when the list is initialized
  12.                 name (string)        : the name of the HTML select element
  13.                 size (integer)        : the size of the HTML select element
  14.                                           size == 1 --> drop-down list box
  15.                                           size > 1 --> scrolling list box 
  16.                             
  17.                 The following properties should be considered private, and
  18.                 should not be set by the outside world.  The object uses
  19.                 these properties internally.                
  20.                 ---
  21.                 lastLink (string)    : the last URL accessed
  22.                 links (array)        : an array of URL strings
  23.                 labels (array)        : an array of labels that correspond to the URLs
  24.                 maxItems (integer): the total number of items allowed in the list;
  25.                                           defaults to 25
  26.                 numItems (integer): the number of elements in the links and labels 
  27.                             arrays
  28.  
  29. METHODS:        The following methods should be considered public, and
  30.                 can be called by the outside world.
  31.                 ---
  32.                 addLink             : adds a URL and label to the links and labels arrays
  33.                 getOpenerURL    : gets the URL of the opener window
  34.                 isDuplicateURL    : determines if a given URL accessed already exists in the list
  35.                 render             : writes out the HTML that defines the select element
  36.                 update            : update the HTML select list with most recent links and labels
  37.  
  38.                 The following methods should be considered private, and
  39.                 should not be set by the outside world.  The object uses
  40.                 these methods internally.                
  41.                 ---
  42.                 validateLocation : makes sure URL selected in opener window is valid
  43.                                          before proceeding to add links to the list
  44.  
  45. DESC:            This object allows developers to create an HTML select form element
  46.                 that populates itself with a history of navigated pages. For any given
  47.                 host domain (e.g. www.netobjects.com, www.microsoft.com, etc.) the navigator will
  48.                 track all pages visited in the domain and present them in an HTML
  49.                 select list.  The user may jump to history list items by selecting
  50.                 an item in the list.
  51.                 
  52.                 This object is generally for use on a small pop-up window of it's own.
  53.                 You should create the pop-up window from a form button or the onLoad
  54.                 method on another window. This navigator will then track the history of URL's navigated in this
  55.                 window that opened the navigator window, provided they are all in the
  56.                 target domain.
  57.  
  58. NOTE:            This object will work ONLY with pages of the same domain.  If you
  59.                 attempt to access pages outside of the domain in which the navigator is
  60.                 launched, you will get a security violation.
  61.                 
  62. PLATFORMS:    Netscape Navigator 3.01 or higher, 
  63.                 Microsoft Internet Explorer 4.0 or higher
  64.  
  65. USAGE:        The following code shows an example of how to use the object in a
  66.                 typical scenario.  See the individual method definitions for more
  67.                 information.
  68.                 
  69.                 // Example of how to call the navigator from an opener window.  This
  70.                 // page will open a window that contains a navigator object 
  71.                 
  72.                 function OpenNavWin( sourceFile, width, height ) {
  73.                     navWin = window.open(sourceFile,'NavWin','toolbar=0,width=' + width + 
  74.                                 ',height=' + height + ',directories=0,status=0,scrollbars=0' + 
  75.                                 ',resize=0,menubar=0');
  76.                 } // end OpenNavWin
  77.  
  78.                 // Later in in the <BODY> of the page, launch the window like so:
  79.                 <FORM NAME="LaunchForm">
  80.                 <!-- Launch History.html, which contains the HistoryNav object, in a pop-up window -->
  81.                 <INPUT TYPE=button NAME="Launcher" VALUE="Launch History Navigator" 
  82.                     onClick="OpenNavWin('histtest.html', 350, 175)">
  83.                 </FORM>                
  84.                 
  85.                 /////////////////////////////////////////////////////////////////////
  86.                 
  87.                 // The pop-up window (e.g. 'History.html') should contain the following 
  88.                 //    code in the <BODY> in addition to the object definition, which should be placed in the
  89.                 //    <HEAD> of the document. 
  90.  
  91.                 // Create the object.  The select list will be named "hnav" 
  92.                 // on the page.  A size of 1 is specified, so it will render as a 
  93.                 // drop-down list.  Up to 20 items may be stored in the list.
  94.                 myHistory = new HistoryNav("www.netobjects.com", "hnav", 1, 20);
  95.  
  96.                 // Render the initial HTML on the page
  97.                 myHistory.render();
  98.                 
  99.                 // Start the listener which listens for page changes
  100.                 HistoryListener("myHistory", myHistory);
  101.  
  102. ====================================================================== */
  103. function com_netobjects_HistoryNav( obj ) {
  104.  
  105.     // "Public" Properties - can be modified by outside world
  106.     this.domain = (obj.domain+"" != "undefined" && obj.domain != null) ? obj.domain.toUpperCase() : "";
  107.     this.firstLabel = (obj.firstLabel+"" != "undefined" && obj.firstLabel != null ? obj.firstLabel : "There arcurrently no items in the histy navigator.");
  108.     this.name = (obj.name+"" != "undefined" && obj.name != null) ? obj.name : "HistoryNav1";
  109.     this.size = (obj.size+"" != "undefined" && obj.size != null) ? obj.size : 1;
  110.     this.selectName = (obj.selectName+"" != "undefined" && obj.selectName != null ? obj.selectName : "");
  111.  
  112.     // "Private" Properties - should not be modified except by object methods
  113.     this.labels = new Array();
  114.     this.lastLink = "";
  115.     this.links = new Array();
  116.     this.maxItems = (obj.maxItems+"" != "undefined" && obj.maxItems != null) ? obj.maxItems : 25;
  117.     this.numItems = 0;
  118.  
  119.     // "Public" Methods - can be called by outside world
  120.     this.addLink = hnAddLink;
  121.     this.getOpenerURL = hnGetOpenerURL;
  122.     this.isDuplicateURL = hnIsDuplicateURL;
  123.     this.render = hnRender;
  124.     this.update = hnUpdate;
  125.     this.historyListener = HistoryListener;
  126.  
  127.     // "Private" Methods - should not be called except by other methods
  128.     this.refreshLinks = hnRefreshLinks;
  129.     this.validateLocation = hnValidateLocation;
  130.  
  131.     // Initialize this.lastLink
  132.     this.lastLink = this.getOpenerURL();    
  133.  
  134.     /* ======================================================================
  135.     FUNCTION:    hnValidateLocation (HistoryNav method: validateLocation)
  136.     
  137.     INPUT:        none.
  138.     
  139.     RETURNS:        none.
  140.     
  141.     DESC:            This function validates any locations discovered when the opener
  142.                     window's location changes.  If the location is valid, the link
  143.                     and label are added to the lists of links.
  144.     ====================================================================== */
  145.     function hnValidateLocation() {
  146.         var locn = this.getOpenerURL().toUpperCase();
  147.         // Make sure the location is not empty and the domain is valid
  148.        if (locn != "") {
  149.            // Do not attempt to add link unless domains are the same
  150.            if(locn.indexOf(this.domain) != -1) 
  151.                this.addLink(); 
  152.        }
  153.        else { // close history tracker if opener URL cannot be found (i.e. opener is closed)
  154.        }    
  155.     } // end hnValidateLocation
  156.     
  157.     
  158.     /* ======================================================================
  159.     FUNCTION:    hnAddLink (HistoryNav method: addLink)
  160.     
  161.     INPUT:        none.
  162.     
  163.     RETURNS:        none.
  164.     
  165.     DESC:            This function adds a url and corresponding optional label to the
  166.                     links and labels arrays.  It then calls update() to update the
  167.                     HTML select list.
  168.     ====================================================================== */
  169.     function hnAddLink() {
  170.         var url = "";
  171.         var label = "";
  172.         
  173.         url = this.getOpenerURL();
  174.     
  175.         if (url != this.lastLink && url != "") {
  176.             // Set lastLink to the url just detected
  177.             this.lastLink = url;
  178.             
  179.             // Only add link if it doesn't already exist in the history list
  180.             label = window.opener.document.title;
  181.             if (!this.isDuplicateURL(url)) {
  182.                 this.numItems++;
  183.                 
  184.                 // If the number of items exceeds max allowed, strip off the old URL
  185.                 if (this.numItems > this.maxItems)
  186.                     this.refreshLinks();
  187.                     
  188.                 this.links[this.numItems-1] = url;
  189.                 // Add the label.  If no label was given, make the label the same as the link
  190.                 this.labels[this.numItems-1] = (label != null || label+"" != "undefined") ? label : url;
  191.                 // Update the options list
  192.                   this.update();
  193.             } // end inner if
  194.        } // end outer if
  195.     } // end hnAddLink
  196.     
  197.     
  198.     /* ======================================================================
  199.     FUNCTION:    hnRender (HistoryNav method: render)
  200.     
  201.     INPUT:        none.
  202.     
  203.     RETURNS:        none.
  204.     
  205.     DESC:            This function writes out all necessary HTML to render the initial
  206.                     select list on the page.  You should not call this function more
  207.                     than once per object.
  208.     ====================================================================== */
  209.     function hnRender() {
  210.         document.writeln('<FORM NAME="' + this.selectName + '">');
  211.        document.writeln('<SELECT NAME="' + this.selectName + '"' +
  212.                         'onChange="window.opener.location.href = this.options[this.selectedIndex].value">');
  213.         // Initialize options array up to maxItems.
  214.         // This sets the width
  215.         for (var i=0; i < this.maxItems; i++) {
  216.             document.writeln('<OPTION>' + this.firstLabel);
  217.         }
  218.         document.writeln('</SELECT>');
  219.         document.writeln('</FORM>');        
  220.         
  221.         // Blank out all items but the first
  222.         for (var j=this.maxItems-1; j > 0; j--) {
  223.             document.forms[this.selectName].elements[this.selectName].options[j] = null;
  224.         }
  225.                 
  226.         this.update();
  227.     } // end hnRender
  228.     
  229.     
  230.     /* ======================================================================
  231.     FUNCTION:    hnUpdate (HistoryNav method: update)
  232.     
  233.     INPUT:        none.
  234.     
  235.     RETURNS:        none.
  236.     
  237.     DESC:            This function uses the links and labels arrays to update the
  238.                     HTML select list on the form.
  239.     ====================================================================== */
  240.     function hnUpdate() {
  241.         if (this.numItems > 0) {
  242.             with (document.forms[this.selectName].elements[this.selectName]) {
  243.                 // Blank out all options
  244.                 for(var i=this.numItems-1; i >= 0; i--) 
  245.                  options[i] = null;
  246.              // Fill array with most recently trapped at top of list
  247.                 for (j=0; j < this.numItems; j++)  
  248.                 options[j] = new Option((j + 1) + ") " + this.labels[j], this.links[j]);
  249.             } // end with 
  250.     
  251.             // Select the most recent entry
  252.            document.forms[this.selectName].elements[this.selectName].options[this.numItems-1].selected = true;
  253.         } // end if
  254.         else
  255.            document.forms[this.selectName].elements[this.selectName].options[0].selected = true;
  256.     } // end hnUpdate
  257.     
  258.     
  259.     /* ======================================================================
  260.     FUNCTION:    hnIsDuplicateURL (HistoryNav method: isDuplicateURL)
  261.     
  262.     INPUT:        url (string) : the url to test
  263.     
  264.     RETURNS:        true, if the url is a duplicate
  265.                     false, otherwise
  266.     
  267.     DESC:            This function compares the url parameter to all links and labels
  268.                     stored.  It returns true or false to indicate whether or not url
  269.                     is a duplicate of a link already stored.
  270.     ====================================================================== */
  271.     function hnIsDuplicateURL( url ) {
  272.         var isDuplicate = false;
  273.         
  274.         for(i=0; i < this.numItems; i++)
  275.             if (this.links[i].indexOf(url) != -1)
  276.                 isDuplicate = true;
  277.         
  278.         return isDuplicate;
  279.     } // end hnIsDuplicateURL
  280.     
  281.     
  282.     /* ======================================================================
  283.     FUNCTION:    hnGetOpenerURL (HistoryNav method: getOpenerURL)
  284.     
  285.     INPUT:        none.
  286.     
  287.     RETURNS:        the URL of the opener window, if the window is open;
  288.                     "", otherwise
  289.     
  290.     DESC:            This function compares the url parameter to all links and labels
  291.                     stored.  It returns true or false to indicate whether or not url
  292.                     is a duplicate of a link already stored.
  293.     ====================================================================== */
  294.     function hnGetOpenerURL() {
  295.         var result = "";
  296.         if (window.opener+"" != "undefined" && window.opener != null) 
  297.             result = window.opener.location.href+"";
  298.     
  299.         return result;
  300.     } // end hnGetOpenerURL
  301.     
  302.     
  303.     /* ======================================================================
  304.     FUNCTION:    hnRefreshLinks (HistoryNav method: refreshLinks)
  305.     
  306.     INPUT:        none.
  307.     
  308.     RETURNS:        none.
  309.     
  310.     DESC:            This function refreshes the links and labels arrays by
  311.                     removing the oldest (first) link and label in each array,
  312.                     then moving the other links over one position.  This method
  313.                     is used to keep the list from exceeding this.maxItems.
  314.     ====================================================================== */
  315.     function hnRefreshLinks() {
  316.     
  317.         for (var i=0; i < this.numItems; i++) {
  318.             this.links[i] = this.links[i+1];
  319.             this.labels[i] = this.labels[i+1];
  320.         }
  321.         this.numItems--;
  322.     
  323.     } // end hnRefreshLinks
  324.     
  325. /* ======================================================================
  326. FUNCTION:    HistoryListener (companion to the HistoryNav object)
  327.  
  328. INPUT:        objName (string)        : a string representing the name of the HistoryNav
  329.                                                 object on the page
  330.                 histNavObj (object)    : a HistoryNav object on the page
  331.  
  332. RETURNS:        none.
  333.  
  334. DESC:            This function starts a recursive setTimeout loop that calls histNavObj's
  335.                 "validateLocation" method to validate any change of location in the 
  336.                 opener window.  The parameter objName must be the EXACT name of the
  337.                 HistoryNav instance you created on the page (it is case-sensitive).
  338.                 The histNavObj parameter should contain the corresponding HistoryNav 
  339.                 object itself.
  340. ====================================================================== */
  341.    function HistoryListener() {
  342.     // Start the recursive timer
  343.     listenerTimer = setTimeout(this.name + ".historyListener()", 1000);
  344.     // Check locations of pages that the listener "hears"
  345.     this.validateLocation();
  346.   } // end HistoryListener
  347. } // end HistoryNav constructor
  348.  
  349.     /* ******************** END HistoryNav Object ******************** */
  350.  
  351.