This copy of the Jasc MCML reference manual is archived at http://www.chipchapin.com as part of an article, "Creating Custom Web Pages using Jasc Media Center Pro and MCML"  Click here to go back to the article.

MCML is part of Jasc Software's product Media Center Pro. For more information see http://www.jasc.com/


 

 

 

MCML Reference and Tutorial

Revision 1.0e

November 6, 1999

 

 

MCF QUICK REFERENCE

MCML QUICK REFERENCE

MCML OVERVIEW

MCF COMMAND REFERENCE

MCML INSTRUCTION REFERENCE

CAPABILITIES FILES

MCML TUTORIAL

GLOSSARY

 

 


MCF QUICK REFERENCE

copy filename.ext
gen filename [ unique | uniquenamed=filename | count=n | foreach=pagename
    | xtotal=n xpadding=n [ ytotal=n ypadding=n ] ]
    [ columns=n ] [ numformat="spec" ]

MCML QUICK REFERENCE

(All of the instructions below must appear within an MCML tag; i.e., "<MCML instruction>".)

albumcomment
albumtitle
htmlname
if [ not ] [ +n | -n ] testelse /if
loopcount [ offset=n ] [ numformat="spec" ]
pagename [ +n | -n ] [ maxlength=n ]
pagenum [ +n | -n ] [ numformat="spec" ]
repeat [ count=n | foreach=pagename ] … /repeat
sourceheight [ +n | -n ] [ offset=n ]
sourcewidth [ +n | -n ] [ offset=n ]
sourcejspath [ +n | -n ] [ maxlength=n ]
sourcename [ +n | -n ] [ maxlength=n ]
sourcepath [ +n | -n ] [ maxlength=n ]
table  /table
  tablecell
  emptycell
  tablenewrow
  tablebottom
thumbcomments [ +n | -n ] [ maxlength=n ]
thumbdiskid [ +n | -n ] [ maxlength=n ]
thumbkeywords [ +n | -n ] [ maxlength=n ]
thumbname [ +n | -n ] [ maxlength=n ]
thumbheight [ +n | -n ] [ offset=n ]
thumbwidth [ +n | -n ] [ offset=n ]
thumbmaxheight [ offset=n ]
thumbmaxwidth [ offset=n ]
thumbnum [ +n | -n ] [ numformat="spec" ]
thumbtableheight [ +n | -n ] [ offset=n ]
thumbtablewidth [ +n | -n ] [ offset=n ]
usernum [ offset=n ] [ numformat="spec" ]
usertext [ maxlength=n ]

 


MCML Overview

MCML ("Media Center Markup Language") is a set of instructions for dynamically creating HTML pages based upon the contents of a Jasc Media Center Plus albumfile. The user activates this functionality by first opening an albumfile, then selecting the Export to HTML menu option and making appropriate selections from the ensuing dialog.

Some general notes about MCML and its usage:


MCF COMMAND REFERENCE

An explanation of the meanings of various text styles in the Synopsis portion of the following reference pages:

text
Bold text must appear in the MCF file exactly as shown.

text
Italicized text is replaced by appropriate text as described on the reference page.

text | text
Items separated by a vertical bar indicate that only one of these items may be present.

[ text ]
An item surrounded by brackets indicates that the enclosed items are optional.

NAME

copy  —  specifies a file to be copied to the output directory

SYNOPSIS

copy filename

CLAUSES

filename

The name (including extension) of a file that is to be copied without changes to the output directory for the site design. This must be a single file that resides in the same directory as the current MCF file; wildcards and pathname components are not supported.

DESCRIPTION

The copy command is used in the MCF file to identify files that need to be copied intact from the site design directory to the user’s selected output directory whenever the Export to HTML process is run.

Files that might be copied using this command may include background or other non-changing images, HTML files that do not require dynamic changes based upon the exported album, JavaScript source files, Java applets, CGI programs, common thumbnails for non-image file types, etc.


NAME

gen  —  declares an MCML file used to generate one or more HTML files

SYNOPSIS

gen pagename [ unique | uniquenamed=filename | count=n | foreach=pagename
    | xtotal=n xpadding=n [ ytotal=n ypadding=n ] ]
    [ columns=n ] [ numformat="spec" ]

CLAUSES

pagename

The filename (without extension) of an MCML source file that is to be used to generate one or more HTML files for the site design.

unique

Indicates that exactly one HTML page of this page type is to be generated, regardless of how many thumbnails are being exported. Note that using this clause or the uniquenamed clause are the only ways to create an HTML page that does not have a numeric suffix appended to the filename. If no clauses are specified, this is used as the default.

uniquenamed=filename

Indicates that exactly one page of this page type is to be generated, regardless of how many thumbnails are being exported. In addition, indicates the exact output filename that should be assigned to the created file (including any extension). Note that using this clause or the unique clause are the only ways to create an HTML page that does not have a numeric suffix appended to the filename. Also note that non-HTML text files can be generated using this clause.

count=n

Indicates that exactly one HTML page of this page type is to be generated for each n thumbnails that are being exported, regardless of the size of those thumbnails.

foreach=pagename

Indicates that one HTML page of this page type is to be generated for each page of the page type named by pagename. Each page of the current page type will be provided with the same set of thumbnails and sizing information used by the corresponding page of the referenced page type. The referenced page type must have already been declared (via its own gen statement) in the same MCF file, on a line prior to where it is referenced by a foreach clause.

xtotal=n

Indicates the total amount of horizontal space available (in pixels) for the display of thumbnails and/or information. This information is used to dynamically calculate the number of thumbnails per page for the current page type. The xpadding clause must also be present when this clause is used.

xpadding=n

Indicates the amount of horizontal space that should be allocated for each thumbnail in excess of the native size of thumbnails in the current album. This information is used to dynamically calculate the number of thumbnails per page of the current page type. The xtotal clause must also be present when this clause is used.

ytotal=n

Indicates the total amount of vertical space available (in pixels) for the display of thumbnails and/or information. This information is used to dynamically calculate the number of thumbnails per page for the current page type. The ypadding, xtotal and xpadding clauses must also be present when this clause is used.

ypadding=n

Indicates the amount of vertical space that should be allocated for each thumbnail in excess of the native size of thumbnails in the current album. This information is used to dynamically calculate the number of thumbnails per page of the current page type. The ytotal, xtotal and xpadding clauses must also be present when this clause is used.

columns=n

When used along with one of the non-unique "size" clauses (foreach, count, or X/Y sizes), this clause overrides the calculated number of columns and sets it to value n, without altering the total number of thumbnails assigned to each page. Otherwise, it sets the number of columns to n and selects all thumbnails to appear on a single page.

numformat="spec"

Specifies how any numeric suffixes to the generated HTML filenames should be formatted. The spec argument takes the form of a printf() format specification, which should specify the formatting of a single integer argument. When the numformat clause is not used, a default format of "%i" is used (which simply uses the number without any leading zeroes). Note that no attempt is made to test the provided spec for validity; rather, it is merely passed to the internal formatting function, so it is important to be certain that a valid spec is used.

DESCRIPTION

The gen instruction is used in the MCF file to identify MCML files that are to be used for the generation of HTML files whenever an albumfile is exported using the current site design. Each MCML file should be regarded as the description of a single page type.

A maximum of one "size" clause can be selected for each gen command, as they are mutually exclusive. The "size" clauses are as follows: unique, uniquenamed, count, foreach, and the inter-dependent set of clauses xtotal, xpadding, ytotal and ypadding. If the referenced MCML file is to utilize a thumbnail table, either the xtotal and xpadding clauses or a foreach clause referring to another MCML file that used the xtotal and xpadding clauses must be used.

If only xtotal and xpadding are given, the export engine uses them to determine the number of columns of thumbnails to create, and outputs all thumbnails to a single page. If the ytotal and ypadding clauses are provided in addition to xtotal and xpadding, the engine will determine both the number of columns and rows that will be created, and will generate one or more HTML pages as needed to display all exported thumbnails.

Note that the ytotal and ypadding clauses may not appear without the corresponding xtotal and xpadding clauses. In other words, the export engine will not create an HTML page with a fixed number of rows and an infinite number of columns.

Each generated HTML file will be given the same name as the source MCML file, plus a unique number (only if multiple pages could be created by the gen instruction) that is formatted as specified in the numformat clause, and the extension ".htm". The only exception to these naming conventions is when the uniquenamed clause is used.

