Template Developer Kit - Magic Gallery Creator

MagicScript Template Developer Kit

The template developer kit is intended for more advanced users of Magic Gallery Creator. The information in this kit will allow you to create your own templates to create custom galleries, online stores or other collections of images and text.

Magic gallery is flexible enough to build the most complicated and demanding templates for personal and professional websites. The MagicScript template format gives you full control over your images, tables, links and pages. We are also constantly improving the template language to allow for more flexibility, if you have a suggestion please let us know.

Primer

A template is a simple text file format with text, HTML and template tags. The most basic template looks like this:
<html>
  <body>
    <%PHOTO%>
  </body>
</html>
Magic Gallery Creator will read this template and substitute an HTML image tag for every photo tag that it sees. In this example the <%PHOTO%> will be replaced with <img src="firstimage.jpg"> where firstimage.jpg is the name of the first file selected in Magic Gallery.

The above template will produce a simple web page with one photo. You can place additional template tags into a template to create tables, links and even to prompt the user for additional information.

This is the foundation of creating template pages. Once you create a template page you can place the template into the template folder of Magic Gallery Creator. You can also place a .preview image in that directory to give your template a preview.

The template directory is typically “C:\Program Files\magic gallery\templates“ but can vary between different computers. The template file must end in the .htm extension to be recognized by Magic Gallery.

If you are interested in writing templates we recommend you take first look at the templates provided with Magic Gallery and use this document as a reference when you have questions.

Template Tags

Tag Name

Description

<%PHOTO%>

Places a photo on the page

<%PHOTOLIST%>

Places a list of photos on the page

<%THUMBNAIL%>

Places a thumbnail image on a page and links to it.

<%OVERFLOW%>

Allows you to process remaining images on another page

<%PICTURENAME%>

Places the name of the picture on the page

<%PICTURELINK%> Places a link to another picture using the <a href> tag

<%PICTUREURL%> Places the full URL to a picture without a tag

<%COPYPICTURE%> Copies a picture from the template directory into the folder of the gallery being created.

<%GETTEXT%> Prompts the user to enter information.

<%GETCOLOR%> Prompts the user to pick a color

<%GETDATA%> Gets Data from an excel document

<%HTMLNAME%> Places the name of the HTML page being generated.

<%HOMEURL%> The URL of the galleries first page. Used to return to the gallery index.

<%INTLTEXT%> Returns the international text for a specified string.

<%FTPSITE%> The text entered into the FTP field of magic gallery.

<%WIDTH%> Places the width of the current image on the page

<%HEIGHT%> Places the height of the image on the page

<%PAGES%> Places a list of overflow pages in a page list

<%Keyword%> Places a random keyword or phrase on your page

<%BannerAd%> Places a random banner ad on the page

<%CurrentPicture%> Places the number of the current picture

<%PictureCount%> Places the total number of photos

<%PHOTO%>

This tag places a photo on a page. The tag gets replaced with an image tag at runtime: <img src=”filename.jpg”> . Photos will be resized and placed into a gallery directory that is a peer to the HTML file thatyou specify. If you save your gallery to C:\My Documents a gallery directory will be created in my documents folder to hold the pictures from the gallery. The photo name will be the same as the original image name with the jpg extension.

Optional Parameters

Description

Default Value

Imagesize

Specifies the maximum height or width to resize an image in pixels

original image size

target
Specifies the location where images will be placed relative to the current html file
current directory

altdata
Specifies alt tag text to be extracted from an excel data file blank



Examples:

           Place the original photo on the page
           <%PHOTO%>
           Place a photo wiyh maximum size of 300 in the current directory
           <%PHOTO imagesize=300 %>       

           Place a photo with maximum size 300 in the imagefolder directory
           <%PHOTO imagesize=300 target="imagefolder" %>   
           Place a photo in the current directory set the alt text to the 
           description column in an excel data f file 
           <%PHOTO imagesize=300 atltext="Description" %>   
