I would see these starter templates as fairy simple and straightforward-- to give the new user the sense that they are accomplishing something without having to do heavy coding. Of course, once people start using them they will have questions and want to change them, but at least they can start working and feel productive.
For example, what if there was a simple blog that would generate a simple website that someone could actually use. Using free bootstrap templates a person could set the title of their blog, create posts, add pictures, and export an html directory. I’m tempted to take this project on. . . I bet I could do it in 2-3 hours.
Without taking away from anything that’s been said here, I’d float a thought about the difference between templates and examples.
Recently I’ve been working on creating a TBX that will produce a web site/blog and on this and the previous forum there are working links to TBX files that other users have used to do the same task. So as I was starting out I dug these up and looked at them.
What I found was that they all approached the same task in wildly different ways. They also all worked with info differently from how I imagined my own (very simple) project doing things. Still I dug in to see how they worked and tried to adapt them to seve as a base. I’d delete what wasn’t useful to me and mark things that needed to be reworked. But over and over I found myself with either a) near-empty files that were basically a blank canvas or b) semi-complete files that I understood imperfectly but needed to be heavily adapted. Ultimately, I decided that I would save myself work or confusion by just starting from scratch.
Once I was well along in my project, those same files were useful examples that gave me ideas of things I might do that I had overlooked working on my own. Using them as inspiration made my own project better. But even then, the examples weren’t something I could cut and paste things into my own project. I understand some kinds of actions better than others, and there’s no point in dropping things into my project that I don’t feel comfortable adjusting. I need to do things using the actions that make sense to me. So what happened is that I’d see something done in an example and would then figure out (usually with help from the forum) how to use “my” actions to do something similar.
What I’ve wound up with in the end produces the HTML that I wanted exactly and in a browser that output looks very similar to the output of the examples I looked at. But my TBX file is very very different from those examples. Here’s the thing though: I understand how mine works and when I’ve had to tweak things, I’m not at a loss how to do it because it’s all rigged up in a way that makes sense to me.
My point in all of this is that the flexibility TBX may make the distinction between templates and examples disappear. Almost anything a user might want to do–if they are going to chose to do it in TBX–is probably going to be something they want to customize. And if that’ s the case, then template are likely to function simply as an examples. Which is fine. But if it’s true, then dealing with a blank canvas (and all the difficulties that can entail) may be inevitable.
Just to be clear: my point in the previous post is NOT that there shouldn’t be templates. It’s just that any templates may serve very different purpose than they do in other applications. Because users will probably depart from them so quickly and so completely, the templates may inspire but probably won’t save anyone from the learning curve.
I’ve taken one of those documents – from 2004! – that Marisa Antonaya published. Marisa’s starting point is a document that produces a simple web site. The bits and pieces, and the CSS needed for presentation, are in this file
I updated the document for Tinderbox 7, which was not a difficult task. The main thing that the document needed was to have the HTML templates inserted into the Tinderbox document. In 2004, we kept our HTML templates in separate .html files and referenced them in the Tinderbox document – that practice went away a long time ago.
There are likely other modernizations possible, but this is merely a “starting point” after all. For example, the HTML is not canonical HTML 5. It still works, though. I’ll leave it to others to revise the templates and fully modernize them.
The two major factors in building a successful website using a Tinderbox document are the export templates and the CSS to style the site. Marisa’s document is a good learning tool because it is simple yet robust enough to demonstrate how Tinderbox interacts with HTML code and CSS styling – even 13 years after the document first appeared. Very little software, in my opinion, resists the deprecation of time as well as Tinderbox does.
I agree with Brian’s notes and comments. I’ve learned a lot from the templates / starting points / examples (I don’t care what they’re called) from the Tinderbox exchange, the old Wiki, the old Cookbook site, and all the Tinderbox weekends – I own them all. Someone here was mentioning those files are imperfect. Well – yes they sometimes are, but that’s not the point.
The point is that the Tinderbox community for a long time has supported people who want to learn – frequently by sharing these files. (I am confident that no one has or ever will be as supportive in this respect as Mark Anderson.) For better, and rarely for worse, the enthusiasm and pedagogical value of the shared examples has always be excellent, in my opinion.
For my own documents, these examples are teaching tools – I’ve never used them as a real “starting point” – I prefer to build from scratch using best practices I’ve learned elsewhere.
@PaulWalters, I like the work done on Antonaya blog. It has great directions and could be a good starting place for someone wanting to make a blog. In the blog that I created, I was aiming for barebones simplicity. What you updated is better in the long run.
I have learned a lot from those places as well. However, I’ve gone down many dead ends with code that isn’t recommended any more.
I’m suggesting having 3-4 templates or examples or demos that are well cultivated to serve as the basis for someone learning TBX, but also to allow someone to start doing some work while they are in the process of learning. Looking at broken tbx’s can be useful, but for a new user it can be overwhelming.
I think it’s worth noting these simple general export examples which walk newcomers into the basic aspects of HTML export and which form the building blocks of more complex tasks like blogs.
I should explain the above 3 posts relate to an example TBX which is a (very!) preconfigured Tinderbox file for making a blog. There is a lot of detail, so it merits its thread. It could have gone in the Tutorials section but I put it in Export and figure it’s not worth moving again. Anyway, if interested in blog-type export, check out the BoxPress thread.
I’ve decided to go ahead a post the blog file I spoke about in my earlier post since it’s designed for a blog that is primarily for book/movie reviews and my commonplace book…which means it kind of hits the three initial suggestions launching this thread. I don’t see how it could be used as a template but maybe it has things in it that might serve to spark ideas for somebody? (who knows lol)
The caveats are: I don’t know HTML or CSS and built all of this by working with a couple books open to show me what to do. It works (or seems to so far) but it’s not necessarily pretty.
What I think is cool about it is:
the if^…^else^…^ export code for the various log templates that create brief sidebar descriptions for each post based on available attribute data
the way I’m managing images externally using child notes to generate the necessary <img> info and ^include()^ to place images within a note.
the category and link pages built up using basic links
The note called “Instructions” is actually my notes to myself: I wrote it so I don’t forget how things work and mess anything up as I get used to using it and, alas, didn’t take the time to update it beyond what I need to remember before posting here. And the RSS is a cut and paste from @mwra’s TbRef file with updated info. I haven’t taken the time to see if it works after my fiddling though. So probably best to ignore it.
This looks nice. I like the idea of notes as placeholders for external images. I’ll probably adopt that for aTbRef at some point as it makes it easier to use multiple images per HTML page. I’d probably go with a central container for all images as some get re-used to don’t have a single ‘parent’ note.
Anyway, a very interesting TBX with lots of detail - thanks for sharing.
You’ve hit on a couple factors that I think make these shared templates more useful:
Including liner notes, as it were, that explain what the template does, how it works, and possible gaps and improvements.
Refactoring the work of others
In my experience, these are two marks of a successful coding: it contains self-documentation, and it refactors proven patterns.
I like also that your template is straight forward and gets the job done. I enjoyed reading your instructions and the code itself. Sometimes in forums like this we find shared code that is so extremely densely packed and idiosyncratic that it is difficult to imagine ever learning from it.
** One minor glitch: over here the file complains that it is missing export template: /Templates/Web Site Template
Actually this points out something I hadn’t even thought to mention: I don’t upload everything that exports to the server. I need the index note and the contents of the posts container and the pages container. The style sheet is stable and already on the server. The images are in DevonThink and get uploaded from there.
So when I export I actually just grab the files/folders from the export files that I need and manually upload them to their server folders in a couple batches. It’s a bit more work, but not much.
Sometimes in forums like this we find shared code that is so extremely densely packed and idiosyncratic that it is difficult to imagine ever learning from it.