This article describes how HTML pages for aTbRef (v5, as of 18 July2014) re created in a Tinderbox document.  The 'atbref.tbx' source document (download) contains templates and ancillary boilerplate to export not only the actual 'content' of the site but produce all the CSS, scripts, etc. The template described is '5-basic_all'. The templates are all in the the container '/TEMPLATES' of the TBX and boilerplate notes are in '/BOILERPLATE'.

The design concept uses HTML5. Most Tinderbox users should be able to skim read this article for the general points, but it is aimed at those wanting to move beyond the basics of HTML export in Tinderbox.

The HTML code as shown below may differ from the original insofar as line beaks have been added to assist clarity in this article. The actual template's use of white space and line breaks is designed to emit neatly laid out HTML source code.

The aTbRef page discussed below can be seen at http://www.acrobatfaq.com/atbref5/index/Menus/BasicMenuBar.html. The page may change from the screen grabs below if the site is subsequently updated.

How a typical page looks

It is not possible to show every variant of the page - for instance this page has no content image but it does shown the primary parts of a general content page:

  1. Header content (not visible).
  2. Quick-links panel.
  3. Navigational 'cookie crumb' trail.
  4. Tinderbox app icon.
  5. Title panel.
  6. Optional: Deprecated content warning. [Not used by this page: example of use.]
  7. Optional: Attribute note key attribute table. [Not used by this page: example of use.]
  8. Optional: Export Code note key attribute table. [Not used by this page: example of use.]
  9. Optional: Action Code Operator note key attribute table. [Not used by this page: example of use.]
  10. Content - the $Text of the source document.
  11. Change listing - only used by version change listings (see example).
  12. 'Similar To' links panel.
  13. Navigational links panel.
  14. Navigational 'cookie crumb' trail (same as #3 above)
  15. Quick-links panel (same as #2 above).
  16. Google Translate feature.
  17. Date of production (export) of the page.
  18. Google Search feature (restricted to aTbRef URLs).
  19. Creative Commons Licence.
  20. Footnote information.
  21. Tracking code for Google Analytics (not visible).
  22. Google Translate script - for #16 above (not visible).

A single template, with lots of conditional export code makes the simple looking web-page seen above. The main template uses another seven templates and boilerplate code includes to cover all the possible optional variations found in the source notes.

What is the benefit of conditional content?

Originally, the aTbRef used a separate template for many of the above variations. This means that if anything, like the list of 'quick links' changed, then every template affected needed editing and it's easy to forget a template in the process of doing updates. Now every page of main content is exported using just one template. Of course, having all the conditional sections is complex and is not something for a new user to attempt from outset, unless familiar with HTML and coding.

Conditional inline code, or include? There's no right or wrong. Generally, if it is more than a few lines of HTML, I find it better to place the optional/alternate content in another note and include it.

Boilerplate or Template?

  • Boilerplate has no formal meaning within Tinderbox but it is essentially code/text you wish to include in a template but which is common to all notes using that export. In many cases, such as with support script for the google features, the included content is 'just' plain text that happens to be HTML and Javascript code. In some cases, like the quick links panel, the note benefits from using an attribute value (though *not* from the note currently being exported); boilerplate allows for that. Ideally use the built-in 'Code' prototype for such notes as that strips out all $Text->HTML creation of tags such as <p> tags. This means you write the HTML code you want into the text but if you use ^text^ as the boilerplate note's template, then any deliberate export ^code^ you place in the $text is still process and the already evaluated result is passed back into the main template.
  • Templates. In some cases, the optional section is just a significant section bit of the current template's code that isn't needed by all notes. Here, it is the key attribute like 'tables' used by some sections of the site that list what codes and attributes do. In this case the include calls the current document ('this') - instead of some boilerplate note - and runs extra template code. Because the focus is the curent note, the attribute values are drawn from it, which is what you want. If in doubt, don't use an include but leave the code on the main template but enclosed by the same conditional ^if^ statement - the extra template section is only exported if the test condition is met.

Switches built into the main template

Switches built into the main template

These booleans set/altered from within the '5-basic'_all template control the following elements found below:

  • Tracking code for Google Analytics (analytics) - #21.
  • Google Translate box (#16) and supporting script (#22).
  • 'Similar To' links panel (#12).
  • Google Search (#18).

1. HTML head code

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>^title^</title>
<link rel="stylesheet" type="text/css" href="^root^^value($CSSTemplate(CSS))^">
</head>

The only point of interest here is the link to the site's CSS styling code which is itself a Tinderbox-generated note. The CSS is actually in a note at TB path /CSS/styles. That exports a document at /css/styles.css. The latter is the value of $CSSTemplate(CSS). This method works around the problem of getting relative links with no markup. Using ^linkTo("/CSS/styles")^ would emit '<a href="../css/styles.css" >styles</a>' with unwanted HTML instead of the desired '../css/styles.css'.

2. Quick-links panel

The author uses aTbRef daily for his own work as well as for community support. This content offers easily found jump-links to the most used reference content (e.g. system attribute descriptions, action code operator listings, etc.). This is the code:

	<div id="quicklinks-head5">
		<p id="qltop" class="quicklinks">^include("quicklinks-panel")^</p>
	</div>

The boilerplate include's note text is this code:

Quicklinks: ^linkTo("System Attribute List","Attributes")^ | ^linkTo("Full Operator List","Action Codes")^ | ^linkTo("Export Codes - Full Listing","Export Codes")^ | ^linkTo("Designators")^ | ^linkTo("Date Formats")^ | ^linkTo("aTbRef Site Map")^ | <a href="^value($MyURL)^^path(current)^">Here</a>

The enclosing <div> aids CSS styling.

Footnote: the 'Here' link is just a convenience for getting the URL of the current page when the site is being viewed in a Fluid.app SSB pinned to the Mac menu bar, which has no location bar showing the current page URL (which is needed when trying to add links to supports posts/emails). The boilerplate note's $MyURL holds the 'root' of "http://www.acrobatfaq.com/atbref5/".

3. Navigational 'cookie crumb' trail

3. Navigational 'cookie crumb' trail

This gives the reader some idea of where they are in the overall outline of the document. The ancestor containers are all click-able links and the first items is effectively the 'Home' button for the site (perhaps that is a bit obscure!). This is the code:

	<div id="navtrail5">
		<p class="cookietrail"><b>^ancestors("",""," : ","")^^title^</b></p>
	</div>

The enclosing <div> aids CSS styling.

4. Tinderbox app icon

4. Tinderbox app icon

Nothing special - just Tinderbox's program icon used (with Eastgate's permission) to help identify the purpose of the site. This is the code:

	<img src="^root^images/TinderboxIcon.gif" alt="Tinderbox Icon" width="64" height="63" id="iconcell5">

5. Title panel

This holds the note's title ($Name). It is styled along the lines of old Mac Help documents - that's the reason it is like this, you can make yours any style you like. The code:

	<div id="headertable5">
		<h1>^title^</h1>
	</div>

6. Deprecated content warning

Not seen in the example note. Some notes are flagged with a user boolean $IsDeprecated. This is context the author considers worthy of an explicit warning to suers that they are reading about methods they should no longer use. [example of use]. The code:

^if($IsDeprecated==true)^
^include("/BOILERPLATE/5-deprecated")^
^endIf^

The boilerplate is this:

<div id="deprecated">
<p>This pages describes features, codes or syntax whose use is now <b>DEPRECATED</b>, i.e. not advised either for new or continued pre-existing use.</p>
<p>Deprecated aspects of Tinderbox may be supported on a legacy basis but the latter support can't be presumed to be indefinite. Therefore you should update your active TBX documents to latest practice as soon as practical.</p>
</div>

Styling of the div puts the panel with a red fill so it is hard to miss.

7. Attribute notes

Not seen in the example note. If a note uses the prototype for a system attribute, this includes a key attribute table-like section [example of use]. The code added is:

<hr>
<div id="attributetable">
	<div id="attributetableleft" style="display:inline-block;">
		<p class="attributetabletext"><b>Attribute Data Type:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Attribute Default Value:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Attribute Group:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Attribute Purpose:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Attribute Inherited from Preferences?</b>&nbsp;&nbsp;&nbsp;</p>
		<p class="attributetabletext"><b>Attribute Read-Only?</b>&nbsp;</p>
		<p class="attributetabletext"><b>Attribute Intrinsic?</b>&nbsp;</p>
		<p class="attributetabletext"><b>Attribute First Added:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Attribute Altered:</b>&nbsp;</p>
	</div>
	<div id="attributetableright" style="display:inline-block;">
		<p class="attributetabletext">&nbsp;^value($AttributeDataType)^ &nbsp; [^linkTo(^value($AttributeDataType.capitalize()+" Attributes")^,^value("other "+$AttributeDataType+"-type attributes")^)^]</p>
		<p class="attributetabletext">&nbsp;^value($AttributeDefault)^</p>
		<p class="attributetabletext">&nbsp;^value($AttributeGroup)^ &nbsp; [^linkTo(^value($AttributeGroup+" Attributes")^,^value("other "+$AttributeGroup+" Group attributes")^)^]</p>
		<p class="attributetabletext">&nbsp;^value($AttributePurpose)^</p>
		<p class="attributetabletext">&nbsp;^if(^equal(^value($AttributeInheritsPrefs)^,true)^)^Yes^else^No^endif^</p>
		<p class="attributetabletext">&nbsp;^if(^equal(^value($AttributeReadOnly)^,true)^)^Yes^else^No^endif^</p>
		<p class="attributetabletext">&nbsp;^if(^equal(^value($AttributeIntrinsic)^,true)^)^Yes^else^No^endif^</p>
		<p class="attributetabletext">&nbsp;^value($CodeFirstAdded)^</p>
		<p class="attributetabletext">&nbsp;^value($CodeAltered.format(", "))^</p>
	</div>
</div>
<hr>

8. Export Code notes

Not seen in the example note. If a note uses the prototype for an Export code, this includes a key attribute table-like section [example of use]. The code added is:

<hr>
<div id="attributetable">
	<div id="attributetableleft" style="display:inline-block;">
		<p class="attributetabletext"><b>Code Type:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Code Scope of Action:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Code First Added:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Code Altered:</b>&nbsp;</p>
	</div>
	<div id="attributetableright" style="display:inline-block;">
		<p class="attributetabletext">&nbsp;^value($CodeType)^ &nbsp; [^linkTo(^value($CodeType)^,"other codes of this type")^]</p>
		<p class="attributetabletext">&nbsp;^value($CodeScope)^ &nbsp; [^linkTo(^value($CodeScope)^,"codes with similar scope")^]</p>
		<p class="attributetabletext">&nbsp;^value($CodeFirstAdded)^</p>
		<p class="attributetabletext">&nbsp;^value($CodeAltered.format", ")^</p>
	</div>
</div>
<hr>

9. Action Code notes

Not seen in the example note. If a note uses the prototype for an Action code, this includes a key attribute table-like section [example of use]. The code added is:

<hr>
<div id="attributetable">
	<div id="attributetableleft" style="display:inline-block;">
		<p class="attributetabletext"><b>Operator Type:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Operator Scope of Action:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Operator Purpose:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Operator First Added:</b>&nbsp;</p>
		<p class="attributetabletext"><b>Operator Altered:</b>&nbsp;</p>
</div>
	<div id="attributetableright" style="display:inline-block;">
		<p class="attributetabletext">&nbsp;^value($OpClass)^ &nbsp; [^linkTo(^value($OpClass+" actions")^,^value("other "+$OpClass+" type actions")^)^]</p>
		<p class="attributetabletext">&nbsp;^value($OpScope)^ &nbsp; [^linkTo(^value($OpScope+"-based operators")^,"operators of similar scope")^]</p>
		<p class="attributetabletext">&nbsp;^value($OpType)^ &nbsp; [^linkTo(^value($OpType+" operators")^,^value("other "+$OpType+" operators")^)^]</p>
		<p class="attributetabletext">&nbsp;^value($CodeFirstAdded)^</p>
		<p class="attributetabletext">&nbsp;^value($CodeAltered.format", ")^</p>
	</div>
</div>
<hr>

10. Content - the $Text of the source document

This is the main part of the visible document - the $Text of the note. If the note uses an image (the design allows for zero or one images per note) it is included here. A use attribute $WebImageLandscape indicates whether the image needs to be shown above all text or can be shown alongside it. There is a 3 way condition in the code below: no image (just text), an image to the side of the text or an image above text.

Images.

This is the code:

^if($WebImage)^
	^if($WebImageLandscape==false)^<div id="copyblock">
		^do("ImgTag",^root^images/^value($WebImage)^,,,^title^,,"grabimg")^
		<p style="color:#009900">Source note: ^value($Path)^</p>
		^text^
	</div>
	^else^
	<div id="menublock">
		^do("ImgTag",^root^images/^value($WebImage)^,,,^title^,,"grabimgmenu")^
	</div>
	<p style="color:#009900">Source note: ^value($Path)^</p>
	^text^
	^endIf^
^else^
	<p style="color:#009900">Source note: ^value($Path)^</p>
	^text^
^endIf^

11. Change listing

For the per-version release notes (actually agents) a little extra text and a listing of links is dropped in [see example]. The code:

^if($Prototype=="_change_agent" & $ChildCount>0)^
	<p>This version is cited in the following notes:</p>
	<ul>^children("/TEMPLATES/change_item")^</ul>
^endIf^
</div>
<hr>

12. 'Similar To' links panel

This panel replicates TB's 'similar to' function and notes the first 10 matches for the current note. Be aware, this is processor intensive and if included makes the export much slower (from a minute or so on a fast Macbook Pro to closer to 15 mins - albeit for c.2,500 exported pages). The attribute controlling this is

13. Navigational links panel

This section uses a series of nested conditional sections to add links to previous/next siblings and to parent elements to assist with easy browsing of content. Links in places like the TB support forum will often point people deep into the content. This along with the cookie crumb trail help give an idea about related content nearby. The code:

^if($OutlineDepth>1)^
<div id="footertable">
	<p id="uplink">Up: ^linkTo(parent)^</p>
	<div style="width:100%;text-align:center">
		<p>
		<span id="prevlink" style="text-align:right;">
		^if(^previousSibling^)^
		Previous:&nbsp;^linkTo(prevSibling)^&nbsp;
		^else
		^&nbsp;
		^endif^
		</span>
		<span id="nextlink" style="text-align:left;">
		^if(^nextSibling^)^
		Next:&nbsp;^linkTo(nextSibling)^&nbsp;
		^else^
		&nbsp;
		^endif^
		</span>
		</p>
	</div>
	<hr>
	<div id="footertablecookietrail">
		<p class="cookietrail"><b>^ancestors("",""," : ","")^^title^</b></p>
	</div>
</div>
<hr>
^endif^

14. Navigational 'cookie crumb' trail

This is simply a repeat of #3 above. The code is the same albeit with a discrete styling <div>:

	<div id="footertablecookietrail">
		<p class="cookietrail"><b>^ancestors("",""," : ","")^^title^</b></p>
	</div>
</div>

15. Quick-links panel

This is simply a repeat of #2 above. The code is the same albeit with a discrete styling <div>:

<p id="qlbottom" class="quicklinks">^include("quicklinks-panel")^</p>

16. Google Translate box

This is the code:

^if($UseGoogleTranslate("5-basic_all")==true)^
^include("google-translate-top")^
^endIf^

That will insert the anchor element for the JavaScript powered Google Translate.

 

17. Date of production (export) of the page

17. Date of production (export) of the page

This indicates when the page was last updated (i.e. exported). the code:

<p><i>[Last updated: ^today(d M y)^, using v^version^]</i></p>

18. Google Search feature

18. Google Search feature

This implements Google's Custom Search Engine (CSE). In this case the results are limited so must come from within the aTbRef site.

19. Creative Commons Licence

Creative Commons (CC) Licence. Currently using the v3 licence (aTbRef v6 will use v4). this is set up to make it easier to re-use this content on a regulated network such as a university LAN without having to seek express permission. The insert code is this:

^include("5-cc-panel")^

That pulls in this code:

<p><a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/3.0/deed.en_GB"><img alt="Creative Commons Licence" style="border-width:0" src="^root^images/88x31.png" height="31" width="88" /></a></p>
<p><span property="dc:title">aTbRef</span> by <a href="http://www.acrobatfaq.com/atbref5/index.html" property="cc:attributionURL"><span property="cc:attributionName">Mark Anderson</span></a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/3.0/deed.en_GB">Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License</a>.</p>
<p>[See aTbRef CC licence Attribution &amp; Waiver info]</p>

It should be noted that the above includes one small tweak. The CC site's suggested code pulls the licence icon from CC's own server.  For portability of the aTbRef resource, a local version of this has been substituted.

20. Footnote information

Footnote information about the source of the site data. The include code is this:

^include("5-tb-credits")^

This brings in this code:

<p><a href="http://www.eastgate.com/Tinderbox/index.html" title="Tinderbox from Eastgate Systems Inc." target="new"><img src="^root^images/made_with_tinderbox.png" alt="Made with Tinderbox" width="133" height="18"></a> Content, Tinderbox export and web design by Mark Anderson, <a href="http://www.shoantel.com/services.html" target="new">Shoantel Limited</a></p>

21. Tracking code for Google Analytics

This include inserts the JavaScript code used for Google Analytics to track page use.

^if($UseGoogleTracking("5-basic_all")==true)^
^include("google-tracking")^
^endIf^

The include adds the actual JavaScript.

22. Google Translate supporting script

This inserts the additional JavaScript needed to make #16 work. Code:

^if($UseGoogleTranslate(5-basic_all)==true)^
^include("google-translate-bottom")^
^endIf^

The include adds the actual JavaScript.