Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com)
http://www.eastgate.com/Tinderbox/forum//YaBB.cgi
Tinderbox Users >> Exporting from Tinderbox >> Making an HTML outline (expandable/contractible)
http://www.eastgate.com/Tinderbox/forum//YaBB.cgi?num=1240192762

Message started by Marcelo Mirage on Apr 19th, 2009, 9:59pm

Title: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 19th, 2009, 9:59pm

I couldn't find this specific project in the forum (I may have overlooked it):

How could we go about creating an html page outline? Not editable, of course, but expandable and contractible? So as to have the same basic abilities of an outliner application?

I'm thinking in the lines of Stretchtext ( natematias.com/stretchtext/ ), with a few adjustments to the original project (there are a few issues that have to be addressed, like overlapping text when two expandable paragraphs are opened simultaneously and some minor formatting problems).

However, TB's 4.6.2 version doesn't seem to export Nathan's Tinderbox sample of stretchtext correctly, (I might be doing something wrong, who knows)... has anyone updated the code?

If not stretchtext, does anyone have another solution?

====
On a second note: this is my first post in this forum. But I have been with you guys for a while.
My regards to you all!



Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Bernstein on Apr 19th, 2009, 11:07pm

Updating Nathan's stretchtext demo should be easy.  And I've done a collapsible outline demo at several Tinderbox weekends, too, using a related but more primitive technique.  (I use something similar for the book cover popups at markbernstein.org.)

Much depends on exactly what you want to do.  Have you a particular javascript in mind?  Or a Web page style?  Are you starting from scratch?

The best approach, I think, is to figure out what sort of HTML you want, and then you'll see how to get Tinderbox to give you the HTML.  So, let us know more about where you'd like to go, and we'll work out a path.

FWIW, I'll be writing a bit more about stretchtext shortly.  I can't quite yet, because its related to a paper for Hypertext '09, and the conference deserves first crack at the work. But that will be coming along shortly.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 20th, 2009, 4:55am

I think I've found the breaks. These aren't a fault of the original author, TB has moved on meaning some code renders differently or not at all.

Problem #1. In export template "prefix-suffix.html", v4.6.2 doesn't like this line:

