Art HTML Listing 3.0 Help www.zzee.com | Support | You are here: Contents > 9. File Types and Icons

# 9. File Types and Icons

www.zzee.com | You are here: Contents > 9. File Types and Icons

File icons and media types mapping is defined in the file "ext.txt", which is XML file. There are two sections in it: (a) <extensions>, where file type and icon can be defined by file extension and (b) <types>, where file type and icon can be defined by media type. The type and image mapping works this way:

- First media type and icon are tried to be found by file extension.
- If not found, then file media type is got from the operating system and <types> section is used.
- If still not resolved, then "other" item from <types> section is used.

If Options > "File types" is set to "Taken from Windows", then icons will be resolved via "ext.txt" file as described above, while file types are taken from Windows.

## 9.1. Icons Replacement and Redistribution

www.zzee.com | You are here: Contents > 9. File Types and Icons > 9.1. Icons Replacement and Redistribution

Supplied icons are taken from Gnome desktop environment, and are under the LGPL license, and because the images contain their own source, so they are automatically distributed in the source form, and thus can be redistributed or modified by anyone, providing that LGPL terms are met.

You can replace the provided icons with your own. If you replace them by icons with different size, then you need to adjust those templates which use icons and change width and height parameters fo <img> tags. If you replace the icons with the icons of different name, then you need to replace icon names in file "ext.txt".

# 10. Templates

www.zzee.com | You are here: Contents > 10. Templates

To build a listing file Art HTML Listing uses output templates. Here is the description of all ready made templates.

You can edit any template by hand, using generic text editor, for example, Notepad. You need to be familiar with HTML coding. Each HTML template uses XHTML for markup and cascading style sheet (CSS) to define appearance such as colors, fonts, etc. More information about HTML/XHTML and CSS can be found at W3C web site.

## 10.1. Templates Manipulations

www.zzee.com | You are here: Contents > 10. Templates > 10.1. Templates Manipulations

All templates are defined in the file "templates.txt" located in the AHL installation folder, which is a simple XML-like file. Each definition is held inside <template> tag. Each template consists of:

- Template definition in "templates.txt" file
- Template file in "templates" folder
- Optional image file in "templates" folder

There are the menu items and the button toolbar to facilitate template manipulations, such as copying, renaming, editing template file, changing according image and description. To delete a template from the list, you need to remove its definition from "templates.txt" file, you can also delete or leave the according template file in the "templates" folder.

Image for a template should be a BMP file with 320x240 resolution, and needs to reside in the "template" folder.

## 10.2. Developing Templates

www.zzee.com | You are here: Contents > 10. Templates > 10.2. Developing Templates

Templates use text preprocessor language ZZI2. You can copy templates to build new ones upon existing ones.

### 10.2.1. ZZI2 Scope, Current Item

www.zzee.com | You are here: Contents > 10. Templates > 10.2. Developing Templates > 10.2.1. ZZI2 Scope, Current Item

AHL ZZI2 is the language made specially for processing file listings. The main task that ZZI2 does is iterating through files/folders of the listing, and the key conception of ZZI2 is the file/folder item. At each given time it handles only one item (current item), which is the scope of all echo and if constructs. Thus the file/folder item used is implied in every echo and if construct. Current item is changed using for or repeat constructs.

### 10.2.2. ZZI2 Syntax

www.zzee.com | You are here: Contents > 10. Templates > 10.2. Developing Templates > 10.2.2. ZZI2 Syntax

The ZZI2 syntax resembles the SSI one, and a ZZI2 expression looks like:

    <!--#keyword [parameter1="value1" [parameter2="value2"] ...] -->

That is, each ZZI2 language construct is an HTML comment, where "<!--" is directly followed by the '#' sign and then by a keyword. Optional name="value" pairs may follow, both double and single quotation marks are recognized, so the following are the same statements:

    <!--#echo var='fullname' -->
    <!--#echo var="fullname" -->

### 10.2.3. ZZI2 Keywords and Constructs

www.zzee.com | You are here: Contents > 10. Templates > 10.2. Developing Templates > 10.2.3. ZZI2 Keywords and Constructs

#### 10.2.3.1. "Echo" Constructs

www.zzee.com | You are here: Contents > 10. Templates > 10.2. Developing Templates > 10.2.3. ZZI2 Keywords and Constructs > 10.2.3.1. "Echo" Constructs

All echo constructs print the value of the variable, specified in var parameter. var="varname" parameter is required. The variable is evaluated for the current item. See below for the list of the allowed variables. Example:

    <!--#echo var='dwld1m' -->

The example will print the value of the download time at 1Mbit/s for the current file.

All echo keywords are shown in the table:

Keyword | Description
--- | ---
echo | Prints the value of the variable.
echoe | Like echo, but encodes the printed value with HTML encoding.
echou | Like echo, but converts the value to upper case.
echol | Like echo, but converts the value to lower case.
echon | Like echo, but truncates the value if its length exceeds the number of characters specified in the required parameter size="integer_value". If the value is truncated, then "..." is added to it. Example:
    <!--#echon var="fullname" size="20"-->
echoen | Like echon, but encodes the printed value with HTML encoding.

#### 10.2.3.2. "If" Construct

www.zzee.com | You are here: Contents > 10. Templates > 10.2. Developing Templates > 10.2.3. ZZI2 Keywords and Constructs > 10.2.3.2. "If" Construct

If construct is the block conditional construct and it will print (or not print) the block of text it contains, depending on the value of the variable. var="varname" parameter is required. Closing endif construct is required, alternative else construct is optional. Besides the variable, if construct may have optional re="regexPattern" parameter, which is used to evaluate the value of the variable against the regular expression specified in regexPattern. Regular expressions syntax used in ZZI2 is the generic regular expressions syntax similar to that of Javascript or PHP, and a subset of that from Perl language.

Example 1:

    <!--#if var="isdir"-->
    Block A
    <!--#else-->
    Block B
    <!--#endif-->

If the current item is directory, then block A is printed. Otherwise block B is printed.

Example 2:

    <!--#if var="level"-->
    Block A
    <!--#endif-->

If the current item is being processed recursively (i.e., the recursion depth level is positive), then block A is printed. Otherwise nothing is printed.

Example 3:

    <!--#if var="fullname" re="\.html?$"-->
    Block A
    <!--#else-->
    Block B
    <!--#endif-->

Here we pass the regular expression to evaluate the full file name of the current item against. So, if the file name ends in ".htm" or ".html", then the regular expression will match the file name and thus the block A is printed. Otherwise block B is printed.

#### 10.2.3.3. "For" Construct

www.zzee.com | You are here: Contents > 10. Templates > 10.2. Developing Templates > 10.2.3. ZZI2 Keywords and Constructs > 10.2.3.3. "For" Construct

For construct is needed to loop through the items (files and folders) of the listing, and it changes the current item. var="varname" parameter is required. Closing endfor is required. For loops may not be nested within each other. Here the variable passed in var parameter has a different meaning, all possible variables used in the for construct are described in the table:

Keyword | Description
--- | ---
files | Loops through all files of the listing. Doesn't recurse.
folders | Loops through all folders of the listing. Doesn't recurse.
tree | Loops through all files and folders recursively. Recursion depth is set in the project settings, at Source tab. Recursion may happen immediately (like in "Tree" template) or after all siblings of the folder to dive in will be processed (like in "Recursive Folder Listing" template), this is switched using Options / "Process recursive subfolders in the end".

Example 1

    <!--#for var="files"-->
    Block A
    <!--#endfor-->

Repeats block A so many times how many files are in the listing.

Example 2

    <!--#for var="folders"-->
    Block A
    <!--#endfor-->

Repeats block A so many times how many folders are in the listing.

Example 3

    <!--#for var="tree"-->
    Block A
    <!--#endfor-->

Repeats block A so many times how many files and folders are in the listing. And also will recurse on folders if it finds a folder to be recursed.

#### 10.2.3.4. "Repeat" Construct

www.zzee.com | You are here: Contents > 10. Templates > 10.2. Developing Templates > 10.2.3. ZZI2 Keywords and Constructs > 10.2.3.4. "Repeat" Construct

Repeat loop may be used only inside for construct which uses files or folders variable name. It changes the current item. Basically, it can be used to create a N column listings like in "Compact 3 column list" template, it simply repeats N times the block it contains. Repeat constructs may not be nested inside each other. Closing endrepeat construct is required, alternative elserepeat construct is optional, but highly recommendable. Var parameter should have a numeric value N, telling how many times repeat loop should be repeated. Elserepeat is executed when there are no more items, so repeat can't change the item anymore, but to finish the things, and make sure that exactly N times are completed.

Example. Let's assume we have 5 files in the listing.

    <!--#for var="files"-->
    A
    <!--#repeat var="2"-->
    B
    <!--#elserepeat-->
    C
    <!--#endrepeat-->
    D
    <!--#endfor-->

Then the result will be: ABBD ABBD ABCD. In the last repeat loop, it processed block C because the items were exhausted and it had to complete its job by executing alternative elserepeat block.

#### 10.2.3.5. Variables Used in "Echo" and "If" Constructs

www.zzee.com | You are here: Contents > 10. Templates > 10.2. Developing Templates > 10.2.3. ZZI2 Keywords and Constructs > 10.2.3.5. Variables Used in "Echo" and "If" Constructs

All variables are calculated for the current item. Here is the alphabetic list of all variables.

