[TW5] Please explain pagetemplate and overall structure

[Mat]

On and off for a couple of months I've tried to get the hang of TW5... and failed every time. It took a long time for me to get into TWC but I finally did get there and one of the best ways to control/customize it was via a theme (based on Bairds MPTW) where the various templates etc were collected in one place. I'm hoping to get there witht TW5 too but, darn, I can't get an overview of this.

For starters, could someone please give (or point to) an top-down overview  of the general strategy for how the page elements are split up. In English not code, please.

This is what I think I've understood, please correct me;

First of all, where page elements are defined is very different from TWC.
The commands/markup for defining the parts are different - they are in html in TWC but in TW5 they are in a "Jeremy-defined" markup language (based on and very close to established markup language which name escapes me)
In TW5 the tiddler PageTemplate is named $:/core/ui/PageTemplate. The meat of this is this part:

<$list filter="[all[shadows+tiddlers]tag[$:/tags/PageTemplate]!has[draft.of]]" variable="listItem">
<$transclude tiddler=<<listItem>>/>
</$list>

...which filters out all tiddlers tagged "$:/tags/PageTemplate". Not sure what that variable listItem is/does.
It is clever to use a filter in the pagetemplate rather than hard coding which page elements to use because this lets us add new elements without actually messing this this pagetemplate tiddler but instead simply by adding the tag.

The result from the filter are these:

$:/core/ui/PageTemplate/alerts
$:/core/ui/PageTemplate/sidebar
$:/core/ui/PageTemplate/story
$:/core/ui/PageTemplate/topleftbar
$:/core/ui/PageTemplate/toprightbar

Now, these elements are placed in the right place on the screen either by magic or by brain gamma rays from Jeremy. My best guess is magic, because I cannot imagine how brain rays would penetrate my bunker and with magic it would all make perfect sense and this would also explain a lot of other questions I have.

Ok, I'll start with this. Please, I'd love to hear your comments.

Thank you!

<:-)

[TheDiveO]

Hi Mat,

the magic that escaped you consists of two things, if I remember correctly (because I was somehow involved at some later stage):

• the list field of the PageTemplate itself: this general-purpose field controls the initial sequence in which the template part tiddlers listed here are rendered. It is populated with the core template parts tiddlers. So this sets up the overall structure in form of a virtual list, on which the second part of magic builds...
• additional template part tiddlers which are correctly tagged:
• if such an additional tiddler either has its list-before or list-after field set, then this field references another template part tiddler and this tiddler is either inserted into the ordered sequence before or after the referenced tiddler (that is, into the virtual list mentioned before).
  
• if no placement is specified using one of the two fields mentioned above, then the template part tiddler is inserted at the end of the (virtual) list.
  

Please note that this virtual list is only built when rendering a template, so it does not become visible in its own.

Regards,
TheDiveO

[Jeremy Ruston]

The mechanism for ordering tagged tiddlers that TheDiveO explains is documented here:

http://tiddlywiki.com/#Tagging

Best wishes

Jeremy

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.
To post to this group, send email to tiddl...@googlegroups.com.
Visit this group at http://groups.google.com/group/tiddlywiki.
For more options, visit https://groups.google.com/d/optout.

--
Jeremy Ruston
mailto:jeremy...@gmail.com

[Evolena]

The commands/markup for defining the parts are different - they are in html in TWC but in TW5 they are in a "Jeremy-defined" markup language (based on and very close to established markup language which name escapes me)

In TW5, all is tiddlers. So the ui elements are also tiddlers, written in WikiText. See the shadow system tiddlers beginning with $:/core/ui/
 

In TW5 the tiddler PageTemplate is named $:/core/ui/PageTemplate. The meat of this is this part:

<$list filter="[all[shadows+tiddlers]tag[$:/tags/PageTemplate]!has[draft.of]]" variable="listItem">
<$transclude tiddler=<<listItem>>/>
</$list>

...which filters out all tiddlers tagged "$:/tags/PageTemplate". Not sure what that variable listItem is/does.

It's a way to access each item of the list inside the ListWidget. By default it is the currentTiddler variable, but you may want not to modify this currentTiddler variable to use both the currentTiddler (the tiddler where you are) and the listItem (the item of the list you are processing). Not sure my explanation is clear, though.
 

It is clever to use a filter in the pagetemplate rather than hard coding which page elements to use because this lets us add new elements without actually messing this this pagetemplate tiddler but instead simply by adding the tag.

The result from the filter are these:

$:/core/ui/PageTemplate/alerts
$:/core/ui/PageTemplate/sidebar
$:/core/ui/PageTemplate/story
$:/core/ui/PageTemplate/topleftbar
$:/core/ui/PageTemplate/toprightbar

Now, these elements are placed in the right place on the screen either by magic or by brain gamma rays from Jeremy. My best guess is magic, because I cannot imagine how brain rays would penetrate my bunker and with magic it would all make perfect sense and this would also explain a lot of other questions I have.

For the PageTemplate especially, it's CSS magic, in the vanilla theme (http://tiddlywiki.com/#%24%3A%2Fthemes%2Ftiddlywiki%2Fvanilla%2Fbase).

/*
** Page layout
*/

.tc-topbar {
    position: fixed;
    z-index: 1200;
}

