Textpattern CMS support forum

You are not logged in. Register | Login | Help

#31 2019-11-26 10:49:53

Destry
Moderator
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,295
Website

Re: Documentation: overview/orientation

jakob wrote #320239:

As part of the textpattern.tips relaunch

Re-noticing that again.

So, that, on top of a writing a ‘series’ of articles with screenshots and all, that could take you some time. But you could say better than me.

In any case, I’ll proceed with my initial plan to write the single, low-frills walk-through doc I mentioned. I have some other items to wrap up first, but that will be added to my ticketed priorities. Maybe it appears before any glossier material and is one-step closer to themes heaven.


Wordworkin’ for you.

Online

#32 2019-11-26 14:11:08

Destry
Moderator
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,295
Website

Re: Documentation: overview/orientation

WebmistressM wrote #320257:

Text Pattern

Text Pattern 👀
🤔
Text Pattern ≠ Textpattern 🧐
Text + (p + Pattern/P) = Textpattern 🤓
Text + (p + attern) = Textpattern 😑
Text + pattern = Textpattern 😏
Textpattern = Textpattern 🤙
<txp:if_status status=“🤙”> 👍 <txp:else/> ≠👍 </txp:if_status> 😬


Wordworkin’ for you.

Online

#33 2019-11-26 17:40:56

Destry
Moderator
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,295
Website

Re: Documentation: overview/orientation

Destry wrote #320249:

  1. docs: Themes panel (links to 2 and 4)
  2. docs tute: Create a theme (links to 1, 3, and 4)
  3. Tips: End-to-end portfolio tutorial (links to 1 and 4, at least)

My mind was warbling today…

It could be useful to think about 1, 2, 3, etc in terms of a single narrative, even though separate document parts. Imagine we have the following content list (a ToC) reflecting a progressive-learning series of instructions, where each piece is informative by itself for different user needs/interests. And the contents list itself (not much more) is a principle web page in the Themes site. And the site provides a main navigation link to this important page, whether it’s the homepage link, or another called ‘Instructions’, or whatever.

  1. Introduction
  2. Theme packages and functionality
  3. Creating a standard theme package
  4. Creating custom site genre package
  5. Creating theme packages as flat-files
  6. Porting a theme to Textpattern structure

Introduction

This could actually represent the introductory paragraph on the respective Themes website page, followed by the contents list itself. Nothing complicated or over-thought.

Here’s how to rock your own themes:

{Content list}

Theme packages and functionality

This link would be to the Themes panel page currently on my to-do list (due to some related revisions there). The page is envisioned to have two main topics:

  • Theme package structure
  • Theme creation and management

The first topic would be a conceptual overview of Textpattern themes, perhaps framing them in a couple of logical ways, using some possible terminology as it might relate with mental models people already have; a notion Bloke and I were kicking around earlier in this thread:

  • Standard ‘skin’ packages, being simple skinning of the default blog structure’s presentation (i.e. styles changes only, no markup changes to pages and forms)
  • Custom site ‘genre’ packages, involving changes to the underlying pages and forms too. I used the term site ‘genre’, suggesting a different kind of site than the default blog (e.g. portfolio, photo album, business site, whatever), but it could just as well be ‘site structure’. Whatever.

We’re talking a pretty short section here for that conceptual bit.

The second main topic/section is the detailing of the theme panel’s primary functionality for creating and importing themes, and understanding the related functionality in other back-end panels (e.g. the contextual theme menus) to make themes actually work. Again, very straight forward and concise material here.

Creating a standard theme package

This would be the other user doc on my to-do, the walkthrough. It would be a simple demonstration of the standard ‘skin’ theme package introduced in the previous doc. Skinning the default front-end; styles only, no changes to pages or forms, except possibly to add a couple more sections for expansion of the presentation possibilities.

The alternative is, perhaps, to fold this simple walkthrough into the themes panel doc as a third main section/topic, rather than have two separate documents in user docs. But I’d like to keep that thought on reserve until I see what the altogether volume of instruction turns out to be after some drafting.

Either way, the sections of the themes panel doc can serve as the links in the contents list at the Themes site level.

Creating a custom site genre (structure) package

This would be where Jakob’s advanced article(s) come(s) in at the Textpattern Tips site. As he mentioned, he’d focus on a ‘portfolio’ site, which is a site genre, and would require editing the pages and forms. A step-wise increase in tutorial complexity, as it were.

If he indeed wanted to write the piece in multiple parts, then that item in the main contents could have subitems for each series piece.