^if(#linkedFrom(Prefix/Suffix))^

...as it treats the slash in the prototype note's title as a division, to no useful result (no HTML ouptput). However, the code works if you re-write the line as:

^if(#linkedFrom("Prefix/Suffix"))^

...or, as #codes are now depreacted, as...

^if(linkedFrom("Prefix/Suffix"))^

FWIW, a clearer way to write the above - as it show the actual evaluation being made - is:

^if($Prototype=="Prefix/Suffix")^

...noting that the '==' equality operator is syntax new to v4.6+. The 'margin-notes', 'prefix-suffix', and 'subheading' templates all make this slightly oblique use of #linkedFrom to test for the current note's prototype.

Problem #2. Unless you publish to the supplied export folder - thus overwriting the supplied example, your output will lack an 'elements' sub-folder holding at JS and CSS files needed. For now, simply copy paste the 'elements' folder to your output folder.

Personally, I've moved away from external templates unless many different TBXs will share the same templates; of course editing one template to fix an issue will affect all ouptput using it which may - or may not - be desirable depending on your needs and style of work.

I also prefer to keep the CSS as exportable notes so I can quickly find and check code. However, with the JS files as above if you are sharing the code across many TBXs' output then there may be more sense in manually placing the code in the export location; you're unlikely to be editing the JS code as much/often. If you are using a modern JS framework (Prototype, jQuery, MooTools, etc.) then the size if the JS libraries may outweigh your TBX HTML output so internal storage in the TBX would bulk your document unnecessarily. All of which goes to show there's no single 'right' way to to things with TB export!

Problem #3. Image export. When I first tried the export in v4.6.2, the image used in the exported 'Writing Tinderbox Stretchtext' note export edit's image to a different name/location than the HTML page expected.  I did wonder if it was some side effect of the alias of 'including images' confusing TB.  Aliases now export as separate files and I'm not sure if that was true when Nathan wrote his example. I can't repeat the problem, so may be if you export a second time this issue will go away! Tip: when writing a doc like this it can be handy to explicitly note the TB version used - though I'm as guilty as anyone of forgetting to do this in my examples.

Problem #4. Less a problem than a puzzle. I can see no apparent need for the alias of the 'Prefix/Suffix' prototype in the 'System Prototypes' container.  I don't think it does any harm, but nor do I think it should be there.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 20th, 2009, 10:42am

to Mark B.,

Hmm... what I want, what I want... at first, let's try a simple: clicking on a disclosure triangle next to each entry that would expand/contract the level immediately below, just like an ordinary outliner.  

Yes, I'm starting from scratch. The idea is to have a basic setup to be used whenever I need to share an outline-structured document. HTML format is ideal because it's compatible with all platforms and so no special app. is required.

Can this be done without javascript? I'd like to learn that.

But hey, in Steve's sonnet http://steveersinghaus.com/stretchpoem/poem.html that dissolving effect, looks smooth! Wouldn't hurt to learn that one too.

I don't really have a specific project in mind, Mark, I just want to find, explore (and hopefully master) a few different techniques.

========

to Mark A.,

Thanks, man. I'll implement the corrections you pointed out. I'm really attracted to the stretchtext concept. It does suggest a ground-breaking approach to reading, writing, and presenting text.

Cheers!

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 20th, 2009, 11:03am

@Marcelo. It sounds as it you want an outline with headings that have hidden 'contents' that's shown/hidden on a mouse-click. If that's the case, IMO, stretch text seems a too-complex solution as it's attempting to resolve a different problem; you'll end up doing a lot of content surgery that's not directly related to your output needs. If you read Nathan's original notes, the demo isn't written for nesting more than 2 (more?) levels, certainly not N levels [added later]:

Quote:
With the default template, expandable paragraphs may be nested two-deep. With modification to the CSS, deeper levels of nesting can be possible.


I'd also add one more question - how much data are you looking to export?.  If you do everything in one browser page you may find that if it's a lot (not a fixed figure!) the page may not perform as you want.

My initial guess is you want a recusing template where each note is output as a heading that when clicked shows/hides its body copy ($Text) and the headings for it's children - allowing drill-down. CSS is used to mirror outline level by increasing the left margin for each level.

The bits that get harder are expand-all and collapse all with will need some JavaScript DOM functions to loop through the document showing/hiding stuff.

Anyhow, it's easiest to draw out what functionality you need/want before passing samples around.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 20th, 2009, 11:36am

Actually, if you use nested lists (<ul> tags, etc.) it saves you having to think about indenting. You can see the principle, in the site map page for aTbRef. The latter page is 164kb - big for a web page. Imagine the page  size if each listed item included (hidden) inline content.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 20th, 2009, 11:59am

Collapsible outlines are truly an amazing didactic tool. One could, theoretically, fit a rather fancy summary of, say, a Dostoievsky's novel, in a single page!

I like to demonstrate to my students the notion of multiple substructures within a complex literary work, which helps them visualize the work as a whole when levels are collapsed OR explore it in finer detail as needed, when expanded. The possibilty of synthesis and analysis within a single text... a revolutionary resource, indeed! Only a century ago, this could arguably be considered the critic's impossible holy grail.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 20th, 2009, 12:10pm

@Mark A.

But yes, Mark, I'm thinking of nested lists, at first, but also, later on, the possibility of embedding stretchtext's resources, like marginal note, images, etc.

I'm thinking of this single page as a FANCY document. In sum, something just like Nathan's document, with this one additional resource: the "N levels" you mentioned.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 20th, 2009, 12:24pm

That's fine but be aware that at some point page size, host resources or browser memory leaks (if not careful with DOM scripting) may limit extensibility. How many notes are we talking about? 10s, 100s, 1000s?

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 20th, 2009, 4:06pm

Mark A.:
Quote:
It sounds as if you want an outline with headings that have hidden 'contents' that's shown/hidden on a mouse-click
.

I'm not sure I understand what you mean. If I did, then "yes": each heading would be a note's name, just like in TB's Outline view. Each can be shown/hidden on a mouse click.


As for the number of notes... I have no idea, Mark, since I don't have a particular theme in mind, but only the structure itself. It can in theory go well beyond the hundreds, or no more than a few dozen.

I want to make clear, friends, I'm proposing this as a general case study, not a particular task, with  specific content. If I can understand how it's done, I can post a tutorial on the technique. That's my primary intention. The technique must be flexible enough so as to adapt to many different situations.






Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 20th, 2009, 6:21pm

If you do go the collapsible oultline route, this article might be useful. You'd need to expand the JS to add showing of title & text vs. title alone but the article is a good starting point using unobtrusive JS methods making your HTML templates simpler to write.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 20th, 2009, 7:43pm

Highly informative article, Mark, thanks. Lots to chew on.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 20th, 2009, 8:41pm

@Mark B.:
Quote:
And I've done a collapsible outline demo at several Tinderbox weekends, too, using a related but more primitive technique.


Can you show us how?

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 20th, 2009, 8:58pm

Ok, here's what I have in mind so far:

We'd only use the notes' names for the outline. I think the $Text could be used for something else, but I don't have any ideas yet.


- "N" levels are not really necessary, on second thought. I think root + 3 levels down is good enough. 4 levels should give us enough depth of analysis.

- So, if we're dealing with, say, a book summary, root level would contain introductions, chapters and appendices. Level 1 would be for the major topics within the chapters. Levels 2 and 3, for eventual expansion of the topics. But all levels would not consist of more than one phrase or two. That's where marginal notes come in: if a topic deserves further expansion (whole paragraph comments, images, sidenotes, etc.), we'd click on a linked word in the outline and a marginal note would appear on the right side (like in Nathan's layout) -- I never liked popup windows, they're distracting, they disrupt the reading flow.



Title: Re: Making an HTML outline (expandable/contractible)
Post by Johnnie Wilcox - mistersquid on Apr 20th, 2009, 10:01pm

There is no reason you couldn't have a practically unlimited number of "stretchtext" links that load into iframes. What this would mean is that the initial load of the HTML page could be as small as you want for initial presentation. The disclosure of certain passages would then load on-demand and in-place. This is precisely what I do for the links marked "load" in my zombie bibliography. (For example, the link for "Anonymous. A "Capitalistic Sublime?." and the second and third links for Balibar.)

I would like to offer more information than simply to say "it's possible," but it will take time to put together a proper tutorial/walkthrough. The Tinderbox document, the HTML templates, and the JavaScript code are considerably complex and will take time to abstract for general purposes.

As Mark B. suggests, put together the requisite HTML and JavaScript first. Then abstract that structure into Tinderbox. If you do it right, you will be able to add new items by merely assigning a prototype and adding text. (That is, all the gory HTML and JavaScript details can [and should] be templatized and [consequently] automatically and uniquely generated.)

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 20th, 2009, 10:32pm

@Johnnie: Just finished checking your Zombie page. Nice use of timeline, great colors! The layout is just the way I like it, clean. Good job, man!

As for my personal project, there's no rush. I'll be gathering info here and there and will eventually figure it out. But I think a tutorial on this topic would cover a lot of ground and could be useful to the community, so I'll make one in the end...

I'm beginning to see a split in my project: one, a simple way to create an html page mimicking a basic outliner (expand/contract each list item). Two, a more complex project which would combine this outliner with stretchtext's resources.

But first things first.  

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 20th, 2009, 11:00pm

@Johnnie: offtopic, I know, but I just wanted to let you know I greatly admire your work in http://wilcox.cx/courses/20084/theory/syllabus/daily. Beautiful. Paradigmatic, really. I have mentioned and shown your page to my colleagues down here as a model for a great syllabus. Thank you.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 21st, 2009, 5:25am

To help get you started with the outline export, I've just made a small demo TBX. I've included stub CSS and JavaScript library files - they expert but are empty save a comment.  This should help you to experiment without worry too much about where such code lives - see the 'how to use' note in the demo.

For those new to HTML export a 'gotcha' to watch for is that while TB will export a new page if the source note content has changed there are some instances where it may not export a new page when you expect one:
  • The changed note data is in a note included via the export template.
  • The changes made only exist in the template.
When experimenting with TB and HTML export, it is thus often useful to dump all, or affected pages of, the previous HTML export before doing a new export to ensure your most recent changes are correctly exported; this applies regardless of whether the templates are notes or external files.

[Notes:
- It was written in v4.6.2, using v4.6+ syntax. With a review of the export template code, it should be possible to make it work with older TB versions.
-In the demo, the secondary template ('sitemap-titles') uses a ^setRoot()^ call as a workaround for a current glitch. If this is fixed, it may be necessary to remove that code - the give-away will be if the link generated points to the wrong export location.]


Actually, I believe that Tinderbox does always export changes, even under the circumstances discussed here.  --MB

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 21st, 2009, 9:48am

@Mark A.:

Thank you, Mark! Although the export result, as it is, doesn't give use us the option for each child to be hidden or shown -- you state:
Quote:
The templates supplied may easily be adapted either to show more content, e.g. note text as well as title, and/or to add interactivity such as showing/hiding elements within the outline.
--, so it is certainly a step forward!  So I'll be playing with the templates to find out how one can add the show/hide interaction.

Once again, thank you for your effort!

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 21st, 2009, 9:52am

@Mark A.:
Quote:
For those new to HTML export a 'gotcha' to watch for is that while TB will export a new page if the source note content has changed there are some instances where it may not export a new page when you expect one:
The changed note data is in a note included via the export template.
The changes made only exist in the template.
When experimenting with TB and HTML export, it is thus often useful to dump all, or affected pages of, the previous HTML export before doing a new export to ensure your most recent changes are correctly exported; this applies regardless of whether the templates are notes or external files.
.


This SHOULD be corrected, right? Or what's the use of the updated export behavior if we can't always rely on it?

I never had that problem with my updated exports, but it's great that you pointed out, since I'd never suspect that if anything went wrong.

I believe that you can rely on updated export behavior. --MB

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 21st, 2009, 11:25am

I see Mark B's already commented in the foot of your last post - I'd take his comments over mine!

My 'demo' from earlier today isn't a formally maintained document, just something I made up from a test file from another export challenge I had - use the file as you want! Ask here if you get stuck. I can't know what app version you are/will be using and was just trying to be helpful by indicating that if the export worked differently in versions after v4.6.2 it might be because the ^linkTo^ issue is fixed and my ^setRoot^ kludge has an unwanted result.

~~~~~~
I've deliberately held off from doing anything based directly on Nathan's stretch text file as I still see the file as his. Hopefully I'll see him shortly at the London TB weekend so I should be able to discuss possible versions.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Johnnie Wilcox - mistersquid on Apr 21st, 2009, 1:38pm

Marcelo,

I am humbled that you find my syllabus a model worth sharing.

This thread gives me strong motivation to prioritize the tutorials and sample files I've been planning to make. I'll post back when I have something usable.

--Johnnie

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 21st, 2009, 2:09pm

@Johnnie:
Quote:
This thread gives me strong motivation to prioritize the tutorials and sample files I've been planning to make. I'll post back when I have something usable.


I'm glad this newbie was able to lure a master out of his cave!

We'll be expecting with great interest.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 21st, 2009, 4:22pm

OK, here is an updated TBX expanding this mornings version. It incorporates the collapsing outline method shown here: http://www.boutell.com/newfaq/creating/outline.html.

Sample output from the TBX is at http://www.acrobatfaq.com/tbdemos/sitemap/SiteMap.html

The next step might be to add part of the stretch text mechanism to show/hide the note text by clicking on the title. Note, that will mean editing the JS for the collapse method as the expand/collapse click event would need to be limited to the +/- images. Another enhancement would be to extend the outline JS to add 'expand all' and 'collapse all' functions.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 21st, 2009, 7:35pm

@Mark A: I think you nailed it, Mark!

But, concerning your tbx doc, the "sitemap" template:

line 8:
Code:
url(styles)

and
line 10:
Code:
url(outline-scripts)


are these right? 'cause:

line 7:
Code:
url(/CSS/outline)

and
line 9:
Code:
url(/SCRIPTS/outline)

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 21st, 2009, 11:35pm

Mark A., everything went beautifully. I exported a long outline (over 600 items!) and the result was perfect!

So, let's see what's left:

1. The Expand/Contract All is certainly desirable, especially for long lists.

2. Keyboard navigation (arrow keys):
- left arrow = hide children (conserve all states, so if expanded it'll recall the structure)
- right arrow = expand (recalling all children's states)
- up arrow = select (highlight) one item above
- down arrow = select one item below

2.1 (future) additional navigation features:
- shift (or ctrl, or ... it must be a cross-platform key) + right arrow = expand all children below selected note.
- shift + left arrow = contract all children below selected note.

3. highlight the currently selected item (for visual reference without the mouse cursor)

4. Stretchtext implementation -- which, as you mentioned, will require some js modifications so every character in the text can potentially trigger a specific action, and not just treating the whole item as a single block. (btw, currently, not only the arrow is clickable, but the entire item is treated as a single object).

Uffff..... enough already?



Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 22nd, 2009, 4:14am

Re the CSS & Script calls....

As the expanding outline code is not mine (and I don't yet understand the total code flow) I included Mr (first name?) Boutell's code verbatim but in different files to the ones I'd already supplied.

Why do some ^url()^ calls have paths and some names? Well, the Boutell example chooses to name all its support files 'outline.ext'**. TB can have multiple notes of the same name (the extension is set via HTMLExportExtension) but when referring to them a path is needed otherwise the first (in outline order) will always be the one referenced automatically. There are other ways to set the export filename but I like this one as it's easier to see what goes where upon export. If the export filenames and source notes differ, that's hard.

** and place them in the same folder as the HTML.  If you want to change that, you'll need to edit the JavaScript in 'outline.js'

Re or other reply....

#2. You in a browser, IMO unmodified arrow keystrokes should remain in their existing role as ways of scrolling the page up/down/left/right. Ideally, you should use modifiers for the purposes stated.

#2.1 You want to research event trapping and unobtrusive JavaScript.  The new collapsing code is implemented in unobtrusive fashion but one that will require modification when you add your code for trapping (modified) arrow keystrokes.  This topic is probably best pursued in a specialist JavaScript forum.

#3. Again an unobtrusive JavaScript method should suffice. You likely want to add this into the expand/collapse function(s).

#4. For simply showing the text, expanding the functionality of the expand collapse will be cleaner easier to implement. I'd limit stretchtext to within the context of a note's text (^text^). I'd consider carefully the effect on margin notes when you collapse an item to ensure it too dis-/re-appears.

Simple cut'n'paste of the Boutell code gets you the last file I posted. Adding your desired features will involve careful integration of advanced level JavaScript.

Let us know how you get on, it will be good to see your finished result.


Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Apr 22nd, 2009, 3:14pm

@Mark A.:

1.
Quote:
Why do some ^url()^ calls have paths and some names? Well, the Boutell example chooses to name all its support files 'outline.ext'**. TB can have multiple notes of the same name (the extension is set via HTMLExportExtension) but when referring to them a path is needed otherwise the first (in outline order) will always be the one referenced automatically. There are other ways to set the export filename but I like this one as it's easier to see what goes where upon export. If the export filenames and source notes differ, that's hard.


- Understood. Nice to know. I was interpreting paths in Tinderbox differently, so now it's all clear. First thanks.

2.
Quote:
You in a browser, IMO unmodified arrow keystrokes should remain in their existing role as ways of scrolling the page up/down/left/right. Ideally, you should use modifiers for the purposes stated.


- Agreed. I realize I was getting a little carried away....hehehe...


Quote:
... an unobtrusive JavaScript method should suffice. You likely want to add this into the expand/collapse function(s).


- Dusting off my JS books now... second thanks.


Quote:
I'd limit stretchtext to within the context of a note's text (^text^).


- I was just thinking about a good use for $Text... but it's too early to post about it and I'm not sure it belongs to this topic. I just want to know if $Text could, theoretically, function as the marginal note itself... and... ah... forget it!


Quote:
Simple cut'n'paste of the Boutell code gets you the last file I posted. Adding your desired features will involve careful integration of advanced level JavaScript.


- Yes, I realize that. But Boutell's code is already a great start. I'll just try to understand what he's done. That's enough learning material for now. We know at least it works as it is, so it wasn't time wasted. The first of the two projects I mentioned in a previous post is officially resolved: we have a nice and easy method to make Tinderbox create flawless HTML expandable/contractible outlines.


Quote:
Let us know how you get on, it will be good to see your finished result.


- I sure will, Mark. My intention is to share with the community whatever I can accomplish with Tinderbox. You see, since I'm a beginner in every sense of the word (I only learned about HTML what... a few months ago?), so things you guys already take for granted are an absolute marvel to me. I'm sure there are people in this position out there, so that's my crowd.

If my posts seem naive for some, the more experienced, that's because they really ARE naive. And in spite of that, you guys, Mark A., Mark B., Johnnie, have taken the time to help me in this project. So thank you all for your patience.

I hope this thread served to encourage newbies with their own "naive" projects.



Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Apr 22nd, 2009, 4:02pm

I'm no JS expert either and I didn't want to get your hopes up that a full solution is around the corner. I think the biggest challenge, from a non-expert's perspective is blending together the several different bits of JS written by different authors.

You might find this useful, it is a JS library for handling keystroke events.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jul 12th, 2009, 4:28am

@Mark A.:

Mark, just a small detail I just can't figure out how to change (concerning the sample file you made available): to every note that has children is added the clickable image icon on the left. The problem is that for those that do not have any children, they won't be vertically lined up with the siblings.

Can we have all the siblings lined up? Maybe a conditional like: if note has children, don't indent, if not, then indent npx to the right... but how can that be done? in the css?


Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jul 12th, 2009, 8:10am

OK, the originals code's fine. Lining up is a visual layout issue, solved with CSS. I've updated the outline collapse demo. I've used the same filename so it should over-write the original:
http://www.acrobatfaq.com/tbdemos/HTML_outline_collapse.zip

For the curious, I've made 2 changes to the original. I've added one CSS style (to the /CSS/styles) and made one of the lines conditional in template /TEMPLATES/sitemap-titles. How it works it that if an item has no children, then the title gets a 26 pixel left padding to allow for the space otherwise occupied by the +/- icon.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jul 13th, 2009, 10:52am

@Mark A.: Great. Everything went fine. I just made it 30px in order to line up correctly in my MB. I suppose setting the padding in pixels will present this minor problem. Wouldn't it be better done in em's?

Thanks a lot, Mark! I've just used your invaluable help to set up a template, which I'm submitting to Mark B. for a place in the Public Exchange File.

You have no idea how useful this technique was to my workflow!

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jul 13th, 2009, 11:05am

Re the spacing. Following the practices of much more savvy web designers I get the impression that em or px (pixels) are good for vertical padding and px are generally better for horizontal padding. For instance you might want inter-paragraph space to scale with increased font-size but you might not want you gutters to grow so much if at all. The only agreement is that generally pt (points) are bad, maily due to the way Microsoft Browsers don't scale them; bug or alternate design standard, who's to say but the IE/pt handling is not generally liked, thus use of em & px.

Ideally set your base 'normal' text to a particular size and scale everything else - you can use pos/neg percentages instead of having to hard code actual font sizes.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Nov 8th, 2009, 8:57pm

Hi, guys.

I've been successfully using a TB model quite often now. I think I have worked out all the details so it can be used as a general model. The exported HTML should mime "Explorer View" (on the left, the outliner, on the right, the note's text).

Any questions, let me know.

@Mark B. :
It could be featured in the Public Exchange Files, should you wish it. The zip (Outliner+TextFrame.tbx.zip) is in your "screencasts" folder in Dropbox.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Bernstein on Nov 8th, 2009, 9:45pm

Great.  Please email too (info@eastgate.com); we're busily packing for Tinderbox Weekend San Francisco, and so need all the reminders we can get!

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Bernstein on Nov 12th, 2009, 7:00pm

It's now available on the Public File Exchange.

It might be good to start a fresh thread!

Title: Re: Making an HTML outline (expandable/contractible)
Post by Paul Walters on Nov 13th, 2009, 5:09am

This is excellent.  Very timely; I'm just now starting something that needs exactly this approach.

Marcelo - obrigado!  And all who supported the work, too.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Patrick Lynch on Dec 5th, 2009, 4:58pm

I, too, have found the Outliner&TextFrame amazingly useful. However, when I start replacing the "Outliner" with another phrase (e.g. Action Plan Agenda 12.3.09), the dropdown menus stop working. It looks to my novice eyes that the DEF files are not copying over.
Patrick

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Dec 6th, 2009, 5:14pm

Assuming you've started with the file on the File Exchange, your problem is this - see contents of index.html;

Code:
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
     <title>index.html</title>
</head>
<frameset cols="50%,*">
       <frame src="outliner.html"/>
     <frame src="Def/1.html" name="view_frame"/>
</frameset>

</html>

Notice how frame #1 looks for "outliner.html"?  That file name is derived - as you may guess from the name of a note named "Outliner". Change the note name and the exported file is different. all in not lost...

Luckily there is a fix for this without you re-coding all the export stuff. Select the note that was originally called "Outline". Open HTML view - Cmd+Opt+H.  If the "File name" box doesn't say "outliner" (case-sensitive) or says nothing, change the box contents to "outliner" (without the quotes). Now HTML export should work as expected. Plus, you've just found out how to export one file to the name of another.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Dec 7th, 2009, 6:15pm

Yes, I thought I had fixed that. I have an updated version which already has the File name set to "outliner.html" in the HTML view. So the container's title would only be used as <h1> heading for the title. But I think Mark B. hasn't updated it in the File Public Exchange.

@Patrick and Paul: Thank you guys, I'm glad you found it useful.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Dec 7th, 2009, 7:06pm

Actually, the version I have - via the exchange - does have Marcelo's correction of the outline page export name in it so I guess Patrick must have got the earlier version.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 12:24pm

I noticed a text link is automatically converted to a weblink (at least in v5):

1. Create a new document.
2. Add two notes, named "1" and "2"
3. Add text to note "1" and link this text to note "2"
4. Open HTML view on note "1".

result: a <a href> tag is created automatically.  

Very handy.

But why isn't this conversion occurring in my Outline&TextFrame template?

e.g.:

1. Open the template document.
2. Add a text in note "1" and link it to note "2"
3. Open HTML view for note "1"

result: <a href> is not created.

p.s.: As soon as I learn the solution, I'll ask Mark B. to update the template at the Public File Exchange http://www.eastgate.com/Tinderbox/Exchange.html to version 3 (Outliner&TextFrame_v3.tbx)

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 2nd, 2010, 1:12pm

I think it's because your 'missing' link end at a note that is exported as an include to another note. As the referenced aTbRef explains such links - though functional within Tinderbox - don't export. A note isn't always exported in one place only - an include might occur in several different exports, all based on the same TB note. How does TB know to which note it should link; it can't. If you want cross-links you need to scale back on includes. It is for this reason that aTbRef, which has a lot of cross-referencing, doesn't use includes when exporting.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 4:22pm

I see...

Might there be a workaround? If not, then each link will have to be a legitimate weblink, right? I wonder if any clever agent trick could automatize this procedure...

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 4:26pm

But come to think of it:

Quote:
Note that basic and text links to other notes are suppressed on export if the target note is not exported as a stand-alone page - e.g. the target is only exported as part of the inline body text of another note.
(TbRef)

Well... the target note in question IS a stand-alone page, isn't it?

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 5:41pm

My experiments show that the linkage works when target note is a child (not a descendant, but just a child) of the note that contains the text link:


However, I noticed that the target note is in /Def , and not (curiously) /outliner (which was supposed to be the target). This might indicate a problem with ambiguity... or not... I'm confused...

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 2nd, 2010, 5:45pm

OK, so '1' links to '2'. But it is exported twice.  Once as '2.html' and once as part of Outliner.html, which use the include ^children(list-item)^.  So to which version of '2/ does '1' link?

I think that in template 'OUTLINER_TEMPLATE' , instead of
  ^Children(list_item)
…you meant to use:
  ^childLinks^

See: ^children^, ^childLinks^

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 6:01pm

Sorry, Mark... I'm not sure I understood your observation.

1. Note '1' is exported twice? Yes, it IS part of outliner.html (only ^title^ is exported, though), but its ^text^ (which contains the link) is only exported as /Def/1.html

2. Notice that the /Oultiner container is NOT to be exported AS A FOLDER (The children will be exported individually in /Def, but /Outliner itself will only be exported as outliner.html)

3. Why would I use ^childLinks instead of ^Children? The /outliner container's only purpose is to export itself, as "outliner.html", which is to become the left frame. At least I'm getting exactly the result I expected using ^Children

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 6:27pm

Besides, I've just noticed, the outliner_template is NOT USED by any note. It can be deleted altogether. (actually, "/outliner" uses "sitemap" as template)

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 2nd, 2010, 6:56pm

No, OUTLINER is exported as 'outliner.html' - take another look at the code. Earlier, I cited the wrong template name but the problem is the same as the 'sitemap' template has this line:
  ^Children(/Templates/sitemap-titles)
…which is effective telling Tinderbox to include [sic] every children of the current note using the template 'sitemap-title.

Even though the 'sitemap-titles' template only uses each note's title, it is still an include within the file exported a 'outliner.hmtl'. So, the notes '1', '2', etc., are all exported at least twice - once as standalone and once as an include within 'outliner.html.

A number of export codes, as listed here, result in an include on export.

In order to achieve the left-pane hierarchy you want, you probably need to try ^linkTo^ rather than ^childLinks^ as the latter gives a plain HTML list.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 8:54pm

Ok. It was about time I revised the whole document.

I realized there were a bunch of unnecessary notes. Things work as usual, but document structure now is much clearer.

Here's a temporary link to version 3: http://dl.dropbox.com/u/76377/TinderboxForum/Outliner%26TextFrame_v3.tbx.zip Until Mark B. can update it in the PFE.

@Mark A.
Still... I cannot figure out a way to implement text links' automatic conversion to weblinks. If you can think of a solution, Mark... I still don't see how ^linkTo^ can replace ^children^ in the sitemap template... pardon my sloooow neurons...

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 9:26pm


Quote:
Even though the 'sitemap-titles' template only uses each note's title, it is still an include within the file exported a 'outliner.hmtl'. So, the notes '1', '2', etc., are all exported at least twice - once as standalone and once as an include within 'outliner.html.


If that's true, why is it that SOME links DO get assigned with an <a href> (only children)? Since every note is exported twice, NO links should be converted, right?

But take a look at version 3. Export the result and check note "1" in your browser. See the links for the first two (because they're children of "1")? See the links for descendant notes not working? ONLY immediate children convert links.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 9:39pm

Concerning Outliner&TextFrame_v3.tbx, there's a strange export behavior: in order to have ALL the files exported correctly, you must export it TWICE (notice that the first time will only export 1 file into /css, for instance)... go figure...

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 9:52pm

EUREKA!!!

Don't ask me why, but here's the solution: when you want a text link to become a weblink, you must link the selected text to the desired note's ALIAS, INSIDE /Def, and not to the original note!!!

GO FIGURE! I have no idea why this works, but it just does! I've updated v3. Check note "1" and see that all the links work properly!!!

WHY, o, WHY?

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 2nd, 2010, 10:15pm

Ok, I'm about to start a new topic, as this one got too long and full of dead ends. It's still nice to see all the work in progress.

But before that, I'd like to find out:

1. Why must this particular document be exported TWICE in order to have ALL the files exported?

2. Why do text links get converted to weblinks when (and only when) the selected text is linked to an alias inside /Def, but don't get converted when it's linked to the original note (inside /Outliner)? (I guess only Mark B. might be able to crack this one).

As soon as the two questions are answered, I'll start a new topic only to explain the workings of the template and its strange idiosyncrasies.

Here's the expected result, so far: http://dl.dropbox.com/u/76377/TinderboxForum/Export/index.html

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 3rd, 2010, 11:03am

#1. Some pages are only exported twice because you, as the TBX's author coded it that way. Tinderbox exports what you tell it to export.

#2. You're confusing aliases with includes. An alias exports to HTML as a separate note with it's own inbound and outbound basic links - not those of its original - plus the original's text links (as both share the same text). Re includes: a note is exported normally only once, to its place in the export hierarchy plus it gets exported again if you (a) use one of the group of include export codes I mentioned earlier and (b) the note falls within the scope of such an include.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 3rd, 2010, 12:18pm

It occurred to me that aTbRef's sitemap ought to suffer the same problem, but doesn't. You can download the TBX. The note that creates the sitemap is called "aTbRef Site Map", third from last in the root level outline. That file is exported the once, using template 'sitemap' (in the TBX). The relevant part is this code:


Code:
<ul>^include(A Tinderbox Reference File,/TEMPLATES/sitemap-titles)^</ul>

The 'A Tinderbox Reference File' note is the parent note to all exportable content. so what does (internal) template 'sitemap-titles' do.


Code:
<li>^linkTo(this)^
^if($ChildCount & $HTMLExportChildren)^<ul>^children(/TEMPLATES/sitemap-titles)^</ul>^endIf^</li>

Although ^children^ is used, the child notes aren't actually included - all we do is use a reference to them  - the ^linkTo^. I suspect that where I to use anything like ^text^ or ^title^ in the latter template, I'd have the same problem at Marcelo's outline.

Anyway, I'd suggest taking a look at my TBX and the sitemap code and applying the same to yours. I've not time to fix everything but see my modified version of your outliner, here. Nottice how we move the notes from 'Outliner' to a new container 'Def'. This allows us to achieve the same trick as aTbRef. BUT, there is a new problem, links clicking in the left pane load their result in the left pane.

The problem is that ^linkTo()^ syntax doesn't allow us to add the code to target the right =-hand frame.  The fix to that - which I'll leave for you - is to use unobtrusive JavaScript to make all links inside the Outliner page use a target pointing links to the right frame. A benison of being forced to do this is it is the modern style of doing such things - inline 'target' attributes don't validate under some DTDs.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 3rd, 2010, 1:09pm

But Mark, the fact is that the template is working just fine without any modification to sitemap!

I have already exported a few documents and had no problem with the outcome.

I think we're dealing with different problems here. I'm assuming you think the template is not working properly. But it is, even v1 and v2, with all the unecessary elements, still worked. v3 is fine too. The ONLY issue was that text links didn't export as <a> tags, so copying notes from one document to the template would not preserve, nor even allow weblinks. In my last posts, I just wanted to implement the possibility of automatically assigning text links to weblinks, that's all. It turned out, it worked the way I described in the previous post.


Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 3rd, 2010, 3:48pm

OK, you have me totally confused.  Your previous post asked for help on two problems which you now say don't exist.  I guess we're all fixed then.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 3rd, 2010, 6:30pm

LOL

Well, the two problems I mentioned STILL exist, but they're not what you were trying to solve:

1. The export question: what happens to the document that I need to export TWICE (i.e., I must run shift + cmd + H twice) in order to have all the notes correctly exported (try it: check the export result, check, for example, the /css folder, notice that only ONE file was created, not THREE as it should. Now, try exporting once again, and you'll see all the notes in place). AH, now I see what the confusion was about: you thought I was talking about the notes being exported twice, one as part of outliner.html, the other as a standalone note at /Def, which is fine.

2. The strange fact that if I link a selected text to the original note, it won't become an anchor tag. But if I link the same selection to the ALIAS in /Def, it will work properly.

I'll take some screenshots to illustrate what I mean.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 3rd, 2010, 8:00pm

Ok, step by step, 1st issue:

1. Open Outliner&TextFrame_v3.tbx

2. Add the following text to note "1":


3. Link selected text to the corresponding note in /outliner:


4. Notice it's a text link, not a weblink:


5. Do the same with 1.2.1:


6. Now, link the other two, NOT to the notes in /outliner, but in /def:

and


7. Now, watch what happens (opt + cmd + H):



See how the last two links became anchor tags, and the first two did not?

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 3rd, 2010, 8:46pm

The second issue:

1. Open Outliner&TextFrame_v3.tbx

2. Export the whole thing to an empty folder (I just left the png's because this is TB 5.0.1):


3. Look at the number of files actually exported:


4. Now, export once more over that, and all of a sudden:


See that 1 file was added to each folder? That's what I meant by "having to export TWICE".

=============
But this problem is solved now. I made a new copy over, zipped it, and the one that is now available is exporting everything the first time around, so, behold:

http://dl.dropbox.com/u/76377/TinderboxForum/Outliner%26TextFrame_v3.tbx.zip

(the zip file contains the tbx doc and the export folder result. It will be available until Mark B. can update to v3 in the Public File Exchange)

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 4th, 2010, 5:53am

Re point #2 of your post three back, that is as I'd expect. Aliases have their own inbound basic links, as distinct from their original notes's inbound links.

Re the export-twice issue. I now understand to what you're referring, but can't replicate it.  I guess there was a glitch in your older TBX export set-up that's now resolved.

Export of HTML links. (Note - the demo you posted doesn't have the links described). I added the links as per your previous post and can replicate the result.  The result is simple.  Note '1.1' and '1.2.1' are never exported to their equivalent TBX location but rather are included within 'Outliner.html'. As TB doesn't link to includes (for the reasons already discussed), the TB links to notes inside 'Outliner' doesn't become an HTML link.

It seems you didn't get forwarded the HTML/coding corrections I tried to pass on back in November 09 having seen your earlier version of the demo. Anyhow, I've applied corrections to your v3 TBX (the last link you posted above). I'll add a link to my version with the corrections below, but first a summary of changes:
  • Template names.  The existing names are a little confusing for other users. The HTML frame exports via 'page' and the pages export via 'frame'. I've reversed the titles so the 'frame' template is used to export the frameset (index.html) and individual note pages are exported using template 'page'.
  • Note 'index.html' uses 'frame' template.
  • Agent 'Def' sets children to use 'page' template
  • Your 'page' template, is now called 'frame'. Now has correct DTD - it needs a framset DTD. Closed all open tags in accordance with  XHTML requirements. Added an encoding tag to the <head> in order to meet W3C validation criteria.
  • Your 'frame' template is now called 'page'. Added a <body> element, added tag closures, etc. to achieve valid HTML code.
  • 'sitemap' template.  Cleaned up HTML, removed DTD-invalid 'onload' handler (which is now moved to a JS script (see below).
  • 'sitemap-titles' template. Cleaned up layout to give cleaner HTML code structure on export.
  • As TB v5.x has currently suspended embedded image support, I've removed the oopen/oclose notes. I suggest adding comment to the 'About this Document' note explaining use of the images (which you zip with the TBX. If not using exported embedded images it might make more sense to code so the PNGs use an /images/ folder in the export (and update the TBX code accordingly) as that's a cleaner layout for actual active use of this model.
  • Script 'outline-scripts'. Added code to make unobtrusive attachment of an onload command to the outliner page. This method allows the HTML to validate against the given DTD.
  • Use of Bank Gothic oultine font. I've not changed this but I'd suggest doing so. The style of the font makes it hard to tell upper/lowercase characters apart in a project where we need to cite some names in code, making it easier for the user to use the wrong case. Still this is a stylistic choice, like the outline which has too much contrast for my eyes (I had to soften it by changing from black to grey background #222222). Anyway, I'll leave those items to you or the eventual users to change as they see fit.
OK, here's a link to a TBX with the above fixes added:  Outliner-v3-ed.tbx.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 4th, 2010, 8:08am

Wow, man, thanks for your effort!


Quote:
Aliases have their own inbound basic links, as distinct from their original notes's inbound links.

That clarifies things. Since aliases are NOT the same as the originals, it makes sense that the links to the originals wouldn't show, since the originals are not exported. However, there's really no way to tell whether a link is bound to an alias or to an original, is there? In the browse links, one cannot tell. Here's a suggestion to Mark B., a feature request.


Quote:
Re the export-twice issue. I now understand to what you're referring, but can't replicate it.  I guess there was a glitch in your older TBX export set-up that's now resolved.

Yes, the glitch is gone, so... that's resolved.


Quote:
Export of HTML links. (Note - the demo you posted doesn't have the links described). I added the links as per your previous post and can replicate the result.  The result is simple.  Note '1.1' and '1.2.1' are never exported to their equivalent TBX location but rather are included within 'Outliner.html'. As TB doesn't link to includes (for the reasons already discussed), the TB links to notes inside 'Outliner' doesn't become an HTML link.

Fully understood.


Quote:
Template names.  The existing names are a little confusing for other users. The HTML frame exports via 'page' and the pages export via 'frame'. I've reversed the titles so the 'frame' template is used to export the frameset (index.html) and individual note pages are exported using template 'page'.

Ok... I reasoned frames are inside a page, not the other way around. But it's fine.


Quote:
Note 'index.html' uses 'frame' template.

Ok... since the names got switched, that makes sense.


Quote:
Agent 'Def' sets children to use 'page' template

Again, makes sense as the names were switched.


Quote:
Your 'page' template, is now called 'frame'. Now has correct DTD - it needs a framset DTD. Closed all open tags in accordance with  XHTML requirements. Added an encoding tag to the <head> in order to meet W3C validation criteria.

Thanks! That was something I could never suspect.


Quote:
Your 'frame' template is now called 'page'. Added a <body> element, added tag closures, etc. to achieve valid HTML code.

Ok... wow... didn't realize I left so many open tags!


Quote:
sitemap' template.  Cleaned up HTML, removed DTD-invalid 'onload' handler (which is now moved to a JS script (see below).
'sitemap-titles' template. Cleaned up layout to give cleaner HTML code structure on export.

Nice. Thanks once again.


Quote:
I suggest adding comment to the 'About this Document' note explaining use of the images (which you zip with the TBX. If not using exported embedded images it might make more sense to code so the PNGs use an /images/ folder in the export (and update the TBX code accordingly) as that's a cleaner layout for actual active use of this model.

Agreed.


Quote:
Use of Bank Gothic oultine font. I've not changed this but I'd suggest doing so. The style of the font makes it hard to tell upper/lowercase characters apart in a project where we need to cite some names in code, making it easier for the user to use the wrong case. Still this is a stylistic choice, like the outline which has too much contrast for my eyes (I had to soften it by changing from black to grey background #222222). Anyway, I'll leave those items to you or the eventual users to change as they see fit.

Fair enough. I didn't spend much time considering cosmetics. I kind got used to differentiating between upper and lower case in Bank Gothic, but it sure is confusing. As for the colors, in my case it's always guesswork, I'm horrible at that.

====
The link for the document is broken. Can you check?

====

Mark, I can't thank you enough for your help, as usual. This project has been a great learning experience. Considering I barely knew anything about HTML before that, I can safely state that the little I learned I owe this adventure (not to mention how much I learned of Tinderbox itself)

====

Well, as soon as I have access to your edited document, I'll make a few changes and submit it to PFE.

I hope the readers of this thread have also gained with our discussion.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 4th, 2010, 10:58am

I've fixed the link in the previous post - the path was right but I guess the filename upset the browser.

Glad the points make sense. I learned the hard way that the cleaner (more valid) the HTML I write the fewer hard-to-fix glitches I get!

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 4th, 2010, 3:42pm

Ok, here we go,

version 4 is ready: http://dl.dropbox.com/u/76377/TinderboxForum/Outliner%26TextFrame_v4.zip
[edit]Current version now is 5.1[/edit]

(temporarily, until Public File Exchange can be updated)

@Mark A.:
1. I left the background color alone.
2. Bank Gothic is gone.
3. /Images folder is created. A placeholder, for now.
3.1 A warning was added about the image drawback in v5.0.1


Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 4th, 2010, 5:51pm

Thanks, but what I get is pretty broken. I've spent a good while poking at it but I can't find all this things you've broken since the last version. I strongly suggest you add in the TB text links in note '1' cited in the thread as the lack of them is confusing.  

It looks as though you swapped the code for the frame/page templates but didn't update the pages that use them.  The images in the left pane are missing - probably because you didn't update the JS script that uses them.

The last demo I posted worked. Why don't you use that file rather than your v3 as your start and add back anything you want - at least that way we know the export works before you start editing.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 4th, 2010, 10:09pm

My kingdom for a working version!!!

Mark, check your version. Export isn't working for me. Everything is a mess now, 'cause I just can't find a working copy anymore.


Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 5th, 2010, 7:04am

Marcelo, I've found and fixed a number of issues. Just doing some polishing - will post file when I'm done. Here's a taster:



I've:
  • Generally rationalised naming so those grabbing a copy via the exchange will find the structure more intuitive. I've used a DisplayExpression with a few key notes to indicate their export name or what they do (e.g. the right frame).
  • 'Def' is now the 'Right Frame' - i.e. what it actually does.
  • The 'Frame' (and its template) are now 'Frameset', making it unambiguous as to what it does.
  • Added specimen exporting/non-exporting links
  • Some deeper outline nesting to test outliner code
  • Added a new template for plain text export (for readme files)
  • Found/fixed errors in the scripts exports and scripts themselves.
  • Fixed CSS syntax errors
  • Added an exporting /images/ folder. A readme.txt is placed there to trigger the folder creation.  Currently the user has to place the outline's PNGs in there by hand.  When the outliner's done, making the think into a TB wizard could automate the placement of the images. If going the Wizard route, this is best done once the TBX is finished.
  • Adjusted colours for readability (less contrast)
  • Used a more legible font with better upper/lower case disparity (feel free to adjust this!)
  • ..and more.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 5th, 2010, 8:34am

Marcelo, try this: O-TF.zip

This exports without problems on my 10.5.8 system using TB v5.0.1. The only task is to place the 2 PNGs in the /images/ sub-folder of the HTML export (the JS script is adjusted to expect the images be there).

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 5th, 2010, 11:06am

hehehe.... this is embarrassing... but it ain't working...

1. Ok. First, the agent "Right Frame". We needed a slight modification to the query> descendedFrom(Outliner) > you did not capitalize it, so the agent wasn't finding anything.

2. The /Prototypes folder was inside /Outliner. I moved it up to "control".

3. A strange "1.html" is created in root directory. It was actually the webname given to /Prototypes, which was being exported. I switched to HTMLDontExport, but oddly, it's still being exported regardless...

4. That bug about having to export twice in order to have all the files created is still around. I'm beginning to suspect of a bug in Tinderbox 5.x or OS X 10.4.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 5th, 2010, 11:34am

Oh bother - don't know how those errors crept in. Items 1-3 fixed, plus some links from note 1 had gone awry and are fixed. Issue#4, I can't replicate.  Which specific files aren't being created on first export?

I've uploaded a new zip to the above URL - the zip name is the same but the TBX inside is is now 'O-TF_v5-1.tbx'.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 5th, 2010, 11:36am

Re the 2-export issue, I don't think just looking at the file count is enough. Look at the exact filenames and note those failing on the first export. I don't see it here but it doesn't meant it isn't happening elsewhere. I'm on v5.0.1 on OS 10.5.8.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 5th, 2010, 11:44am

Ok... if you don't mind, I have played Frankenstein (I know it's usually a bad idea, but this time I really paid attention to every detail and have successfully exported everything).

http://dl.dropbox.com/u/76377/TinderboxForum/Outliner%26TextFrame_v5.1_MM.zip

I have added the MM suffix (Marcelo Mirage) to avoid confusion.

I have added a decimal to version 5 (now 5.1), otherwise we'll end up with a huge number of versions out of minor changes.

I have cloned your O-TF.tbx version's javascripts and templates, so all your modifications were taken into account.

I have fixed the minor glitches I mentioned in my last post.

The "export twice" phenomenon is gone now with this current version. So everything is in place.


So, if you'd care to check this current version (take your time... you must be sick of it  ;))


p.s.: as for your modifications>

Quote:
Generally rationalised naming so those grabbing a copy via the exchange will find the structure more intuitive. I've used a DisplayExpression with a few key notes to indicate their export name or what they do (e.g. the right frame).

Ok, the change was taken.



Quote:
'Def' is now the 'Right Frame' - i.e. what it actually does.
The 'Frame' (and its template) are now 'Frameset', making it unambiguous as to what it does.
Added specimen exporting/non-exporting links
Some deeper outline nesting to test outliner code
Added a new template for plain text export (for readme files)
Found/fixed errors in the scripts exports and scripts themselves.
Fixed CSS syntax errors


Ok, all these were taken.


Quote:
Added an exporting /images/ folder. A readme.txt is placed there to trigger the folder creation.  Currently the user has to place the outline's PNGs in there by hand.  When the outliner's done, making the think into a TB wizard could automate the placement of the images. If going the Wizard route, this is best done once the TBX is finished.


Prior to TB 5.x I didn't have to resort to a Wizard in order to export the images (in the correct png format). I'm sure it'll work just fine when TBX is finished.



Quote:
Adjusted colours for readability (less contrast)
Used a more legible font with better upper/lower case disparity (feel free to adjust this!)


Not that I don't agree with your choice, but I'd prefer to leave my settings for font and colors, that way I can spot my versions faster (ah, it's just too much trouble to change everything back. So let the users decide).




Quote:
..and more.


I also made some slight modifications... too tiny to mention. Well... at least we have a working version...

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 5th, 2010, 12:33pm

OK, lots of snaglets for you (mostly cleaning up action code, e.g. ^code in actions is deprecated since v4). I'll let you do these:
  • 'Prototypes OnAdd should be: $IsPrototype=true; $HTMLDontExport=true;
  • '*entry' OnAdd should be: $Prototype="*entry";
  • '*entry' Rule should be: $webName=$HTMLExportFileName+$HTMLExportExtension;$HTMLDontExport=false;
  • Incidentally, good TB form is CamelCase for attributes, so $WebName would be better than $webName. As the two attribute names are different attributes, if you do correct this one, make the new attroibute, use an agent (all notes with $webName not empty) to copy $webName to $WebName, then you can delete $webName. update all code referring to the attribute, key attribute lists etc - this is why doing the naming right pays off, it's a pain to fix later; that said the existing name works - to me it looks like a typo when I see it in actions, etc.
  • 'Right Frame' Agent.  No action needed - the agent only finds things descended from -'outliner' and that seeds the correct prototype which in turn sets a rule for the notes/aliases.  We don't have to do all that work again.
  • 'outliner'. OnAdd: $Prototype="*entry";
  • 'outliner & '*entry'. $Color: bright blue warmer. Basic 'bright blue' is way too harsh to look at for any length of time in this set-up.
  • Set outline MapBackgroundColor to '#292929'.
  • Repair defined colour 'dark warm gray' back to '#554a40'.
  • Open any Info view, Appearance group, select Color in the left column, then edit button at bottom. In the edit dialog change the default to 'light warm gray dark'. The grey notes will now look OK on the #292929 background.
  • I'd have stuck with my way for making the image folder; but I'll agree to differ!  When images return, I doubt we'll be using the placeholder trick - not least as TB-exported images are JPEGs - your script will then fail as it expects a PNG file.  The way to get the images into this folder is to make a TB Wizard (instructions in aTbRef) when done.
  • I checked and scripts are working OK.
  • 'styles' CSS & frames css - insert a blank line line before a:visited. This is for code tidiness - no actual change.
  • Links in content notes - all missing!
  • Template 'sitemap-titles' - to get syntax to current style change entries of ^get(webName)^ to ^value($webName)^ (or to ^value($WebName)^ <g>).
  • I think that's it...!


For test, I'd try some slightly deeper levels of nesting, and try some notes with non-number names - even something Unicode (accented) perhaps just in case it make some glitch we'd not foreseen.




Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 5th, 2010, 3:07pm


Quote:
'Prototypes OnAdd should be: $IsPrototype=true; $HTMLDontExport=true;

Done!


Quote:
'*entry' OnAdd should be: $Prototype="*entry";

Done!


Quote:
'*entry' Rule should be: $webName=$HTMLExportFileName+$HTMLExportExtension;$HTMLDontExport=false;

Done!


Quote:
Incidentally, good TB form is CamelCase for attributes, so $WebName would be better than $webName. As the two attribute names are different attributes, if you do correct this one, make the new attroibute, use an agent (all notes with $webName not empty) to copy $webName to $WebName, then you can delete $webName. update all code referring to the attribute, key attribute lists etc - this is why doing the naming right pays off, it's a pain to fix later; that said the existing name works - to me it looks like a typo when I see it in actions, etc.

Agreed and done!


Quote:
'Right Frame' Agent.  No action needed - the agent only finds things descended from -'outliner' and that seeds the correct prototype which in turn sets a rule for the notes/aliases.  We don't have to do all that work again.

No, the agent does two things: it seeds the correct prototype AND, most importantly, it corrects the $HTMLExportFileName according to its sibling position ($HTMLExportFileName=^get(SiblingOrder)). I did this to ensure names are always synchronized and in order. I also use the agent to assign the template (although another method could be used, it doesn't matter). So let's leave those.


Quote:
'outliner'. OnAdd: $Prototype="*entry";

Done!


Quote:
'outliner & '*entry'. $Color: bright blue warmer. Basic 'bright blue' is way too harsh to look at for any length of time in this set-up.
Set outline MapBackgroundColor to '#292929'.
Repair defined colour 'dark warm gray' back to '#554a40'.
Open any Info view, Appearance group, select Color in the left column, then edit button at bottom. In the edit dialog change the default to 'light warm gray dark'. The grey notes will now look OK on the #292929 background.

Done, done, done!


Quote:
I'd have stuck with my way for making the image folder; but I'll agree to differ!  When images return, I doubt we'll be using the placeholder trick - not least as TB-exported images are JPEGs - your script will then fail as it expects a PNG file.  The way to get the images into this folder is to make a TB Wizard (instructions in aTbRef) when done.

Actually, in Document Preferences, we can (could) choose to export images as either jpg or png. In TB 4.7.1, I simply chose png and the two images were exported correctly, without any wizard. Maybe you forgot about that option. All I know is that it worked, while TB was handling images.


Quote:
'styles' CSS & frames css - insert a blank line line before a:visited. This is for code tidiness - no actual change.

Done!


Quote:
Links in content notes - all missing!

Not here... the last two links in note "1" are fine.


Quote:
Template 'sitemap-titles' - to get syntax to current style change entries of ^get(webName)^ to ^value($webName)^ (or to ^value($WebName)^ <g>).

Ok, done (I wonder why ^get was working).


OK. All things considered, behold:
http://dl.dropbox.com/u/76377/TinderboxForum/Outliner%26TextFrame_v5.2_MM.zip

And here, the export result:
http://dl.dropbox.com/u/76377/TinderboxForum/Export/index.html

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 5th, 2010, 4:15pm

JPG vs. PNG export - you're right. I was writing in a hurry and overlooked that.

Code in the agent. Make that: $HTMLExportTemplate="/Templates/page"; $HTMLExportFileName=$SiblingOrder

The ^codes are supported in action code - but for legacy reasons.  However, as this will be shared with other users, we might as well use current code. Plus it reduces the likelihood of having update the code at a later time.

The only thing that's missing is the links.  Note 1 has the 2 'wrong' links in place but not the 2 correct ones and note '2.1'. Aha! I suspect when the TBX moves to a new location, the agent is initially empty and thus the links - to its aliases - are lost before the agent re-populates. Hmm. That might be a valid reason to re-architect this bit. I wonder what Mark B thinks (he's probably in a snow-bound airport right now) - at least all(?) the other glitches in the TBX are - I think now ironed out.

Anyhow, just about done!

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 5th, 2010, 5:06pm


Quote:
The only thing that's missing is the links.  Note 1 has the 2 'wrong' links in place but not the 2 correct ones and note '2.1'. Aha! I suspect when the TBX moves to a new location, the agent is initially empty and thus the links - to its aliases - are lost before the agent re-populates. Hmm. That might be a valid reason to re-architect this bit


Hmm... it's worth verifying that with Mark B.. But I think you're right: the links to aliases disappear because so do aliases themselves (they're dynamically renewed). Makes sense.

Tell you the truth, I'm not satisfied with that method anyhow. It's just a temporary solution. Ideally, text links should be bound to the original notes. But that's not possible with the current system.

At least, if the user cares enough about linkage, he CAN do it (it only takes time to reassign all the links again).

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 5th, 2010, 5:19pm

I'm thinking... Would an agent be able to identify all the links (text>original) and 'transpose' them automatically to the corresponding alias (text>alias)? Frankly, I don't see that happening.

But there might be a solution out there...

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 5th, 2010, 5:36pm

Not time to try this here, but - if you let Outliner export all its children (which won't affect the left pane function) the links will all persist. In template 'outline-titles' change this part of the code:
<a href="right-frame/^value($WebName)^" target="view_frame">
to:
<a href="^url(this)^" target="view_frame">

The 'target' attribute loads the page in the right frame of the frameset.

If that works, you don't need 'Right Frame' at all, nor $WebName (nor the prototype code to set it).

Give it a try (in a copy of the TBX!). I'm doing this all in my head, but I think it should work.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 5th, 2010, 7:34pm

The $WebName attribute was created, Mark, in order to avoid unexpected HTML name conversion. It's much safer to deal with 1.html, 2.html, ... than their real names (some titles might be really big, or might contain foreign characters).

If we dispense with agent "Right Frame", we cannot assign the names by SiblingOrder, since nested notes are not siblings (I needed a place where all the notes are siblings). OutlineOrder wouldn't work either, since their numbering wouldn't begin with '1.html', and I'd like that for clarity and for keeping control (count) of all the notes exported.


But your strategy might work, the originals are exported and /Right Frame is simply in charge of converting the names... the only problem is that folders would be created with each nest. Not a problem per se, but, I find much cleaner if all the notes are placed within a single folder.

Another problem: wouldn't the notes then REALLY be exported twice? Didn't you say that wouldn't work? I run a test and find out. Stay tuned.

+++++=

YES!!!! It works!

Behold, v5.3, now with working text links:
http://dl.dropbox.com/u/76377/TinderboxForum/Outliner%26TextFrame_v5.3_MM.zip

And here's the export result:
http://dl.dropbox.com/u/76377/TinderboxForum/Export/index.html


++++++++++
(now I'll have to change the name Right Frame to something more meaningful... how about "Renamer")

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 5th, 2010, 8:03pm

For those who have been patiently following this thread, good news: version 5.3 is working and better than ever! You can safely download a copy from the link above. I don't think there will be radical structural changes (for now  ;). Subsequent changes will be mostly style and fine-tuning.

Future modifications would include:

- Keyboard navigation (contrary to Mark A.'s taste, but i'd like to be able to expand/contract notes using keyboard arrow keys instead of clicking each time).
- A simple navigation menu in the right frame.
- And a few other things I have in mind.

(open for suggestions also)

Have fun!

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 6th, 2010, 5:01am

That looks better!  No sign of the double export issue, but then I never did see it here.

The '*entry' prototype Rule can be deleted - it's now running in every inheriting note yet tries to populate an attribute we don't use (and which could also be deleted, by way of clearing up used features). Add this second expression to the 'outliner' and '*entry' notes' OnAdd:
   $HTMLExportTemplate="/Templates/page";
...and delete it from Renamer's AgentAction.

A neat general point to note is that:
   <a href="^url(this)^">^title^</a>
is the same as
   ^linkTo(this)^
So, where - as in your project - you need a linkTo but also want extra <a> tag attributes (target, title, etc.), then the ^url^ appraoch digs you out of the whole.

Keyboard navigation - look at a library like JQuery which might allow you to add in such functionality.  The code I put in the user-scripts will enable you to easily add this unobtrusively.

Right fame navigation.  The aTbRef source TBX's templates have good examples you can use.

With regards to export filenames, I assume you've had problems in the past with accented (Brazilian) Portuguese characters.  The Unicode support changes in v5+ ought to make those go away.

If people want default naming all they have to do is change the 'Renamer' agent (the old Def/Right Frame agent) 'Action' box code to
   $HTMLExportFileName=;
...as the latter code resets the default.  Run the agent once - check the Info view, HTML Group, of a note inside 'outliner' and check HTMLExportFileName is inheriting.  The user can then delete 'Renamer'.

Incidentally another way to give simple unique filenames, and without an agent, is to add a user attribute of date type Number with the 'sequential' option ticked. At the point of creating the attribute, TB gives a sequential number (starting from 1) to every note (probably attributes too?) in the YBX working in currnet oultine order. After that every new item is alloted the next sequence number. Although the numbers won't necessarily be a continuous sequence or matching the visual sequence of notes, the data is unique to each note and 'safe' HTML export filenames.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 6th, 2010, 11:59am


Quote:
The '*entry' prototype Rule can be deleted

If I delete the $WebName=$HTMLExportFileName+$HTMLExportExtension rule in *entry, how will $WebName be assembled? I did what you recommended, deleted the rule, but added the expression in the "Renamer" agent as an action.

but, on second thought:

Quote:
yet tries to populate an attribute we don't use

$WebName is not used? Oh, yeah, you're right... no need for that, since we have  $HTMLExportFileName=$SiblingOrder as a "Renamer" action to set the file name to sequential integers.

However, $WebName is indirectly used in the small outliner view for "Renamer", as a column item. Users can see the whole name of the notes to be exported (I find that reassuring, though not necessary). Of course, I could just open two columns, one for HTMLExportFileName and HTMLExportExtension, but these two attributes are not available in column view. So let's leave that, for reference.



Quote:
Incidentally another way to give simple unique filenames, and without an agent, is to add a user attribute of date type Number with the 'sequential' option ticked. At the point of creating the attribute, TB gives a sequential number (starting from 1) to every note (probably attributes too?) in the YBX working in currnet oultine order. After that every new item is alloted the next sequence number. Although the numbers won't necessarily be a continuous sequence or matching the visual sequence of notes, the data is unique to each note and 'safe' HTML export filenames.


Yes, but a continuous sequence gives us clues about the relative positions of each note that semi-random numbers would lose. It also provides a quick way of knowing the total number of notes exported.

====
Ok, I'll fix these and upload v 5.4.



Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 6th, 2010, 12:07pm

Here we go:
http://dl.dropbox.com/u/76377/TinderboxForum/Outliner%26TextFrame_v5.4_MM.zip

Plus, I fixed a minor glitch ("Renamer" query was looking for 'outliner' instead of "Outliner")... oops.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Mark Anderson on Jan 6th, 2010, 12:13pm

Inter-note links still missing from note '1' (2 of 4) and note '2.1' (all 3).

Moving the Renamer into the 'control' section is a nice touch.

Title: Re: Making an HTML outline (expandable/contractible)
Post by Marcelo Mirage on Jan 6th, 2010, 3:25pm

Ok. Links fixed.

Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com) » Powered by YaBB 2.2.1!
YaBB © 2000-2008. All Rights Reserved.