Creating your own asset types

If you add an asset type, you must create a folder in the Asset Templates folder, having the same name as the asset type, and containing as a minimum a default fxindex.htm and fxitems.xml file. This folder can also contain any graphic files that may be useful in the presentation of the asset type's display pages in the Asset tab: for example, a banner graphic referenced from fxindex.htm, or icon graphics commonly used to represent asset files (particularly non-graphical assets such as code fragments).

When a user creates a new asset folder and chooses the asset type for that folder, the files in the template folder are copied to the new asset folder.

When a user drags a file into the Assets tab, the Asset Manager reads the template in the fxitems.xml (or fxmaster.xml) file to determine what kind of information to prompt the user for, and to put in the Item element corresponding to the asset.

When a user drags a file from the Assets tab into a document, the Asset Manager runs the script in the fxitems.xml (or fxmaster.xml) file, which does the work of inserting the asset into the image.

When a user opens any folder in the Asset tab, the fxindex.htm file is opened in the lower pane, usually to display a representation of the assets in that folder.

As you are developing and testing fxitems.xml and fxindex.htm files, you can reload your most recent versions from the currently displayed asset folder by right-clicking and choosing Refresh from the pop-up menu. To load files from one of the Asset Templates folders, you have to create a new asset folder.

Sample fxindex.htm and fxitems.xml files are found in the Samples\Asset Templates folder.

The fxindex.htm file

Every folder in the assets tree contains an fxindex.htm file. When a user opens that folder in the Asset tab, the fxindex.htm file is displayed in the lower pane. If the folder contains assets (that is, it contains an fxitems.xml file with one or more entries), then the content of fxindex.htm is dynamic: the file will contain scripts that read the entries in fxitems.xml and display them in a useful way, so that the user can easily identify the assets and drag them into a document.

Note: The fxindex.htm file is processed by a browser component, not by HoTMetaL PRO; therefore HoTMetaL PRO's scripting interfaces cannot be used in that file. You can use standard JScript and VBScript code.

There is a sample fxindex.htm file in the folder. Instead of explaining the code in detail, we suggest that you study the Samples\Asset Templates\fxindex.htmsample file, which is is annotated with comments that explain the actions of the scripts it contains. Naturally, you are free to devise your own techniques for displaying assets, but most fxindex.htm files will carry out the following basic steps:

  1. The file contains an OBJECT element that refers to an ActiveX control that reads an XML file and creates a data structure.
  2. A JScript script uses this control to read the fxitems.xml file containing entries (Item elements) corresponding to the assets and creates a data structure
  3. Another script traverses this data structure and obtains information about an asset from the corresponding Item element. This information can be customized (as explained in the section on the fxitems.xml file), but generally it consists of at least an asset filename, an icon filename, a description, and a unique identifier.
  4. This information is then written to the document window (that is, the lower pane of the Asset tab), usually formatted as a table row.
  5. The previous two steps are carried out for each Item element.

The sample fxindex.htm can easily be adapted to most requirements.

You should also give some thought to the design of your fxindex.htm: for example, choose a pleasing background color, and include a heading or banner graphic that explains what type of assets the page contains. For assets that may be difficult for some users to understand, you can include a short documentation section, or links to other documents.

If a folder does not contain any assets, it still needs an fxindex.htm file to display a descriptive page in the lower pane of the Asset tab. For example, the fxindex.htm could contain text or a graphic that explains what kind of assets are in the subfolders of the current folder.

The fxitems.xml file

Generally speaking, the fxitems.xml file will need more customization for a new asset type than the fxindex.htm file will. There is a sample fxitems.xml in the Samples\Asset Templates folder.

The fxitems.xml file contains the following configurations:

fxitems.xml is also updated dynamically as assets are added to the folder: an Item elements for each new asset will be added to the file.

This information can be placed in the fxmaster.xml file instead of individual fxitems.xml files. You may find it easier to centralize your templates and scripts in this way. You will still need an fxitems.xml file, but it will have very simple content:

<?xml version="1.0" standalone="yes"?>
<Items></Items>

If the fxitems.xml file does contain the Item template and script, it must have the following structure, in which the template and script are enclosed in a Template element:

<?xml version="1.0" standalone="yes"?>
<Items>
<Template>
   <Item ....>
   ....
      <SCRIPT>
      ....
      </SCRIPT>
   </Item>
</Template>
...Other <Item> elements, inserted automatically when
assets are added...
</Items>

The Template element is not required in the fxmaster.xml file.

If the template and script for an asset type are contained in the fxmaster.xml file instead of the fxitems.xml file, then when a new asset is created, the user will be prompted to choose the asset type from among all the available asset types. If the fxitems.xml file contains the template and script, the asset type is assumed to be the one specified by the template.

The Item template

Here is an example of a simple Item template:

<Item Type="File" Class="Fig" ID="%Filename%"
         FILEFILTER="*.jpg;*.gif;*.png">
<Icon SRC="%Filename%"/>
<Description>%ASK:Description:%{Description}</Description>
<Filename SRC="%Filename%"/>
<SCRIPT Language="JScript">
...
</SCRIPT>
</Item>

For now we'll ignore the SCRIPT part of the template, since it doesn't affect the structure of the Items that are written to fxitems.xml.

The sample template above would cause an Item element such as the following to be written to fxitems.xml:

<Item Type="File" Class="Fig" ID="scully06.jpg"
    FILEFILTER="*.jpg;*.gif;*.png">
<Icon SRC="scully06.jpg"/>
<Description>Scully saves Mulder again!</Description>
<Filename SRC="scully06.jpg"/>
</Item>

The SCRIPT

The SCRIPT element in the fxitems.xml file contains a script that does the work of inserting the asset into the document when a user drags it from the Asset tab and onto a document. If the asset has type `File' the script will also copy the asset file from the asset folder to a location relative to the document that it is being inserted in.

If the asset is simply being inserted into the document at the location that it's dropped, the script can be relatively straightforward, like the script in the sample fxitems.xml. This script carries out the following basic steps:

  1. Get the full path to the asset file.
  2. Create the attribute value that will specify the filename.
  3. Define a function buildpath that calculates the location where the asset file will be copied.
  4. Define a function dropfxnow that copies the file and performs the insertion; this often requires that some markup be generated. This function can be very simple (as in the sample file) if the asset is simply inserted into the document at the position the user drops it. Some assets, such as style sheets, may require more complicated manipulations of the document structure.
  5. Check whether the document has ever been saved. If it has, call buildpath and dropfxnow. If it hasn't, prompt the user to save the document.
  6. Check a second time whether the document has been saved. If it has, call buildpath and dropfxnow.

Text and text file assets

Assets consisting of text files are handled in almost the same way as image assets. The main difference is that the icon representing a text file cannot be the file itself. You either have to predefine an icon and hard-code it in the Item template, or else prompt the user to enter the name of a template file when the asset is created. You should also prompt the user for a description, and display the description in fxindex.htm, because the icon will likely not be informative enough for the user to know the exact contents of the file.

Assets can also consist of blocks of text (as contrasted with files containing text). For example, you could create an asset consisting of a table, any other element, or a block of text by dragging and dropping it into a text category in the Assets tab. Text assets are handled slightly differently.


Right arrow
Next Topic
Left arrow
Previous Topic
Table of contents
Table of Contents

Copyright © SoftQuad Software Inc. 1999