Creating theme packages as flat-files

Up to now, the different documents have been describing theme package creation using out-of-the-box functionality. But this could introduce another tutorial opportunity for someone; another walkthrough of a site genre demonstration via a flat-file installation of the Textpattern. And since Jakob is proposing to do a portfolio site, this one should be something different, perhaps a business site, or whatever.

Obviously this tutorial would want to link to yet another tutorial on setting up a flat-file installation, so there’s still another opportunity to write a needed piece.

Porting a theme to Textpattern structure

This one just crossed my mind, as I see it asked about in other threads. So, seems like yet another tutorial opportunity.

—-

By my humble reckoning, such an approach to themes docs offers this result:

  1. Leverages writing duty (if we can get a couple more pen-lickers)
  2. Addresses some documentation needs
  3. Makes headway to themes site content (putting a little light in that direction); and perhaps is the only _text_-type content needed there at first, other than the prerequisite blurbs.

Food for thought only. Kick it to the dirt if it belong there.

Last edited by Destry (2019-11-26 18:32:21)


Wordworkin’ for you.

Online

#34 2019-11-26 18:39:29

Destry
Moderator
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,295
Website

Re: Documentation: overview/orientation

This poor thread got seriously hijacked. Sorry Bloke. :{

Should we move it to ‘Themes discussion’, and maybe change the title to fit. I feel like that might be safer than breaking it out as two threads.

Or just let it sit. Might miss the visibility on topic, though.

I’ve no forum power for it, in any case. (And no thanks.)


Wordworkin’ for you.

Online

#35 2019-11-26 22:47:58

jakob
Admin
From: Germany
Registered: 2005-01-20
Posts: 3,592
Website

Re: Documentation: overview/orientation

That looks like a pretty bold undertaking you outline there. I can’t help thinking you might be able to reduce the volume of work significantly by avoiding revisiting too much general templating ground already covered elsewhere.

As I see it, Textpattern’s themes facility

  • creates a formalised packaging mechanism for an organisational structure that that was already inherent to Textpattern: pages, forms and styles.
  • allows you to import/export packaged themes for safekeeping, transferring, sharing, etc.
  • allows you to install several themes alongside each other and mix and match between them for different sections (site structure parity permitting).
  • allows you to develop a new theme while leaving the public view unchanged.
  • allows you to show someone else (another logged in user) a preview of changes before they go live.
  • because you can link to your theme’s path, you can also include your own theme-related assets within a theme (js, webfonts, etc.). [Note: need to check they don’t get erased on exporting to disk and clearing unused forms]
  • (planned for later: will allow you to include plugins and theme-specific variables)
  • with extra plugins: allows you to work on templates, forms and css styles as flat-files with a text-editor etc. of your preference.

A couple of notes that sprung to mind from what you wrote:

Skins / themes – I suppose you could draw a distinction between skinning and theming but in my view style changing isn’t specific to theming functionality. It was always possible to make several CSS styles/files and switch them via the sections panel. I don’t know if you’d make a whole new theme just to switch a single css file, and if I’ve read the docs correctly a theme must include some basic default files so a style-only theme may not really be possible.

Flat files – There’s the aspect of exporting a theme to files and importing a theme from files, which you can do out of the box as-is. And then there’s developing themes with flat files which at present requires another plugin, e.g. etc_flat or rah_flat. People can do the former already so that mechanism is definitely worth documenting. The latter is also useful (I think) but as it requires non-core plugins, is it suitable for the “official” docs, or should it be a tip or tutorial?

Porting a theme to Textpattern structure – this almost always entails rebuilding a theme using Textpattern’s conceptual model and tags. I don’t think there’s any kind of specific correspondence between Textpattern’s theme model and that of other CMSes that one could “operationalise” into a process – apart from analysing the original theme and rebuilding in Textpattern. Perhaps that’s something one could work through in a tutorial as an example of how to set about it, but it would likely differ sometimes considerably depending on the theme or the source/CMS of the original theme. I would de-prioritise that.

Mix and match – this is something I’ve not really explored so I could be wrong here but … while I understand the principle of being able to assign page templates from different themes to your sections, it might be wise to caution against false expectations as I don’t think you can bolt together different themes and expect to end up with a uniform site experience.

As far as I understand this, for this to work well, e.g. seamlessly, the themes you switch between must share some common structural patterns and styling. If you meld together sites of completely different natures or looks, at best your sections will function fine but look totally different and at worst it may be broken (depending on how defensively the theme was built, e.g with if_plugin, if_custom_field, if_excerpt, if_article_image …).

On the other hand, where theme authors conceive their themes according to similar patterns/conventions (as is the case with some WP “theme foundries”), then this could work quite well where the site structures are not totally different.

Proposed tutorial series – having said the above, my proposed article series – what you called a genre site – would cover the general ground of structuring a template, with pages, forms and tags. It is, however, intended as a beginner’s development tutorial, picking up what Oleg said about making the patterns clear. It would assume HTML and CSS knowledge and I would not go into the hows and whys of styling (except very generally or where pertinent) but simply supply the CSS code to drop in. The idea would be that it covers two aspects: how to go about making a site with Textpattern, and how to make a theme.

I mentioned a portfolio site as it allows you to address some common Textpattern conceptual structures without getting too specialised and serves well for any kind of “collection” site, whether a designer’s portfolio, a builder’s or kitchen fitters list of references, a local what-to-see-and-do guide, a cooking recipe site, an arts and crafts site, product showcase site, book or film review site, and so on and so forth … anything with categorised collections.

I have a fairly clear idea of the intended structure already. And, as you noted, I have some other work to complete on the tips site first ;-) … and then general day-to-day work so it will not be ready in a week’s time.