Notes: After each photo is parsed the following photo will be the next photo in the Magic Gallery list. Photos will not repeat unless you add multiple photos in Magic Gallery Creator.

<%PHOTOLIST%>       <%/PHOTOLIST%>

Places a list of photos on a page, replaces the tag with the parsed contents of the photolist. This template tag is a matched tag, this means that it has an open and a close tag. If you include one without the other your template may have problems. The tag body can contain any other tags.

Optional Parameters

Description

Default Value

Count

Specifies ho many times the photo list should be repeated

Repeat until all photos are used

Examples:

Display 3 photos:

<%PHOTOLIST count=3 %>
    <%PHOTO%> <br>
<%/PHOTOLIST%>

Display all the photos with some text:

<%PHOTOLIST %>
   Odd Picture: <%PHOTO%>
   Even Picture: <%PHOTO%>
<%/PHOTOLIST%>

Tip: Photolists can be nested!!! This will allow you to create a photo table.

Display a 3x3 table of photos:

<table border=1>
<%PHOTOLIST count=3 %>

<tr>
<%PHOTOLIST count=3 %>
<td>
<%PHOTO%>
</td>
<%/PHOTOLIST%>
</tr>

<%/PHOTOLIST%>
</table>

Display a table of photos that is 3 photos wide and uses all the photos:

<table border=1>
<%PHOTOLIST %>
<tr>
       <%PHOTOLIST count=3 %>
       <td>
       <%PHOTO%>
       </td>
    <%/PHOTOLIST%>
</tr>
<%/PHOTOLIST%>
</table>

<%THUMBNAIL%>

This tag places a thumbnail image on a page and links to the larger picture.. This tag is replaced with an image tag nested in an anchor tag. You can specify the size of both the image and the thumbnail. You can also specify the page that should contain the thumbnail.

Usage:    <%THUMBNAIL thumbnailsize=200 template=image.htm %>:


Optional Parameters

Description

Default

Imagesize

Specifies the maximum height or width to resize an image in pixels

Original Image

Thumbnailsize

Specifies the maximum width and height of the thumbnail

150

template

Specifies the template file that should be parsed to create the full size page for the image.

The default is to link directly to the larger image without a template

target
Sets the location where images will be saved Default value is the current directory

altdata
Sets the alt text data for the thumbnail image that is pulled from the column of an excel file.
blank

discard
If this is set to true the tag will not produce any html output.
blank

frametarget
If this is set this will redirect the thumbnail link to a specific frame
blank

Examples:

      Create a thumbnail that’s 150px that links to the original image:
      <%THUMBNAIL %>

   Create a thumbnail that’s 50px that links to the original image:
     <%THUMBNAIL thumbnailsize=50 %>

     Create a thumbnail that links to a larger image parsed by template image.htm:
     <%THUMBNAIL thumbnailsize=50 template=image.htm %>

     Create a thumbnail that places the image files in the folder thumbnails.
     Also fill in alt text from the Excel column 'title'. For more info on using excel data see here:

      <%THUMBNAIL thumbnailsize=50 altdata="title" target="thumbnails" %>

    Create a list of four thumbnails that link to a page containing the larger picture

<%PHOTOLIST count=4 %>
      <%THUMBNAIL thumbnailsize=200 template=image.htm %>
<%/PHOTOLIST%>

      In the above examples the image.htm file would contain:
           <HTML> This is the larger picture <%PHOTO imagesize=400 %> </HTML>

Both the thumbnail image and any branch pages created by template are saved in the same folder as the gallery folder. Thumbnail pages are saved with the same name as the image that that is being thumbnailed. For example image.jpg would have an associated image.htm, for this reason it is not recommended that you have images with the same name in the same gallery.

Tip: By setting the template you essentially create a page branch. For a thumbnail you generally have one <%PHOTO%> tag on the branch but if you want you can place multiple images into the branch.

Note: If you set both the imagesize and the targettemplate only the targettemplate value will change the size of the image that you link to.

<%OVERFLOW%>    <%/OVERFLOW%>

