# Placeholders and Include Files

This section lists the placeholder tokens used by BBEdit templates and include files, and describes the use and capabilities of include files.

## Overview of Placeholders

Placeholders are processed under the following circumstances:

- When a new HTML document is created from a template, the placeholders in the template are replaced with their current values. (The new document receives the substituted text; the original template file is not modified.)
- When the Update Document command (part of the HTML Tools) is invoked, any placeholders in the documents being updated are replaced with their current values. (Since the placeholders are replaced, subsequent updates do not update the substituted text.) Although this command is part of the HTML Tools, it can be used in any document whenever you want to use placeholders.
- When a file is included in another file using the #bbinclude directive (or a related directive), any placeholders in the included file are replaced with their current values before the text is included. (The include file itself is not changed, only the included text is substituted.) All of the above methods of invoking placeholders can also invoke included files, which can have placeholders of their own.

###### Note

The placeholders described in this chapter are only available for use with the HTML Tools' Update command. They cannot be used with BBEdit's Clippings command, nor can Clippings placeholders be used in include or template files.

BBEdit supports the following placeholders. Placeholders are not case-sensitive.

Placeholder | Replaced By...
--- | ---
#ABBREVDATE# | Abbreviated date--e.g., Sun, Aug 15, 2006
#BASE# | The BASE tag as entered using the New HTML Document command
#BASENAME# | The name of the file stripped of its rightmost period-delimited portion. For example, if the file is named "test.html", the base name is "test", while if the file is named "test.foo.html", the base name is "test.foo".
#BASE_URL# | The value of the BASE URL specified in an HTML document's header (useful if you want to refer to the document's location on the server)
#CHARSET# | The character set specified in the New HTML Document command
#COMPDATE# | Compact Date format--e.g., 15-Aug-06
#CREATIONDATE# | The creation date of the current file--e.g., 15-Aug-06
#CREATIONTIME# | The creation time of the current file, formatted according to your Format settings in the International panel of the System Preferences
#DATETIME XXX# | Inserts a localized, region-aware date whose format is specified by the ICU format string XXX (see "Date Formats" below)
#DATETIME_GMT XXX# | Inserts the universal, region-aware date whose format is specified by the ICU format string XXX (see "Date Formats" below)
#DIRPATH# | The path on the server as specified in the Sites panel of the Setup window. Strips any leading slash from the path string
#DOCSIZE# | The size of the current document plus included images in bytes
#DOCTITLE# | The title of the current document as extracted from the <TITLE> tag
#DONT_UPDATE# | Marks a document so that the HTML Update tool will ignore it during processing
#FILE_EXTENSION# | The filename extension for the file (determined as the rightmost period-delimited portion of the filename, without the period). For example, whether the file is named "test.html" or "test.foo.html", the filename extension is "html".
#FILENAME# | The file name of the current file
#GENERATOR# | Generator name used for "Give BBEdit Credit" in New HTML Document function (e.g., "BBEdit 11")
#GMTIME YYY# | The current GMT time formatted according to the parameters YYY (see "Time Formats" below)
#LANGUAGE# | The language specified in the New HTML Document command, in format (space)lang="en"
#LINK# | The LINK tag as entered using the New HTML Document command
#LOCALPATH# | The full local path to the current file
#LOCALTIME YYY# | The current local time formatted according to the parameters YYY (see "Time Formats" below)
#LONGDATE# | Long Date format--e.g., Sunday, August 15, 2006
#MACHINE# | The machine name as specified in the Sharing section of the System Preferences.
#META# | Any META tag entered using the New HTML Document command
#MODIFIEDDATE# | Modification date of the current file--e.g., 15-Aug-06
#MODIFIEDTIME# | Modification time of the current file, in the format specified in the International section of the System Preferences
#MONTHDAYNUM# | Numeric value of the day of the month
#MONTHNUM# | Numeric value of the current month
#PATH# | Path to access your documents from the Web server, as specified in your HTML Web Site preferences
#PREFIX# | As #DIRPATH# but does not strip the leading slash of the path
#REAL_URL# | The real URL for the current document in its current location
#RELATIVE# | The relative path from the current file back up to the Local Server Root (inserts a path of the form "../../" to tell the browser to "back up" to the site's root directory)
#ROOT# | Path to the Local Site Root, as specified in your HTML Web Site preferences
#ROOTPATH# | The file's path relative to the Local Server Root specified in the HTML Web Site preferences to the current file
#SERVER# | URL of your Web server, as specified in your HTML Web Site preferences.
#SHORTDATE# | Short Date. Day, month, year--e.g., 08/15/06
#SHORTUSERNAME# | Returns the login (short) name instead of the full user name
#TIME# | Current time, according to your Format settings in the International panel of the System Preferences
#TITLE# | Title of the current document as entered using the New HTML Document command
#USERNAME# | The owner name (for the currently logged in user)
#YEARNUM# | The current year--e.g., 2006

