Open wion opened 4 years ago
wion
commented
4 years ago 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
commented
4 years ago wion
commented
4 years ago 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
commented
4 years ago Title not yet actually changed, so correcting issue title to match status.
wion
commented
4 years ago @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
commented
4 years ago @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 _errordefault.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.
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
commented
4 years ago 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
commented
4 years ago 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
commented
4 years ago I'm not uploading there, just creating an initial them in the Themes panel using the New theme form.
petecooper
commented
4 years ago Ah, yeah - that's doable.
wion
commented
4 years ago 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
commented
4 years ago 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
commented
4 years ago 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
commented
4 years ago @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:
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
commented
4 years ago 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
commented
4 years ago 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
commented
4 years ago 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
commented
4 years ago 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
commented
4 years ago @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
commented
4 years ago @bloke, a near if not last question, hopefully.
I get the Update from disk scenario, which I presume means:
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
commented
4 years ago 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:
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
commented
4 years ago 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
commented
4 years ago Only when all themes represented in the filesystem are in the database will the dropdown not be present.
Heh. We're good!
wion
commented
4 years ago @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:
This sample naming fits the opposite of the default new theme creation examples being use, which are:
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:
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
commented
4 years ago Title and file name has been changed to something more reflective and attractive.
wion
commented
4 years ago @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
commented
4 years ago This is how it works if the on-disk Theme contains 'essential' assets that are missing:
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
commented
4 years ago 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
commented
4 years ago Oooh good point. Ummm. Yeah. Maybe we need it.
bloatware
commented
4 years ago Though default section has its Page/Style assigned too, my bad. You are right, default Page/Style are only default, not mandatory.
Bloke
commented
4 years ago Ah yeah, true. Just wondering if we can remove the hard-coded 'default' since I can't see any situation nowadays where a Section will ever be "unset". Maybe I'm not thinking hard enough.
Bloke
commented
4 years ago Great stuff, Destry. Really lovely tone to it.
Notes/edits (suggested changes in bold):
The "Assigning multiple themes" section needs some light editing, methinx. The workflow here hasn't changed much since 4.7. It's always been integrated such that when you pick a theme, the Pages and Styles list is populated with the assets in that theme only.
Also need to mention that instead of assigning them one by one, you can use the multi-edit tool. That invalidates: "For this situation, you must manually assign themes, and the relevant page and style in the theme package, to each section, one at a time..." because you can apply a theme's Page/Style to multiple Sections at once via multi-edit.
The main difference in 4.8 is that the dev/live switch in the multi-edit tool works differently. Instead of being a 'soft switch' that tries to assign the section as a preview - and only if it can - it now makes a dedicated switch to the chosen assets. The dev and live environments are distinct and well-defined (there's a column for the dev theme assets in the txp_section table, instead of just relying on a pref like it did in 4.7).
When exporting, we'll probably insist that a theme is zipped up for easy distribution and we'll only host a single downloadable bundle file per theme on the Themes repo, so you might wanna also mention that once you've exported a theme, to zip up the abc-my-theme directory and everything below it for distribution.
Finally, for now, are we standardizing on using 'form' as a name for an 'edit panel'? Seems a mite confusing given we're talking about Textpattern forms too. We standardized on using 'panel' (e.g. The Preferences panel, The Write panel, etc) to disambiguate from being termed a Page and thus clashing with our template Page concept. Should we come up with a disambiguated name here too for the 'edit' step?
Thanks for all your hard work on this. Awesome stuff.
EDIT: Damn, you've made a tonne of changes since I started writing this post :)
wion
commented
4 years ago
- [x] The single directory can be thought of as a ‘package’ and its contents can be thought of as ‘assets’ organized in subdirectories by type.
- [x] You can switch theme context again at any time from any assets panel by using the Theme menu again
- [x] assets between the different themes are paired well
This one I couldn't find based on your text, which means I had probably edited out the former copy since you first looked at it. But I could tell you were talking about the 'Updating themes' section, so I added a version of that as the second para in that section. It's a nice addition. Thanks!
- [x] . . . [updating a theme from disk creates an exact copy in the database from what is on disk, merging with what you have already and overwriting if any assets are named the same.
Btw, in relation to the above item, the checkbox option on 'Update from disk'; the string reads: 'Delete theme templates from disk too'. It's not phrased well, and missing punctuation. Better like this: ‘And delete theme assets from disk?’ It's a little different from the others because the total delete action is already a given on database, now we're asking 'And from disk too?'
This next one, I never knew that about the contextual behaviour of pages/styles menus to the themes menu. But then I've never created a theme before either. ;) I'm sure this is all foreign to most people, though. Anyway, I suspect, again, I had revised this section to account for this part, but please verify let me know if not yet right.
- [x] The "Assigning multiple themes" section needs some light editing, methinx. The workflow here hasn't changed much since 4.7. It's always been integrated such that when you pick a theme, the Pages and Styles list is populated with the assets in that theme only.
This part confused me with the 'multi-edit' tool. But I see now, you mean the With selected... controls, then select 'Change theme/page/style'? Good catch. I wasn't aware of those. Yes, that's easier than one-by-one as a first go-to. I'll work that in. Thanks!
- [x] Also need to mention that instead of assigning them one by one, you can use the multi-edit tool. That invalidates: "For this situation, you must manually assign themes, and the relevant page and style in the theme package, to each section, one at a time..." because you can apply a theme's Page/Style to multiple Sections at once via multi-edit.
Not sure I got this right but it seems okay to me in the Switching themes section? I don't really talk about 'soft switch'. Let know.
- [x] The main difference in 4.8 is that the dev/live switch in the multi-edit tool works differently. Instead of being a 'soft switch' that tries to assign the section as a preview - and only if it can - it now makes a dedicated switch to the chosen assets.
Maybe needs expansion... You can set both Dev and Live and the same time? What's the scenario for wanting to do that?
- [x] The dev and live environments are distinct and well-defined (there's a column for the dev theme assets in the txp_section table, instead of just relying on a pref like it did in 4.7).
In relation to that section assignment option, though; the whole line of boxes and menus; it might be easier to take in lists form, no?. See my image for that one, which was kind of necessary anyway to make work as a sane doc image width.
Have done. But is there a particular zip format wanted? Or will it matter?
- [x] When exporting, we'll probably insist that a theme is zipped up for easy distribution and we'll only host a single downloadable bundle file per theme on the Themes repo, so you might wanna also mention that once you've exported a theme, to zip up the abc-my-theme directory and everything below it for distribution.
are we standardizing on using 'form' as a name for an 'edit panel'? Seems a mite confusing given we're talking about Textpattern forms too . . . Should we come up with a disambiguated name here too for the 'edit' step?
Ah, that old chestnut. I was just using 'form' in a normal 'web form' sense, not really thinking about it. When like this, 'Edit theme form', where the label, normally a proper noun, becomes a proper adjective, the context is pretty clear, I think, but I'll change them to 'Edit theme editor' instead. That works, too. Perfectly fine.
I don't think standardizing any specific term will work though. And who will pay attention anyway? ;) A good rule of thumb is (worth adding to the guide, in fact), if the grammar/spelling is correct, strings are formatted correctly (within best reason), and it just makes sense at the sentence level. It's probably fine. Each para might need its own jiggling, but that option to just find the right syntax/diction is often good enough and leeway enough.
wion
commented
4 years ago It was late last night when working on the 'Assigning multiple themes' section. Is the Irish thing too much? I kind of like it.
wion
commented
4 years ago @Bloke , is what is said here about the theme 'shell' remaining, along with the non-standard elements true? Or does Textpattern actually know how to remove the package directory too and leave only the non-standard files sitting there like abandoned animals, but not showing up in the Import menu?
Deleting themes
. . . As a safety precaution, if theme packages on disk contain standard theme directories having non-standard subdirectories (e.g. styles/sass), they will not be deleted by Textpattern; rather, the package container will remain, along with the non-standard subdirectories and files inside the directory. This shell of a theme and its non-standard elements will need deleted manually since the software does not recognize such elements.
Bloke
commented
4 years ago The 'shell' thing is perfect. I'll review the other changes now.
wion
commented
4 years ago I can't find the Issue, but I thought @bloatware had mentioned somewhere that blue 'Active' links would be changed to 'Activate' links, which is why I'm leaving that for now. Is that actually the plan, though?
wion
commented
4 years ago I thought I might add one more section, very end; something like 'What now?' and briefly give a vew pointers/links -- no actual tutorial stuff -- toward the design direction. The diving board. Maybe flat-file plugins, an eye on Textpattern Tips, whatever. Any ideas to throw in there? The point being: 'now you have mechanics; here are some creative approaches...' kind of thing. I don't know. Maybe not. It's already a good piece; longish but not bloated, me thinks. Just thorough.
bloatware
commented
4 years ago @wion I've just pushed activate to dev, but would strongly suggest that we switch to pictograms whenever possible. Multiplying text strings is bad for performance, and they are not easily reusable in all languages. For example, the current active string does not agree well with 'theme' in Russian.
wion
commented
4 years ago . . . strongly suggest that we switch to pictograms whenever possible.
No problem for me. I guess that's a @philwareham thing. Can you provide that issue link here, where that discussion was happening, please? I'll try to follow along, but someone should remind me if/when the presentation of those links changes again.
By the way, is it a problem to make the green 'active' links bold, too. I think that really helps with the distinguishing aspect under the current conditions, because the spelling is subtle, and so it sht color difference. If not, no big deal.
Bloke
commented
4 years ago Good stuff, thanks. I'll read it more thoroughly later. A few things:
#duplicate-via-the-with-selected-controls.Might be worth an aside to mention you don't have to use disk at all for themes. It's only if you want to share them, or back them up, or put your theme assets under version control that people will likely do it.
A further note on that point: if you create a new theme in the UI it will not appear on disk. It's solely resident in the database until such time as you Export to disk. Now, if you choose not to export it at all, the checkboxes in the With selected tool regarding 'disk' operations don't make sense. What disk copy?
Unfortunately we can't omit the checkboxes, as you may choose one or more themes from the list and some might be on disk, while others might not. JavaScript does not know and can't find out directly.
We could, perhaps, 'tag' each row in the UI with a data- attribute indicating its on-disk status. Then perhaps if you select all entries that are not represented on disk, the checkbox could be omitted? Not sure if that is worth investigating or if it makes things too confusing from a UX/documentation viewpoint. (@bloatware what do you think?)
Either way, if you try to perform a disk-based operation (e.g. Update from disk when the theme is not resident on disk) you'll get a warning after the action runs telling you which parts it could or couldn't do. If the entire disk action fails you'll get a red failure box. If part of the action fails (e.g. it could update one of your choices but not the other) you'll get an amber warning box. If all actions succeed you'll get a green success box.
‘And delete theme assets from disk?’
Fine by me. Or fix the punctuation. It's just a language string.
I don't really talk about 'soft switch'.
Don't need to mention the 'soft' switch nature of 4.7. That was just for you, for context.
Maybe needs expansion... You can set both Dev and Live and the same time?
Making your live and dev environments match avoids surprises, since you'll see the same theme when you browse the front end, regardless if you're logged in or not.
In relation to that section assignment option, though; the whole line of boxes and menus; it might be easier to take in lists form, no?
Yes, I did wonder that. If we put line breaks in or divs or something around the two blocks, I presume JS will render them that way when it draws that fragment, but I don't know about lining things up. @philwareham what do you think to something like this?
mockup change theme/page/style
is there a particular zip format wanted? Or will it matter?
Nope. Out of our control at the moment. Txp doesn't handle zipping/unzipping yet. Perhaps if we allow you to "upload" a theme bundle when the Themes site comes online and unpack it on disk, we might care. But that's only a possibility.
bloatware
commented
4 years ago is it a problem to make the green 'active' links bold, too.
No problem for me. I guess that's a @philwareham thing. :-)
Bloke
commented
4 years ago Can we adjust the Importing themes number list for clarity please. Something like this (tweak to taste):
[ EDIT: not sure if 'unrepresented' is a bit clunky ]
If you didn’t see the menu before, it is because it works in context with the themes directory, as follows:
wion
commented
4 years ago FYI, just focus on the developmental editing for now. Typos and other copy edits can wait. I might even find those along the way anyway (such as that link). You can even do those when I'm done with the final first draft. ;)
wion
commented
4 years ago A few things:
Those are all done. I removed the shamrock nonsense. Like I said, working late. ;)
Might be worth an aside to mention you don't have to use disk at all for themes.
Good one. I've added a parenthetical. And see the endnote that links back to it. Easier. ;)
A further note on that point: if you create a new theme in the UI it will not appear on disk. It's solely resident in the database until such time as you Export to disk.
Yeah, I think this is intuitive from the rest. At least that's how I understood it at this point, and if I understand, it's dummy-proof.
Cont...
wion
commented
4 years ago That's not to suggest the design, exactly; just to show an alternative idea to linear. To me it's a lot easier to make sense of.
But I'm going to leave it like that for the time being, even if not actual UI, because otherwise it runs too wide for practical purposes. I'll put a caption on it to explain in context it's just a deviation for docs purposes.
wion
commented
4 years ago Now, if you choose not to export it at all, the checkboxes in the With selected tool regarding 'disk' operations don't make sense. What disk copy? . . . Unfortunately we can't omit the checkboxes, as you may choose one or more themes from the list and some might be on disk, while others might not. JavaScript does not know and can't find out directly.
Hmm... I know you're just talking aloud to me, but that might actually deserve being an endnote to provide some explanation for those who might come across it. I don't want to weigh main text down with such side explanations, though.
Either way, if you try to perform a disk-based operation (e.g. Update from disk when the theme is not resident on disk) you'll get a warning after the action runs telling you which parts it could or couldn't do. If the entire disk action fails you'll get a red failure box. If part of the action fails (e.g. it could update one of your choices but not the other) you'll get an amber warning box. If all actions succeed you'll get a green success box.
That, OTOH, is probably worthy to add in text somewhere. I'll get back to that later.
wion
commented
4 years ago Can we adjust the Importing themes number list for clarity please.
Yep. Switched out. Thanks. That was just figuring aloud on my part.
wion
commented
4 years ago Making your live and dev environments match avoids surprises, since you'll see the same theme when you browse the front end, regardless if you're logged in or not.
This one I might need more clarification... Let's look at this from the context of someone who just installed Txp, is not a developer. Might only want to swap a 'skin' on the default theme. What does 'live' and 'dev' environments mean in a default install of Txp?
'Development' is that new location stored in the txp-tables, or something? And 'Live' just refers to the websites live front-end?
Bloke
commented
4 years ago 'Development' is that new location stored in the txp-tables, or something? And 'Live' just refers to the websites live front-end?
'Development' is a theme that is active on one or more Sections that are only for logged-in users to see. That is, a preview of what the changes you've made will look like. This allows you to see the effect of your meddling without affecting public visitors (as long as you're careful and don't start deleting plugins or changing prefs or whatever).
'Live' is what everyone else - the public, not logged in - sees.
I admit that setting them both the same is not a usual occurrence but if you're done with your edits and want to synchronise everything for now until such time as you start diverging with a new theme in future, it's handy to be able to do it in one step instead of having to set the current theme live and then go back and do it again to change your dev environment.
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:
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
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.