When the foreach clause is used, the MCML page to which it refers must have appeared earlier in the same MCF file (on its own gen command line).


MCML INSTRUCTION REFERENCE

An explanation of the meanings of various text styles in the Synopsis portion of the following reference pages:

text
Bold text must appear in the MCML file exactly as shown.

text
Italicized text is replaced by appropriate text as described on the reference page.

text | text
Items separated by a vertical bar indicate that only one of these items may be present.

[ text ]
An item surrounded by brackets indicates that the enclosed items are optional.

NAME

albumcomment  —  include album comment text

SYNOPSIS

<MCML albumcomment>

CLAUSES

None.

DESCRIPTION

The albumcomment instruction is replaced by the album comments text for the album being exported, if any.

If no text is available, the instruction will simply be removed and nothing will be inserted in its place.


NAME

albumtitle  —  include album title

SYNOPSIS

<MCML albumtitle>

CLAUSES

None.

DESCRIPTION

The albumtitle instruction is replaced by the title of the album being exported, if any. Note that this is the title that has been assigned to the album under Album Properties, which may or may not be the filename to which the album was saved.

If no title is available, the instruction will simply be removed and nothing will be inserted in its place.


NAME

htmlname  —  insert the HTML filename prefix provided by the user

SYNOPSIS

<MCML htmlname>

CLAUSES

None.

DESCRIPTION

The htmlname instruction is replaced by the text that the user has entered into the required "Filename" field on the Export to HTML dialog.


NAME

if  —  execute or skip a block of text based upon results of a test

SYNOPSIS

<MCML if [ not ] [ +n | -n ] test >
…
[ <MCML else> ]
…
<MCML /if>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the thumbnail or page to be tested should be that found at a relative offset from the current thumbnail or page. Negative values select the thumbnail or page n positions before the current one, while positive values select the thumbnail or page n positions after the current one.

not

Indicates that the result of test should be inverted before being applied; i.e., if test succeeds, then the following block of text should not be processed, and visa versa.

DESCRIPTION

The if instruction allows a subsequent block of text to either be processed or skipped, based upon the outcome of a conditional test that is specified in the instruction. If the test succeeds, the subsequent block of text is processed; if the test fails, the following block of text is skipped. (Note that the not clause, when present, reverses this behavior.)

The block of text to be affected by the outcome of the test is delimited by the if instruction itself (at the beginning) and a terminating /if instruction (at the end). An optional else instruction may appear somewhere within the delimited block of text, indicating the end of the block of text to be processed when the test succeeds, and indicating the start of a second block of text that is only to be processed if the test fails.

An if statement may be enclosed within other if statements, as well as within repeat loops and thumbnail tables. Similarly, a repeat loop or a thumbnail table may occur within a block of text inside an if statement. Note that all such if, repeat and/or table instructions must be terminated in the reverse order of which they are began. I.e., if a repeat instruction is contained within the block of text of an if instruction, the terminating /repeat instruction must also occur within that same block (including before any else instruction).

Only one test may appear within a single if statement. The available tests are shown in the following table:

 

Test clause

Functionality and usage

thumb

Succeeds if the referenced thumbnail exists (i.e., a thumbnail is available at the referenced position). Since there is always a current thumbnail, this test will always succeed except when a thumbnail other than the current one is being tested (using relative addressing). Testing for the existence of thumbnails other than the current one is the expected normal use of this test.

thumbcomments

Succeeds if the referenced thumbnail has comments text.

thumbkeywords

Succeeds if the referenced thumbnail has any keywords associated with it.

filetype=type

Succeeds if the file type of the referenced thumbnail matches the given type value. The available values are:

  • image — a browser-supported image file
  • media — a browser-supported multimedia file
  • other — a file type unsupported by browsers

page

Succeeds if the referenced page exists (i.e., a page of the current page type is to be generated at the referenced position). Since the current page always exists, this test will always succeed except when a page other than the current one is being tested (using relative addressing). Testing for the existence of page other than the current one is the expected normal use of this test.

loop_lt_page

May only be used when the if statement occurs within a repeat loop. Succeeds if the current value of loopcount is less than the page number of the referenced page (either the current page or a page specified by relative addressing).

loop_eq_page

May only be used when the if statement occurs within a repeat loop. Succeeds if the current value of loopcount is equal to the page number of the referenced page (either the current page or a page specified by relative addressing).

loop_gt_page

May only be used when the if statement occurs within a repeat loop. Succeeds if the current value of loopcount is greater than the page number of the referenced page (either the current page or a page specified by relative addressing).

linking

Succeeds if the user specified that the generated HTML should link to source files, rather than copy them to the output directory. Note that the engine itself returns appropriate paths to the source files according to the user's selection, but this test may be used if additional adjustments to the HTML output are required or desired when links to local files are in use.

flip

A special test, flip succeeds the first time it is called for a page, and then succeeds every odd time it is called (3rd, 5th, 7th, etc.). This can be used to alternate two different blocks of text in a loop or table. Note that, if a separate block of text is to be executed when flip fails, such text should be placed in an else block, because using a second if statement with a not flip test would trigger the flip test back to a "succeeded" result.


NAME

loopcount  —  get the value of the repeat loop counter

SYNOPSIS

<MCML loopcount [ offset=n ] [ numformat="spec" ]>

CLAUSES

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

numformat="spec"

Specifies how the returned value should be formatted. The spec argument takes the form of a printf() format specification, which should specify the formatting of a single integer argument. When the numformat clause is not used, a default format of "%i" is used (which simply returns the number without any leading zeroes). Note that no attempt is made to test the provided spec for validity; rather, it is merely passed to the internal formatting function, so it is important to be certain that a valid spec is used.

DESCRIPTION

The loopcount instruction is replaced by the current value of the counter used to perform repeat loops. This instruction may only appear within a repeat loop block of text; use outside of such a block of text is flagged as an error. The loop counter always start with ‘1’ the first time through a loop, and increments for each additional loop execution until the loop is complete. (The returned value may be adjusted without affecting the loop counter itself by using the offset clause.)

An example of the usage of this instruction would be the creation of a list of page number indexes when a foreach=pagename clause is used in the enclosing repeat loop.


NAME

pagename  —  get the full filename of a page of the current type

SYNOPSIS

