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.
The following entries are useful only in the static version of the script; i.e., these are input fields and terms used in the static script generation form.
- Script Controls
- In the Script Controls section of the form, you'll fill in
those parameters that control the actual behavior of the script when it is
installed on your site.
Each of the Script Control fields accepts only letters (upper or lower case), numbers, or the underscore (_) character. - Term Entry
- You can use this section to key in your terms one at a time. After you enter
each term, click the Add Term To List button to include the term
in the term list below.
Only printable characters are allowed in the titles, URLs, and descriptions; i.e., no tabs, line feeds, etc. Also, any angle brackets (<>) included in your term entries will automatically be converted to entities (< & >). - Term Title
- The Term Title is the actual term that will be matched.
Note that xref does not automatically find plural versions of terms;
if you want to match both the singular and plural version of a term, you'll need to
specify both as separate terms in your list.
By default, xref term matching is case-sensitive; it will only match terms if they appear in the page with exactly the same case as defined here. You can override that behavior by setting the No Case flag. - Term URL
- The Term URL is the URL that your defined term will link to.
Note that this link will not be directly verified by this script; so that you can
enter local or absolute URLs to whatever resources you require. So enter it carefully!
- Term Description
- This optional field should be a brief description of the term (one or two brief sentences,
at most). If it is entered, it will be included as the title for any
link created for this term.
If it's left blank, the link title will be left blank when links are created. - Term List
- This is the full list of terms that your script will search for in Web pages. You can
enter terms in this list one at a time using the fields in the Term Entry
section, or you can enter them en-masse by pasting them into this text box. Or you can do
some combination of both.
If you enter terms directly in this text box, then you must follow a few rules:- The term, URL, and description should all appear on a single line, with a tab between each field.
- The tab character itself is not allowed within the term, URL, or description fields (nor are any other non-printable characters).
- Each term definition (term, URL, description) should appear on its own line.
- Any literal angle brackets included in the terms will automatically be converted to entities (< & >).
- Results
- This will hold the resulting xref script after you click the
Generate button. Just copy and paste this script into a file on your site,
and you're ready to include it in your and your affiliate's Web pages!