The overflow tag is generally used to create a secondary page with more pictures. Often you will have a special template for your first page of photos and will want to have a more simple page for the rest. The overflow tag makes it easy to do this. This tag requires an opening and closing tag. If you have one without the other the template will not function properly. The overflow tag will replace itself with a <A> link tag. The body of the overflow tags will be placed inside the hyperlink allowing you to link using either an image or text.

If Magic Gallery has no more pictures to parse then overflow page will be discarded.



Optional Parameters

Description

Default Value

href

Specifies the target for the overflow page

The default will be set to the name of the current webpage plus a number counting the page.

template

Specifies the template to use for generating the overflow page.

The default is to repeat the current page template

count
Specifies the number of pages to link back to. Default is blank

Examples:

        Place any remaining photos on a page called default2.htm link to this page with the text.

<%OVERFLOW %>
See more photos on the next page
<%/OVERFLOW%>

Place any remaining photos on a page called morepictures.htm and link to this page with an image.

<%OVERFLOW href="morepictures.htm" template=photolist.htm %>
<img src=morepicture.gif border=0>
<%/OVERFLOW%>

Place any remaining photos on a page called morepictures4.htm where the number 4 is changed depending on the number of pictures.

<%OVERFLOW href="morepictures*.htm" template=photolist.htm %>
<img src=morepicture.gif border=0>
<%/OVERFLOW%>

Note that the * will be replaced by the page number. This is very useful for large galleries. This pattern is also used in the pages tag to link all the overflow pages together.It is recommended that you take a look at the template "12 pictures on a page" to see how this works.

Link to the previous overflow page.

<%OVERFLOW count=-1 %> Previous Page <%/OVERFLOW%>



<%PICTURENAME%>

This tag places the file name of the picture on the page.. The tag gets replaced with an image file name at runtime.



Optional Parameters

Description

Default Value

Date

Specifies if the date should be included as part of the picturename

true

count
Specifes the offset count for the picturename to return
0



Examples:
Place a photo and it's name on the page
<%PHOTO%>
<%PICTURENAME%>
Note: If you have turned off the date option in magic gallery, then the date parameter will be ignored

<%PICTURELINK%>    <%/PICTURELINK%>

The picturelink tag is generally used to link to another picture page. It's most common use is to link to the next picture in a series or the previous picture. The picturelink tag will create a link to the picture specified in the count parameter. This tag requires an open and close tag to function correctly.

If the image is not available the contents of this tag are discarded.

Optional Parameters

Description

Default Value

count

The number of pictures ahead to skip to

1

discard

Determines if the body of the picturelink tag is discarded when a link is not available

TRUE



Examples:
Place a photo on a page and link to the next andprevious pictures.
<%PICTURELINK count=-1 %> Previous Picture <%/PICTURELINK%>
<%PHOTO%>
<%PICTURELINK count=1 %> Next Picture <%/PICTURELIN%>
Place a photo on a page and link to the next and previous pictures.
<%PHOTO%>
<%PICTURELINK count=-2 %> Previous Picture <%/PICTURELINK%>
<%PICTURELINK count=1 %> Next Picture <%/PICTURELIN%>
Note: Note the picturecount changes after you process a picture. In the above example the previous picture link is set to -2. This is because linking to -1 would be the same picture. In the previous example the link is placed before the picture so -1 is the correct previous picture.
Make the photo a link to the next photo if it's available. 
But don't discard the photo if there is no next picture.
<%PICTURELINK count=1 discard=false %> <%PHOTO%> <%/PICTURELINK%>
<%PICTUREURL%>

The PictureURL tag is used to in more advanced templates where you wantto create your own type of link to a picture. It is very similar to the way that the PictureLink tag works however it only returns the URL for the picture page, it does not create an anchor tag. It's most common use is to add a next or previous link in an image map or to place picture information into a form..

Optional Parameters

Description

Default Value

count

The number of pictures ahead to skip to

1



