Welcome, Guest. Please Login
Tinderbox
  News:
IMPORTANT MESSAGE! This forum has now been replaced by a new forum at http://forum.eastgate.com and no further posting or member registration is allowed. The forum is still accessible via read-only access for reference purposes. If you wish to discuss content here, please use the new forum. N.B. - posting in the new forum requires a fresh registration in the new forum (sorry - member data can't be ported).
  HomeHelpSearchLogin  
 
Pages: 1 2 
Send Topic Print
Getting Started with Mark A's Export Tutorial (Read 13457 times)
J Fallows
Full Member
*
Offline



Posts: 418

Getting Started with Mark A's Export Tutorial
Sep 29th, 2014, 7:22pm
 
[Please see update below.]
Mark, thanks for the very useful export-demo files, you have posted today here: http://www.eastgate.com/Tinderbox/forum//YaBB.pl?num=1412015986.

As I have worked through the five demos, I understand what each of them is doing, and why.

My question involves what happens *before* files get in the condition you have created here. Which template did you assign to each of these files? Where did you get those templates? Was it a matter of just clicking the File/Built-in Templates/HTML command from the program menu? Was there any special place you had to either find or place the templates?

After a TB note has been assigned a template, as these notes obviously have, we no longer see which template it is from the HTML tab on the text window of the display. (I realize that you can find it from the Get Info pane, but I bet some users don't realize that.) Before a template has been assigned, you need to know which one goes with which kind of note—parent, child, envelope, recursive, etc.

I know this is second-nature obvious to those who are used to exporting from the file, as some other features have become second nature to me. But would you mind please backing up one step to show what led to the files you have offered here?

Sincere thanks once again.

UPDATE: Mark, I now see that each how-to note contains an explanation of the template, eg:
Quote:
The export uses 2 templates, called ‘recurse’ and ‘child-item’. they are contained in the document so you can see how they do their work.


So thank you for that part of the explanation. Still curious: Were these part of the built-in suite? Did you hand craft them? How would someone who wants to replicate these actions go about it? Should we copy-and-paste those included templates into data bases of our own?

Sincere thanks, and you see that I am embracing the spirit of not being afraid to ask dumb questions.
Back to top
 
« Last Edit: Sep 29th, 2014, 7:29pm by J Fallows »  
  IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Getting Started with Mark A's Export Tutorial
Reply #1 - Sep 30th, 2014, 3:26am
 
Good questions! Just the sort of thing I hoped to hook out as I'm very aware people find different parts of the overall process hard to guess. So, I'll try and shed some more light on the process…

Quote:
My question involves what happens *before* files get in the condition you have created here. Which template did you assign to each of these files?Where did you get those templates? Was it a matter of just clicking the File/Built-in Templates/HTML command from the program menu? Was there any special place you had to either find or place the templates?


Unlike TB5, TB6 only uses internal templates, by which I mean notes within the current TBX file that the user [sic] has set to that purpose. Any note can be a template and this is set up by:
  • Adding a 'built-in' template via the file menu.
  • Setting $IsTemplate to true. This can be done via:
    • Properties Inspector, Prototype tab, 'Template' tick-box.
    • Setting $IsTemplate via the Quickstamp.
    • Showing $IsTemplate as a Key Attribute and ticking the attribute's tick-box.
    • Setting $IsTemplate via a prototype or via an $OnAdd action, e.g. the Templates container added when inserting a built-in template has just such an $OnAdd action.
    • Any other action method such as a stamp or agent action.
It's worth noting that a template can be 'un-made' by reversing the $IsTemplate setting. For instance, you might want to retire a template but keep the code around. Do this by setting $IsTemplate to false (un-ticking the box); the note is now a normal note and can't now be used as a template. Of course, there's nothing to stop you toggling $IsTemplate back on to start using it again. Very flexible!

TL;DR - if you're itching to just know the quickest way to add a template to a doc, jump to my next post in the thread.

Because making a note into a template is controlled by an attribute, any note anywhere in the doc can be a template, with one exception: prototypes that are set to be templates. This makes sense as a deliberately planned prototype is used to 'style' other notes rather than be used directly itself.

So that's how a document gets to have a template. A template can live anywhere, but unless you're personal style demands otherwise (people take different approaches) my strong recommendation is to use a root-level Templates folder. Better still, start by adding any built-in template as this will create two root level containers (if not already there): 'Templates' and 'Prototypes'. The latter will hold a prototype 'HTML Template' which sets up non-default note characteristics things like a monospaced text font and disabled smart quoting, etc., such as are desirable in a template.

This is getting long, more in my next post.
Back to top
 
« Last Edit: Sep 30th, 2014, 4:35am by Mark Anderson »  

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Getting Started with Mark A's Export Tutorial
Reply #2 - Sep 30th, 2014, 4:05am
 
Setting up an HTML template in TB6
What's the simplest way to set up a template so I can export my doc?

  • File menu -> Built-in Templates -> HTML
  • This adds
    • a 'Prototypes' container at root level in the TBX
    • an 'HTML Template' prototype in that container
    • a 'Templates' container at root level in the TBX
    • 2 templates in that container. 'HTML page' and nested inside it, 'HTML item'
At this point you can use 'HTML page' as you export template (explained below). Or any note you now add to the the Templates folder will automatically be made a template and be available for use.  If you don't want the default-added template you can delete it (and its child without harm - assuming no notes are set to use it!).

Setting a default template. At present, Document Settings lacks an export tab. There is a good reason - v6.0.x is still using most TB5 methods but a review of the whole export process is slated for v6.x. at that point some export settings may return. For now, setting a doc default template needs manual editing via the inspector. I'll assume we're using 'HTML page' in the default 'Templates' container, i.e. at $Path "/Templates/HTML page".

You can set a document default by setting the default value of $HTMLExportTemplate:
  • Open the Document Inspector, 'System' tab.
  • In the top search box type 'HTMLExportTemplate' (no quotes) and click Return. TB will now find and select the correct category and attribute.
  • Check that $HTMLExportTemplate is indeed selected and then in the 'Default' input box enter '/Templates/HTML page' (no quotes). Click the Return key.
All notes set to export (by default, they all are except the Prototypes and Templates containers) will use the 'HTML page' template. To see this, select any exporting note in the doc, open the HTML Inspector, 'Export' tab. Its 'Template' pop-up menu should show '/Templates/HTML page'.

Setting a note to use a non-default template. Assume you've added a new export template 'My HTML page' to the Templates container and you want to use it for note 'Project X'. So:
  • Find and select note 'Project X'.
  • Open the HTML Inspector, 'Export' tab.
  • The 'Template' pop-up should show the document default template (as set up above). Open the pop-up.
  • Select '/Templates/My HTML page'.
  • Done! When exporting, this page will use the selected non-default export template.
Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Getting Started with Mark A's Export Tutorial
Reply #3 - Sep 30th, 2014, 4:31am
 
Nesting templates. This confuses some people, because by chance all 3 available built-in templates used nested pairs of templates.

Nesting implies nothing except a possible relationship. In the built-in templates, the nested template is used by the containing template, normally for recursing content (see my export exercise #5).

Actually, any template can call any other - assuming the code makes sense to do so. Nesting templates really is just one way of reminding your self what goes with what in the export process, nothing more.

Nesting poses once gotcha in v6.0.0 through v6.0.4 as creating a new child note (Shift+Return creating a note) of a template doesn't assign the HTML Template prototype and thus make it a template; you need to check and assign the prototype yourself. Nesting/moving notes that already have a prototype is no problem. Anyway, as of v6.0.5 (when it comes) this edge case is fixed.
Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Getting Started with Mark A's Export Tutorial
Reply #4 - Sep 30th, 2014, 4:34am
 
Quote:
After a TB note has been assigned a template, as these notes obviously have, we no longer see which template it is from the HTML tab on the text window of the display. (I realize that you can find it from the Get Info pane, but I bet some users don't realize that.) Before a template has been assigned, you need to know which one goes with which kind of note—parent, child, envelope, recursive, etc.

Wrong place to look, though I see your train of thought. In v6, see the 'Export' tab of the HTML Inspector. the 'Template' pop-up shows the currently set export template (it's full path).
Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Getting Started with Mark A's Export Tutorial
Reply #5 - Sep 30th, 2014, 4:49am
 
Quote:
Still curious: Were these part of the built-in suite? Did you hand craft them? How would someone who wants to replicate these actions go about it? Should we copy-and-paste those included templates into data bases of our own?


Part of a built-in suite? No, I wrote these for the exercises, back in c.2009. IIRC it was originally content for attendees at a Tinderbox Weekend conference. About the only change I made to the templates in checking them for v6 was to change to an HTML5 doctype (nerdy HTML stuff most folks don't need to know/worry about)

Did you hand craft them? Yes, but a judicious amount of copy/paste was involved.

How would someone who wants to replicate these actions go about it? Plagiarise! Rip, mix and burn. Copy all or as much code as you need to your own documents (as yet v6 doesn't allow inter-doc drag-drop) - just make sure you're pasting into a template note. An earlier replay explained how to make a new template. Basically, as long as you've set up a Templates folder correctly, any new note you create inside that container should be a template. Or,  duplicate an existing template, set a new $Name and then delete all the $Text and paste in new stuff. Either way is good.

Should we copy-and-paste those included templates into data bases of our own? Sure, only only use the ones you find pertinent. The template names, the code, etc., aren't tablets set in stone. They're just examples of the basics. For those who understand HTML I hope it's enough to enable folk to start mixing their own. Less sure-footed on HTML but have a precise need? Ask here: show the code you've got and describe your need/idea. In the latter case do accept that you might be asking for something that can't currently** be done.

** Long-term users will know new features get added all the time.  A well explained need, and which can to accommodated can often added quite quickly. It's one of the things I like about small software houses - things don't have to go via corporate for approval.
Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
J Fallows
Full Member
*
Offline



Posts: 418

Re: Getting Started with Mark A's Export Tutorial
Reply #6 - Sep 30th, 2014, 8:28am
 
Mark A, these are extraordinarily useful. Thank you very much for the time and care that went into preparing them.

And, as with so many things, once you explain it, it's obvious!  Wink Sort of.. But it now is obvious-enough to me that for the first time I feel as if I can make this part of my basic Tinderbox toolkit.

Thanks!
Back to top
 
 
  IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Getting Started with Mark A's Export Tutorial
Reply #7 - Sep 30th, 2014, 9:18am
 
Obvious after the fact - yes indeed. Thanks for your questions - about things I overlooked to mention - and the answering of which will I hope enrich use of the exercises. At some point I'll try to reverse some of the data into the exercises.
Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Corey Colyer
Full Member
*
Offline



Posts: 11
Morgantown, WV, USA
Re: Getting Started with Mark A's Export Tutorial
Reply #8 - Oct 1st, 2014, 10:28am
 
Mark... Thank you for these.  They are clear and easy to follow.  

From your exercises, I now understand that I can export any attribute into an HTML file by including the attribute embedded within carets (^) in the template.  Probably obvious to others, but an epiphany to me.  For instance:

Code:
</head>
<body>
<h1>^title^</h1>
Created by: ^Creator^ on ^Created^
^text^
^children(child-item)^
</body>
</html>
 



Generates an extra line in at the top of the HTML just after the H1 that says:  "Created by Mark Anderson on 11/15/2009". Brilliant!  This will prove to be very handy for me in generating lecture notes for my students which can include dynamic due dates and other features from the syllabus.  

I am still a little confused about the nested templates.  I understand that in EX-5 there are two templates (recurse & child-item).  From your explanation up thread, it's not clear to me if the code ^children(child-item)^ is referencing the second template, or referencing an attribute in the tbx.  This question betrays my ignorance of the internal attribute structure of tbx files.  Is child-item an attribute in the tbx file?

So the question: if my export template relies on nested templates, do I have to declare that reliance in top-level template?  Or will Tinderbox automagically figure that out based on the existence of another template that meets the necessary conditions?

Again, I thank you for this tutorial.  It is very helpful.
Back to top
 
 
WWW Corey Colyer colyecj   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Getting Started with Mark A's Export Tutorial
Reply #9 - Oct 1st, 2014, 12:07pm
 
@Corey, yes you can insert attribute values that way. I'm not sure what example you were following as the two code you used are now deprecated (see more). Here are the correct replacement codes:

^Creator^  - use ^value($Creator)^
^Created^  - use ^value($Created.format("l"))^ (date formatting strings)

Nesting templates in TB has absolutely no effect on how templates interact. Eastgate's built-in samples are nested simply to help indicate these templates are used together. Add the built-in HTML set and revers the nesting and then use the 'HTML page' template - it still works by using the 'HTML item' template, proving the TB outline nesting of templates (as opposed to other notes) has no effect on export.

As to Exercise 5.  The 'EXPORT ME' is the only note to use the 'recurse' template.  The 'recurse' template calls all children (in this case the 2 of 3 that are set to export), using 'child-item'. The actual recursion part - sorry I chose bad template names here - occurs inside 'child-item' as it calls itself.  A very simplistic analogy is me giving you a box of chocolates with these very simple instructions:
  • Open the box.
  • Eat a chocolate.
  • If there is another chocolate eat it and repeat this instruction or, if no remains chocolates else close the box.
Now, als long as you can stomach the sweetness you'll finish the box be there 5 sweets or 500.  The 'child-item' template is playing the same game but in code. It takes the current notes data then asks each of it's children to do the same in in their doing so they ask their own children he same question and thus the process reaches all the way down a branch of the outline until every descendant has been poled for information which they pass back. Recursion is complex - it's not lesson 1 in coding - but as a TB user you don'y need to understand the mechanics, just that with the system seen in exercise 5 you can pull large amounts of data with just do templates.  Here is the same trick used to replicate the outline (site structure) of aTbRef.

Next to your other question…
Back to top
 
« Last Edit: Oct 1st, 2014, 12:08pm by Mark Anderson »  

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Getting Started with Mark A's Export Tutorial
Reply #10 - Oct 1st, 2014, 12:24pm
 
Quote:
So the question: if my export template relies on nested templates, do I have to declare that reliance in top-level template? Or will Tinderbox automagically figure that out based on the existence of another template that meets the necessary conditions?

Yes, but the 'declaration' can occur in two ways. The two template system is sometimes referred to and the envelope and letter method as there is one envelope - the top, calling template - and as many (similar) pages as needed, the latter being re-use of the second template.

To re-iterate, nesting - as seen in Tinderbox, does nothing of itself. Indeed, if it's causing doubt or confusion, just un-nest the templates.  Nothing will break.

Why did I say the declaration can be done two ways.  Consider the ^children^ code options:

^children^
^children("templateX")^

In both cases the current template will pull back data from each of its (exporting) children. However, let's assume the TBX document's default export template is called "templateY" - we don't care what it does except that we also don't want to use it in our recursing template:

^children^                    --> will return data using using 'templateY'
^children("templateX")^ --> will return data using using 'templateX'

In other words, method 2 overrides the default per-note allocation of 'templateY' and tells TB to do the export task using 'templateX' instead. An added bonus is this means that if 'templateY' is an HTML page type of template, than the note can export itself as a single HTML page and contribute data to the recursing export. Pretty neat!

I'm sure this will prompt more questions. Keep them coming and I'll do my best to answer. Tip: in trying to learn this stuff start with very simply tests like in my exercise files. Don't just try and applying it immediately to you 200 note TBX as you'll find any errors hard to spot and fix. Start small and scale up as you burgeoning expertise allows.
Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Corey Colyer
Full Member
*
Offline



Posts: 11
Morgantown, WV, USA
Re: Getting Started with Mark A's Export Tutorial
Reply #11 - Oct 1st, 2014, 1:16pm
 
Quote:
I'm not sure what example you were following as the two code you used are now deprecated (see more). Here are the correct replacement codes:


Aha!  I should have been more clear.  Your small, clearly documented, tbx files were the perfect size to explore.  Since there were only a couple of notes and one (or two) templates in each, I was able to focus carefully on components and ask myself what each component did.  Previously, I assumed that the ^codes^ were a specialized macro syntax.  But looking at your examples, I discovered that they look like $attributes.  That led me to hypothesize that that this convention exports the contents of attributes and should export any attribute.  So I tested and confirmed  (Something undoubtedly you and Mark B have amply documented elsewhere, but I've missed).

Thank you for the heads up on depreciated code.  I will study this further.

Quote:
Why did I say the declaration can be done two ways.  Consider the ^children^ code options:

^children^
^children("templateX")^

In both cases the current template will pull back data from each of its (exporting) children. However, let's assume the TBX document's default export template is called "templateY" - we don't care what it does except that we also don't want to use it in our recursing template:

^children^                    --> will return data using using 'templateY'
^children("templateX")^ --> will return data using using 'templateX'

In other words, method 2 overrides the default per-note allocation of 'templateY' and tells TB to do the export task using 'templateX' instead. An added bonus is this means that if 'templateY' is an HTML page type of template, than the note can export itself as a single HTML page and contribute data to the recursing export. Pretty neat!


This answers my question.  I'm going to play with this and will post more questions as they arise.  Thanks!
Back to top
 
 
WWW Corey Colyer colyecj   IP Logged
Mariusz Pisarski
Full Member
*
Offline



Posts: 26

Re: Getting Started with Mark A's Export Tutorial
Reply #12 - Jul 18th, 2015, 7:37pm
 
Hello,

Thank you for the great post on exporting. I am using an old tbx 5 updated to tb 6 that on the export still generates <h3> instead of <p> although in the template file there are no hints of >h3>. How to replace it throughout the project and within Tinderbox?
Back to top
 
 
  IP Logged
Mark Anderson
YaBB Administrator
*
Offline

User - not staff!

Posts: 5689
Southsea, UK
Re: Getting Started with Mark A's Export Tutorial
Reply #13 - Jul 19th, 2015, 7:29am
 
Based on what you report, it is likely that you've got larger font sizes headings in your $Text triggering the auto-heading markup during export - see more here. If it's not the latter look at the template code. There are only 4 possible sources for the <h3> being created via :
  • Explicit inline HTML mark-up in $Text.
  • Auto-markup via ^text^ as explained in the link above.
  • Mark-up in the export template.
  • (rare) Post processing via $HTMLExportCommand.

Back to top
 
 

--
Mark Anderson
TB user and Wiki Gardener
aTbRef v6
(TB consulting - email me)
WWW shoantel   IP Logged
Mariusz Pisarski
Full Member
*
Offline



Posts: 26

Re: Getting Started with Mark A's Export Tutorial
Reply #14 - Jul 25th, 2015, 7:56pm
 
Thank you, I will get back with my findings. The <h3> problem has been happening to me throughout different operating systems and different Tinderbox versions.
Back to top
 
 
  IP Logged
Pages: 1 2 
Send Topic Print