page: Themes: Creating, using, and sharing

[wion]

New title: Themes: Creating, using, and sharing https://docs.textpattern.com/build/themes-creating-using-and-sharing

Formerly... https://docs.textpattern.com/themes/front-end-themes

Reason the page is needed

One example:

I’m so far finding the answers, but only after looking all over the place. It’d be nice if there was one big “This is basically what you need,” type of document/page. – craigbass76, the tech writer

What will be the scope and structure of document?

• What is the tutorial start point? (Probably recent completion of a fresh install. Take it from there.)

• What is the tutorial completion point? (Having exported a theme package for some demonstrated example or two.)

• What are the essential sections of the document body? (That likely remains to be written and revised through several iterations, as usual.)

• Can any of these sections be supplied as unique one-to-many content components, as per discussion, to use across other doc pages? (That likely needs to be a new issue labeled with 'architecture' and 'researching'.)

Resources to review, reference, and/or use

• Hive theme; the software's default
• Themes panel doc and it's hu-gi-mongous pophelp. ;)
• Sections panel features; drop down menu location/explanation
• Front-end themes structure
• Active/Preview links; still not firm yet?
• Theme assets; Oleg insights
• Hack porting a theme; Julian's great insights for where to begin, pull ideas as useful
• flat-file theming; plugin mode
• skin auto-rotation

What other forum threads or resources should we look at?

Notes

This thread suggests theme creation is easier if you're running in flat-file mode with etc_flat.

• Can it be done using only core functionality? If so, this qualifies the doc as a 'user doc'.

• Should there be two docs: one for core-approach and one with plugin approach? No, I now think not. The 'Themes panel' doc can be honed down to reflect the basic mechanics. The longer tutorial can have endnotes for such notions of convenience (e.g. plugin usage, whatever.)

Cleanup

Eliminate anything in the /themes directory that is no longer needing to sit there and mummify after this venture is over.

[wion]

I think the existing Front-end themes page can be used and refactored into a fully elaborated 'Creating a theme' tutorial.

Proposal: We don't refer to front-side themes as 'front-side' (i.e. we drop the adjective). We simply say 'themes', which means front-side by default. Back-end themes are distinguished by saying 'administration theme(s)' (i.e. using the adjective).

[wion]

#130

[wion]

Possible title change, or merge of page altogether. Well see how it plays out first... https://forum.textpattern.com/viewtopic.php?pid=320264#p320264

[wion]

Title not yet actually changed, so correcting issue title to match status.

[wion]

@Bloke or @bloatware, in this current doc, it talks about the manifest.json file. It shows the file having these values if only the two required fields (name and title) are used when creating the theme:

{
"title": "The Human-friendly Title",
  "version": "unknown",
  "description": "none",
  "author": "unknown",
  "author_uri": "none",
  "txp-type": "textpattern-theme"
  }

But when I run a theme creation test in the demo site and skip the optional fields, I notice Txp automatically adds 0.0.1 for version and the account username for author.

Wouldn't those values be what shows in a manifest.json file if these two fields were skipped? Or are the values in the file (vs. the Themes panel table display) still just none as indicated?

[wion]

@Bloke or @bloatware, another question about the page (which I am currently adding to and revising)...

It has a few sections that talk about default theme structure, what subdirectories and templates are essential or not in a theme package, and what Txp does if any essential part is missing when importing a theme. For example is says the pages directory and specifically the two files, default.txp and error_default.txp, are essential and will be created if missing when importing a theme. So far so good understood. ;)

I'm a little confused about the nuances of this part, though:

Theme updates thereafter will not overwrite the existing essential pages.

1. If these are essential elements, how is it possible that a theme would be distributed without them in the package? Wouldn't that mean the theme didn't work to begin with and shoudn't be shared?
2. What does 'theme update' mean? Does it mean to suggest like with plugins, where the original theme author creates a new version, and the current site owner imports the new version over the top of the older version?
3. If Txp initially auto-adds any missing essential elements when importing a theme, then those added elements must be used in the current site structure if the theme is used, right? Even if just the default template code?