Examples:
Place the photo information in a form.
<Form method="post" action="moreinfo.asp">
    <input type=hidden value="<%PICTUREURL count=0 %>"
    <input type=submit value="Send an e-postcard">
</form>
Place next and previous links in an image map
<map name="FPMap0">
<area href="<%PICTUREURL count=1 %>" shape="circle" coords="230, 68, 18">
<area href="<%PICTUREURL count=-1 %>" shape="circle" coords="185, 67, 17">
<area href="<%HOMEURL%>" shape="circle" coords="140, 65, 19"></map>
<img border="0" src="raizlabs_snapshot.jpg" width="420" height="103" usemap="#FPMap0">

Note: this is Similar to the PictureLink tag only here we just return the URL without creating
a wrapper of <a> tags around the image.
<%COPYPICTURE%>

The copypicture tag does not produce any visual output to the gallery but it does allow you to copy files in the process of creating a gallery. This tag is useful when you want to add a standard image or standard file into the gallery folder.

Optional Parameters

Description

Default Value

filename

The name of the file to copy.

There is no value the current image will be copied.

target
The destination directory to copy the file The default value is the current directory

Examples:
Copy a standard image into the same folder as this webpage. 
<HTML>
<%PHOTO%>
<%PICTURELINK%><img src=next.gif><%/PICTURELIN%>
<%COPYPICTURE filename=mytemplate/next.gif %>
</HTML>
Copy an image into the "stockphoto" directory

<%COPYPICTURE filename=mytemplate/gallery.gif target="stockphoto" %>
Copy the original image to the current gallery:
<%COPYPICTURE%>
The picture will be copied as picturenameLarge.jpg and placed in the gallery directory. 
The text Large helps prevent this image from overwriting the thumbnail image in the same
directory. See how this is used in the Photo Printing Gallery.
Note: Note the source of the image is always relative to the template directory unless you are copying the original image. Copy image operations will look in the templates\mytemplate folder of the magic gallery directory.
(C:\program files\magicgallery\templates\mytemplate\)

Note: File copy conflicts are ignored so you can copy the same image into the same folder without getting a warning.

<%GETTEXT%>

The gettext tag will bring up a dialog box asking the user to enter some text. This tag can be used anywhere in your page to enter additional information into your page. It is most often used to add comments, titles and descriptions for pages.

Optional Parameters

Description

Default Value

prompt

This is the text that will be shown to the user asking them to enter information

"Enter a title for this picture"

INTLPrompt
If this value is specified the prompt will be extracted from the international language file
none

count
The image to show when prompting for text
0

cache
If this value is set to true the value will be returned from the cache without prompting the user. This can be useful if you want to use a value more then once without repeating the question

INTLPrompt

The prompt will be extracted from the international text file. If the value does not exist it will be extracted from the English language file. Current values that are supported for INTLPrompt are:

PromptGalleryName What is the name of your gallery?

PromptGalleryPageName What is the title for this page of thumbnails?

PromptGalleryDescription Enter a one or two paragraph description of this gallery.

PromptGalleryColor Choose a color for your gallery.

PromptPhotoDescription
Enter a description for this photo

Examples:
My favorite color is: <%GETTEXT prompt="What is your favorite color"%>
<%PHOTO%> This picture was photographed by 
<%GETTEXT count=-1 prompt="Who took this picture?"%>
<%GETTEXT  INTLPrompt="PromptGalleryName" %>
Note: If the user has enabeled the option to never ask questions
these will always be filled in with a cached value if one exists. 
<%GETOLOR%>

This tag will allow you to bring up a dialog box asking the user to select a color. This tag can be used anywhere in your page to select a color. The value returned will always be an HTML formatted color.

Optional Parameters

Description

Default Value

prompt

This is the text that will be shown to the user asking them to enter information

"Choose a color"

INTLPrompt
If this value is specified the prompt will be extracted from the international language file
none

Note: See GetText for additional information on the INTLPrompt tag.

