WildView - Basics

ildView Basics

WildView is a Java applet that can be used to build dynamic displays on a World Wide Web page. You create these displays by entering layout instructions -- which are similar to HTML tags -- in a text file (or files). When the WildView applet starts, it reads these layout instructions from the file, and based on the instructions read, the WildView applet will load the modules that it needs in order to create your display.

The following documentation will provide you with a general description of the HTML <APPLET> tag, give you some suggestions as to where to put the WildView components on your web site, and introduce you to the WildView layout file, which is the key to creating WildView displays.

For detailed information about the WildView applet, please refer to the Applet page. For details about each of the modules included with WildView (and how to use them in a WildView layout file), please refer to the Modules page.

If you run into trouble using WildView, please review the Troubleshooting page. If the troubleshooting tips do not resolve the problem, please submit a bug report to Modern Minds. Be aware that while registered users are always given priority, we will attempt to respond to all requests for assistance from those evaluating WildView within the free 30-day trial period.

Finally, please take time to examine the examples that have been provided. The examples demonstrate some practical applications of WildView and can serve as a good starting point for your own creations.

Now, without any further ado, let's get started by reviewing how applets are added to a web page (if you are already experienced with using applets, you will probably want to skip to the next topic).

pplets

To add an applet to a HTML document, you use the <APPLET> tag to specify the applet, and the <PARAM> tag to specify parameters to be passed to the applet. The general format of the <APPLET> tag and the <PARAM> tag is:

<APPLET
   ALIGN=alignment
   VSPACE=pixels 
   HSPACE=pixels
   WIDTH=pixels
   HEIGHT=pixels
   CODE=appletFile
   CODEBASE=baseURL
   ALT=alternateText>
...

<PARAM
   NAME=name
   VALUE=value>
...

</APPLET>

The <APPLET> tag attributes are:

`ALIGN`	This optional attribute specifies the alignment of the applet. The possible values of this attribute are the same as those for the `IMG` element: `left`, `right`, `top`, `texttop`, `middle`, `absmiddle`, `baseline`, `bottom`, `absbottom`.
`VSPACE`	This optional attribute specifies the number of pixels above and below the applet. It is treated the same way as the `IMG` element's `VSPACE` attribute.
`HSPACE`	This optional attribute specifies the number of pixels on each side of the applet. It is treated the same way as the `IMG` element's `HSPACE` attribute.
`WIDTH`	This required attribute specifies the width of the applet's display area.
`HEIGHT`	This required attribute specifies the height of the applet's display area.
`CODE`	*This required attribute gives the name of the Java Applet class file (for the WildView* applet, the file is `WildViewApplet.class`).**
`CODEBASE`	This optional attribute specifies the base URL of the applet (the directory in which the applet is located). If this attribute is not specified, then it is assumed that the Java class files will be found in the same directory as the HTML file.
`ALT`	This optional attribute specifies any text that should be displayed if the browser understands the `APPLET` element but cannot run applets written in Java.

The <PARAM> tag attributes are:

`NAME`	The name of the applet-specific attribute. The documentation for the applet will provide you with valid `NAME`s.
`VALUE`	This is the value that is associated with the `NAME` attribute. The documentation for the applet will provide you with valid `VALUE`s for the `NAME` attributes.

Below is a simple <APPLET> tag for the WildView applet to give you an idea what a actual applet tag looks like:

<APPLET CODE="WildViewApplet.class" WIDTH="96" HEIGHT="96"> <PARAM NAME="maxSizeKB" VALUE="10"> <PARAM NAME="panelSet1" VALUE="WildBkgnd.TXT"> </APPLET>

The following are a few things to keep in minds when using applets:

Java is case sensitive. When specifying file names or parameters, make sure that the file names, the parameter names, and the values have the correct uppercase and lowercase characters. If the documentation says that a parameter name is maxSizeKB, then make sure you enter it as

<PARAM NAME="maxSizeKB" VALUE="10">

and NOT as

<PARAM NAME="maxsizekb" VALUE="10">

(note that all characters are lowercase), and NOT as

<PARAM NAME=maxSizeKB VALUE="10">

(note missing quotation marks).
If you are just getting started with applets, make things easy on yourself by putting all of the applet class files and any other files that the applet might need (i.e., graphic image files, etc.) in the same directory as your HTML file. This way you can leave the CODEBASE attribute out, and you do not need to worry about specifying paths to files.

Once you get the applet working the way you want it to work, then you can try moving the files around to other directories, if desired.
If an applet encounters an error (either because you entered something incorrectly, or -- heaven forbid -- because of a bug), the applet will usually log an error message. The error message log is often very handy when trying to figure out what went wrong.