TXP Builders – finely-crafted code, design and txp

Offline

#36 2019-11-26 23:41:25

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 8,842
Website

Re: Documentation: overview/orientation

jakob wrote #320271:

[Themes] creates a formalised packaging mechanism for an organisational structure that that was already inherent to Textpattern: pages, forms and styles.

Exactly. We’ve always had themes, in some capacity. You’ve always been able to assign a different Page/Style to a Section.

Our notion of a Theme simply bundles up this concept into a disk-based package that is more easily shareable, and adds a few niceties like being able to test in-development layouts using live content without (too much) fear of breakage, as long as the organizational components don’t differ too wildly.

include your own theme-related assets within a theme (js, webfonts, etc.). [Note: need to check they don’t get erased on exporting to disk and clearing unused forms]

They don’t. They are kept if synchronising. Might even be kept if deleting, I can’t remember if we decided to blat everything or just the assets we understand as a Theme (Pages, Forms, Styles).

a theme must include some basic default files so a style-only theme may not really be possible.

Correct. A theme always contains at least one Page, one error Page (I think), one Stylesheet and six ‘essential’ (unquote) Forms.

while I understand the principle of being able to assign page templates from different themes to your sections, it might be wise to caution against false expectations as I don’t think you can bolt together different themes and expect to end up with a uniform site experience.

Yes, but if that’s your goal, then we’re not going to stop anyone. I’ve seen sites where the /blog is radically different to the main site – new masthead, different layout, everything. Presumably, it was either done for a reason or was amateur hour, I’m not entirely sure which.

As far as I understand this, for this to work well, e.g. seamlessly, the themes you switch between must share some common structural patterns and styling.

Not necessarily. If you’re previewing a development theme on existing content then you’ll get weird/broken results if you have a live Page template named ‘bart’ and an in-dev template named ‘homer’. At least in 4.7.x. As far as I recall, this has been relaxed in 4.8 since we now have a dedicated column for the in-dev template name per section, so in theory they can co-exist. Haven’t tested it rigorously yet.

But if you’re simply using a new theme on two different Sections, you can go nuts. Make them all have different names, different block structures, Forms, whatever. Since you (as site administrator/designer) assign a theme/page/style combo to Sections by hand – exactly as we have always done, just with the additional layer of choosing a Theme first – you are free to choose whichever ones you want.

This is of primary interest if, for example, you’re fed up of your custom-designed photoblog and like the look of Pat64’s photoblog theme on the (upcoming) themes site. You can download the zip, unpack it in your ‘/themes’ directory and import it. You can then assign it straight away to just your ‘/photoblog’ Section if you want to live dangerously. Or test it as an in-dev theme with your live photos on one or more Sections. Maybe you leave it that way and intend one day to roll it out to the rest of your site after some tweaks, but want to get the ball rolling and get feedback on it. Up to you.

On a related note, maybe a plugin could offer split-testing functionality and switch between two themes, recording which was offered for each page visit so that analytics software can analyse conversion rates (note to self/Oleg: investigate this one day and offer core helpers if required, as it should now be possible fairly easily with a plugin).


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Offline

#37 2019-11-27 08:37:45

Destry
Moderator
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,295
Website

Re: Documentation: overview/orientation

