The “Add Persistent Include” command allows you to embed an external file inside your HTML document. This inclusion is handled by Ruble itself. Once you’ve added the include statement, use the “Update Document” command to refresh any included files.
An inclusion is done using a special HTML comment:
<!-- #rrinclude "footer.html" -->
<!-- end rrinclude -->
Once you’ve updated the document, the contents are pulled inside the inclusion markup:
<!-- #rrinclude "footer.html" -->
<div class="footer">Copyright (c) 2006, WebDesignCorp.</div>
<!-- end rrinclude -->
Note: Included documents are also processed for additional inclusions and placeholders.
You can optionally specify parameters for the included file. Parameters are provided following the filename.
<!-- #rrinclude "header.html" #title#="Home Page" -->
<!-- end rrinclude -->
With a header.html file that looks like this:
<h1 class="header">#title#</h1>
Producing:
<!-- #rrinclude "header.html" #title#="Home Page" -->
<h1 class="header">Home Page</h1>
<!-- end rrinclude -->
The update command also processes document “placeholders”. Placeholders are written in this format:
#variable#
The following placeholders are available:
| Placeholder | Example Result |
|---|---|
| #abbrevdate# | Abbreviated date: Sun, Aug 15, 2006 |
| #basename# | Filename without extension. |
| #compdate# | Compact date: 15-Aug-06 |
| #creationdate# | Creation date: 15-Aug-06 |
| #creationtime# | Creation time: 1:20 PM |
| #docsize# | Resulting document length in bytes |
| #dont_update# | Special: presence will prevent document updating |
| #filename# | Document filename |
| #file_extension# | Document file extension |
| #generator# | Ruble |
| #gmtime# | GMT time |
| #localpath# | Full path to current file |
| #localtime# | Local computer time |
| #longdate# | Long Date: Tuesday, August 15, 2006 |
| #modifieddate# | Modified date: 15-Aug-06 |
| #modifiedtime# | Modified time: 1:20 PM |
| #monthdaynum# | Day of Month: 15 |
| #monthnum# | Month Number: 08 |
| #shortdate# | Short Date: 08/15/06 |
| #shortusername# | Login name of current user |
| #username# | Name of current user |
| #yearnum# | Current Year: 2006 |
In addition to these, all of the Ruble environment variables (those starting with a “TM_” prefix) are available as placeholders. For example:
#organization_name#
Will populate using the TM_ORGANIZATION_NAME environment variable.
The date-based placeholders may also specify a format that can be used to customize the date output. For example:
#gmtime %b %e, %Y# (Aug 15, 2006)
If you want to make that footer.html include more useful, you can use placeholders. For example:
<div class="footer">Copyright (c) #yearnum#, #oragnization_name#.</div>
This would then produce the following, when included and processed:
<!-- #rrinclude "footer.html" -->
<div class="footer">Copyright (c) 2006, WebDesignCorp.</div>
<!-- end rrinclude -->
It is also possible to produce included content using scripts. If the included file is a script, it is run and the output is placed inside the include block.
<!-- #rrinclude "scripts/header.pl" #class#="huge" -->
<!-- end rrinclude -->
.pl (Perl), .py (Python) and .rb (Ruby) scripts are currently recognized. For the above example, the “header.pl” script is run with the following parameters:
header.pl (source_filename) class huge
The Perl script in this case can process the parameters like this.
#!/usr/bin/perl
my ($filename, %args) = @ARGV;
print "<h1 class='$args{class}'>Header for $filename</h1>"
That would end up producing this:
<!-- #rrinclude "scripts/header.pl" #class#="huge" -->
<h1 class='huge'>Header for /path/to/example.html</h1>
<!-- end rrinclude -->