I guess I'm confused why anyone would possibly share a theme that was missing essential elements, or that it's possible to even do so with Txp. That seems like something Txp should prevent from happening at time of trying to 'Export to disk', like throwing a error message saying:

Sorry. No can do. Your theme package is missing these essential elements: tack, tack, tack...

[bloatware]

Dunno, @Bloke and @NicolasGraph are your men for everything theme-related. But how can you upload a theme to @petecooper demo site, I thought it was write-protected?

[petecooper]

But how can you upload a theme to @petecooper demo site, I thought it was write-protected?

It is. Well, it should be. I haven't found a way to bypass it from the front side yet. Obviously new pages / forms / styles can be added, but a theme cannot be added…now I'm worried.

[wion]

I'm not uploading there, just creating an initial them in the Themes panel using the New theme form.

[petecooper]

Ah, yeah - that's doable.

[wion]

My questions are with regard to what's written on the current user doc page this issue is concerned with. Probably questions for @Bloke. Sorry @bloatware .

[Bloke]

Theme updates thereafter will not overwrite the existing essential pages.

Outdated information. You can choose now via the checkbox when you import/export/delete to overwrite the files or the currently installed theme assets in the database. The first part of that section in the docs is fine: the stuff will be created if it doesn't exist (though it should exist).

The only time stuff might not exist is if the author has tinkered with the theme or built it on-disk from scratch (i.e. not used the admin interface to create the theme). The theme author may have renamed the 'default' Page as 'supergrid' for example and distributed the package like that. But on import, you will have the well-known (a.k.a. essential) Pages created (empty) just so things have less chance of breaking tags.

We should probably review this in 4.8, since the new dev theme workflow means there's no need for the "essential" Pages to exist any more. Switching to a theme in dev will set the correct Page properly, whereas in 4.7 it is a "soft" switch that relied on the Page name being the same as in the live theme.

The concept of essential Forms, however, remains for now.

[manifest.json] Wouldn't those values be what shows in a manifest.json file if these two fields were skipped?

Yes, the version and author are auto-created if omitted.

[wion]

Great. Thanks, @Bloke. I can finish up this revision with that, commit, and then ping you for a technical review, if that's okay.

[wion]

@Bloke , I'm getting close to a finished first draft. I have another question, though, in the final stretch. Let's say you have the scenario where a theme change objective is to use the same site structure but a different theme on each section. As I understand it so far, one would then go to the Sections panel to individually assign themes to panels in the Edit section controls, respectively.

But, is that it in this scenario? I.e. if one does that:

1. Is it necessary to make additional new assignments in the Uses page and Uses style controls too? (Maybe only when the page and/or style name is different?)
2. Or, ideally, do they change automatically in relation to the theme assignment, assuming there's only one page and one style in the theme package?†

Any other relevant clarity appreciated.

† Ideal, if true. And would suggest a possible UI change to better show the subordination of page and style controls to theme control by indenting them under the latter; making the power of influence more clear. Whatever.

[wion]

Now that I ask that second question and think about it, one probably has to make all three assignments, and the page and style assignment make clear which of each in the theme package is the one to use. No?

[Bloke]

Yes, you must assign all three elements at once. There are no separate Page and Style assignment options.

When you alter the first drop-down (Theme) the options in the other two dropdowns alongside change to reflect the available Pages and Styles in that Theme. You can only pick from those assets available in the chosen theme you elect to apply to one or more selected Sections.

It changes very subtly in 4.8 - you can bulk apply a theme directly from the Themes panel and it will attempt to set the chosen theme (after confirmation if you want it to become Live) for all Sections that have matching assets.

For example, if your live 'About' and 'Portfolio' Sections used a Page template called 'one-pager' and your in-development theme didn't have that Page name (perhaps it only had 'default' and 'archive' defined) then clicking the 'Activate' link on the Themes panel (and confirming) would switch all sections that had either 'default' or 'archive' Page templates to the new theme. 'About' and 'Portfolio' would be left alone for you to manually (re)assign at your leisure using the multi-edit tool.

This workflow helps alleviate site breakage when switching themes, while also offering a handy shortcut for bulk-assigning Themes without having to do the multi-edit select-and-apply dance.

But, as I say, the latter is 4.8 functionality.