If you are using Netscape Navigator, the error log can be displayed by selecting the "Show Java Console" option from the "Options" menu.

In Netscape Communicator, the error log can be accessed by selecting the "Java Console" option from the "Communicator" menu.

The Java error log for Microsoft Internet Explorer is a bit trickier to access then it is in the Netscape browsers. First you must make sure that Java logging is enabled. To do this, select the "Options..." menu option from the "View" menu, then click on the "Advanced" tab. At the bottom of the panel you should see a checkbox labeled "Enable Java Logging." If this box is not checked, then you will need to click the checkbox to select it, then restart your browser.

Once Java logging is enabled for Internet Explorer, Java error messages are logged in the file javalog.txt which should be found in the Windows directory (usually C:\WINDOWS\JAVA\javalog.txt) if you are running Internet Explorer on a Windows machine.

here the Pieces Go

In order to use WildView on your web site, you will need to copy all of the Java class files (i.e., those files that end with the extension of ".class") that are located in the documentation's "Java" directory to a web site directory (or to any directory that you want to use while you are designing your WildView display).

You do have some options as to how to organize the different WildView components within the directory.

The easiest way to use WildView is to simply place everything in a single directory. This means that your HTML, the WildView class files, and your WildView layout files (and any other files, as for instance graphic image files) will all be thrown together.

Using this (somewhat messy) approach, you do not need to worry about the CODEBASE attribute of the <APPLET> tag, nor do you need to concern yourself with specifying paths to files for applet parameters or with specifying paths to files for attributes in WildView layouts.

You might want to consider this "toss everything together" approach when you are initially designing a WildView display, or when you just want to experiment. With everything in one directory, you eliminate the possibility of errors related to the incorrect placement of files and errors due to the incorrect specification of file paths.

If you want to keep things a bit more tidy, then you can create a directory structure to organize the different components.

A very simple structure would involve creating one new directory in which all of the WildView files would be placed (i.e., the class files, your layout files, and any other files like graphics files used in your design). The only change that you would need to make in order for this arrangement to work is a change to the <APPLET> tag in the HTML file (which should not be in the new directory).

If your new directory is called "WildViewJava," then you need to add a CODEBASE attribute to the <APPLET> tag as illustrated below:

<APPLET CODEBASE="WildViewJava" CODE="WildViewApplet.class" WIDTH="200" HEIGHT="100">

With this simple directory structure, you will not need to specify paths to files. WildView will function just as if you had dumped everything into one directory.

It is also possible to create a more elaborate directory structure, if desired. The one thing to keep in mind is that all of the WildView layout files, graphic image files, etc. that you use for your WildView design must be located in the same directory as the class files, or in a directory below the directory that contains the class files.

To see an example of a more elaborate directory structure, take a look at the directory structure of the WildView Examples that are included with the package (i.e., look at the "Examples" directory and the "Java" directory).

For further information, see the in-depth Applet and Module documentation, which has detailed information regarding specifying paths for those parameters that accept file names.

ayout File Format

