Open wion opened 4 years ago
wion
commented
4 years ago That last share was helpful in two respects: in addressing that relevant section better about the two options (Dev/Live), etc. and segueing into starting the Previewing section.
I realize now what was nagging me about the current document structure, too, so I'm going to slightly change the headings/structure in that respect too.
wion
commented
4 years ago @Bloke, in the re-headed Previewing (development) themes section, I think I should add an item (to the list of things to especially pay attention) about the Themes column. But what should I say? I see the grayed out default theme name and a new name next to it. What is that telling me?
Bloke
commented
4 years ago The greyed-out one is the one that's publicly live. The other one is the dev one that overrides it. Thus it shows visually which is 'active' for you and other logged-in users, while also showing you what the rest of the world see.
You may also see some assets in red. Those are where you've switched to a theme (perhaps using Developer preview from the With selected... tool, or when using Active/Preview from the Themes panel) but the page/style that was in place has been deleted or is not present in the theme. That's a warning that if you make this theme live as-is, things will break as you will not have the red assets assigned to it.
wion
commented
4 years ago @Bloke, on that mention of 'Developer preview'... what is the difference between the two options?
Also, here's a test I just tried on the demo site...
So, I guess my questions are:
There are so many ways and places to change things now, and contexts, that I get overwhelmed and lost in the woods if I go too deep into them. Can't find my way out again.
wion
commented
4 years ago The point of asking is that I'm explaining the red text scenario as you mentioned before, and trying to offer options what to do in such a case. That last scenario is confusing me. Maybe you can offer something better to say.
See the other two mentions in that section... https://docs.textpattern.com/themes/themes-a-complete-walk-through#preview-link
Bloke
commented
4 years ago Developer preview allows you to decide what you want to do with the current 'preview' or 'staged' (in-development) theme assets that are assigned to the section(s) you selected. So:
Yes there are many ways to achieve things here, but if you think about it from a workflow perspective, you can take action in a variety of ways. For example:
... and many other workflows and combinations besides.
As you can see, depending on what you want to achieve there are a few routes. All of them lead to the same place - assets assigned to sections for you and/or logged-in users - it's just that some are more efficient than others, involving fewer clicks and hoops, depending on what you want to do.
The bottom line is that we're allowing your live server to act as a staging server as well. So you can develop and preview and have clients sign-off a design in (relative) safety using live article content. No other CMS (as far as I'm aware) does this.
In a typical scenario, you usually end up:
a) exporting the database and files, setting up a new (sub)domain or server with a Txp install containing the cloned content, make your changes, then have to worry about porting the changes back and how to resync the databases after your live content has moved on since you took the DB snapshot.
b) setting up fake Sections on your live site, ensuring they don't show up to regular visitors, then assigning your dev templates/styles on those Sections to allow clients to see what you're developing. But then you have to create a bunch of fake content too, or muck about with <txp:article_custom>, since articles can only be assigned to one Section at a time.
Our dev/live workflow tools sidestep all the hacks and all the drudgery of the staging/live dance.
It's pretty fuckin' sweet :)
wion
commented
4 years ago Excellent. Yep. That's how I like to approach it, by task objective and the most efficient way to complete it. It's for that reason I don't think every path to the doghouse needs documented. Just the most obvious/quickest/intended paths, if that makes sense. But my paths may not always be the paths others like. And in this case I'm still discovering this functionality. I don't want to write a bible, either. So if I seem like I"m going astray in the doc, let me know. Like you've done here. Thank you!
wion
commented
4 years ago @philwareham, @bloke, @bloatware,
Are we pretty stable with the Themes UI design now? I'd like to get back to this doc and revise/finish it in relation.
philwareham
commented
4 years ago I think so, I’m happy with the latest UI. Definitely finished for 4.8.0 release anyway. Cheers Destry - appreciate your patience on this documentation with all changes we did!
wion
commented
4 years ago Okay. Revising against the latest 4.80-dev demo.
bloatware
commented
4 years ago What should we do with the former 'dev preview' link/functionality? Dump it entirely (and remove its code), put the link on individual theme page or something else?
wion
commented
4 years ago I'm just trying to keep up, but I thought the 'dev preview' or 'preview' functionality was dropped in favour of the Select with... functionality on the Section panel side. But let me see if I understand as it is now with a clean installation:
Seems to me there are a lot of ways to create a new dev theme, but not so clearly labeled as such.
To me at this point I have now created a theme in development. Presumably I can't preview a theme in development until I've either created a new theme or duplicated one. This makes sense.
Now let's say I've made a few changes to the new development theme's CSS file. How do I preview that? Do I click the Assign sections link for that theme? Is assigning sections what must be done before I can preview it? I don't know, but the command 'assign sections' may not make sense at this point if you came by my path.
What should I do to preview my dev changes at this point?
Why not have a 'Preview' option in the selection menu? I.e. go back to step 6, but now I want to preview my dev theme. I check the box for it and select 'Preview'. That seems very straightforward to me. But I guess that's exactly what the Assign sections link is supposed to do.
We seem to be back to a problem of semantics.
Personally, I don't think 'Assign sections' is the right command to give so early on. I think 'preview' was better. From there (a preview standpoint) a person can then decide if they want to assign sections or not.
Sorry to make it confusing again.
philwareham
commented
4 years ago I think we can drop the dev preview link idea, yes.
bloatware
commented
4 years ago The idea was to provide a one-click way to 'preview' in-dev themes, and @wion seems to agree it makes sense. It's a relatively safe operation, unlike assigning 'live' themes (replaced by 'Assign sections' link now). The question is where to put 'preview' link: individual or list themes page? Checkbox would not do because you can not preview multiple themes at once.
wion
commented
4 years ago Checkbox would not do because you can not preview multiple themes at once.
Arg! I overlooked that.
What is an ‘individual’ themes page? You mean in sections panel context?
If so, then, as mentioned, I think the proposition of ‘assign sections’ comes too early. What if I want to create new sections first? In which case ‘assign’ doesn’t even make sense yet.
This makes sense to me:
In other words, I think it makes more sense to change the ‘Assign sections’ link on the Themes panel records to ‘Preview’, then leave the assigning steps to the sections preview view, where the action is more in context with the appropriate panel (and decision flow).
If none of that makes sense, then I give up, because I still don’t understand it either, apparently.
wion
commented
4 years ago Checkbox would not do because you can not preview multiple themes at once.
What if you walked them through it with an error message to make it clear they can only select one box in this case?
This is assuming you want to leave the 'Assign sections' link as it is.
bloatware
commented
4 years ago Individual theme page is where you land when clicking on 'New theme' or an existing theme link. But it's not ideal workflow-wise since before previewing a new theme one must save it, which takes him back to the themes list.
Restricting the multi-edit widget to a single item does not look very natural. And it takes two clicks anyway...
wion
commented
4 years ago Individual theme page is where you land when clicking on 'New theme' or an existing theme link.
Ah, the metadata form? That's what it seems like to me since there's nothing there to do with what's actually in a theme (i.e. assets), just most of what goes in the manifest file.
Well, if that's the case, then I hardly see anything wrong with putting a Preview link inside the form view. Like you said, it's harmless; certainly won't make things worse.
wion
commented
4 years ago Let me know what y'all decide about the dev theme Preview functionality. I had already spent some time writing documentation about it, and when read again, it seems like useful functionality indeed. I personally don't understand why you would not want development preview functionality. It seems essential in themes development.
Bloke
commented
4 years ago I still think it has value to be able to quick-switch all dev -> to live or to revert back to live.
bloatware
commented
4 years ago I'm also missing some kind of 'assigned sections' indicator for theme select box on Form/Page/Style tabs. You do some changes and then realize it's a wrong theme...
wion
commented
4 years ago Question...
Let's say I do this workflow:
What am I looking at when I click the 'View' link under the Name column for that section now? Is it the live section or the new dev section?
If it's the new dev section I just created in step 3, then that is effectively the 'preview' feature I would be hunting for as a user, and we can probably not quibble further about it. Though I think that connection needs to be made more clear, case in point.
wion
commented
4 years ago Maybe those 'View' links should be in the Theme column instead, and immediately next to the dev or live theme, as the case is. Then the association is perfectly clear.
bloatware
commented
4 years ago What am I looking at when I click the 'View' link under the Name column for that section now? Is it the live section or the new dev section?
Devs who have enabled 'dev preview' option are always seeing the 'dev' theme when one is set.
wion
commented
4 years ago 'Dev preview' option? What else am I missing? Is there a spec everyone except me is working off of?
wion
commented
4 years ago Do you just mean to say that when a 'Development' pill shows up on a section, then that's the trump view for that section?
bloatware
commented
4 years ago It depends on Admin/Enable development theme preview? preference state. You can enable or disable dev preview there.
wion
commented
4 years ago How did I keep overlooking that? No wonder I was clawing in the dark.
Okay, that changes things. So as it seems now, I can preview a development theme (meaning I can view it on the front end as I edit assets). As far as it seems to me, that's all the preview functionality one really needs.
I'll leave it to you devs to decide if a quick theme switcher thing is needed, but as I see it, this functionality is already provided for by the selection controls in the Section panel after clicking the 'Assign sections' link. Maybe we should leave it at that and move on.
Unless I'm missing something, there is no further issue here, right? I think I grasp it now to finish docs as the current 4.80-dev demo shows.
wion
commented
4 years ago I really need these images, but I can't produce them from the demo site. I assume you devs have tested the import features (thus see the menu) somewhere... Can anyone provide the two images as requested, s'il vous plaît.
I can put a call out in the forum too, if necessary.
@Bloke , @bloatware , @philwareham
wion
commented
4 years ago Maybe I'll see if I can find a theme to import in my own site. Any suggestions of one to try? I won't actually use it, per se, but at least trigger the menu.
Bloke
commented
4 years ago Sorry, @wion. I can take this if you like, but you can do it yourself on a site:
wion
commented
4 years ago Heh. I didn't even think about exporting. I'll do that, thanks, @Bloke. It would probably be good to walk through both processes anyway.
wion
commented
4 years ago Easy-peasy. Thanks.
I'm not sure how many theme's I'll ever actually make, but I've certainly come to understand the themes functionality better after all this.
wion
commented
4 years ago @Bloke, I think I've updated this doc now so it's correct against current functionality, including imagery. When you get a chance, please give it a technical review.
Don't trouble yourself to keep a list of problems found, to relay to me, yadda yadda... Feel free to tweak and fix whatever issues you find, technical or orthographical. If you think there are structural issues, however (i.e. flow of ideas through the doc), and there could be, let me know what you think about that. I'd like to tackle that part again, if so.
When your done, I'll give it one last proof read, then seek debutante themers from the forum for their feedback on understanding the concepts explained. The real test.
Bloke
commented
4 years ago I'm about a third of the way through (slow on this phone using H+ by the seaside!) and it's great so far.
One thing: there are a few internal links to 'assigning multiple themes' and that segment appears to have been axed. Should the links be pointing to another section I haven't found yet, or is this section meant to be in the doc somewhere?
Also, in the 'asset association' section, there's a broken image link. Can you fix that please? Ta!
Bloke
commented
4 years ago Gone through it all. Nice work, Destry-san.
wion
commented
4 years ago I'll fix the items you found. Thanks a lot.
wion
commented
4 years ago @Bloke, I've made a couple structural changes where the flow and bloat was bothering me.
For example, there's a new Multi-selection controls section now that brings better attention to those important controls, specifically the 'Change themes/pages/styles' option. This also makes it possible to refer back to that section later in the doc to reduce repetitive descriptions where feasible.
I've also created the Assigned sections indication section to bring better focus to those new pill features too. In this case a couple of things occurred to me:
That's certainly what I would expect to happen, but I didn't actually try assigning both dev and live to a theme, so I'm wondering if that question is true. If so, then I should probably add that graphic to this section too.
wion
commented
4 years ago Scratch that second question. I just tested it. ;) It seems not to be the case; rather, if a theme has both a dev and live assignment, it simply appears with a green 'In use' pill and no orange indication at all, either in the Themes panel or Sections panel.
I guess that makes sense, but certainly a behaviour to make clear in the doc, so I'll do that.
Bloke
commented
4 years ago Nice idea regarding the multi-edit section. That does consolidate things nicely.
Regarding singular vs plural column names, well, we have singular 'Page' and 'Style' too, yet there could be a dev and a live Page assigned separately (if, for example, you named a Page differently in your Dev theme compared to the Live theme, you see the horizontal line and the two Pages listed).
There's only really ever one Theme/Page/Style in use - the live one. The dev state is just a convenience for iterating a design, so it's probably not worth the upheaval to change the labels at the moment.
Oh, one more thing, where did mention of the Deploy to live / Reset to live multi-edit option go? It only appears if you have set a dev theme.
wion
commented
4 years ago There's only really ever one Theme/Page/Style in use - the live one. The dev state is just a convenience for iterating a design, so it's probably not worth the upheaval to change the labels at the moment.
That makes sense now after yet more exploration.
Oh, one more thing, where did mention of the Deploy to live / Reset to live multi-edit option go? It only appears if you have set a dev theme.
There are some adjusted/new sections under the Production (live) themes section. See if that's what you're referring to. The information was there before, but just not called out plainly by a clear header.
What I'm recognizing is there is no real way to theme switch all in one shot unless a site is setup to use a single page and style across every section. Otherwise, a person will have to make multiple passes with the assigning controls, regardless whether a single theme across the whole site or a different theme on every section.
By the end of the 'Production (live) themes' sections, after having already read through the development sections before it, the explanations of using the selection controls border on being beat to death; only different by the context of single theme or multiple themes. But I think the consolidation is as much as can be while still remaining clear under the different contexts or objectives people might have.
I need to check internal links again, but I'll do that tomorrow.
Bloke
commented
4 years ago Yeah, sort of. But that's where the Deploy to Live multi-edit option comes in. It allows you to, essentially, stage your entire setup and then switch it live in one go.
So you can, for example:
Preview everything using your logged-in powers, make sure everything hangs together, then from the Sections panel:
All your selected sections will get their current dev theme(s) copied to live. One shot.
If at some point during development, you or your client decide that the direction things are heading is a load of crap and you want to start again on a bunch of sections, select the sections you want to "unstage", choose 'Developer preview' from the multi-edit list, and select 'Reset to Live'. The current Dev theme(s) will be unassigned, thus the previous Live theme(s) will be shown to logged-in users.
Yes, you still have to set things up and do multiple passes to assign multiple themes as you develop the site, but the critical thing is that you don't have to make all the changes quickly and leave your site in potential limbo at go-live time. The multi-edit option will copy dev -> live - regardless of which theme/page/style you've used - in one go for the selected sections.
Does that make sense?
wion
commented
4 years ago
- Choose 'Developer preview' from the multi-edit list.
I don't see any such option in either 4.8.0-dev demo or my local 4.8.0-dev installation. It must really be bleeding edge.
Bloke
commented
4 years ago It only appears after you've made at least one theme dev.
wion
commented
4 years ago I must have overlooked it then, because I've made a lot of themes dev in the course of working on this document. Clearly it needs to be documented.
A suggestion for the future, if I may... That for any new, significant functionality to be introduced in the software and needing documented; that it be briefly summarized in a development spec, or whatever, principally naming what new functionality it includes and where to find it and when to see it in the peek-a-boo nature of hiding things in the UI.
I suspect this themes project was one of the more challenging that Txp will ever see, and once done there won't be a greater effort, but if, say, unlimited custom fields is going to be another bear to document, it would be nice to have such a spec first for the tech writer, to be more efficient than foolish.
I will investigate and edit further.
wion
commented
4 years ago Oh, that looks kind of familiar. ;)
But now I'm confused why there is even a 'Live' check box option in the 'Change theme/page/style' controls. I thought that was the new way of deploying a theme asset to live on a section.
wion
commented
4 years ago Anyway, I think I just need to add a new 'Deploy to live' section in the Production part of the doc and that should be good enough.
Bloke
commented
4 years ago now I'm confused why there is even a 'Live' check box option in the 'Change theme/page/style' controls. I thought that was the new way of deploying a theme asset to live on a section.
It's a way of deploying stuff live. If you only have one section to push live, or if you have a few sections that share a single theme, then you can just do it there. Choice of pushing a theme to live/dev is handy.
But if you want to stage the entire site with multiple themes across many sections, the Developer preview multi-edit offers the least downtime when switching over from dev->live. Just one action.
The Developer preview info was in the doc in an earlier iteration (at least I thought it was) so maybe it got chopped out during an edit storm. Or, perhaps during testing as the docs was being developed, the option 'disappeared' because it only shows up if there are development themes assigned. We need to do this, because the option doesn't make sense otherwise.
wion
commented
4 years ago The Developer preview info was in the doc in an earlier iteration (at least I thought it was) so maybe it got chopped out during an edit storm.
That's exactly what happened. And I chopped it under the confused impression that functionality was changing, then I just overlooked it every time. But I'm glad the preview functionality is there and understand it better; it cleared yet more things up for me.
And despite the loopy-loop race-track editing, I think we're close now, and it's even better than ever. The document is a bit more concise in places, progresses more logically, has clearer section links, for the most part, with more intra-document linking.
I need to remove some obsolete images now, add a couple of new/improved ones, and make another copyedit and link-check pass, then I'll ping you for one more golden-seal review before seeking the public impression.
wion
commented
4 years ago 4.8.0 in the house! Good job, everyone.
I’ll get back to this doc as soon as the kids return to school on Monday.
Or, when I can. Feel free to edit if I’m overly delinquent.
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.