[wion]

Understood. Crystal. Thank you!

Erm, I've actually taken the approach on this, due to recent signs of a New Year rollout of 4.8, to center the doc around 4.8, so that Active feature is accounted for. :} But the doc is not so radically different that we can't fluff it here and there with 4.7 notes (a la {: footnotes .information} styling) to make the masses happy; the notes can then be excised at launch. I'll bank on your sound review comments for tweaking.

I will say here in advance that I'm really on the fence about this just becoming the new Themes panel doc because it's heavily centered on that panel. On the other hand, it covers related features and workflows from other panels (case in point) so it is outside the scope of just the Themes panel. And the delivery is a big departure from how panel docs have been written up to now; more explanatory and stepwise-progressive than just describing thing 1, thing 2, etc. And, it's the first test run of using images again in very minimal but strategic fashion. It is, quite literally, a tutorial, but entirely focused on core functionality; no hypothetical site structures or design examples. It's a perfect place for an external tutorial like Julian's to continue on from. I like it. So, do let me know how to jump off this fence post! And if it does go to Themes panel, then it opens up the door for doing the same on other panel pages. But, there again is a fence-post quandary, because I think themes functionality is about the only panel page that warrants this kind of elaboration. I mean, I can't see doing this with languages, or preferences, lol, or hell, take your pick. But Themes! After writing this, I see Textpattern back-end by a completely different model, with themes center stage. 'Just write!' got the boot!

[wion]

I'm going fold in your insights on the last question, then commit. It won't be done, I'll have many passes to make undoubtedly, but it will be easier to see and tag-team on.

[wion]

@Bloke , edits so far are pushed to docs. Still a few sections to fill, copy to clean, images to change, etc. And I'm going to fold the import and default structure parts at the end into each other when I get to those. But there's enough there that you could look at the technical aspects of other sections, when you get a chance, and let me know if something is off or could use a bit more clarification. Add notes here, if any, by what section of doc they're concerned with, and I'll rope them in as I go. Thanks!

[wion]

@bloke, a near if not last question, hopefully.

I get the Update from disk scenario, which I presume means:

1. Move an new version of a community theme (which has already been imported to themes panel before) to the themes directory
2. Use the With selected controls to update the database version.
3. Use the option for aligning/deleting files

But I don't understand how the community theme was added to the panel table to begin with. I.e. how do you first import a community theme? I don't see the obvious.

[Bloke]

Okay, there's a sort of symbiotic relationship between disk and database but live and in-dev themes can only be previewed on the site if they are installed to the database. The assets (Pages/Styles/Forms) won't run from disk... although of course you can reference anything in the folder so if you have additional js/css/whatever files in there, you can incorporate them directly.

To get a theme into play first:

• Download it from some repository.
• Unzip it to your '/themes' directory into the theme's own sub-directory.
• Visit the Themes panel.
• Above the table is a dropdown showing a list of themes that are on disk but not installed in the database. Pick the one you just unzipped.
• Click Import.

Then it's in play and you can make changes in the DB (live/dev), make it live, whatever. You can 'backup' your database theme assets to disk and/or make changes on disk and import those to your database so they can be used on your site.

If you subsequently delete the theme from your database and elect to leave the disk files alone then the disk-based theme once again appears in the dropdown above the table and can be reimported. Only when all themes represented in the filesystem are in the database will the dropdown not be present.

Does that make sense?

[wion]

Yep. I think so. This is the part I was missing...

Above the table is a dropdown showing a list of themes that are on disk but not installed in the database.

This 'disk menu' doesn't appear in the demo site, of course (because no themes are on disk), so it must be a contextual menu that only shows up when there are themes on disk?

If so, then I get it.

[wion]

Only when all themes represented in the filesystem are in the database will the dropdown not be present.

Heh. We're good!

[wion]

@bloke, or anyone, I'm not in a position to Import themes, so I have no idea what the theme import menu looks like that appears at the top of the Themes panel table when an external theme has been initially added to the themes directory. Can anyone please provide me with an image of the menu itself, open, and showing one theme named and titled as follows, whichever is the case:

• Name: xyz-imported-theme
• Title: An Imported Theme