<MCML pagename [ +n | -n ] [ maxlength=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the filename to be returned should be that of a page at a relative offset from the page currently being generated. Negative values select the page n pages before the current page, while positive values select the page n pages after the current page. If the resulting page is not valid (i.e., the offset attempts to select a page before the first page or after the last), no text is returned.

maxlength=n

Indicates the maximum number of characters that should be returned. If less than n characters are used by the returned text, or whenever the maxlength clause is not used, all characters are returned.

DESCRIPTION

The pagename instruction is replaced by the full filename of a selected HTML page of the current page type. The default is to use the filename of the current page, unless the +n or n clauses are used.

The filename will include the extension, but will not include any pathname component (since all HTML files are placed in the same directory).

An example of the usage of this instruction would be the creation of a linked list of pages, with each page providing a link to the pages immediately before and after it.


NAME

pagenum  —  get the index number of a page of the current type

SYNOPSIS

<MCML pagenum [ +n | -n ] [ numformat="spec" ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the index value to be returned should be that of a page at a relative offset from the page currently being generated. Negative values select the page n pages before the current page, while positive values select the page n pages after the current page. If the resulting page is not valid (i.e., the offset attempts to select a page before the first page or after the last), no text is returned.

numformat="spec"

Specifies how the returned value should be formatted. The spec argument takes the form of a printf() format specification, which should specify the formatting of a single integer argument. When the numformat clause is not used, a default format of "%i" is used (which simply returns the number without any leading zeroes). Note that no attempt is made to test the provided spec for validity; rather, it is merely passed to the internal formatting function, so it is important to be certain that a valid spec is used.

DESCRIPTION

The pagenum instruction is replaced by the index number portion of the filename of the selected HTML page of the current page type. The default is to use the filename of the current page, unless the +n or n clauses are used. Page index numbers always start with ‘1’ for the first page of any given page type, and increment until the last page of that type is reached.

An example of the usage of this instruction would be the creation of a link to a page of a different page type, but which is relative to this page type in that the same number of thumbnails are assigned to each page. This will always be the case whenever one page is "mirrored" to the other using a foreach=pagetype clause in the MCF file.


NAME

repeat  —  process & output a block of text multiple times

SYNOPSIS

<MCML repeat [ count=n | foreach=pagename ]>
     <MCML /repeat>

CLAUSES

count=n

Indicates that the loop should be performed n times.

foreach=pagename

Indicates that the loop should be performed once for each page to be generated of the page type named by pagename. The referenced page type must have been declared (via a gen statement) in the MCF file. The extension of the MCML file should not be included in pagename.

DESCRIPTION

The repeat instruction is used to repeat a block of text a certain number of times. The count clause may be used to loop a fixed number of times, or else the foreach clause may be used to repeat the loop a number of times equivalent to the number of pages of a named page type that is being exported. Only one of these clauses may be used with a single repeat instruction.

The block of text to be repeated is the text that follows the repeat instruction, and the end of that block of text is marked by a terminating /repeat instruction. Other MCML instructions may occur within the block of repeated text. Any such MCML instructions will be processed once for each loop.

When a loop is being performed via a repeat instruction, the loopcount instruction may be used to get the current value of the loop counter, and several tests are available in the if instruction for the loop counter as well.

Note that, during HTML generation, each repetition of a block of text within a repeat block is separated from the others with a carriage return. As such, it is strongly suggested that the repeat and /repeat instructions should be placed on separate lines by themselves, to underscore this fact and to confirm that the resulting HTML will work properly with the carriage returns included.

The repeat instruction may not be nested; that is, a second repeat loop cannot occur within a block of text already being repeated as part of a repeat loop. The MCML table instruction must also be treated as a loop for the purpose of observing this restriction.


NAME

sourceheight  —  get the height in pixels of the source image

SYNOPSIS

<MCML sourceheight [ +n | -n ] [ offset=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the height to be returned should be that of the source file associated with a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), or if the referenced thumbnail is not an image type that is known to web browsers, a size of 0 is returned.

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

DESCRIPTION

The sourceheight instruction is replaced by the height (in pixels) of the source image associated with the current thumbnail, or the source image associated with a thumbnail at a specified offset from the current thumbnail if the +n or n clauses are used.

An example of the usage of this instruction would be the creation of a popup window of the correct size to display the source image. Note that it will usually be advisable to test the thumbnail first to make sure it is of an image type that can be displayed before doing such a thing. See the if instruction for details on how to go about such testing.


NAME

sourcewidth  —  get the width in pixels of the source image

SYNOPSIS

<MCML sourcewidth [ +n | -n ] [ offset=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the width to be returned should be that of the source file associated with a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), or if the referenced thumbnail is not an image type that is known to web browsers, a size of 0 is returned.

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

DESCRIPTION

The sourcewidth instruction is replaced by the width (in pixels) of the source image associated with the current thumbnail, or the source image associated with a thumbnail at a specified offset from the current thumbnail if the +n or n clauses are used.

An example of the usage of this instruction would be the creation of a popup window of the correct size to display the source image. Note that it will usually be advisable to test the thumbnail first to make sure it is of an image type that can be displayed before doing such a thing. See the if instruction for details on how to go about such testing.


NAME

sourcejspath  —  get the full pathname of a source media file

SYNOPSIS

<MCML sourcejspath [ +n | -n ] [ maxlength=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the pathname to be returned should be that of the source file associated with a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), no text is returned.

maxlength=n

Indicates the maximum number of characters that should be returned. If less than n characters are used by the returned text, or whenever the maxlength clause is not used, all characters are returned.

DESCRIPTION

The sourcejspath instruction is replaced by the pathname of the source file associated with the selected thumbnail. The default is to use the current thumbnail, unless the +n or n clauses are used.

If the user has specified that all source files are to be copied to the output directory, the filename will not include any pathname component. Otherwise, a full absolute pathname will be returned.

This instruction differs from the sourcepath instruction only in that any/all reverse backslashes ‘\’ are escaped with an extra backslash. This is necessary only when the returned text is to be used as an argument for a JavaScript function or the like. For normal purposes the sourcepath instruction should be used instead.


NAME

sourcename  —  get the filename of a source media file

SYNOPSIS

<MCML sourcename [ +n | -n ] [ maxlength=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the filename to be returned should be that of the source file associated with a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), no text is returned.

maxlength=n

Indicates the maximum number of characters that should be returned. If less than n characters are used by the returned text, or whenever the maxlength clause is not used, all characters are returned.

DESCRIPTION

The sourcename instruction is replaced by the filename of the source file associated with the selected thumbnail. The default is to use the current thumbnail, unless the +n or n clauses are used.

If a full pathname to the file is required, use the sourcepath instruction instead.


NAME

sourcepath  —  get the full pathname of a source media file

SYNOPSIS

<MCML sourcepath [ +n | -n ] [ maxlength=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the pathname to be returned should be that of the source file associated with a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), no text is returned.

maxlength=n

Indicates the maximum number of characters that should be returned. If less than n characters are used by the returned text, or whenever the maxlength clause is not used, all characters are returned.

DESCRIPTION

The sourcepath instruction is replaced by the pathname of the source file associated with the selected thumbnail. The default is to use the current thumbnail, unless the +n or n clauses are used.

If the user has specified that all source files are to be copied to the output directory, the filename will not include any pathname component. Otherwise, a full absolute pathname will be returned.

Note that if the returned text is to be passed to a JavaScript function, the sourcejspath instruction should be used instead, as it will "escape" any backslashes, allowing a full path to be handled properly by JavaScript.


NAME

table  —  create a table of thumbnails

SYNOPSIS

<MCML table>
…
[ <MCML tablecell> ]
…
[ <MCML emptycell> ]
…
[ <MCML tablenewrow> ]
…
[ <MCML tablebottom> ]
…
<MCML /table>

CLAUSES

None.

DESCRIPTION

The table instruction and its "sub-tags" are used to identify parts of an HTML table that should be placed by the export engine as needed to create a thumbnail table; that is, a table for the display of thumbnail information.

The text that immediately follows the opening table instruction is considered to be the header for the thumbnail table. Text that follows each of the remaining "sub-tags" is associated with that sub-tag. Text may include other MCML tags (except for loops and other tables, as explained below); any such MCML tags will be processed each time the text is used during the building of the table. Association of text with the final sub-tag ends, and processing of the table begins, when the terminating /table instruction is encountered.

The opening table instruction and the terminating /table instruction are required elements. Each of the other "sub-tag" elements is optional, and may be included or omitted as needed. Normally the text contents of each block should be:

Table sub-tag

Contents of the associated block of text

table (the opening tag)

Table header <table>, and the opening of the first row of the table <tr>.

tablecell

Table data about a single table cell, including the opening <td> and closing </td> tags for the cell.

emptycell

Table data about a single table cell with no contents, including the opening <td> and closing </td> tags for the cell.

tablenewrow

The closing of a table row </tr> and the opening of a new table row <tr>.

tablebottom

The closing of the final table row </tr>, and the ending of the table </table>.

 

The order in which these blocks of text are generated by the export engine is as follows:

table (table header)
tablecell (as many times as needed for the current table row)
tablenewrow (if another table row is needed)
tablecell (again, as many times as needed)
(repeat tablenewrow and tablecell groups as needed to finish the table)
emptycell (if needed to finish a table row after no more thumbnails available)
tablebottom (table footer)

Note that the various sub-tags generate no HTML table tags on their own … they merely indicate to the export engine which sections of text should be used when creating the table. Therefore, all required HTML <table>, <tr> and <td> tags must be included by the designer in the blocks of text within a table instruction. (See the "MCML Tutorial" for additional explanation.)

When a thumbnail table is being processed, the current thumbnail is incremented for each new tablecell that is created. Therefore, MCML instructions within the tablecell block and other sub-tags need not worry about finding thumbnail information through relative addressing or other such means; instead, they can simply refer to the current thumbnail and expect it to be the correct one for that location in the table.

Even though the table instruction has been specifically designed for the creation of HTML tables of thumbnails, it is possible to use it for other purposes as well.

Note that, during HTML generation, each block of text generated from a table section is separated from other such blocks with a carriage return. As such, it is strongly suggested that all of the various table instructions and sub-tags should be placed on separate lines by themselves, to underscore this fact and to confirm that the resulting HTML will work properly with the carriage returns included.

The table instruction is regarded as a looping instruction for the purpose of observing the restriction against nested loops; that is, a table instruction may not enclose or be enclosed within a separate repeat or table instruction.


NAME

thumbcomments  —  get the comments text for a thumbnail

SYNOPSIS

<MCML thumbcomments [ +n | -n ] [ maxlength=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the comments to be returned should be those for the thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), no text is returned.

maxlength=n

Indicates the maximum number of characters that should be returned. If less than n characters are used by the returned text, or whenever the maxlength clause is not used, all characters are returned.

DESCRIPTION

The thumbcomments instruction is replaced by the text in the comments field of the selected thumbnail. The default is to use the current thumbnail, unless the +n or n clauses are used.

If no comments are available for the selected thumbnail, no text is returned.


NAME

thumbdiskid  —  get the disk ID for a thumbnail

SYNOPSIS

<MCML thumbdiskid [ +n | -n ] [ maxlength=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the disk ID to be returned should be that for the thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), no text is returned.

maxlength=n

Indicates the maximum number of characters that should be returned. If less than n characters are used by the returned text, or whenever the maxlength clause is not used, all characters are returned.

DESCRIPTION

The thumbcomments instruction is replaced by the original disk ID of the source file as it is stored in the selected thumbnail. The default is to use the current thumbnail, unless the +n or n clauses are used.

If no disk ID is available for the selected thumbnail, no text is returned.

Note that the disk ID will still point to the original location of the source file as recorded in the album, even if the user has chosen to copy the source files to the HTML output directory.


NAME

thumbkeywords  —  get a text listing of keywords for a thumbnail

SYNOPSIS

<MCML thumbkeywords [ +n | -n ] [ maxlength=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the keywords to be returned should be those for the thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), no text is returned.

maxlength=n

Indicates the maximum number of characters that should be returned. If less than n characters are used by the returned text, or whenever the maxlength clause is not used, all characters are returned.

DESCRIPTION

The thumbkeywords instruction is replaced by a comma-delimited list of the keywords for the selected thumbnail. The default is to use the current thumbnail, unless the +n or n clauses are used.

If no keywords are available for the selected thumbnail, no text is returned.


NAME

thumbname  —  get the internally-generated filename for a thumbnail stamp

SYNOPSIS

<MCML thumbname [ +n | -n ] [ maxlength=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the filename to be returned should be that for the thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), no text is returned.

maxlength=n

Indicates the maximum number of characters that should be returned. If less than n characters are used by the returned text, or whenever the maxlength clause is not used, all characters are returned.

DESCRIPTION

The thumbname instruction is replaced by the unique filename of the saved thumbnail stamp image as it was generated during the Export to HTML process. The default is to get the thumbnail stamp filename for the current thumbnail, unless the +n or n clauses are used. As these thumbnail stamp files are always saved to the output directory, no pathname is included in the returned text.

Special: If there is no stamp available for the thumbnail in the album, a common name is assigned to the thumbnail that refers to an expected "common thumbnail stamp" file that should be included in the site design and copied to the output directory. This "common filename" is what will be returned by thumbname for any such thumbnails. The possible common names are:

File Type (extension)

Common Thumbnail Name

MP3

_mcexpt_mp3.gif

MID

_mcexpt_mid.gif

WAV

_mcexpt_wav.gif

Other (file types with no stamps and no web support)

_mcexpt_unk.gif

If a site design does not wish to support these file types, then the common thumbnail stamp files need not be included; however, in any such design the MCML files should test the file type before using the thumbname instruction in an HTML <img> tag. Failure to do so could result in the outward appearance that images are missing from the web page (the "red X" in the browser where the image should have appeared).


NAME

thumbheight  —  get the height in pixels of the thumbnail stamp

SYNOPSIS

<MCML thumbheight [ +n | -n ] [ offset=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the height to be returned should be that of the thumbnail stamp associated with a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), or if the referenced thumbnail is not an image type that is known to web browsers, a size of 0 is returned.

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

DESCRIPTION

The thumbheight instruction is replaced by the height (in pixels) of the thumbnail stamp image associated with the current thumbnail, or of the thumbnail stamp image associated with a thumbnail at a specified offset from the current thumbnail if the +n or n clauses are used.

The returned value is the exact height in pixels of the actual stamp image associated with the selected thumbnail. It does not in any way take into account the native thumbnail size of the album.


NAME

thumbwidth  —  get the width in pixels of the thumbnail stamp

SYNOPSIS

<MCML thumbwidth [ +n | -n ] [ offset=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the width to be returned should be that of the thumbnail stamp associated with a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), or if the referenced thumbnail is not an image type that is known to web browsers, a size of 0 is returned.

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

DESCRIPTION

The thumbwidth instruction is replaced by the width (in pixels) of the thumbnail stamp image associated with the current thumbnail, or of the thumbnail stamp image associated with a thumbnail at a specified offset from the current thumbnail if the +n or n clauses are used.

The returned value is the exact width in pixels of the actual stamp image associated with the selected thumbnail. It does not in any way take into account the native thumbnail size of the album.


NAME

thumbmaxheight  —  get the maximum height in pixels of thumbnail stamps

SYNOPSIS

<MCML thumbmaxheight [ offset=n ]>

CLAUSES

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

DESCRIPTION

The thumbmaxheight instruction is replaced by the maximum height (in pixels) of thumbnail stamp images in the current album, as defined by the native thumbnail size of the album. It does not vary based upon the current thumbnail.

Note that it is possible for individual thumbnails in an albumfile to exceed this value.

An example of the usage of this instruction would be to set the size of cells in a thumbnail table, so that the cell would be an acceptable fit for most or all thumbnail stamps from the albumfile being exported.


NAME

thumbmaxwidth  —  get the maximum width in pixels of thumbnail stamps

SYNOPSIS

<MCML thumbmaxwidth [ offset=n ]>

CLAUSES

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

DESCRIPTION

The thumbmaxwidth instruction is replaced by the maximum width (in pixels) of thumbnail stamp images in the current album, as defined by the native thumbnail size of the album. It does not vary based upon the current thumbnail.

Note that it is possible for individual thumbnails in an albumfile to exceed this value.

An example of the usage of this instruction would be to set the size of cells in a thumbnail table, so that the cell would be an acceptable fit for most or all thumbnail stamps from the albumfile being exported.


NAME

thumbnum  —  get the index number of a thumbnail

SYNOPSIS

<MCML thumbnum [ +n | -n ] [ numformat="spec" ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the index value to be returned should be that of a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), no text is returned.

numformat="spec"

Specifies how the returned value should be formatted. The spec argument takes the form of a printf() format specification, which should specify the formatting of a single integer argument. When the numformat clause is not used, a default format of "%i" is used (which simply returns the number without any leading zeroes). Note that no attempt is made to test the provided spec for validity; rather, it is merely passed to the internal formatting function, so it is important to be certain that a valid spec is used.

DESCRIPTION

The thumbnum instruction is replaced by a value representing the index position of the selected thumbnail. The default is to use the position of the current thumbnail, unless the +n or n clauses are used. The returned value will always be ‘1’ for the first thumbnail being exported, and increments until the last thumbnail is reached.

Note that this index value must not be used to reference thumbnail stamp images, as the Export to HTML engine is free to assign any filenames it sees fit to such files when it creates them.

An example of the usage of this instruction would be the creation of a link to an individual page that is to be associated with a particular thumbnail in a thumbnail table or any other page type that includes multiple thumbnails.


NAME

thumbtableheight  —  get the adjusted height in pixels of the thumbnail stamp

SYNOPSIS

<MCML thumbtableheight [ +n | -n ] [ offset=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the height to be returned should be that of the thumbnail stamp associated with a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), or if the referenced thumbnail is not an image type that is known to web browsers, a size of 0 is returned.

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

DESCRIPTION

The thumbtableheight instruction is replaced by the height (in pixels) of the thumbnail stamp image associated with the current thumbnail, or of the thumbnail stamp image associated with a thumbnail at a specified offset from the current thumbnail if the +n or n clauses are used.

If the thumbnail stamp is larger than the native thumbnail size of the albumfile, the returned value is adjusted to cause the thumbnail stamp to match the native thumbnail size without alterations to the aspect ratio of the thumbnail stamp image.

An example of the use of this instruction would be the definition of the size of a thumbnail stamp image in an HTML <img> tag, where it is desirable to have all thumbnails fit within the available space (such as in a thumbnail table) regardless of their actual size.


NAME

thumbtablewidth  —  get the adjusted width in pixels of the thumbnail stamp

SYNOPSIS

<MCML thumbtablewidth [ +n | -n ] [ offset=n ]>

CLAUSES

+n | -n

An optional numeric value (which must be preceded by a plus ‘+’ or minus ‘-‘ sign) indicating that the width to be returned should be that of the thumbnail stamp associated with a thumbnail at a relative offset from the current thumbnail. Negative values select the thumbnail n positions before the current thumbnail, while positive values select the thumbnail n positions after the current thumbnail. If the resulting thumbnail does not exist (i.e., the offset attempts to select a thumbnail before the first or after the last), or if the referenced thumbnail is not an image type that is known to web browsers, a size of 0 is returned.

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

DESCRIPTION

The thumbtablewidth instruction is replaced by the width (in pixels) of the thumbnail stamp image associated with the current thumbnail, or of the thumbnail stamp image associated with a thumbnail at a specified offset from the current thumbnail if the +n or n clauses are used.

If the thumbnail stamp is larger than the native thumbnail size of the albumfile, the returned value is adjusted to cause the thumbnail stamp to match the native thumbnail size without alterations to the aspect ratio of the thumbnail stamp image.

An example of the use of this instruction would be the definition of the size of a thumbnail stamp image in an HTML <img> tag, where it is desirable to have all thumbnails fit within the available space (such as in a thumbnail table) regardless of their actual size.


NAME

usernum  —  include a numeric integer value provided by the user

SYNOPSIS

<MCML usernum [ offset=n ] [ numformat="spec" ]>

CLAUSES

offset=n

Specifies a value to be added or subtracted from the value before it is returned.

numformat="spec"

Specifies how the returned value should be formatted. The spec argument takes the form of a printf() format specification, which should specify the formatting of a single integer argument. When the numformat clause is not used, a default format of "%i" is used (which simply returns the number without any leading zeroes). Note that no attempt is made to test the provided spec for validity; rather, it is merely passed to the internal formatting function, so it is important to be certain that a valid spec is used.

DESCRIPTION

The usernum instruction is replaced by the integer value that the user has entered into the "user-supplied value" field on the Export to HTML dialog. The precise caption of this field is determined by the capabilities file for the selected site design.

If no value is available, the default string of "0" will be returned.


NAME

usertext  —  include a text string provided by the user

SYNOPSIS

<MCML usertext [ maxlength=n ]>

CLAUSES

maxlength=n

Indicates the maximum number of characters that should be returned. If less than n characters are used by the returned text, or whenever the maxlength clause is not used, all characters are returned.

DESCRIPTION

The usertext instruction is replaced by the text that the user has entered into the "user-supplied text" field on the Export to HTML dialog. The precise caption of this field is determined by the capabilities file for the selected site design.

If no text is available, the instruction will simply be removed and nothing will be inserted in its place.


Capabilities Files

Since site designs can vary widely in their capabilities, it is desirable to be able to modify the Export to HTML dialog to suit the capabilities of the selected site design (that is, the design whose name is currently selected in the drop list of that same dialog). In addition, we would often like to be able to provide some information about the site design (appearance, capabilities, and limitations) to the user before they attempt to export using that design.

To facilitate this, two optional files may be placed in the site design directory (along with the MCF file, MCML files and other associated files). The filenames of these files are _caps.ini and _caps.bmp, and they are referred to collectively as "capabilities files", as they define the capabilities of the associated site design to the Export to HTML user interface. They are not added to the MCF file, and they do not affect the actual Export to HTML process in any way … their only function is to customize the dialogs as needed to make the use of the associated site design as clear to the user as possible.

The capabilities files are optional. If they are not present, the dialogs will be configured in a standard fashion whenever that site design is selected, and the Info button (for displaying descriptive information about the selected site design) will be disabled. Note that the _caps.bmp file will not be used unless the _caps.ini file is also present.

The _caps.ini file contains one or more option lines that describe the capabilities of the site design, along with lines of plain text that are displayed to the user when the Info dialog for that site design is shown. Any options that are omitted from the _caps.ini file will be set to their default values (as if no capabilities file was present at all). Each of the option lines begins with a pound sign (#) which is followed immediately (with no intervening whitespace) by a keyword that describes that option, which is followed immediately by an equals sign (=). Following the equals sign is a string or value that describes the desired setting of that option for the associated site design. The available keywords are listed in the following table:

#UsesSourceFiles

If the site design needs to link to or copy source files during the export operation, this option should be set to 1 or "Yes". If source files are not used by the site design, this option should be set to 0 or "No". The latter setting causes the "Linking" options in the Export to HTML dialog to be disabled. The default setting when option is not present is "Yes".

#Text1Description

If the site design utilizes one or more instances of the usertext instruction, a brief descriptive caption for the associated text field (which appears under "Design-specific fields" in the dialog) must be provided using this option. If this option is not present, or if no caption is provided, the associated text field is disabled, and any occurrences of the usertext instruction in the MCML for the site design will be replaced during the export with a null string (i.e., nothing).

#Text1Default

If the #Text1Description option (above) has been used, a default value for the associated text field may optionally be specified using this option. If this option is not present, there will be no default text for the associated field. (See the NOTE below for additional information.) This option must follow the #Text1Description option.

#Num1Description

If the site design utilizes one or more instances of the usernum instruction, a brief descriptive caption for the associated numeric field (which appears under "Design-specific fields" in the dialog) must be provided using this option. If this option is not present, or if no caption is provided for the option, the associated field is disabled, and any occurrences of the usernum instruction in the MCML for the site design will be replaced during the export with the value ‘0’.

#Num1Low

If the #Num1Description option (above) has been used, this option may be optionally used to specify the lowest permissible value for the field. If this option is not present, the lower limit will default to a value of ‘-32768’. This option must follow the #Num1Description option.

#Num1High

If the #Num1Description option (above) has been used, this option may be optionally used to specify the highest permissible value for the field. If this option is not present, the upper limit will default to a value of ‘32767’. This option must follow the #Num1Description option.

#Num1Default

If the #Num1Description option (above) has been used, a default value for the associated numeric field may optionally be specified using this option. If this option is not present, the field will default to a value of ‘0’. (See the NOTE below for additional information.) This option must follow the #Num1Description option.

NOTE: each time that the Export to HTML dialog is initially displayed, the last selected site design will be selected by default, and any text or numeric values that the user had last entered for items in the "Design-specific fields" box will be restored, rather than the defaults from the capabilities file. If the user switches to another site design, and then switches back, their old settings are lost, and the defaults revert back to those given in the capabilities file.

Any blank lines or lines beginning with a colon (:) are ignored (the colon may be used to insert comments in the file). All other lines (i.e., non-blank lines that do not begin with either a colon or a pound sign) are assumed to be a text description of the site design. All such "description lines" are concatenated together in the order they appear in the _caps.ini file (with carriage returns removed and a space inserted between each line for readability), and the resulting text is displayed to the user in the Info dialog for the associated site design.

The _caps.bmp file may any standard Windows BMP image file, containing one or more screen captures or other graphics deemed appropriate to display to the user in the Info dialog for the associated site design. For the best results, it is recommended that the image be pre-scaled to an approximate size of 280 pixels wide by 210 pixels tall. If the _caps.ini file is present for a site design, but a _caps.bmp is not provided, the text "no screen available" will be shown in its place in the Info dialog.


MCML Tutorial – Creating a simple site design using MCML

The easiest way to get started in creating site designs using MCML is to first design an HTML page with the desired appearance. (Obviously it will be helpful to keep in mind the sorts of things that MCML can and cannot do as you are designing the HTML.) As you become more comfortable with MCML you might decide to create site designs from the ground up in MCML, without an ensuing HTML step, but a distinct advantage to designing the HTML first is that you can more easily see what works visually, and what doesn’t. We will take this approach as we create a fairly simple HTML site design and then convert it to MCML so that it may be generated automatically by the Export to HTML capability of Jasc Media Center Plus.

We’ll start by writing some straightforward HTML for showing one or more pages of thumbnailed images:

<html>
<title>Gallery</title>
<body>

<h1 align=center>Gallery</h1>
<p align=center>page 1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="page2.htm">page 2</a></p>
<br><hr width=400 align=center><br>

<table align=center>
<tr>
<td align=center valign=top width=120 height=110>
<img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>
<td align=center valign=top width=120>
<img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>
<td align=center valign=top width=120>
<img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>
</tr><tr>
<td align=center valign=top height=110>
<img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>
<td></td>
<td></td>
</tr>
</table>

<hr width=400 align=center>
</body></html>

Notice that we added a place near the top of the page for links to multiple pages. Exactly which chunks of text are linked, and to what names, don’t matter to us right now; we just needed to decide how we wanted linked text and non-linked text to look. For the same reason, we added enough thumbnails (just using the same image file for each) to create a table with multiple rows and multiple columns, so that we feel comfortable with how the spacing will look. We also made sure to use some empty cells on the last row, for reasons that will become clear later.

When we view this page with a web browser, we see something like the following screen:

 

Now let’s get started on creating an MCML file for this page design. Copy the HTML file to a new filename, "default.mcml", and open that file for editing with a text editor. (We use "default" whenever we want any HTML pages generated from this MCML file to be named with a name specified by the user; we could chose another name, but then the HTML files would have that name as well.)

First let’s take care of some of the easiest changes. Right at the top of the file we see some page titles that currently say "Gallery":

<html>
<title>Gallery</title>
<body>

<h1 align=center>Gallery</h1>

Wouldn’t it be nice to have the title of the albumfile shown in those places instead? To do so, we only need to substitute the appropriate MCML tag for each occurrence of the title "Gallery", that tells the Export to HTML process that we want the current albumfile title to appear here instead. The MCML tag we need for this is the albumtitle tag:

<html>
<title><MCML albumtitle></title>
<body>

<h1 align=center><MCML albumtitle></h1>

Note that we are only using capital letters for the "MCML" portion of each of the MCML tags to set them off from the surrounding HTML text. Like HTML tags, MCML tags are not case sensitive; we could just as easily use all capital letters for the HTML tags and all lowercase for the MCML tags in order to differentiate them, or the same kind of letters throughout if we aren’t concerned about it.

Now let’s get down to the core of changing this page into MCML. The primary difficulty we have to address is to figure out how to place thumbnails within a table using MCML. What makes this hard is that, unlike when we design an HTML page, we can’t know exactly how many thumbnails are going to be in the table when it is actually generated (during an Export to HTML process). What we need to do is divide up the different changes that occur during the generation of a table, and tell the Export to HTML engine (via MCML instructions) what to do for each of those changes.

Here is the basic set of "tasks" for generating a table in HTML, in order of execution:

  1. Start the table with "<table>" and begin the first row with "<tr>"
  2. Create cells (columns) with <td> … data … </td> until we get to the end of the row
  3. End the row and start a new row "</tr><tr>"
  4. (3.1. Repeat steps #2 and #3 until we get to the end or run out of data)

  5. Optionally create empty columns to the end of the row if we run out of data in the middle of a row (to maintain the alignment of columns with the preceding rows)
  6. End the table with "</tr></table>"

Since step #3.1 is simply a repeat of steps #2 and #3, we can see that there are five different "tasks" that happen in the course of creating a typical HTML table. Two of them (#1 and #5) only happen once (at the start and end of the table, respectively), and the other three may be repeated many times in between.

When creating an MCML file, our task is to provide information about each of these five tasks to the Export to HTML engine, so that it can build the table as it needs to, depending upon the set of thumbnails it has to work with. To do this, MCML provides a unique instruction to label each of the five required tasks. Those labels, numbered to match the tasks described above, are:

  1. Table
  2. Tablecell
  3. Tablenewrow
  4. Emptycell
  5. Tablebottom

To begin a table in MCML, we always start with the <MCML table> tag, which also marks the beginning of the "task #1" block of code. Then, we insert each of the other "sub-tags" as needed, to mark the blocks of code that are needed for the rest of the "tasks". After we have provided all of the needed information, we end the table with the <MCML /table> terminating tag. The other four tags are considered to be "sub-tags" of the table tag … they are only valid within a block of MCML table information. There are no terminating tags for any of the table sub-tags; the MCML interpreter assumes that whatever text follows such a tag is part of that section of the table, until either another sub-tag or the overall table terminator is encountered. All of the subtags are optional; if any of the sections is not provided, then no text will occur in the HTML output file whenever that part of the table is being generated. (Generally, however, most of these sub-tags will be needed.)

Now, how do we take all of this information and create a working MCML table? Believe it or not, it’s much easier than the above may have made it sound. Here is the table portion of the original HTML code we are working from, with each line numbered with the task it represents (as defined earlier):

1: <table align=center>
1: <tr>
2: <td align=center valign=top width=120 height=110>
2: <img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>
2: <td align=center valign=top width=120>
2: <img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>
2: <td align=center valign=top width=120>
2: <img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>
3: </tr><tr>
2: <td align=center valign=top height=110>
2: <img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>
4: <td></td>
4: <td></td>
5: </tr>
5: </table>

Notice that the lines associated with task #2 (individual cells of data) are actually a number of repeats of almost exactly the same two lines. If this table had more than two rows of data, there would similarly be multiple groups of lines associated with task #3. The number of times those groups of lines need to be repeated depends entirely upon how much data is being shown in the table … but that is for the Export to HTML engine to determine, and not our job. We only need to tell the engine how to create a single cell (for task #2) and how to start a single new row (for task #3).

Here is the above table, after having been initially divided into sections and labeled with the appropriate MCML tags:

<MCML table>
<table align=center>
<tr>
<MCML tablecell>
<td align=center valign=top width=120 height=110>
<img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>
<MCML tablenewrow>
</tr><tr>
<MCML emptycell>
<td></td>
<MCML tablebottom>
</tr>
</table>
<MCML /table>

Notice that all of the HTML table tags for rows, columns, and the table itself still need to be included in the text; the only job of the MCML tags is to identify the various table sections to the Export to HTML engine. This is because it is very often desirable to add additional arguments to the HTML table tags, in order to make things look exactly like is intended. Furthermore, it is quite possible to create an MCML table that doesn’t actually generate an HTML table, but rather some other sort of arrangement of thumbnail data … this would not be possible if the MCML table tags always "forced" the equivalent HTML tags.

(Most MCML tables will look a lot like the above … so much so that it may behoove MCML designers to save a copy of a table like the above as a template for the creation of future MCML tables.)

But we’re not done yet. If we stopped here, the generated table would have the correct number of rows and columns (matching whatever set of thumbnails are being exported at the time), but all of the cells would still show a single image and name, specifically "shot17.jpg". That wouldn’t be very useful!

This is easily solved, but first we need to briefly touch on one of the tasks that the Export to HTML engine performs when it is executed. Whenever thumbnails are being exported by the Export to HTML process, and those thumbnails have individual thumbnail images associated with them, the program creates a set of small image files (we’ll be referring to them as "thumbnail files") in the output directory, one for each of the thumbnails. It also keeps track of the unique names it has assigned to each of those thumbnails, so they can be used during the generation of HTML files. The names of these thumbnail files will usually have nothing in common with the source image files they are associated with, so you can’t "guess" as the filenames in your MCML files … you have to use the MCML thumbname instruction to get at them. We have a similar MCML instruction, sourcename, that will give us the name of the actual source file the thumbnail is associated with … this is the appropriate tag to use when showing the name of the file to the viewer.

If you’re wondering about how to define which thumbnail name is selected in a table with multiple thumbnail names, you can relax … you don’t have to! The Export to HTML engine is smart enough to automatically provide information (whether that information be filenames, source names, comments, keywords, or whatever) for the correct thumbnail for each position within the table. All you need to do is tell it where to put that information in a single cell, and the engine does the rest for you.

Here is the tablecell code that we want to change to refer to the correct thumbnail and source file names:

<MCML tablecell>
<td align=center valign=top width=120 height=110>
<img src="shot17.jpg" alt="shot17.jpg" width=80><br>shot17.jpg</td>

Once we’ve replace the references to "shot17.jpg" in the above code with the needed MCML tags to get the correct filenames, we end up with this:

<MCML tablecell>
<td align=center valign=top width=120 height=110>
<img src="<MCML thumbname>" alt="<MCML sourcename>" width=80><br>
<MCML sourcename maxlength=12></td>

Pay special attention to the fact that the MCML tags appear inside quotes on some of the above lines. Remember that, as described in the Overview section of this document, MCML works by replacing its tags with plain text, which is then evaluated as HTML whenever the generated page is viewed in a browser. If the text (such as the source name above) may have a space in it, and having a space in it would require the text to be quoted in the HTML tag, then the MCML tag itself must be quoted as well. The advantage of this is that it allows the same MCML tags to be used in any context within the HTML document … you don’t have to remember different MCML tags for using the name in an HTML tag, versus simply printing the name as text.

But wait a moment … what’s this "maxlength" thing in the last MCML tag for? If you look back at the original HTML code, you’ll note that the last reference to "shot17.jpg" is actually printed as plain text below the thumbnail image of the file.

One problem with not knowing in advance what source files will be included in our generated HTML files is that filenames can easily be long enough to screw up the appearance of our HTML. (The reason web designers don’t usually encounter this problem is that they know all of the files that will be included, and can alter names and formatting to suit their needs.) What we need is a way to keep filenames from becoming so long that they screw up the appearance of our HTML output. But when you consider that the size of text shown in a browser can vary based upon the selected font, settings on the browser, settings on the viewer’s computer, etc., you realize that it is virtually impossible for the export routine to be able to pre-calculate text lengths to avoid such problems.

One solution is to provide a simple capability to never use more than a certain defined number of characters; when used properly, this can prevent such problems in 95% of cases. Accordingly, all of the MCML tags that output text data about thumbnails include an optional maxlength clause to do this. If the maxlength clause is not used, all characters available will be sent to the output, so make sure you’ve thought carefully about this before using (or failing to use) the maxlength clause. Note that you will never want to use maxlength for a filename being embedded within an anchor "<a>" or image "<img>" tag, as the filename will obviously not be valid if some of the characters have been cut off. The maxlength clause need only be considered when a filename is to be shown as plain text, and is particularly valuable when that text is to appear in a table or any other tightly formatted HTML construct.

The full MCML file now looks like this:

<html>
<title><MCML albumtitle></title>
<body>

<h1 align=center><MCML albumtitle></h1>
<p align=center>page 1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="page2.htm">page 2</a></p>
<br><hr width=400 align=center><br>

<MCML table>
<table align=center>
<tr>
<MCML tablecell>
<td align=center valign=top width=120 height=110>
<img src="<MCML thumbname>" alt="<MCML sourcename>" width=80><br>
<MCML sourcename maxlength=12></td>
<MCML tablenewrow>
</tr><tr>
<MCML emptycell>
<td></td>
<MCML tablebottom>
</tr>
</table>
<MCML /table>

<hr width=400 align=center>
</body></html>

But before we can use this MCML file with the Export to HTML function, we need to create one more file. This file is always named "default.mcf", and we’ll refer to it as the "MCF file", or the "master control file" (with obvious acknowledgements to the movie TRON).

The MCF file is the first file at which the Export to HTML export engine looks. It tells the engine where to find all of the MCML files that need to be used to create the associated site design … and, perhaps even more importantly, how to determine the number of pages to create.

Each line in an MCF file will be either a copy command or a gen (generate) command. Copy commands simply instruct the Export to HTML engine to copy the named file to the output directory without modification. These may include static image files (backgrounds, common thumbnails, etc), JavaScript source files, HTML files that will never need to be altered, etc. MCML files should never be used with the copy command.

Gen (generate) commands, on the other hand, indicate the location of MCML files that need to be processed to create HTML files for the site. These lines also describe how the engine should go about deciding the number of files that need to be created. There are a number of different ways in which this can be specified, depending upon the needs of the site design. (For full information on all of the methods that are available, see the reference page for the gen command.)

For our purposes, let’s tell the export engine to fit as many thumbnails as possible into the table, without making the table so big that it always requires scrollbars on the browser. Here, then, is the single command that needs to be in our default.mcf in order to export web pages in our new site design:

gen default xtotal=640 ytotal=480 xpadding=40 ypadding=30>

In the above line, "default" is the name of the MCML file (it must appear without the ".mcml" extension). The rest of the clauses that appear on the line work together as a unit to describe the amount of space available for a table of thumbnails in this MCML page.

The xtotal and ytotal clauses define the amount of space (in pixels) horizontally and vertically that should be treated as available for the display of thumbnails in a table. Not that with the values we’ve specified above, a full page of thumbnails will still create a vertical scrollbar for users with their screen resolution set to 640x480 (because the title information, browser menubars, etc. also use up some of the available vertical space). We could shrink the ytotal value even further to prevent that, but we don’t want to make the table so small vertically that we leave large amounts of the screen unused at higher resolutions, so we’ll leave it like this. (Making these types of choices should be a familiar process to anyone who has ever designed a web page … the need for such decisions is not specific to the Export to HTML function.)

The xpadding and ypadding clauses define how much space (again in pixels) above and beyond the native thumbnail size is required for each thumbnail. Example: a table cell may be formatted in such a way that it includes borders and or text around the thumbnail, which of course uses up some amount of extra space on the screen between thumbnails. The amount of extra space that is required by such additions is what should appear in the xpadding and ypadding clauses.

When the Export to HTML process actually runs, it uses this information, in conjunction with its own information on how many thumbnails are being exported and the native thumbnail size of those thumbnails, to determine how many thumbnails can appear on each page of our design. Then it can determine how many HTML pages will need to be generated from our single MCML page in order to have exported all of the thumbnails.

(A programmers’ note: if you’re wondering why this table size information couldn’t simply be embedded in each of the individual MCML files, consider that one MCML file may at times need to ask for information about the number and/or layout of other MCML files. That, plus the requirement for the copy command, necessitates a separate, "top-level" file for such information.)

Now that we have our two files, "default.mcf" and "default.mcml", we are ready to try the site design out in Jasc Media Center Plus for the first time. To do so, we need to install this site design in a subdirectory below the "MCML" directory, which is in turn below the main application directory where Jasc Media Center Plus resides. Create a subdirectory called "Tutorial" under the "MCML" directory, and copy our two files into this new directory. (The directory name, "Tutorial" in our case, is important because it is this directory’s name that will be shown to the user in the Export to HTML dialog when they are choosing which site design to use.)

Now we are ready to run Jasc Media Center Plus, load or create an album of images as usual, select Export to HTML from the File menu, and select the "Tutorial" site design from the drop list in the Export to HTML dialog. If we get any error messages after clicking on the OK button, we need to go back and look at our MCML code to make sure we didn’t make any typing errors.

If the Export to HTML process completed without any error messages, the result should be one or more HTML files in the output directory that we selected. And when we double-click to view the first HTML file in a web browser, it should look something like this:

 

Note that the number of thumbnails shown may vary from this example, depending upon the native thumbnail size of the album that has been exported. We’ll talk more about that later. Also note that the user’s specified filename will always have a number appended to it with this design, even if only one page of thumbnails has been generated. This is necessary because we have not defined the default page type as unique, and anytime that a page type is not defined as unique, all filename functions of the Export to HTML engine (not to mention loops in the MCML pages themselves) have to assume that more than one page might be present. This can be avoided by always creating a unique default page type (such as a framed titlebar, or a menu page for selecting one or more actual thumbnail pages).

This page doesn’t look too bad … however we can easily see a few things that need further adjustment. The most obvious one is the index of page numbers at the top; it isn’t changing to match the number of pages of thumbnails that may have been created during the export process, and that hardcoded link to page 2 certainly doesn’t point to the correct HTML file either. Obviously we still need to add a little bit more intelligence to our MCML file so that it will work properly no matter how many or few pages of thumbnails we throw at it, and so that the viewer can access all of the pages that are generated.

Here’s the block of HTML that needs to be changed:

<p align=center>page 1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="page2.htm">page 2</a></p>

If this task required a separate entry for each thumbnail we would use an MCML table instruction. However, what’s needed here is an entry for each HTML page that is being generated from this MCML file. For such circumstances, MCML provides a different, more generic way to output a block of text multiple times – the MCML repeat instruction. This instruction can be set to loop a fixed number of times, or (more useful for our needs here) to loop once for each generated page of a particular page type. A terminating /repeat tag encloses the set of lines that are to be repeated.

For our purposes we will just be using the same page type that is currently being generated (since it is the only one we have created for this site design). It is very worthwhile, however, to note that repeat can be used to loop based upon page types other than the current, a capability that is invaluable when creating a site design with multiple page types (one that utilizes frames and menus, for example).

We will use the repeat instruction to show the correct number of pages, but the next question is "how are we going to show the different page numbers?" The answer to this is another MCML instruction that is only found within repeat loops – the loopcount tag. Internally MCML keeps a numeric variable that is initialized to 1 when a loop starts, and increments by 1 upon each subsequent execution of the loop. The loopcount instruction simply takes this number and drops it into the text output at the specified point. As you will see shortly, we will be making use of this instruction in both the text output and the HTML anchor tags of the index section of this design.

But there is still one more issue that must be addressed. We would like for the current page number in the index to not have a link (because any such link would cause it to refer to itself pointlessly, and also because having the current page shown without a link helps identify the current page to viewers).

For this task MCML provides another instruction that will be familiar to those with programming experience – the if instruction. This instruction allows a block of text (optionally including other MCML instructions) to be used or skipped, depending upon the results of a particular test that is performed by the if instruction. As with the repeat instruction described earlier, a terminating /if tag marks the end of the group of lines that are to be used or skipped depending upon the results of the test.

There are a number of different types of tests available for use with the if tag, all of which are fully documented on the reference page for the if instruction. For our purposes we will be using a single test called loop_eq_page, which tests if the loopcount value matches the current page number. Note that this particular test can only be used inside a repeat block (because it uses the loopcount value), and that it can only test the page number of the current page type (there is no "current page" for page types other than the current type).

After incorporating all of the above, the resulting MCML for creation of the index of page numbers looks like this:

<p align=center>
<MCML repeat foreach=default>
<MCML if loop_eq_page>
page <MCML loopcount>
<MCML else>
<a href="<MCML htmlname><MCML loopcount>.htm">page <MCML loopcount></a>
<MCML /if>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<MCML /repeat>
</p>

Note the MCML else statement that appears in the middle of the if block. This should be familiar to anyone who has done any programming … it specifies that the block of code following it should be used if the test in the enclosing if statement failed, rather than succeeded. Therefore, the code here outputs a page number without a link "if the loopcount equals the current page number" … otherwise it outputs the page number with a link.

Also note that we need to build the filename for the HTML anchor tag ourselves, using the name that the user assigns to the page (remember, since this is the ‘default.mcml’ file, the HTML files will be renamed to the user’s selected name) and the loop counter.

We’re almost there, but there is one more thing we should consider. The export process is already calculating the number of thumbnails to show based upon the native thumbnail size of the albumfile in question, but as seen in the lines below, our MCML is always forcing the thumbnails to be 80 pixels wide:

<td align=center valign=top width=120 height=110>
<img src="<MCML thumbname>" alt="<MCML sourcename>" width=80><br>

But what if we want to display the thumbnails at their full resolution, no more and no less? To do this, we would need to dynamically change all of the numbers shown in the above lines to match the size of the thumbnails in the exported album.

MCML provides numerous ways to retrieve thumbnail and image size information, each of which vary slightly in their functionality to fit the specific needs of the site design. For our purposes we will use three of these instructions, thumbmaxwidth, thumbmaxheight, and thumbtablewidth:

All of the MCML instructions for returning thumbnail sizes also provide an optional offset clause, which can be used to adjust the returned size by some positive or negative integer value. We will use this with thumbmaxwidth and thumbmaxheight to leave some extra space between the thumbnail images, and to allow room for the filename. Looking at the above MCML lines, and remembering that we designed the original page with 80x80 thumbnails in mind, we can see that we allowed 40 pixels of extra horizontal space and 30 pixels of extra vertical space for each cell of the table, so we’ll use those values for the offsets. (If you go back and look at the "default.mcf" file for our site design, you’ll see that the xpadding and ypadding values exactly match these offset values, and not by chance either.)

Here, then, are the changes we’ll make to the table cell section:

<td align=center valign=top width=<MCML thumbmaxwidth offset=+40>
height=<MCML thumbmaxheight offset=+30>>
<img src="<MCML thumbname>" alt="<MCML sourcename>"
width=<MCML thumbtablewidth>><br>

After all of the changes listed above have been incorporated, the final MCML file looks like this:

<html>
<title><MCML albumtitle></title>
<body>

<h1 align=center><MCML albumtitle></h1>

<p align=center>
<MCML repeat foreach=default>
<MCML if loop_eq_page>
page <MCML loopcount>
<MCML else>
<a href="<MCML htmlname><MCML loopcount>.htm">page <MCML loopcount></a>
<MCML /if>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<MCML /repeat>
</p>

<br><hr width=400 align=center><br>

<MCML table>
<table align=center>
<tr>
<MCML tablecell>
<td align=center valign=top width=<MCML thumbmaxwidth offset=+40>
height=<MCML thumbmaxheight offset=+30>>
<img src="<MCML thumbname>" alt="<MCML sourcename>"
width=<MCML thumbtablewidth>><br>
<MCML sourcename maxlength=12></td>
<MCML tablenewrow>
</tr><tr>
<MCML emptycell>
<td></td>
<MCML tablebottom>
</tr>
</table>
<MCML /table>

<hr width=400 align=center>
</body></html>

Now, when we export an album with a native thumbnail size of 120 x 120 to our site design, we get output that looks something like this:

 

And if we then export an album with a native thumbnail size of 60 x 60 to the same site design, we get something like this:

Notice that both exported albums now occupy roughly the same amount of room horizontally in the browser window, even though the size of the thumbnails has changed greatly. This now works because we have given the Export to HTML engine enough information to be able to recalculate the page and table contents based upon the contents of the exported album. Also notice how the number of pages shown in the index at the top of the screen was changed when the size of the thumbnails changed (since the number of thumbnails that could appear on a single page was altered).

This is only the beginning of what is possible when creating site designs with MCML. For example, we could easily use ‘if page’ tests combined with relative addressing for HTML pages (using pagename) and a couple of image files (which we would include by using the copy command in the MCF file), to provide graphical arrows for moving back and forth through the pages. We could add ‘if filetype’ tests and handle any non-image thumbnails in a completely different manner from image thumbnails. We could create a separate MCML source to generate a framed menu of pages. We could display other information about the images, either under the thumbnails or on separate, linked pages. We could create tables of thumbnails that only give file information and links, rather than actually showing the thumbnails. Indeed, the possibilities are very nearly endless.

Now it’s your turn. Jump in and try something!

 


GLOSSARY

album (or albumfile)

The basic type of Jasc Media Center Plus document, which contains thumbnails and information about a set of image and/or multimedia files that are stored on fixed and/or removable disks.

current thumbnail

The Export to HTML engine always has a notion of the current thumbnail whenever an HTML page is being generated. The first thumbnail assigned to the page being generated will be the current thumbnail, except when a thumbnail table block is in use, when the current thumbnail is the thumbnail assigned to the current cell of the table.

instruction clause

Any additional text elements within an MCML instruction, that follow the instruction keyword. Clauses are used to customize the function of the MCML instruction to the needs of the current MCML file.

instruction keyword

The first word after "MCML" in an MCML tag, that identifies the type of MCML instruction.

MCF file

A unique file (one for each site design) that specifies, either directly or indirectly, how many of each page type are to be generated. This file must always be named "default.mcf". This file is also referred to as the "master control file".

native thumbnail size

The default size of thumbnails specified within a particular Jasc Media Center Plus albumfile. Users can alter this size on a per-album basis. It is possible that not all thumbnails in the albumfile will conform to this size, but typically most will.

page type

A page of a certain design and/or appearance. A single MCML file defines each page type. One or more HTML pages of a single page type may be generated when the site design is exported. Anything that will eventually exist as an HTML file is treated as a page type.

relative addressing

Use of the +n and n clauses (available for many MCML instructions) to get information about a thumbnail or page other than the current one.

site design

An overall structure of an MCF file, one or more page types and all associated files needed that has been created to form a cohesive output of HTML files, which can display thumbnails and/or other information to the user in a web browser.

thumbnail stamp

The small "thumbnailed" version of an image, normally shown for each image and/or media file in a Jasc Media Center Plus album, that has been written to the output directory as a small image file for use with generated HTML pages.