| Anatomy
of a Web Crossing URL
Scriptname
Default Action
Command Codes
Certificates
Parameters
Replacing These Elements
with WCTL
Passing Variables in URLs
Static-syntax URLs
Troubleshooting
Resources
A full
Web Crossing URL has the following parts, which are explained
in more detail below:
http://your_site/<SCRIPTNAME>[?<COMMAND>[L]@<CERTIFICATE>@<PARAMETERS>]
Portions
of the URL in brackets [ ] are optional.
As an
example, a typical Web Crossing URL might look like:
http://www.webxharbor.com/cgi-bin/webx.cgi?13@123.3ERaaB6EayJ^1@.ee6cd0c
This
URL would display the discussion or folder on the WebX Harbor
site which has the unique
ID number
".ee6cd0c".
Scriptname
The
scriptname is everything after the domain
name, and before
the question mark. The scriptname might or might not include a
cgi-bin directory. Common scriptnames are
webx.cgi, WebX,
webx or webx.dll. It might be
something else entirely.
Depending on your server, the scriptname might be
case-sensitive.
The appearance of the scriptname in a URL means that the page
being served is:
- authenticated
(can make use of authenticateFilter, if present)
and
- the
page runs through the WebX parsing engine,
so
you can make use of WCTL commands in those pages,
even "static"
pages which reside in your html directory.
Default
Action
If
Web Crossing is accessed by domain only (e.g. http://webx.webxharbor.com)
or with a URL containing just the scriptname (e.g.
http://webx.webxharbor.com/cgi-bin/webx)
there is a default action to tell the server
what to display.
You can find this setting in Control Panel >
Customizing > Banner,
Footer, Background and Top-Level Page Appearance in
the section
"Default Command". Unless you want to change the
built-in default
there is no need modify this field.
Command
Codes
The
command code is either a number which tells Web Crossing what
to do, (See Command Codes) or
the name of a macro you have created which you want
Web Crossing
to run.
If the
command code is followed by an L, it directs Web
Crossing to ask
the user to log in before performing the command
specified.
Some
login and registration command codes will automatically login
or register the user and then perform the command.
Thus they take
an actionPath as a parameter. The actionPath is a
second command
code, another at (@) sign, and the parameters for
that command.
For example, the action path to display a particular
folder might
be 14@/Books, or 14@.ee6b9d8.
A full
URL with command code and action path, but no
certificate, might
look like:
http://www.webxharbor.com/cgi-bin/webx.cgi?15@@14@.ee6b9d8
(If
you're curious, the command code
15 shows a login form, and when the user clicks the
login button,
they're logged in and served [command code 14] the
folder or discussion
with the uniqueID of
.ee6b9d8.
)
Certificates
(optional)
Certificates
are used to
- identify
the current user
-
provide an optional tag you can use to configure
the user interface
(for example, showing or hiding certain folders or
discussions,
providing a different language, etc.)
- force
a user's browser to fetch fresh information instead of using
old cached material by including a unique sequence
number
When
you see URLs in your browser location bars, view the
Web Crossing-generated
page source, or when you copy a URL from somewhere within Web
Crossing, your current certificate will be filled in
between the
two @ signs. It's a randomish-looking string of
alphanumeric characters.
(See the sysop
documentation for a further explanation of what
the different
parts of the certificate are.)
However,
when you construct URLs of your own, or make links within Web
Crossing, you need to remove your current
certificate information
from the URL you copied, and either leave it blank or replace
it with the WCTL code %% certificate %%,
which tells Web
Crossing to insert the user's current certificate
value into the
URL. Certificate values expire after 30 minutes, but
if you leave
the old certificate information in the URL, there is
some danger
that someone will access the link containing the old
certificate
information, and be identified by Web Crossing as
the other user
for whom the certificate information was valid. (See
Replacing
These Elements with WCTL, below, and the WCTL
section.)
When
you're constructing your own Web Crossing URLs to
create crosslinks
within your conference or navigation areas, it's
sometimes hard
to know when to include the %% certificate %% code and
when to leave it out. It's a good idea to include it when you
can, because it helps Web Crossing track which user is which,
and helps prevent users with rotating proxy servers from being
asked to log in again. It's especially important if you're not
using cookies for user authentication, because Web Crossing's
primary method for authentication then becomes the
user certificate.
(See Authentication.)
Generally
speaking you should include the %% certificate %% code
if your link satisfies one or both of these
qualifications:
- your
link is served by Web Crossing from a Web Crossing
template, an html page, or control panel entry
- your
link is included in a discussion or folder
header, assuming
you are posting as a host or as a sysop, and you have the
WCTL interpretation checkbox turned on in the
Control
Panel > General Settings > Treat all sysop and host
headings as WCTL templates
If
it's in a page served by the regular web server or in a plain
message, don't include the %% certificate %% code when you
construct the URL or you'll get an error message
when you click
on the link.
A typical
link with the WCTL code in place might look like:
http://www.webxharbor.com/cgi-bin/webx.cgi?13@%%
certificate %%@.ee6cd0c
Note
that you can put spaces within the %% WCTL
tags, but not
between the @ sign and the first % sign.
With
the certificate information removed entirely, this
same URL would
look like:
http://www.webxharbor.com/cgi-bin/webx.cgi?13@@.ee6cd0c
More
information about the optional tag usage can be
found in the sysop
documentation.
Parameters
(optional)
The
parameter is usually a location, either a
hexadecimal unique
ID number or a full path,
but may also be an actionPath (see Command Codes,
just above).
An example
of a uniqueID would look something like: .ee6b9d8. A full path
is simply the path to a folder (not a
discussion or a message)
from the root of the forum, in URL-coded format. In
other words,
spaces and other browser-unfriendly characters are replaced by
escape codes. The escape code for a space is
"%20" so
an URL containing the word San Francisco would
actually need to
be written San%20Francisco.
Following
a uniqueID number, you can use a slash to indicate a
message number
in a specific discussion. (Just to confuse the
issue, computers
start counting with 0, so message #1 is actually
displayed using
/0, message #2 is displayed using /1, and so on.)
Example:
.ee6b9d8/346 would display message #347 of that
discussion.
Replacing
These Elements with WCTL
When
writing a WCTL template within a macro, a control panel entry,
or a discussion or folder heading set to be
interpreted as WCTL,
it's possible to replace nearly the entire URL with
WCTL variables:
a href=
"%% urlBase %%myFormProcess@%%
certificate %%@%%location%%"
UrlBase
corresponds to the domain and the scriptname -
everything up to
and including the ?
MyFormProcess
in this case refers to a custom macro. This could be replaced
with a Command Code
number.
Certificates
are discussed above.
Location
corresponds to the unique
ID of the
folder or discussion.
For
more information on WCTL and WCJS, see the Server-side
Scripting section.
Passing
Variables in URLs
It's
possible to pass form variables in a Web Crossing URL.
The
syntax is to add an exclamation point
followed by the name=value
pairs:
.... ?<COMMAND>@<CERTIFICATE>@<LOCATION>!name=value&name=value
For
example:
http://www.webxharbor.com/webx?myMacro@@.ee6b9d8!color=red&language=english
These
extra parameters must be in a URL-encoded format. For example,
San Francisco would have to be URL-encoded to
San%20Francisco.
These
variables are accessed by the receiving page by the
formula "form.name"
- so in our example you could retrieve
form.color or form.language
in WCTL on the next page and they would have the
values sent via
the URL.
See
the sysop
docs and the section on forms
and WCTL for more detail.
Static-syntax
URLs
If your
Web Crossing server is running in Direct
Web Service mode, there are some shortcuts you
can take when
you create links to Web Crossing material.
http://your_site/<SCRIPTNAME>/<LOCATION>
or
http://your_site/<SCRIPTNAME>?<LOCATION>
Location
can be either a unique ID number
(i.e. .ee6b280) or a full
path. You
can also substitute a ? (question mark) for the /
(forward slash)
and it will all work the same.
So,
for example, this URL would get you to
"Resources You Need"
folder inside the "Web Crossing Developer
Center" folder
at the dev.webxharbor.com site:
http://dev.webxharbor.com/webx/Web%20Crossing%20Developer%20Center/Resources%20you%20Need
This
same strategy can be used to call custom macros:
http://your_site/<SCRIPTNAME>/myCustomMacro
or
http://your_site/<SCRIPTNAME>?myCustomMacro
Troubleshooting
If your
link doesn't work:
- Double-check
the construction. Is the path to Web Crossing correct? Have
you included (or not included) the %% certificate %% tag as
appropriate? Is the location correct?
Resources
Web
Crossing FAQ:
Sysop
Documentation
Sysop
Control Panel
- Site
management
- Customizing
- Banner,
Footer, Background and Top-Level Page Appearance
|
