 |
| Help Index |
The Visual Applet Configurator, from version 1.1 and up, supports
other developers' applets. We at Demicron want to share this program with
other applet developers so that they too can offer their users a user friendly
environment when they configure the applets. To incorporate these applets,
developers must define a plugin definition file (an esupXXX.dat file) and
a VAC script file (.vcs) for each applet.
Folder Structure:The folder structure for a plugin can be complex. Images must be located directly in the plugin folder and not in the VAC installation folder. Applets must be placed in a folder with the same name as the applet main class file (excluding the ".class" part). In there you must place the necessary ".class" files, images and ulaw sound files (".au" files). Apart from the vcs-file, which must be included here, a HTML file including default parameter values for the applet must also be included. These two files must be named exactly as the applet main class file. To add help, a file named "help.html" must also be included into this folder. This file will be executed in a browser when the user clicks on the "help" buttons in VAC. A folder named help must be included under the plugin path and in this folder a file named "help.html" will be the help file executed from the "plugin help..." option in the VAC Help menu. A file named "info.txt" must be included under the plug-in folder. The information in this text file will be read by the plug-in's about dialog. Here is an example of a folder structure (a part of Applet FX Freeware Edition):
Plugin definition file :A plug-in definition file is written in ASCII and must always begin with "esup". The extension must always be ".dat". The parameters in the plug-in definition file are delimited by commas and newline characters, it is as following: pluginname,plugin image name,plugin VAC subpath number of applet categories category path in tree and 1:st category name,JPEG icon image for 1:st category ... category path in three and last category name,JPEG icon image for the last category name of first applet,category path in tree for this applet,JPEG icon image for this applet ... name of last applet,category path in tree for this applet,JPEG icon image for this applet
Example : Applet FX Freeware
Edition,freeware.jpg,freeware The applets and categories in the file above are taken from Applet FX Freeware Edition. In the first row; the first string is the name of the plugin, the second string is the image that will be used for the about dialog (if "none.jpg" is specified then the plug-in will not be listed in the "about plugin..." option) and the last string is the subfolder of the Visual Applet Configurator installation folder, where the plug-in files will be. Note that the plug-in folder must be in this location and nowhere else. Next we define the catalogs of the tree, which in this case will be four. First we define a catalog named "Applet FX" which will have the image "imdemicr.jpg" as icon, under this catalog (by specifying exactly the same name of the parent catalog) we define the subcatalogs "messages", "menus" and "titles" with their corresponding icon images. The applets are "inserted" into the tree after the categories. In a row, the first string is the name of the classname. After that follows the category tree "path" where the applet will be inserted and lastly the icon images follows for that specific applet.
The HTML file:In the HTML file, you will specify the default values that the applet will have. The file must include ONE applet HTML configuration, that will be copied into the user's HTML code by the VAC whenever the user inserts that applet.
VAC script commands and the VCS format:The VCS file defines the applet's configuration dialog. Important things to know about VCS files is that a row is a command and its parameters (it cannot be extended to several rows) are case sensitive. So if something is wrong you can start by checking the case sensitivity. This is especially true for the "section" parameter of a VCS-command, that must have the exact name as the named section. The field tag, which is also used by most commands, is the tag above the field. The mouse-over-info parameter is the text that will appear when the user moves the mouse over that field.
The "sections" command: {sections, sectionname1;sectionname2;sectionname3;sectionname4} With the section VCS-command you can define the sections or pages that will be in the applets configuration dialog. The first section in the configuration dialog is always "general" and this is built into each configuration dialog so you don't have to specify it. The section names following the section command must be delimited by ";". Example : {section,Text;Color;URL} This will define a configuration dialog with the pages "General", "Text", "Color" and "URL"
The "dependencies" command : {dependencies,file1;file2;file3;...;fileN} Some applets may be dependent of files like other class files, images and sounds. In order for the VAC to know what files that should be inserted into the project folder together with the applet class file, you must specify which they are. The system supports the star (*) option in the name part of the file (however not in the extension). Example : Suppose that you have an applet which uses a filter "filter.class", 3 images (image1.jpg, image2.jpg and image3.jpg) and a sound file beep.au. Then you should have the following specification: {dependencies,filter.class;image*.jpg;beep.au} VAC will now, whenever the user inserts an applet into the HTML file (or in file operations like saveAs and SaveToInternet), see to it that the files filter.class, image1.jpg, image2.jpg, image3.jpg and beep.au are copied to where the HTML file is.
The "constant" command : {constant, parametername, parametervalue, 0} The constant command will simply write out a constant value into the HTML code. The last parameter must always be 0 for non-demicron applets. Example : {constant,pi,3.14159265,0} will give the HTML code <PARAM name="pi" value="3.14159265">
The "color" command : {color,parametername,section,field tag,on mouse over information} The color command inserts a color button into a configuration dialog. Example : {color,foreground,Color,Text color,The text color.} will add a color button with the parameter name "foreground" into the section "Color". The field will be named "Text Color" and when the user moves the mouse over the field then the info text "The text color." will appear. The following HTML code will be generated (FFFF00=yellow): <PARAM name="foreground" value="FFFF00">
The "text" command : {text,parametername,section,field tag,on mouse over information} The text command inserts a text field into a configuration dialog. The field will output the text that the user writes as a parameter Example : {text,titletext,Text,Enter title text,The title text.} will add a text field. The following HTML code will be generated if the user writes "Demicron": <PARAM name="titletext" value="Demicron">
The "integer" command : {integer,parametername,section,field tag,on mouse over information} The integer command inserts a text field into a configuration dialog. At the moment, this command gives the same result as the text command.
The "double" command : {double,parametername,section,field tag,on mouse over information} The double command inserts a text field into a configuration dialog. At the moment, this command gives the same result as the text command.
The "file" command : {file,parametername,section,field tag,on mouse over information} With the file command you can insert a file field. However, there will be no check to see if there is a valid filename on this field. Example : {file,backgroundimage,Images,Specify background,The background image.} will give the following code if the user selects or enters "back.jpg": <PARAM name="backgroundimage" value="back.jpg">
The "condition" command : {condition,parametername,section,field tag,on mouse over information} The condition command will insert a checkbox. The checkbox will output the value "Yes" or "No" depending on if it is checked or not. Example : {condition,useitalic,Text,Use Italic font?,Check the box if you want to have italic fontstyle.} will give the following code if the user checks the box: <PARAM name="useitalic" value="Yes">
The "font" command : {font,parametername,section,field tag,on mouse over information} The font command will insert a Font selection field. This field will output a fontname from either the general supported fonts in Java 1.02 or a fontname written by the user. Example : {font,fonttype,Text,Font,The font type.} will give the following code if the user selects "TimesRoman": <PARAM name="fonttype" value="TimesRoman">
The "selection" command : {selection,parametername,section,field tag,on mouse over information,item1;item2;...;itemN,type} With this command you can let the user make a selection. There are three types of these fields. The first type (type = 0) will let the user select an item from a list and the result will be generated as a zerobased index. If the user writes another string into the field it will be ignored and the index 0 will be outputted instead. The second type (type = 1) will output a selected item as a text or the string that the user has entered. The third type (type = 2) is used for communication between applets. The names from the name tag in the applet head will appear here for all applets (except the one you are configuring) within the same HTML file. The user may also enter any type of string. This field will output the result as a string. Example 1: {selection,fruit,Other,Fruit,Choose a fruit,apple;banana;orange;kiwi,0} will give the following code if the user selects "apple": <PARAM name="fruit" value="0">
Example 2: {selection,fruit,Other,Fruit,Choose a fruit,apple;banana;orange;kiwi,1} will give the following code if the user selects "apple": <PARAM name="fruit" value="apple">
Example 3: {selection,sendMessageTo,Communication,Connect to,Select the applet you want to send the message to,-,2} We assume that there is an applet with the name tag "button1" so we will get the following code if the user selects "button1": <PARAM name="sendMessageTo" value="button1">
The "demicronian" command : {demicronian,iscommercial,null} The demicronian command is used only by the Demicron Company's applets and which identifies them as such.
The "texts" command : {texts,parametername,section,field tag,on mouse over information,group,isleader} A command that you will surely use in your configuration dialogs is the texts command which inserts a multiline text field. The multiline text field will output zero based numbered parameter names together with a value that will be one row in the field. The "group" parameter above specifies which list group this textfield belongs to. This value must be between 1-19. In a list group you can have several color lists, file lists and multiline text fields mixed together. The maximum number of parameters outputted by each field of a list group is always determined by the group leader which will be the field that has the last parameter "isleader" set to 1. If you have only one field in a group, then this field must always have this parameter set. Example 1: Lets say that you want to have a text field where the user can enter the menu items. {texts,menuitem,Text,Enter items,Enter the menu items,1,1} will output the following type of code: <PARAM name="menuitem0" value="main"> <PARAM name="menuitem1" value="services"> <PARAM name="menuitem2" value="contact us"> <PARAM name="menuitem3" value="about our company"> Example 2: Let's say that you want to have a text field where the user can enter the menu items AND background images for each item. In this case you want the number of parameters from the file list field to be the same number as the text field. You also need another text field where the user will enter a number of texts that will be shown in the applet and which are independent of the number of items in the menu: {texts,menuitem,Text,Enter items,Enter the menu items,1,1} {files,menuimage,Images,Specify images,Specify the background images for each menu item,1} {texts,message,Text,Enter messages,Enter the messages that will appear randomly in the applet,2,1} this will output the following type of code: <PARAM name="menuitem0" value="main"> <PARAM name="menuitem1" value="services"> <PARAM name="menuitem2" value="contact us"> <PARAM name="menuitem3" value="about our company"> <PARAM name="menuimage0" value="main.jpg"> <PARAM name="menuimage1" value="services.jpg"> <PARAM name="menuimage2" value=""> <PARAM name="menuimage3" value=""> <PARAM name="message0" value="We can offer you applets!"> <PARAM name="message1" value="A lot of them!"> <PARAM name="message2" value="Thanks to Demicron and VAC..."> The user here entered 4 menu items, 2 images and 3 messages.
The "colors" command : {colors,parametername,section,field tag,on mouse over information,group,isleader} The colors command will insert a color list where the user may create or edit a long list of colors. The group function is the same as for the "texts" command. Example: {colors,thecolor,Color,Specify colors,Specify the colors that will be used in the applet.,1,1} will output the following type of code if, for example, the user selects black, red, cyan and green: <PARAM name="thecolor0" value="000000"> <PARAM name="thecolor1" value="FF0000"> <PARAM name="thecolor2" value="00FFFF"> <PARAM name="thecolor3" value="00FF00">
The "files" command : {colors,parametername,section,field tag,on mouse over information,group,isleader} The file list is used if you want the user to specify a list of files. With the browse button on each row the user will be able to search for the file to be specified and then this file will be copied into the project folder. The group function is the same as for the "texts" command. Example: {file,image,Images,Specify images,Specify the images that will be used in the applet.,1,1} will output the following type of code: <PARAM name="image0" value="water.jpg"> <PARAM name="image1" value="rain.jpg"> <PARAM name="image2" value="desert.jpg"> <PARAM name="image3" value="sahara.jpg"> <PARAM name="image4" value="winter.jpg"> <PARAM name="image5" value="ocean.gif">
The "maxitems" command : {maxitems,parametername,,,} The maxitems command will output a number telling how many parameters the leader of a group list field have outputted (see the texts command). If there are several leaders then the one with the largest number of parameters will be valid. Example 1: {maxitems,numberofmenuitems,,,} will output the following type of code if there is a leader list field that has 10 rows: <PARAM name="numberofmenuitems" value="10"> Example 2: In example 2 in the description of the "texts" command, there the code outputted would look like the following: <PARAM name="numberofmenuitems" value="4">
The "book" command : {book,parametername,section,field tag,on mouse over information,type} The textbook can be used when you want the user to enter several pages of text. The user will be able to browse back and forth through the pages by pressing a forward and back button. There are two types of code output; the first type (type = 0) will give the parameter name followed by the page number comma the row and the second type (type = 1) will output each page on a zero based numbered parameter and with the rows delimited by a "|". If a page has less rows than another page, it will not be extended. Example 1: {book,item,Text,Enter pages,Enter the pages that will be displayed in the applet.,0} will output the following type of code: <PARAM name="item0,0" value="Page One:"> <PARAM name="item0,1" value="Demicron's"> <PARAM name="item0,2" value="Visual Applet Configurator"> <PARAM name="item1,0" value="Page Two:"> <PARAM name="item1,1" value="Get it now!"> Example 2: The same configuration but a different type. {book,item,Text,Enter pages,Enter the pages that will be displayed in the applet.,1} will output the following code if the user enters the same information into the text book: <PARAM name="item0" value="Page One:|Demicron's|Visual Applet Configurator"> <PARAM name="item1" value="Page Two:|Get it now!">
The "grid" command : {grid,parametername,section,field tag,on mouse over information} A text grid will give your users the option to enter spreadsheet data. VAC will take all non-empty fields and output them with two parameters for each field in two zero based lists. The first parameter is the text value for the field with the parametername extended with the word "text". The second parameter is the position (zero based x and y coordinates delimited by a comma) for the field with the parametername extended with the word "pos". Example: {grid,item,Text,Enter data,Enter the data.} will output the following type of code: <PARAM name="itemtext0" value="Expenses:"> <PARAM name="itempos0" value="0,0"> <PARAM name="itemtext1" value="$6000"> <PARAM name="itempos1" value="0,1"> <PARAM name="itemtext2" value="$8000"> <PARAM name="itempos2" value="0,2"> <PARAM name="itemtext3" value="$3000"> <PARAM name="itempos3" value="0,3"> if the user has entered a column with expenses.
The "tree" command: {tree,parametername,section,field tag,on mouse over information,separator,base} A tree field gives the user the option to customize
applets that need tree structured parameters in a user friendly way. The
parametername is actually never used in the HTML code, but it is used
to connect several tree subtype fields to the tree. The separator is the
separator character that is used in the applet HTML parameters when separating
each level. The base is the base number for a tree level. Tree fields
support five types of fields: selection fields, file
fields, color buttons, text
fields and check boxes. Example : As an example, we take the rowsubmenu configuration, which is shown as an example in the Working with Tree fields dialog: {tree,item,Items,TreeItems,The tree items.,-,0} <PARAM
name="menuitem-0" value="Cars"> |