The layout file is what makes WildView wild. Without the instructions contained in a layout file, all that will be displayed on the web page by WildView is a rectangular area filled with a solid color or with a background image (rather dull, don't you agree?). With a good layout file, you can have some pretty wild things going on in that rectangle.

The aforementioned rectangular area on the web page in which WildView does its thing is the applet area. The size of the applet area is defined by the WIDTH and HEIGHT attributes of the <APPLET> tag. If your applet tag is

<APPLET CODE="WildViewApplet.class" WIDTH="200" HEIGHT="100">

then the applet area will have a top-left coordinate of (0, 0), a top-right coordinate of (200, 0), a bottom-left coordinate of (0, 100), and a bottom-right coordinate of (200, 100). This is illustrated below:

From now on, we'll refer to the applet area as the display area.

A WildView layout file contains instructions that control how the display area is created and how the display area behaves: these instructions are called tags.

WildView tags are very similar in format to HTML tags. The primary difference is that WildView tags will only work within layout files used with the WildView applet. Other differences are:

HTML uses the characters "<" and ">" as tag delimiters. WildView defaults to using these two characters also, but they can easily be changed to any other character that is not otherwise being used in the layout file.
A WildView tag name must always be capitalized. This is different than HTML where case does not matter for tag names. Note that WildView tag attributes are not required to be in uppercase.
Currently, there are no WildView tags that require an ending tag. For instance, in HTML when you use the <APPLET> tag, you must also supply a </APPLET> tag to define the end of the tag. None of the WildView tags have this requirement.

Like HTML, each tag can have attributes. An attribute has a format of name=value. For instance, to create a table in HTML, you might use a tag like:

<TABLE BORDER="0">In this HTML example, the attribute name is BORDER, and the attribute value is "0".

WildView attributes work the same way as the HTML attributes with the attribute name on the left side of the "=" sign and the attribute value on the right side.

Quotation marks can be used around the attribute value if the value contains a space character, or if you want to preserve the case of the attribute value (without quotation marks, attribute values are converted to lowercase). For most attribute values, you will not need to use quotation marks.

Of the WildView tags, the most important is the <PANEL> tag. The <PANEL> tag defines a portion of the display area in which a module will operate, and it also defines how the module will function.

A module is a Java class that performs a particular function in a panel. For example, the module WVPanelVScroll (which corresponds to the Java class WVPanelVScroll.class) creates vertically scrolling text in the panel area.

In WildView, a layout file is frequently referred to in the documentation as a panel set because it is comprised of a set of <PANEL> tags.

We'll next take a look at the <PANEL> tag and its basic attributes, then we'll examine a functional example of a simple <PANEL> tag.

A <PANEL> tag has the following format:

<PANEL name=panelName module=moduleName x=pixels y=pixels w=pixels h=pixels mouseX=pixels mouseY=pixels mouseW=pixels mouseH=pixels clock=milliSeconds>

As you can see, the basic <PANEL> tag has a number of attributes. Note that different modules will have different attribute requirements, but the attributes shown above can be specified for all modules.

The basic <PANEL> tag attributes are:

name	This is the name of the panel. The panel name can be referenced by tags within other panels to refer to this panel.
module	This attribute names the module that is to be used for this panel. The module name is simply the name of a Java class without the "`.class`" extension. For instance, if vertically scrolling text is to appear in this panel, then the module attribute would be `module="WVPanelVScroll"` (notice that quotation marks must be used because the module name must match the Java class name exactly).
x	This is the left coordinate of the panel within the display area.
y	This is the top coordinate of the panel within the display area.
w	This is the width of the panel within the display area.
h	This is the height of the panel within the display area.
mouseX mouseY mouseW mouseH	The area in which the panel recognizes mouse events does not need to correspond to the panel's display area. These four attributes, like the `x`, `y`, `w`, and `h` attributes described above, define the mouse area for the panel. If these attributes are omitted, then the mouse area defaults to the same area as the display area. The use of these attributes is discussed in the documentation of the individual modules.
clock	This attribute is usually used to control animation speed for the panel. Typically, the attribute value is the number of milliseconds to delay between each frame of animation. A lower value will result in faster animation while a higher value will result in slower animation. If a clock rate is not specified for at least one WildView panel, then a warning message will be added to the Java log, and the clock rate will default to 100 milliseconds (which is equivalent to 10 frames per second).

To illustrate the use of a <PANEL> tag, we will examine a simple application of the WildView applet to create a display that scrolls text vertically. Don't be too concerned if you don't understand all of the parameters; they are all covered in detail in the Applet and Modules portions of the documentation.

For our example, we'll want to create a display area with a width of 200 pixels and a height of 100 pixels. This is done using the following applet tag:

<APPLET CODE="WildViewApplet.class" WIDTH="200" HEIGHT="100"> <PARAM NAME="panelSet1" VALUE="DocPanelSets/VScrollDemo.TXT"> </APPLET>

Now we need to decide where the panel that contains the vertically scrolling text should be located in the display area. Let's arrange to have a margin of 10 pixels above and below the panel, and a margin of 25 pixels to the left and right of the panel. We want the layout to be as illustrated below:

To achieve the desired layout, we create a text layout file (or panel set file) called "VScrollDemo.TXT" and enter a <PANEL> tag as follows:

<PANEL name=TextDemo module="WVPanelVScroll" x=25 y=10 w=150 h=80 clock=50 fontSize=14 fontColor=7D3B9D fontStyle=bold> This is a demonstration of a simple panel that scrolls text vertically from bottom to top. Notice that we have specified a margin of 10 pixels on the top and bottom of the display area, and a margin of 25 pixels on the left and right sides of the display area.

Notice that the text that will be vertically scrolled follows the <PANEL> tag. This is the general method for specifying text (or other sub-tags) for a panel.

Our functioning panel running in the WildView applet is displayed below:

As you can see, WildView makes it quite easy to create a simple animated display. The real power ofWildView, you will find, is when you create layout files (also called panel sets) that contain multiple panels. With panel sets, each panel in the set can function independently, or a panel can communicate with other panels through a feature called "triggers."

You are now ready to proceed to the next section of the documentation, titled "Panel Sets and Triggers," and learn about some of the more advanced features of WildView.