Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Offline
Re: Documentation: overview/orientation
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)
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
Re: Documentation: overview/orientation
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.
Offline
Re: Documentation: overview/orientation
Bloke wrote #320141:
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.
Offline
Re: Documentation: overview/orientation
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> ??
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
Re: Documentation: overview/orientation
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_titlepermlinks for a given Section, apply a theme where the Page/Form hard-codes/section/titlelinks, 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" />..
Offline
Re: Documentation: overview/orientation
etc wrote #320154:
/section/titlelinks should still work for all schemes, evenmessy.
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?
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
Re: Documentation: overview/orientation
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.
Offline
Re: Documentation: overview/orientation
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…
TXP Builders – finely-crafted code, design and txp
Offline
Re: Documentation: overview/orientation
jakob wrote #320239:
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 . . . 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
That’s a fantastic idea. The Tips site seems ideal for a multi-part series like that. Anything in the user docs should be a single document per topic, IMO.
Is this duplicating efforts already begun?
Not that I know of.
@Destry, maybe this is an opportunity for collaboration…
If I didn’t already have list of docs priorities, I’d be happy to collaborate on it. Maybe something in the future? I’d gladly give pages an editor review, though, when you’re done.
I don’t really talk about my undertakings in here, any more than necessary, because it’s out of focus and interest for most people. But for starters, I need to finish the documentation collaboration procedures and have that reviewed. As well finish up the editorial style guide, tackle the general themes creation walkthough (get the themes show on the road, you know), and various checklists tasks . Plus I’m going to look at pophelp at some point to see what can be honed and aligned better with user docs. I suspect more issues will materialize along the way.
I use the docs repo issues to manage everything, so that’s a good place to watch. I also use the Docs Team discussion board for specific writer/editor collaboration topics. That’s not public access, but it might be a place of interest for you to join. Bloke will hook you up. ;)
Offline
Re: Documentation: overview/orientation
Ok, thanks for clarifying. It was that mention of the themes walkthrough that made me wonder whether we were duplicating efforts, but I couldn’t find it earlier.
TXP Builders – finely-crafted code, design and txp
Offline
Re: Documentation: overview/orientation
All I’m expecting to do on that is expand a bit where the Themes panel doc falls short. Administration panel docs are meant to explain the functionality on the panels, not much more, and even themes stuff is a bit hazy for folks, I think, when it comes to hooking it up with other semantic pieces.
So the tutorial will elaborate the functionality a bit while, as phi13 put it, tie it to a ‘narrative’; something a little less abstract. Or maybe this will end up being new Themes panel doc content. I don’t know. We’re thinking about changing those pages up if it makes them more useful that way.
I certainly don’t intend to talk about building a specific site structure beyond the notion that it’s possible and what to take into account. In fact, what I have in mind might be the perfect lead to your series. We’d have these four entry points all linked up in a logical way for a theme-hunter’s journey:
- docs: Themes panel (links to 2 and 4)
- docs tute: Create a theme (links to 1, 3, and 4)
- Tips: End-to-end portfolio tutorial (links to 1 and 4, at least)
- Themes website (all the above and it’s own material)
Maybe 2 moves to 4, eventually. Don’t know. I’m still unclear what the content plan for the themes site is. Off my radar, though.
I have plenty to work on already, so if you want to do your series first, and I wait and see what it is, maybe it’s enough and I don’t have to do something different at risk of being redundant.
I’ve started some paras already, and was hoping to have in a week or so, but let me know what you think.
Last edited by Destry (2019-11-24 20:56:36)
Offline
Re: Documentation: overview/orientation
In fact, I’m probably not the best person to be writing a theme tute since I’ve not really done it for the purposes of sharing one (only to hack a presentation to my needs). Several other people, however, like Phil, phiw13, Patrick, and even etc have (as witnessed by other forum threads). So if any one of you other ‘qualified’ souls, including Julian, can do that, by all means, free me of that task. ;)
Offline
#29 2019-11-25 20:58:07
- WebmistressM
- Member
- Registered: 2011-08-12
- Posts: 61
Re: Documentation: overview/orientation
I think that it takes more than just one person to write good tutorials. I have been interested to see Text Pattern websites start to show more from the 4.8 side (the upcoming txpthemes site, and the documentation getting its update).
subscribing to this thread to follow along
Destry wrote #320251:
In fact, I’m probably not the best person to be writing a theme tute since I’ve not really done it for the purposes of sharing one (only to hack a presentation to my needs). Several other people, however, like Phil, phiw13, Patrick, and even etc have (as witnessed by other forum threads). So if any one of you other ‘qualified’ souls, including Julian, can do that, by all means, free me of that task. ;)
Offline
Offline