#### Date Formats

The #DATETIME XXX# and #DATETIME XXX# placeholders allow you to insert the corresponding date and time values with flexible formatting.

In order to use these placeholders, you must substitute XXX with an ICU date/time format string. ICU is the mechanism used by Mac OS X for date formatting. For full details, please refer to the section "Date/Time Format Syntax" in the ICU documentation.

Examples:

#DATETIME EEE, MMM d, yy 'at' h:mm a#

produces:

Tue, Jul 3, 07 at 5:48 PM

#DATETIME_GMT EEE, MMM d, yy 'at' h:mm a#

produces:

Tue, Jul 3, 07 at 9:49 PM

#DATETIME EEEE 'at' h 'o''clock' a#

produces:

Tuesday at 5 o'clock PM

### Time Formats

The #GMTIME YYY# and #LOCALTIME YYY# placeholders offer you the option to insert the specified time value with flexible formatting.

In order to use these placeholders, you must substitute YYY with a time format using the same expansion options offered by the `strftime' routine (see `man strftime' for further details).

Examples:

#LOCALTIME %r %z on %A#

produces:

06:50:13 PM -0400 on Monday

#GMTIME %r %z#

produces:

10:50:13 PM +0000

### Using the #RELATIVE# Placeholder

When dealing with large web sites that have multiple content folders, it is often useful to specify relative rather than absolute paths for linking documents. The #RELATIVE# placeholder allows you to easily generate relative references in templates and include files by providing a virtual path that uses the ".." construction to "back up" the hierarchy to the root directory of the site.

To use this placeholder, write your links as if they were all relative to the top of your web site, including #RELATIVE# as the first "directory" in the path. For example, consider that you have the following file structure, where each page includes a file which references the separate GIF image.

My_Web_Site:

Folder1:

File1.html

Folder2:

File2.html

File3.html

Folder3:

Folder4:

Folder5:

File4.html

Graphics:

Buttons:

my_footer_button.gif

If you write a relative link as follows:

<img src="#relative#Graphics/Buttons/my_footer_button.gif" alt="">

and then run the Update command, the following links will be generated.

In File1.html,

../Graphics/Buttons/my_footer_button.gif

In File2.html,

../Graphics/Buttons/my_footer_button.gif

In File3.html,

../Graphics/Buttons/my_footer_button.gif

In File4.html,

../../../Graphics/Buttons/my_footer_button.gif

## Include Files

An include file, or just an "include," is a special form of placeholder whose substitution happens to be the contents of another file. If you have used C or certain other programming languages, you may already be familiar with the concept. Using includes, you can reuse standard bits of text content or HTML markup in several templates or clippings entries without having to revise all of those individual files whenever you revise the included text.

### Include File Locations

BBEdit looks for include files first in the same directory as the document containing the directive, then in the same directory as the document into which the processed document is being inserted, and finally in the HTML Templates folder specified in your preferences.

### Simple Includes

A simple include takes the following form:

#bbinclude "filename"

where filename is the full name of the file whose contents you wish to include. When such an include is present in a template or clippings entry, it is replaced with the contents of the specified file when the template is used to build a new document, or when the clippings entry is inserted. (The original template or clippings file is not changed.)

