xref [con't]
|
xref: Parameter Reference
Various parameters are available to help you control how xref performs its duties. Some of these pertain only to the dyanamic version of xref; while others can be applied to both versions. With those parameters that apply to the static version of the script, remember that the parameter applies only to the intial building of the script--once the script is generated, it will always use those parameters! The dynamic version of the script, however, can use any of these parameters uniquely for each page included within. To use these parameters with the dynamic version of the script, you simply include them within the JavaScript call that you make to the script in the first place. For example, to specify a class name to be applied to the links generated by the script, you would do this:
<script type="text/javascript"
src="/cgi-bin/xref.js?link_class=myLinkClass">
</script>And to specify both a link class and a class name to ignore (used to force xref to ignore sections of your page--i.e., not apply links there even if your targeted terms occur) you would do this:
<script type="text/javascript"
src="/cgi-bin/xref.js?link_class=myLinkClass&ignore_class=myIgnoreClass">
</script>Just be sure to place a question mark (?) between the script name and the first parameter,
and an ampersand (&) between any additional parameters. (Note: For brevity, I omitted
the domain name in the script calls above. On your own site I recommend including the
domain name; and the domain name will be required for your affiliates, anyway. i.e.,
src="http://example.com/cgi-bin...", etc.)
- prefix (Static, Dynamic; default WR_)
- The xref script will create a single global JavaScript object on each
page where it's included. The name of this object will be the contents of the
prefix, plus the term xref. Since the default prefix
is WR_, the default object name is therefore WR_xref.
You can avoid namespace conflicts with your existing JavaScripts by altering this prefix; for example, if, by chance, you already have an object named WR_xref on your pages, you can change the name by supplying a different prefix. - link_class (Static, Dynamic; no default)
- This will be the class name applied to any in-page link created by
xref (i.e., the links that will appear beneath your terms). You can use
this class name to apply special styles to the xref links.
There's no default; if the link_class is not supplied, then no class name will be applied to the xref links. - link_target (Static, Dynamic; no default)
- This will be the target attribute that is applied to any links created by
xref. You can use link_target to control the destination
of the links (another window, another frame, a new blank window, etc.).
There's no default link_target; if this field is blank then no target will be applied to the xref links. - ignore_class (Static, Dynamic; default ignoreXref)
- This is a class name that will be ignored by xref; i.e., all
text within a tag to which the ignore_class is applied will be
ignored by the xref scanner, including all sub-elements (children,
grandchildren, etc.) of that tag.
Use this tag to automatically avoid sections of your pages where you do not want automatic links applied; such as page headers and footers, inserted ads, etc. For example, with this xref call:
and this HTML:<script type="text/javascript" src="http://example.com/cgi-bin/xref.js?ignore_class=noLinks"> </script>
the text within the div (Here is some example text.) won't be automatically linked, even if it does contain matching terms.<div class="noLinks">Here is some example text.</div> - allow_class (Static, Dynamic; no default)
- The opposite of ignore_class, the allow_class is a
class name that you will apply to all HTML elements in a page that you do want
xref to scan for potential links. When you specify an allow_class,
then only those HTML elements that are marked with that class will be examined; all other
HTML elements will automatically be ignored.
There is no default for this control. If it is left blank, then all HTML elements in a page will be searched.
Note that if you specify both an allow_class and an ignore_class, and a paticular term on your page matches both (for example, it's in a paragraph with an ignore_class that itself is in adivwith an allow_class), then the term will be ignored. Or, in other words, ignore_class has a higher scanning precedence than allow_class. - expire_hour (Dynamic only; default 15)
- The dynamic version of xref will automatically provide an
Expiresheader with the scripts it returns to the browser; telling the browser that the script is good until the provided hour of the day. Since the script delivered to the browser could be fairly large (depending on how many terms you need to scan for) adding this header prevents the browser from having to re-download the script with every page of your site (or your affiliate's sites) that they hit in succession. The expire_hour is the hour that theExpiresheader will be set to, in military time (i.e., 4:00pm would be 16).
The theory with expire_hour is that you would update your terms list once a day, at a set time of day. Therefore, the script provided by xref would always be good until that time, and the end user's browser needn't redownload it until then. In general, this parameter should not be changed on a page by page basis; its existence allows you to change the expiration time without having to actually modify the distributed version of the script. If the current time is already later than the expire_hour, then theExpiresheader provided by xref will automatically be set to the expire_hour of the next day. - scan_now (Dynamic, Static; default is 0)
- By default, xref won't start searching the page it's on
until that page is fully loaded. This gives you the flexibility of loading the script
anywhere in the page you wish, while still ensuring that the script will find all
the possible text available on the page.
For a quicker response, you might choose to have the script immediately begin scanning the text of the page as soon as it (the script) is loaded. To do so, set the scan_now flag to1, orY.
Note that if scan_now is active, then you must include xref on the page at some point after the text you actually want xref to scan. Otherwise, xref will not "see" the text and will therefore not apply any links to it! - link_all (Dynamic, Static; default is 0)
- By default, xref will only apply a link to the first
of each matched term on a page; i.e., if a particular key term appears several
times on a page, xref will only apply a link to the first one
it sees.
If the link_all flag is set (to1orY), xref will apply links to all of the matching terms on the page (subject to ignore_class and allow_class, of course). - debug (Dynamic only; default is 0)
- Use this directive to receive JavaScript alert messages from xref
when something is wrong; specifically, if the script cannot find or load its necessary
template files. Typically you would use this flag only for initial troubleshooting,
not in general.
- no_case (Dynamic, Static; default is 0)
- By default, xref will apply case-sensitive matching
to the terms scanned on the page; for example, if your key term is Apple,
then xref will only match the term Apple, and not
apple (or aPPLE).
If the no_case flag is set to1orY, however, then xref will match terms regardless of the case of the letters in the term (all three versions of Apple in the preceeding sentence would match).
Use no_case if your terms are unique enough that you don't fear a mis-linked term (for example, your site discusses only Apple the fruit, and not Apple, Inc., the computer and gadget company). - max_match (Dynamic, Static; default is 20)
- The maximum number of terms that will be matched on a single page (but not the maximum
instances of those terms that will be matched; see link_all for
that).
To force xref to create links for all of the terms found on the page, set max_match to 0.
Note that max_match must be an integer; only numeric characters are allowed.
For the developmentally minded among you, on the next page we examine how xref performs its duties; including discussion of a now common trick that allows us to adjust the DOM content of pages on external domains.