Examples:
This is <font color="<%GETCOLOR prompt="What is your favorite color" %>" my favorite color </font>
 
 
<%HTMLNAME%>

This tag places the name of the HTML file that is being created. The tag gets replaced with an HTML file name at runtime.

Optional Parameters

Description

Default Value

Extension

If set to false this will return the filename without the three letter extension

True

Examples:
<frameset rows="*,95">
  <frame name="main" src="magicgallery/<%HTMLNAME extension=false %>1.htm" >
  <frame name="filmstrip" src="magicgallery/<%HTMLNAME extension=false %>2.htm" >
  <noframes><body>
    <%OVERFLOW  template="filmstrip\blank.htm"  %> <%/OVERFLOW%>
  </body></noframes>
</frameset>
In the above example the HTML name is used to create links to the two other pages in this frameset.
Overflow pages will always take the name of the original document with a number. In this example
we use this information to create the correct links for the frame pages.

<%HOMEURL%>

This tag places the url of the gallery home page on the page. The tag gets replaced with the relative path to the HTML file selected as the starting page of the gallery..

Optional Parameters

Description

Default Value

none

Examples:
<a href="<%HOMEURL%>" >  Return to the gallery home </a>
Note that the HOMEURL will be a relative path. If the page that is being generated is 
in a directory the path will often besomething like:  "../gallery.htm"

Note: Changes to this tag are in development
<%INTLTEXT%>

This tag will allow you to place text into your gallery that has been localized for the language of the person using the template. If a particular value is not available in the users current language the english version will be shown.

Optional Parameters

Description

Default Value

ID

This is the ID that will be used to lookup the international text

blank

Note: See the file Enligh_language.txt for additional information on available ID's.

Examples:
<a href="<%HOMEURL%>" > <%INTLTEXT ID="PromptReturnMain" %> </a>

This will result in <a href="default.htm" > Return to main Gallery </a>
<%PAGES%>

This tag places a list of page numbers on the page. This tag is usually used in combination with the overflow tag.Using this allows you to list out all the pages in your gallery created using the overflow.

Optional Parameters

Description

Default Value

href

Specifies where the links will point

Blank

imagecount
Specifies the expected number of pictures on a page
Blank

Examples:

Print out the pages in this gallery:
<%PAGES href="*overflow.htm" imagecount=12 %>

This specified that the pattern for creating links should be to use a number with the link overflow.htm, it also assumes 12 pictures on a page. To see an example of this tag take a look at the BlackOverflow2.htm
 
<%Width%>

This tag places the width of the current image on the page.

<%Height%>

This tag places the width of the current image on the page. .

Optional Parameters

Description

Default Value

count

Specifies the picture in the list if not the current one

Blank

Examples:
This Picture is <%WIDTH%> pixels wide and <%HEIGHT%> pixels tall.
The previous picture was <%WIDTH count=-1 %> pixels wide.
<%KEYWORD%>

This tag places the random keyword or phrase on your page from the keyword file. The keyword file
is located in the install directory of MagicGallery and is called Keywords.txt. You can enter any information you want into this file. Each time you use the keyword tag a random keyword will be used from your list. You can use the keyword tag to place random banner ads, quotes or other material on your page. Each line in the keyword file is separated by a new line.

Optional Parameters

Description

Default Value

none

Examples:
Please visit our sponsor <br> <%Keyword%>
 
<%BannerAd%>

This tag places the random banner ad on your page from banner ads that are available in the magic gallery program.

Optional Parameters

Description

Default Value

none

Examples:
Please visit our sponsor <br> <%BannerAd%>
<%GETDATA%>

This tag is similar to the GetText tag only instead of getting text from the user the program will get text from a Microsoft Excel spreadsheet. A tutorial on using GetData is available here.

Optional Parameters

Description

Default Value

column

the name of the column to look for data

count
the image difference if it's the previous or next image

format
How to format the data if it's not text

Examples:
Image Description <%GetData column="Description" %>
Image Artist <%GetData column="Artist" %>

 