Design-Side Includes: Manual

Web Content Reuser Utility

Design-Side Includes (DSI) is a command-line utility for reusing common sections of HTML code across multiple web pages.

DSI Manual Contents
1) Concepts
2) Page Tags
3) Launching on a Mac
4) Launching (general)

CONCEPTS

DSI inserts HTML Fragments into Base HTML files to produce finished HTML files. For example, the Base files index.bhtml and about.bhtml might both include the Fragment file copyright.fhtml. DSI would combine the Base files and generate the files index.html and about.html which you would then upload to your web server. In addition to support for "includes", DSI supports setting and reading variables and "if" statements based on file names.

PAGE TAGS

DSI supports the following tags embedded in web pages:

include:	`<!--#include file="[FileName]" -->` Inserts a file. The inserted file may itself contain more DSI page tags. By convention, included files have the extension *.fhtml* for Fragment HTML.
if:	`<!--#if expr="$DOCUMENT_NAME=[FileName]" -->` Starts an "if" conditional block. Subsequent lines will be ignored if the statement is false. Statement is considered true if the name of the Base HTML file is [FileName].
elif:	`<!--#elif expr="$DOCUMENT_NAME=[FileName]" -->` Optional "else if" tag be used within an "if" conditional block.
else:	`<!--#else -->` Optional "else" tag used within an "if" conditional block for lines to be included when none of the "if" and "elif" statements are true.
endif:	`<!--#endif -->` Closes the "if" conditional block.
set:	`<!--#set var="[VariableName]" value="[VariableValue]" -->` Sets a user defined page variable for use by the "echo" tag.
echo:	`<!--#echo var="[VariableName]" -->` Includes the value of a previously set page variable. Two page variables are preset by the system. They are DOCUMENT_NAME for the name of the current Base HTML file and LAST_MODIFIED for the current date and time.

NOTES ABOUT DSI PAGE TAGS
*Spaces* -- Spaces around the pound sign ("#") and the equal sign ("=") are not allowed.
*Separate Lines* -- Except for the "echo" tag, each page tag must be on its own line.
*Valid "if" Blocks* -- The "if" conditional block must have an "if" and an "endif", but the "elif" and "else" tags are optional. The "elif" tag is the only one that may appear multiple times.

Example:

**index.bhtml**
`<html><head> <title>Wow</title></head> <body> <h1>Hello World!</h1> <!--#include file="note.fhtml" --> </body></html>`

**note.fhtml**
`<!--#if file="$DOCUMENT_NAME=index.bhtml" --> This is the home page. <!--#else --> <a href=".">HOME</a> <!--#endif --> Page Updated: <!--#echo var="LAST_MODIFIED" -->`

**index.html**
`<html><head> <title>Wow</title></head> <body> <h1>Hello World!</h1> This is the home page. Page Updated: July 16, 2005 </body></html>`

LAUNCHING ON A MAC

Put the dsi.jar file at /Users/<YourUserName>/apps/dsi/dsi.jar. Then put this dsi.sh.command file in the folder with your .bhtml and .fhtml files.

DSI Script:

**dsi.sh.command**
#!/bin/sh cd "`dirname "$0"`" java -jar ~/apps/dsi/dsi.jar mv *.html ..

From Finder, double-click the dsi.sh.command file to process your web files and put the generated HTML files into the parent folder.

LAUNCHING

Design-Side Includes (DSI) is run from the command-line. Use the "java" tool to launch DSI. The basic format is:

> java -jar dsi.jar [SrcDir] [FileName] [NewExt]

Where the three optional parameters are:

SrcDir:	The "source directory" specifies the location of the Base HTML files and Fragment HTML files. Valid directory names are dependent on your operating system. If the directory names includes, spaces, be sure to enclose the names in quotes. The default is the current directory.
FileName:	The "file name" specifies the name of the Base HTML file (ex: *index.bhtml). Wildcards ("") are supported, and the default value is *.bhtml.
NewExt:	The "new extension" specifies the file extension of the new files generated by DSI. The default value is *.html*.

Additionally, the single parameter "-v" tells DSI to just report its version number.

Examples:

> java -jar dsi.jar

*.bhtml

.html

index.bhtml

index.html

> java -jar dsi.jar public_html

public_html

> java -jar dsi.jar public_html *.bjsp .jsp

.jsp

.bjsp files.

> java -jar dsi.jar -v

Displays the DSI version number and takes no other action.

NOTES ABOUT LAUNCHING DSI
*JAR Directory* -- Depending on your system environment and how Java is setup, you will need to specify the path of the DSI JAR file. On most Windows systems, you can use: `set DSIDir=C:\Program Files\Center Key Software\DSI java -jar "%DSIDir%\dsi.jar"` For further information about running JARs, consult the Java documentation specific to your system.
*Java Bin* -- If the Java bin directory is not in your system path, specify the path on the command line. On Windows systems, you can use something similar to: `set JavaBin=C:\Program Files\Java\jre1.5.0_10\bin "%JavaBin%\java" -jar dsi.jar` For further information, consult the Java documentation specific to your system.

NOTE FOR jEDIT USERS

Syntax Highlighting -- If you edit your HTML files with jEdit

, you can turn on syntax highlighting for .bhtml and .fhtml files. Go into jEdit's "modes" directory and open the "catalog" file in a text editor. Now locate the lines:


         <MODE NAME="shtml" FILE="shtml.xml"

            FILE_NAME_GLOB="*.{shtml,shtm,ssi}" />

Add the extensions "bhtml" and "fhtml" so the new lines look like:


         <MODE NAME="shtml" FILE="shtml.xml"

            FILE_NAME_GLOB="*.{shtml,shtm,ssi,bhtml,fhtml}" />

For Mac OS X users, bring up the context menu (right mouse click) for "jEdit.app" (probably in "/Applications") and select "Show Package Contents". You will find the "catalog" file in the "Contents/Resources/Java/modes" folder.