Imagine that you have ten different templates, each of which contains your name, address, phone number, email address, and a copyright statement with the current year in them. Rather than pasting this info into all ten templates, you can create a file named "address.html", put it in your Templates folder, and include this statement:

#bbinclude "address.html"

in each of the templates, at the appropriate point. Later, when the new year arrives, or you move, you only have to update one file, not all ten templates. (You could use the #YEARNUM# placeholder for the year and only need to update the include file when you move!)

Headers and footers are probably the most common uses for include files, but any template or clippings entry may use as many include statements as you wish. Included files themselves may also use #bbinclude directives, up to 16 levels deep.

### Persistent Includes

Simple includes are appropriate for use situations where you want the inclusion to happen only once. Once the file has been included, however, it cannot be changed in any automated fashion. Since the #bbinclude directive is replaced by the included text, the Update tool cannot tell the included text is any different from any other text.

Includes become even more powerful, however, when you can update existing files to incorporate revised include text at a later date. For example, suppose you generate several dozen HTML documents using a template that uses an #bbinclude directive to insert a standard footer containing your email address. Later, you change your email address. After you change it in the footer document, only new HTML files you create from the template will include your new address. What you would really like to be able to do is update all the files you have already created to include the revised footer.

Since this capability is needed primarily in web site maintenance, BBEdit lets you embed the include directive in an HTML comment. An "end bbinclude" comment is also required. The included text is inserted between the two comment markers, but the comments themselves remain in place. The comments are not shown in the browser. This is known as a persistent include.

A persistent include looks like this:

<!-- #bbinclude "filename" -->

<!-- end bbinclude -->

The first time a persistent include is processed, it is handled much like a simple include. However, since the include directives remain in place, and because they mark the beginning and end of the inserted text, the Update tool can "rip out" the obsolete included text and replace it with the updated file. Using persistent includes and the Update Folder or Update Site commands, you can easily make these sorts of changes to entire sites in moments.

###### IMPORTANT

Any changes you have made to the included text after its initial inclusion will be discarded when the persistent include is updated, even if you have not changed the include file.

### Inline versus Block Includes

By default, BBEdit places included content in the document as a block, to ensure that it does not occupy the same line as the include directives. However, if you wish to override this behavior and have BBEdit place the included content inline, you may do so by adding the special option #bbincludeoptions#="inline=true" to the include directive.

<!-- #bbinclude "filename" #bbincludeoptions#="inline=true" -->

<!-- end bbinclude -->

### Include Files with Variables

Include files can be extended even further through the use of variables, which provide a means of inserting arbitrary text when the included file is processed, so that not all instances of the included file are exactly the same. Variables are essentially placeholders that you make up yourself. Some possible uses are to insert names, taglines, alt strings for images, or file names (for files other than the current document) into documents.

###### Note

A variable name consists of a string of alphanumeric characters, enclosed in number signs (the `#' character). Spaces are not allowed in variable names, but underscores may be used to represent word breaks.

Variables can be placed anywhere in an include file, just like placeholders. When you include that file in a document, you specify the variable names and values with it. Consider an include file named "footer.html", which contains the following

<HR>

<IMG SRC="#MY_GRAPHIC#" ALT="#MY_ALT_DESC#">

<H1>#MY_TITLE#</H1>

<BIG>This document copyright 1998-2100 by Sid Zookim.</BIG>

In your document, the Include reference would look like this:

...

<BODY>

...

<!-- #bbinclude "footer.html"

#MY_GRAPHIC#="test1.gif"

#MY_ALT_DESC#="a test image"

#MY_TITLE#="A Test Title"

-->

<!-- end bbinclude -->

...

</BODY>

...

Note that the values of placeholders are specified inside the HTML comment of a persistent include, using a #PLACEHOLDER#="Value" syntax. The quote marks around the value are mandatory; if you need to include a quote mark in the actual value, escape it with a backslash.

### Including AppleScripts

BBEdit allows included files to be compiled AppleScript scripts. The script should contain an "on include" handler which is passed two parameters: a reference to the file from which the script is being called, and a record containing one field for each variable passed in the #bbinclude directive. Scripts can of course also retrieve information from BBEdit, other scriptable applications, or the system. The handler's return value is inserted into the file that included it.

Given the HTML document below:

<html>

<head>

<title>Include Test</title>

<meta name="generator" content="BBEdit 11">

</head>

<body>

<!-- #bbinclude "foo.script" #x#="3" #author#="JEK"-->

<!-- end bbinclude -->

</body>

</html>

The following script inserts three lines: the first containing the file's path, the second containing the parameter "x" passed to it in the #bbinclude directive, and the third containing the parameter "author."

on include(f, vars)

set s to f as text

set s to "File Path: " & s & return & return as text

set s to s & "x: " & x of vars & return & return as text

set s to s & "Name: " & author of vars & return as text

return s

end include

The resulting document might look like this:

<html>

<head>

<title>Include Test</title>

<meta name="generator" content="BBEdit 11">

</head>

<body>

<!-- #bbinclude "foo.script" #x#="3" #author#="JEK"-->

File Path: Boot:Desktop Folder:incl_test.html

x: 3

Name: JEK

<!-- end bbinclude -->

</body>

</html>

### Including Unix Scripts

BBEdit lets you include scripts written in Perl, Python, Ruby, or any other Unix scripting language. The complete path name of the file being processed is passed to the script as its first argument, and any variables in the include statement are passed as additional arguments. (For Perl, all these can be retrieved by your script via @ARGV.)

Any text sent to STDOUT by the script will be taken as the value of the #bbinclude operation and inserted into the HTML file. If an error occurs while running the script, the STDERR output, if any, will be inserted into the file along with the STDOUT, and a single line indicating the error will be added to the error browser.

For example, enter this directive in your HTML file:

<!-- #bbinclude "foo.pl" #length#="2" #width#="3" -->

<!-- end bbinclude -->

Then use this source code for "foo.pl", and save it in the same folder as the HTML file, or in the "Templates and Includes" folder specified in the HTML Web Sites panel of your BBEdit preferences:

#!/usr/bin/perl -w

my $file = shift @ARGV;

my %args = @ARGV;

my $area = $args{"length"} * $args{"width"};

print "Filename: $file\n";

print "Area: $area\n";

When you run the Update command, BBEdit will place the file name in the script's variable $file and the "length" and "width" variables in the associative array (hash) %args.

After the update, the BBEdit file will look like this:

<!-- #bbinclude "foo.pl" #length#="2" #width#="3" -->

Filename: Mac HD:Desktop Folder:sample.html

Area: 6

<!-- end bbinclude -->

In addition, BBEdit will pass information about the current HTML Tools settings to the script in the following environment variables:

BBEditServerURL

BBEditServerPath

BBEditDefaultFileName

BBEditTemplateDirectory

BBEditRootDirectory

BBEditLowercaseTags

BBEditLowercaseAttributes

BBEditAlwaysQuoteAttributes

To access these in your Perl code, use the %ENV environment variable hash. For example, this line of Perl will print the Web server name specified in your BBEdit HTML Web Site preferences:

print $ENV{BBEditServerURL};

Here's an example Python include script.

#!/usr/local/bin/python

import os

import string

import sys

print "Hello Python World!"

print "==================="

print "File being updated: ", sys.argv[1]

print

userVariables = {}

for i in range(2, len(sys.argv), 2):

userVariables[sys.argv[i]] = sys.argv[i+1];

print

print "Dumping the user variables passed to the script"

print "==============================================="

print

keys = userVariables.keys();

keys.sort()

for k in keys:

print "%-30s %s" % (k, userVariables[k])

print

print "Dumping the environment variables set by BBEdit"

print "==============================================="

print

for k, v in os.environ.items():

if (string.find(k, 'BBEdit') == 0):

print "%-30s %s" % (k, os.environ[k])

### Other Include Notes

###### IMPORTANT

Some old versions of BBEdit supported the use of "#include" as an alternative to "#bbinclude". However, this syntax made it difficult to mix BBEdit includes and Microsoft Active Server Page (ASP) directives, so it is no longer supported. If you have existing documents which use this syntax, simply change "#include" and "end include" to "#bbinclude" and "end bbinclude" to continue using them.