.tc-topbar-left {
    left: 29px;
    top: 5px;
}

.tc-topbar-right {
    top: 5px;
    right: 29px;
}

.tc-sidebar-header .tc-sidebar-lists p {
    margin-top: 3px;
    margin-bottom: 3px;
}

.tc-page-controls {
    margin-top: 14px;
    font-size: 1.5em;
}

.tc-story-river {
    position: relative;
}

@media (max-width: {{$:/themes/tiddlywiki/vanilla/metrics/sidebarbreakpoint}}) {

    .tc-sidebar-header {
        padding: 14px;
        min-height: 32px;
    }

    .tc-story-river {
        position: relative;
        padding: 0;
    }
}

@media (min-width: {{$:/themes/tiddlywiki/vanilla/metrics/sidebarbreakpoint}}) {

    .tc-message-box {
        margin: 21px -21px 21px -21px;
    }

    .tc-sidebar-scrollable {
        position: fixed;
        top: {{$:/themes/tiddlywiki/vanilla/metrics/storytop}};
        left: {{$:/themes/tiddlywiki/vanilla/metrics/storyright}};
        bottom: 0;
        right: 0;
        overflow-y: auto;
        overflow-x: auto;
        -webkit-overflow-scrolling: touch;
        margin: 0 0 0 -42px;
        padding: 71px 0 28px 42px;
    }

    .tc-story-river {
        position: relative;
        left: {{$:/themes/tiddlywiki/vanilla/metrics/storyleft}};
        top: {{$:/themes/tiddlywiki/vanilla/metrics/storytop}};
        width: {{$:/themes/tiddlywiki/vanilla/metrics/storywidth}};
        padding: 42px 42px 42px 42px;
    }

<<if-no-sidebar "

    .tc-story-river {
        width: auto;
    }

">>

}

@media print {

    body.tc-body {
        background-color: transparent;
    }

    .tc-sidebar-header, .tc-topbar {
        display: none;
    }

    .tc-story-river {
        margin: 0;
        padding: 0;
    }

    .tc-story-river .tc-tiddler-frame {
        margin: 0;
        border: none;
        padding: 28px;
    }
}

You can see that some values are transcluded from a $:/themes/tiddlywiki/vanilla/metrics/xxx tiddler, because you can change them in the ControlPanel (Appearance/Theme Tweaks tab).
 

[Mat]

Your kind answers here have been helpful and led to a few aha moments! Thank you all!

It also made me realize something...

@Jeremy

I propose that the "How to"- guides in the sidebar Contents tab are of limited use without prior knowledge on how to change the more "infrastructurial" aspects such as the pagelayout, particularly for experienced TWC users. Let me explain:

It is reasonalbe to assume many experienced TWC users have a few "main TWC's" that they've consciously designed and honed to perfection over many years. So, in order to upgrade to TW5 (to take advantage of TW5's additional power, that's why) the first thing they must do is to re-design the overall TW5 layout. This is before "content design" with filters etc, as detailed in the current "How to" guieds on tw.com, become relevant at all. The current (and wonderful!!!) guides assume you're past this need.

Obviously, the skilled coders here don't have this problem and those completely fresh TW don't have any honed TWC's... but I think this is a problem for experienced TW users who are not good coders. Not to mention those who love TW but just wish to use it rather than fiddle a lot. As noted, after years of tiddlyfiddling they know how they want a TW to be laid out for their purposes.

A few guides have come up on these "major layout aspects", often meshed into other help topics, by very generous individuals like Ton Gerner, Dave Gifford, Stephan Hradek and Mario Pietsch (am I missing somebody?) but still it's not exactly simple. And there's the uncertainty that their guides are not up to date/valid.

So here are some ideas that I think would benefit quite a few:

1) Some official instructions dealing with things like pagetemplates and overall layout.
2) ...or how to create custom templates as plugins
3) A few optional core pagetemplates, analog to the themes, set via Control Panel.
4) A kind of dynamic pagetemplate set via Control Panel

The idea with "official" is that there's incentive to keep it updated and many people can help refine it.
Regarding #4 I have included a picture to illustrate the concept.
BTW, in TWC there is this nice (albeit static) overview.

Thank you for listening. I always feel embarassed to say "Somebody else ought to do something" but hopefully my suggestions contribute something even if they're not in the form of code.


<:-)

[Jeremy Ruston]

I'd certainly like to have better documentation about the basics of customisation, and am very happy to accept submissions. For this kind of thing anybody can help - just put up a TW on TiddlySpot containing new documentation tiddlers, and post a link here in the group.

Best wishes

Jeremy

On Thu, Oct 23, 2014 at 2:36 PM, Mat <matia...@gmail.com> wrote:

For some reason there seems to be a problem with the attached picture above so here's a direct link to it.
In case it can't be seen: it is basically a tiddler showing something similarish to this but with checkboxes directly in the elements of the image so that you can check which parts of the overall layout that you wish to be seen. That is only the basic concept. One could imagine an alternative checkbox with option for showing a slider button rather than completely hiding it. An interactive and graphic settings page for the overall layout of things.

<:-)

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.
To post to this group, send email to tiddl...@googlegroups.com.
Visit this group at http://groups.google.com/group/tiddlywiki.
For more options, visit https://groups.google.com/d/optout.