Variable | Type / Meaning
--- | ---
abspath | String, absolute local path in windows format, like "c:\file.txt"
absurl | String, absolute local URL, like "file://c:/file.txt"
accessed | String, "last accessed" date time
attr | String, file attributes in textual form
counter | Integer, counter in the context of the current for loop, also incremented on each repeat loop iteration. Starts from 0.
created | String, "created" date time
dateonly | String, date only fraction of the "last modified" date time, in Windows format
directory | String, the name of the parent directory, just the name without the path
dwld1m | String, download time @ 1024Kbit/s
dwld56k | String, download time @ 56Kbit/s
endrecurse | Boolean, returns 1 if the current item is the artificial item executed after the end of each for loop level. It is needed to properly close the things, to develop correct XHTML or XML. It is used only on for loops with tree variable.
ext | String, extension of the file name, beginning with dot
filesordered | Integer, listing order type
filesorderedhow | Boolean, returns 0 if ascending, 1 if descending
fullname | String, the file name with extension
htmltitle | String, will return the title of an HTML file, will be empty if can't find the title
icon | String, returns relative icon file name
image_dir | String, returns image directory path, specified in Options > Icons, or if "Use local icons" is checked, then will return an absolute local path for the icons directory
isdir | Boolean, returns 1 if item is directory, 0 otherwise
lcounter | Integer, starting from 0, counter in the context of the current for loop, also incremented on each repeat loop iteration. lcounter is reset to 0 on each recursion level (unlike counter).
level | Integer, returns recursion depth level starting from 0.
local_files | Integer, total number of files in in the current folder, this variable is available on for loops with files or tree variable. If for with files is used, then it will coincide with total_files. This variable is needed to make local summaries in case of recursive processing.
local_folders | Integer, total number of subfolders in in the current folder, this variable is available on for loops with files or tree variable. If for with files is used, then it will coincide with total_folders. This variable is needed to make local summaries in case of recursive processing.
local_size | String, total size of all files in in the current folder, this variable is available on for loops with files or tree variable. If for with files is used, then it will coincide with total_size. This variable is needed to make local summaries in case of recursive processing.
md5 | String, MD5 hash of the file, will be empty if current item is folder
media | String, media type of the item
mod2 | Boolean, odd items of the listing will return 1, even ones will return 0
name | String, the file name without extension
now | String, current date time
real | Boolean, returns 1 if the current item is a file or folder. Returns 0 for artificial items executed before the beginning and after the end of each for loop level.
recurse | Boolean, returns 1 if the current item is the artificial item executed before the beginning of each for loop level. It is needed to properly open the XML / XHTML things. It is used only on for loops with tree variable.
recursion | Integer, returns recursion depth set in Source > Recursion options
recursive_files | Integer, returns the number of all descendant files (on all levels of depth) of the folder if Options > "Recursive size for folders" or "Suppress empty folders recursion" is set. Otherwise returns 0. For files it returns the value of its parent folder.
recursive_folders | Integer, returns the number of all descendant subfolders (on all levels of depth) of the folder if Options > "Recursive size for folders" or "Suppress empty folders recursion" is set. Otherwise returns 0. For files it returns the value of its parent folder.
recursive_size | String, returns the total size of all descendant files (on all levels of depth) of the folder if Options > "Recursive size for folders" or "Suppress empty folders recursion" is set. Otherwise returns 0. For files it returns the value of its parent folder.
relpath | String, Relative path (relative to Source > Source Folder)
relurl | String, Relative URL (relative to Source > Source Folder)
sha1 | String, SHA1 hash of the file, will be empty if current item is folder
show_files | Boolean, returns the value set in Options > "Show file items in listing"
show_folders | Integer, returns 2 if folders are shown, otherwise 0. The value is set in Options > "Show folders items in listing".
show_summary | Boolean, returns the value set in Options > "Show summary"
size | String, formatted size of the file. For folders returns empty string, and if Options > "Recursive size for folders" is checked, then returns the recursive size of the folder (after filters are applied).
sizeunit | String, shows the size unit used, except when Options > "File size units" is set to "Dynamic", in this case the size unit is automatically attached to size variable. When the size units is Bytes, returns empty value.
source | String, the absolute path of the source folder
time | String, "last modified" date time, in either Windows or custom format, depending on settings at Options > "Date/time format"
timeonly | String, time only fraction of the "last modified" date time, in Windows format
total_files | Integer, total number of files for the whole for loop.
total_folders | Integer, total number of folders for the whole for loop.
total_size | String, total size of all files for the whole for loop.
willrecurse | Boolean, returns 1 if the current item is folder and it will recurse later. It is used only on for loops with tree variable.

Format of all size variables depends on Options > "File size units" and on the Windows settings of number format, which is set in Windows XP at Control Panel > Regional and Language Options > Regional Options > Customize > Numbers, in Windows 2000 at Control Panel > Regional Options > Numbers.