This sample naming fits the opposite of the default new theme creation examples being use, which are:

• Name: abc-new-theme
• Title: My New Theme

Ideally, you'd provide two images: One of the menu closed, as it would appear normally, and one of the menu open showing the 'xyz' theme as named/titled above, whichever accurately reflects. I'm guessing it's the Title (ideally)?

If you look at the doc, you'll see that the convention I'm using is to crop images directly to the borders of the actual interface controls, so that is shows the borders and control label, but not a pixel (or two) more.

And, if you want, push them to /img directory using the following names:

• themes-import-menu.png
• theme-import-menu-select.png

The image calls are already in place in the 'Importing themes' section.

Or just email me a high res screen grab and I'll process the images myself.

🙏

[wion]

Title and file name has been changed to something more reflective and attractive.

[wion]

@Bloke, one last question, I think. I'm trying tie the sections about default package contents and Txp's handling of external themes when they lack essential default elements, etc. to the importing or updating sections, whichever is relevant, or if both are. My confusion at this point is which is relevant. I think I made it look/sound like the package augmenting is tied to the importing of external themes (that's what made sense to me since it was the 'first contact' with database, as it were), but now I'm thinking it's the 'updating' process? That was a term I remember seeing a lot, in fact, on the original text. Can you clarify? I can then readjust those sections and context, revise the copy, etc, and be able to finish the first full draft.

[Bloke]

This is how it works if the on-disk Theme contains 'essential' assets that are missing:

• If you Install an on-disk theme from the dropdown above the table, all Theme assets (Pages/Forms/Styles) are imported and any missing 'essential' ones are created, and populated with a placeholder HTML comment.
• If you subsequently delete such assets from the database, that's your prerogative.
• If you then export to disk, your theme on disk will not have the essential items you've deleted in it. If you zip and distribute it like that, fine.
• Anyone - including yourself - who updates a theme from disk that contains missing elements will have those assets created automatically in the database. Every time. Placeholder content will be injected in those assets if they were missing on Update.
• If you delete them and Update from disk again, they will be recreated in the database.

Now, that's as it works today. I'm seriously considering - and I'd like your thoughts on this @bloatware - whether to relax this situation in 4.8 now we have a proper live/dev split. I don't think the default Page and Style is necessary any more. When anyone assigns a Theme to a Section, they MUST choose a Theme and MUST choose (from it) a Page and MUST choose (from it) a Style.

We're now protecting content when switching via the Active/Preview links on the Themes panel. For example, if a switch to any given Section would result in that Section not being assigned a Page/Style due to a missing asset compared to how it was before, the Section is skipped for you to do manually later.

I don't think there's any reason to keep this notion of enforced 'default' for Pages and Styles.

However, I think an enforced error_default might still be valid. What's the impact if that is missing? What does Txp do if it finds no error path? If it relies on this, could we design it such that it doesn't?

error_default acts as a backstop to catch all error situations and displays a page to that effect with the code/status message. If you have a dedicated error_404 or 403 or 500 or 451 or whatever, then those are checked first and the more specific one rendered instead. If, after checking all that stuff, it came up empty, is there something we could do? Perhaps render a bare-bones HTML page like we do if the database is missing? Just status code and message, nothing more.

If we did that, we then only have Forms that require this 'essential' treatment due to our ingrained behaviour inside some tags.

Is that workable or have I missed something? I know we hard-code 'default' in core as a fallback Page/Style, but is there any need? Can a Page ever be assigned "nothing" even by mistake? What would be the effect of not having any hard-coded 'default' mentioned? White screen of death perhaps (in the case of Page)? Unstyled content (in the case of Style)? In which case, we probably need to leave this convention intact or find a way to handle it more gracefully.

I'm all for convention, but the above workflow does seem a little OTT now. Thoughts?

[bloatware]

I don't think the default Page and Style is necessary any more.

I was already for relaxing it in 4.7, but which Page/Style would we use on sectionless "home" page?

[Bloke]

Oooh good point. Ummm. Yeah. Maybe we need it.

[bloatware]

Though default section has its Page/Style assigned too, my bad. You are right, default Page/Style are only default, not mandatory.