Documentation: overview/orientation

Destry · 2019-11-20 11:52:41

The vision on this is more significant than I thought, then; suggesting a much different meaning of ‘theme’ than what most people are going to have, including me. Maybe we should have called it ‘Types’ or ‘Genres’ or ‘Site structures’, or whatever, because it’s a lot more than just a visual theme. That distinction will have to be spelled out and emphasized in docs (thinking aloud).

So what you’re saying, then, if in the future you tie in Sections, for example, is if I’m running a default install and the core blog setup, I could import a ‘genre’ package for ‘web magazine’ or ‘real estate agency’ and it can literally change the site structure and off I go in my new direction?

etc · 2019-11-20 11:55:16

Destry wrote #320134:

This notion of providing a scaled-down, simpler theme; doesn’t that also mean providing an alternate default template structure (i.e. besides the default blog templates)? Or are you merely suggesting a simpler ‘skin’ as an alternative to Hive for the existing default markup templates?

What I suggest is a theme where default Page, Style and Form templates are reduced to a bare minimum (e.g. <txp:article /> plus few other tags). It would by no means be a “real” theme (with SEO etc) like Hive, but just a playground for beginners that try to understand txp workflow. As additional benefit users would learn how to switch between two themes.

I assume, that if we wanted themes for a photo blog, say, or a small business website architecture, we can’t just make a theme for that to share with people, it requires them also having the same site architecture or the theme won’t fit/work. Right? I mean, you can’t just rely on sharing a theme package to change a site architecture… or can you? Maybe I’m looking at it wrong?

You are absolutely right, themes can be related to the site structure, for example by using some specific custom fields. But the one I suggest would use only common elements, like Hive does.

Destry · 2019-11-20 12:01:33

Thanks, guys. That was a sudden wake up. I grock it a little better now.

Again, I think the term ‘themes’ is really going to confuse people coming to this from other notions of website themes.

But, wow, so much more powerful.

etc · 2019-11-20 12:03:39

Destry wrote #320138:

Again, I think the term ‘themes’ is really going to confuse people coming to this from other notions of website themes.

But, wow, so much more powerful.

Wait, we have not yet included plugins and prefs in the package..

Bloke · 2019-11-20 12:31:35

We’ve deliberately left Sections out of theming. And, so far, content too. Although both are possible, it’s a minefield. Imagine importing a theme that has article content: where does it go? Overwrite your existing article IDs? If so, you lose content. If not, then the theme author who may have used <txp:article_custom id="1" /> in an imported Page/Form, no longer links to the article they bundled with the theme – it instead points at your article ID 1.

Same with Sections. If you have Sections default and blog linked to your existing content and you import a theme with a blog section defined and linked to the theme author’s Pages (or with different properties such as description), your live site is mashed the instant you import. And what if you have used <txp:section_list sections="about, blog, portfolio" /> and a theme adds/overwrites the blog section or uses its own sections? Your content changes to visitors.

It’s far better/safer for the theme author to bundle up section-agnostic structure and scaffolding – and that will include plugins and prefs once we figure out how to handle clashes – so the site administrator can then test (on their own live data) the theme to see if they like it, and manually apply it to the Section(s) of their choosing once they’re happy it works.

Somewhere in the dim and distant past, Bert Garcia came up with a nomenclature which we loosely adopted, although I’m not sure now if we want to stick to the distinction. Part of me likes it, another part thinks that it’s just confusing to have three ‘levels’ of theming with different capabilities. But essentially, a Package is what you were alluding to above that could make sweeping changes, whereas a simple Theme is just different presentational confetti – <div>s in different places, different colours, different way of laying out article lists, etc.

Last edited by Bloke (2019-11-20 12:39:16)

Destry · 2019-11-20 13:11:24

Bloke wrote #320141:

We’ve deliberately left Sections out of theming. And, so far, content too.

Ah, yes. The actual content. How do I forget that? Another mini wake-up moment.

Same with Sections.

Okay, so there is some limit, and probably wise to keep it that way, with how deep and wide the plug-and-play game goes.

It’s far better/safer for the theme author to bundle up section-agnostic structure and scaffolding – and that will include plugins and prefs once we figure out how to handle clashes – so the site administrator can then test (on their own live data) the theme to see if they like it, and manually apply it to the Section(s) of their choosing once they’re happy it works.

Like. I’ll use some of that.

Somewhere in the dim and distant past, Bert Garcia came up with a nomenclature which we loosely adopted, although I’m not sure now if we want to stick to the distinction. Part of me likes it, another part thinks that it’s just confusing to have three ‘levels’ of theming with different capabilities. But essentially, a Package is what you were alluding to above that could make sweeping changes, whereas a simple Theme is just different presentational confetti – <div>s in different places, different colours, different way of laying out article lists, etc.

Also like, without even reviewing that yet (but I will). I think we’ll see it necessary for people to talk about this functionality (and in terms of their needs) at two levels. We could try and restrict it there: package and skin (as I did in that other thread about seasons rotation), or whatever other terms might better suggest the whole can of sardines versus just the label on it. I suspect most people will just want to mess around at the label level, at least at first until this sinks in.

Destry · 2019-11-20 13:28:03

Bloke wrote #320141:

dim and distant past

Haha. Deja vu !

Yeah, not with the intention of forcing any semantic changes at this point, but I think I’ll be framing it in tutorials like this: ‘themes can be thought of as packages of template assets, and the simplest kind of change is at the presentation layer, or ‘skin’ layer only’. Something along those lines, with some clear demos either way.

Bloke · 2019-11-20 13:52:00

Destry wrote #320145:

‘themes can be thought of as packages of template assets, and the simplest kind of change is at the presentation layer, or ‘skin’ layer only’.

Yeah, sure. At its bare minimum, a skin can be analogous with a change of Stylesheet only; that’s what CSS was designed for after all, to keep the structure the same but change the look.

Our skins (which is what they’re actually called in the code, because we’d already used ‘theme’ for administration themes) can simply be a new Stylesheet, but they can come with additional furniture to dictate where blocks like header, navigation, sidebar, footer and so forth reside in relation to one another if the author supplies Page templates.

Other themes might go further and change the way articles are laid out (usually by changing Form content) or set up list templates in year-month-date format.

Separating out what is ‘the presentation layer’ might be tricky, since we lump Pages, Forms and Stylesheets into “Presentation” in Textpattern, and that’s our only (currently) supported definition of a “Theme”.

When 4.8 rolls in, not only are we considering per-theme prefs and plugins, we’ve gone a bit further as Sections can have their own permlink schemes. Slightly OT, but this has interesting ramifications for anyone building URLs by hand in their Themes. If, for example, you as admin choose breadcrumb_title permlinks for a given Section, apply a theme where the Page/Form hard-codes /section/title links, then your resulting URL structure becomes inconsistent.

Using the <txp:> tags’ built-in link generation will of course honour the in-force permlink scheme so that is the “preferred” method if possible.

Note to self: <txp:if_section permlink="section_title, breadcrumb_title"> ... </txp:if_section> ??

etc · 2019-11-20 22:49:20

Bloke wrote #320147:

When 4.8 rolls in, not only are we considering per-theme prefs and plugins, we’ve gone a bit further as Sections can have their own permlink schemes. Slightly OT, but this has interesting ramifications for anyone building URLs by hand in their Themes. If, for example, you as admin choose breadcrumb_title permlinks for a given Section, apply a theme where the Page/Form hard-codes /section/title links, then your resulting URL structure becomes inconsistent.

Actually, /section/title links should still work for all schemes, even messy.

Note to self: <txp:if_section permlink="section_title, breadcrumb_title"> ... </txp:if_section> ??

That could be handy! And why not <txp:permlink permlink="section_title" />..

Bloke · 2019-11-20 22:57:17

etc wrote #320154:

/section/title links should still work for all schemes, even messy.

Yeah, they’ll work, it just presents inconsistencies in URL structure if ones that are generated by the tags use the permlink mode set in the Section but hard-coded ones in the theme, for example, use a fixed scheme. We should strive to ensure that people can use the tags as often as possible so they don’t have to resort to manually building links too often.

And why not <txp:permlink permlink="section_title" />

Oooh yeah, that too. I like that. Or is there another attribute we already have that can do the same job? I feel like it should be <txp:permlink scheme="..." /> but we don’t use that anywhere either I don’t think. type?

etc · 2019-11-20 23:11:33

etc wrote #320154:

And why not <txp:permlink permlink="section_title" />..

A source of confusion, on a second thought :-) The only universal modes being messy and section_title, other “permlinks” could stop working all of a sudden if they don’t match their sections scheme.

jakob · 2019-11-24 09:44:20

I lost track of this thread while I was briefly out of town. Is someone already in the process of writing a tutorial, then?

As part of the textpattern.tips relaunch, I had envisaged doing an article series as a step-by-step tutorial that would walk through making a very simple but typical portfolio-type site (Phil has the blog site well covered already) with a few sections and templates and showcases basic concepts like section, categories, body/excerpt, custom fields, short tags, page template, forms, individual article and article list contexts and so on.

My idea was to show the path from idea to implementation, i.e. the process of taking a basic outline for a site, identifying content types and page blocks and taking that to code concentrating on the basic HTML structure without additional structured data or JSON-LD markup, which although excellent clouds the clarity of the code. There’d be a downloadable package to accompany it (e.g. on GitHub). I’m a visual person, so it would have pictures / diagrams. I was planning on a basic setup to start with, linking out to other tips where appropriate for more advanced situations. Maybe later tutorials could examine adding “additional features” to that.

I hadn’t imagined that being part of the official “docs”, or as an official theme, but rather as a walk-through for beginners on textpattern.tips as I’ve discovered that after pruning old tips that use dated/obsolete plugins, the number of articles on the site is severely reduced.

Is this duplicating efforts already begun? @Destry, maybe this is an opportunity for collaboration…

Textpattern CMS

Textpattern CMS support forum

#13 2019-11-20 11:52:41

Re: Documentation: overview/orientation

#14 2019-11-20 11:55:16

Re: Documentation: overview/orientation

Destry wrote #320134:

#15 2019-11-20 12:01:33

Re: Documentation: overview/orientation

#16 2019-11-20 12:03:39

Re: Documentation: overview/orientation

Destry wrote #320138:

#17 2019-11-20 12:31:35

Re: Documentation: overview/orientation

#18 2019-11-20 13:11:24

Re: Documentation: overview/orientation

Bloke wrote #320141:

#19 2019-11-20 13:28:03

Re: Documentation: overview/orientation

Bloke wrote #320141:

#20 2019-11-20 13:52:00

Re: Documentation: overview/orientation

Destry wrote #320145:

#21 2019-11-20 22:49:20

Re: Documentation: overview/orientation

Bloke wrote #320147:

#22 2019-11-20 22:57:17

Re: Documentation: overview/orientation

etc wrote #320154:

#23 2019-11-20 23:11:33

Re: Documentation: overview/orientation

etc wrote #320154:

#24 2019-11-24 09:44:20

Re: Documentation: overview/orientation

Board footer