jakob wrote #320271:

. . . avoiding revisiting too much general templating ground already covered elsewhere.

Where is all this general templating ground already covered? Besides here and here, which is all I’m focused on in terms of editing; the latter deserving a title change, most likely. As I see it, if we really want to make this simple and straightforward, those are the only two docs needed, just revise them to be more clear. Add photos, whatever it takes. We should probably revisit the idea of using images in docs anyway.

I was not proposing dispersed documentation by that outline, I was offering an idea to deal with it since dispersed docs seems unavoidable. (And regardless if no body wants to write tutorials about flat-file theming and porting themes, they would no doubt be used if written.) By having the ‘contents’ list in the Themes site, it puts all the resource links in one place, in context of where people will likely expect to find it, eventually.

As for the concept of theming, I think templating is clear as crystal to core devs and a couple (literally two) veteran experts, perhaps including yourself. But from what I see reading around the boards, and including myself, apparently, there’s a lot of confusion. That may not be because core templating is hard, but because it’s a type of theming process unique to Textpattern and needs a certain way to talk about it. That way is necessary from a functional standpoint. I get that. No doubt. But I think we will see that it also needs introduced in a way that bridges any mental models that new arrivals bring about theming a site, which is usually not more than putting a new presentation on the default ready-to-use structure. I see lots of websites that are just default Txp installs with the grey presentation. I’m pretty sure those people, often bloggers, don’t need more structure than that, but may not have the CSS knack either and would appreciate a quick import option for something other than sidewalk cement.

And this issue — will one theme package for site A work on site B — is a touchy one. I suspect that will be where a lot of confusion comes in, for example. And core is also expecting to add preferences, plugins, and maybe even sections? Heh. Drink your Spirulina and sharpen your pencils. We’re going to need more docs than we think, or continual revisions of them.

Though I could be wrong. As I’ve said before, I’m not the person to be writing tutorials about themes. And now I’m certain of it. I’ve never used a theme in my life. In fact, I’m a little worried this terminology must be pushed on me now in Txp. But that’s progress, I guess, and why I’m taking an interest here, to better understand it, holistically, as it progresses.

I truly look forward to reading your tutorials, jakob. I have only one request, similar to Craig’s: just put it in one document, please. ;)


Wordworkin’ for you.

Online

#38 2019-11-27 10:04:40

etc
Developer
Registered: 2010-11-11
Posts: 3,427
Website

Re: Documentation: overview/orientation

Destry wrote #320275:

I see lots of websites that are just default Txp installs with the grey presentation. I’m pretty sure those people, often bloggers, don’t need more structure than that, but may not have the CSS knack either and would appreciate a quick import option for something other than sidewalk cement.

Ideally, for these people replacing CSS should suffice. But the reality is different: sole CSS is not yet flexible enough to transform any layout into another one. Often one also has to change the underlying HTML structure, hence themes must be able to include Pages and Forms too. The drawback is that currently these assets are mandatory, so you can not install just CSS/JS via themes, but this might change one day.

And this issue — will one theme package for site A work on site B — is a touchy one.

This will probably come to its full power with custom fields release. You will be able to combine sections of different nature (shop, news, blog, etc) using a specialized theme for each section.

Offline

#39 2019-11-27 12:50:00

Destry
Moderator
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,295
Website

Re: Documentation: overview/orientation

etc wrote #320278:

the reality is different: sole CSS is not yet flexible enough to transform any layout into another one. Often one also has to change the underlying HTML structure, hence themes must be able to include Pages and Forms too. The drawback is that currently these assets are mandatory, so you can not install just CSS/JS via themes, but this might change one day.

Okay, thanks. That makes it clear to me, then. There is no ‘skinning’ concept to this at all. Rest assured (and you too, Bloke) I will not pursue any such terminology in user docs. ;)

The drawback is that currently these assets are mandatory . . .

Probably more a safeguard than drawback, I surmise; especially as you say, there’s inevitably a little markup tweaking anyway, in which case you need to pass those templates in the package.

Destry wrote #320275:

We should probably revisit the idea of using images in docs anyway.

We have since revisited this notion, and a green light is given now for strategic use of images, albeit according to a few guidelines to be added here. Essentially following the docs mantra: ‘No more than necessary.’ ;)

Hey, that’s a good one, actually. We should put that as a tagline under the user docs head…

Textpattern user documentation
No more than necessary.

Phil!


Wordworkin’ for you.

Online

Board footer

Powered by FluxBB