Ticket #12227 (closed PLIP: fixed)

Opened 3 years ago

Last modified 20 months ago

In-Plone theme editor

Reported by: optilude Owned by:
Priority: minor Milestone: 4.3
Component: General Version: 4.3
Keywords: Cc:

Description (last modified by jonstahl) (diff)

Proposer: Martin Aspeli
Seconder: Jon Stahl

Motivation

We want to make Plone the world's easiest CMS to theme. plone.app.theming, included in Plone 4.2, goes a long way towards that, but creating themes and uploading as zip files is not an effective way to create a new theme. We want to provide a sensible environment in which designers and administrators can create themes without filesystem access or knowledge of Buildout or Python, whilst still allowing them to reuse and download/distribute (via zip files) themes or progress to filesystem development.

Assumptions

N/A

Proposal & Implementation

  • Update the 'Diazo theme' control panel to provide a UI for downloading and creating new in-ZODB themes (the storage and management tools are already part of p.resource / p.a.theming)
  • Integrate a simple file manager, based on  http://labs.corefive.com/projects/filemanager/, but simplified to focus on the left hand side file tree only
  • Integrate ACE with Python syntax highlighting, a Javascript editor:  http://ace.ajax.org/
  • Add tools for point-and-click building of rules by identifying elements in the content + theme

Deliverables

  • Code
  • Tests

Risks

  • Adds a new third party component (ACE) and a dependency on a few jQuery plugins via the file manager.
  • In time, we may want to generalise this out of p.a.theming for use in e.g. Deco or Dexterity
  • This is moderately complex JavaScript, and we don't tend to test in IE very well
  • There's no real non-JavaScript fallback other than going to the ZMI (which is feature complete as such for file management, but not particularly user friendly)

Participants

  • Martin Aspeli
  • Nathan van Gheem

Progress

Work has now been merged to the master branch of:

 https://github.com/plone/plone.app.theming/

Please test away!

We've put out a call to get a better template theme, which will make for a more realistic starting point.

Attachments

plone.app.theming.pdf Download (404.8 KB) - added by optilude 2 years ago.
Mockup from Denys
theming_UI.png Download (190.2 KB) - added by optilude 2 years ago.
Denys has provided the following mock-up. Whilst I am still sceptical that putting the file manager and the theme mapper on the same page will work (it still looks mighty squished) I do quite like some of the styling.
PloneAppThemingFeedback.zip Download (500.1 KB) - added by optilude 22 months ago.
Feedback from Alice Tseng-Planas & her team
plone.app.theming - mock-ups v2.pdf.zip Download (350.6 KB) - added by optilude 22 months ago.
Mock-ups of current state and suggested changes based on Alice's team's feedback

Change History

comment:1 Changed 3 years ago by kleist

  • Type changed from Bug to PLIP

comment:2 Changed 3 years ago by eleddy

approved for 4.3 - please let us know when its ready for review

comment:3 Changed 3 years ago by optilude

  • Description modified (diff)

comment:4 Changed 3 years ago by optilude

  • Milestone set to 4.3

comment:5 Changed 3 years ago by optilude

I think it would be useful to get some more review of this: It's pretty close to completion.

There's no PLIP buildout yet, but you can just checkout the branch from GitHub and build it to test.

comment:6 Changed 3 years ago by optilude

  • Description modified (diff)

comment:7 Changed 2 years ago by optilude

A PLIP buildout and notes are now in place. Review appreciated.

The biggest TODOs are:

  • Possibly some refactoring of the file manager JavaScript. It works well, but could be more visually appealing and reusable.
  • A review of the test coverage
  • A better default theme. Giacomo Spettoli had offered to help here, though not sure if he's had time

At this point, though, I'd like to get some detailed feedback and then we can try to push the required changes through prior to merge.

comment:8 Changed 2 years ago by davisagli

Is the FWT reviewing this? I really want to see this get in. My selfish reason is that I'm trying to help a friend who's not a developer set up a site on Ploud, and having the TTW theme editor would prevent me from needing to set up a local copy of the site. Let me know how I can help.

comment:9 Changed 2 years ago by robgietema

  • Version set to 4.1
  • severity set to Untriaged

PLIP 12227: In-Plone theme editor

PLIP ticket: https://dev.plone.org/plone/ticket/12227

Review 1 by Rob Gietema (rob@…, Rob|4D on irc)

The PLIP was reviewed on Mac OS X 10.7.2 using python 2.6.7 and Firefox 10.0.2.

Review steps

  • Run all the tests.
  • Visual review of the code in the different packages
  • Started instance, created site.
  • Edit theme using the "File manager" and "Map theme" views.

Notes and observations

  • All 300 tests pass, except for one which failed due to a missing file in plone.subrequest. Test coverage is well above 90%.
  • Code in the different packages look sane.
  • Editing using the file manager and theme mapper is really nice. This makes editing themes a lot easier for people new to theming.
  • When I create a new file and try to edit that file it raises an error.
  • The styling and markup of the filemanager view is completely different from the rest of Plone. To keep the UI consistant this needs to change. Some examples:
  • h1 tag used in the toolbar so multiple h1's exist
  • toolbar is right alligned and doesn't match the styling of the rest of Plone (also has icons)
  • Tabs have a different styling and markup then default Plone tabs

Conclusion

Looking very good, this is a really nice feature to have. The styling and markup does need to be changed to match the Plone markup and styling. If that will be fixed I'm +1 for merging.

comment:10 Changed 2 years ago by rossp

Talked about this in today's FWT meeting. Rob's review is above and Alec will be doing another review soon.

Rob's primary concern is different look and feel and would like to know how much work it would be to bring Plone's look and feel to ACE. I like that idea but I worry about maintenance issues in the future if we heavily modify ACE and get ourselves in a place where we stop upgrading ACE from upstream because no one on our side has the energy to update our modifications. davisagli, optilude, can you weigh in on the options for bringing Plone's look and feel to ACE?

comment:11 Changed 2 years ago by optilude

Hi,

I would like some help in the styling department. I'm unlikely to be able to do that myself anytime soon. This is because we've adopted the code from an existing component, and Plone doesn't have CSS styles we could easily steal.

Personally, I think it's a fairly minor issue, since this is admin UI and has no real equivalent in Plone (except perhaps the ZMI).

We have not modified ACE at all. Rob's comments are about the file manager, which is not part of ACE. ACE is only the text editor component, which we are using out of the box.

The file manager was based on a jQuery file manager, but had to be modified to fit the theme editor model. That is isolated to one fairly short file of JavaScript, though, and one page template. All the real complexity is in ACE (and the custom theme mapper code, though that should hopefully be fairly easily maintainable).

Martin

comment:12 Changed 2 years ago by spliter

PLIP 12227: In-Plone theme editor

PLIP ticket: https://dev.plone.org/plone/ticket/12227

UI Review 1 by Denys Mishunov (spliter on irc)

The PLIP was reviewed on Mac OS X 10.7.3 using python 2.7.3rc1 and Google Chrome 18.0.1025.45 beta.

Review steps

Notes and observations

Create theme tab

  • When on "Create theme" tab it should allow me to upload the theme right there wihout switching tabs back and forth. This is important — the form doesn't allow me to create completely new theme from scratch so it has to allow me to upload a theme here.
  • Having some pre-installed themes out-of-the-box is confusing. I have no idea what are those. If you want to provide a demo theme it should be only one. Not 2. And should probably be renamed to something simple like "Demo theme".
  • If we ship with a demo theme, it should at minimum resemble a real-life theme and look completely different from Plone. The bundled examples look like either plain HTML or not finished Plone. If you want, I could come up with a basic boilerplate theme or we could take one of the GPL ones.

Manage theme files view

  • After I put the basic information about my theme I get a screen with the file browser for a theme. The theme, most probably, has been finished in my desktop application. So there is no need to give me the file browser for a thing I have already finished in a much friendlier environment. I would like just 2 buttons — "Manage theme files", "Map the theme". Or, even better, go straight to the mapping process. This is important — if there is no ability to create a theme from scratch, this means the theme should have been completed in a desktop application. This means I don't need file browser for my theme. Ideally, after I fill out title and description for the theme, I need the tool to add rules.xml, manifest.cfg to my theme in the background (if they are still not there) and let me map the theme immediately after that.
  • If we will give the ability to edit the theme itself TTW is it possible, to let people preview the theme (not the mapped content + theme result, but the plain theme itself) after the changes they've made?

Theme mapping view

  • Map theme view is a mess. It should have much better and prominent structure. Text should be consistent. If we call a panel "The Diazo rules" in the description, the corresponding panel should have this exact title and not just "Rules". Would be great instead of the page description have a short paragrpah with explanation and an unordered list of in-page links to the panels for easieer navigation.
  • Content and Theme panels should come first in my opinion. Moreover they should be layed out with some logic. For example

Theme → Content

Rules → Preview

If we see both content and the theme in 50% of the screen we can not show the result in 100% — it doesn't match. Moreover it's better to put preview right below the content to make comparison of the before/after states easier.

  • Rules field shows that it is re-sizable, but I could not "catch" the corner and re-size the field.
  • Any reason the panels have no editor as we had on the theme files view? It is very confusing to get different tools for editing the same information on these 2 screens.
  • The title of the "Preview" panel should be changed. Having "Preview" as the title and "preview" as an action is confusing. "Result" as a title could be an option.
  • "Hover over an element to see its selector." information should be above the panel, not below. Before noticing that, I was wondering whether I should constantly switch back and forth between the "Preview" and "Source".
  • "Last saved:" information should be much more prominent after one has saved a selector. Something like color highlight that dims down after some time. Right now it is using the same font color as the content of a panel located on a really light gray background and you should really know where to look for in order to notice it.
  • The interaction betwen the panels should be more interactive. I have saved some elements in the panels without adding a new rule. What do I do next with that info? The info is not copied in my copy/paste buffer, the information is not copied to my rules file, for example. Probably it's not a task for this phase but this experience should be thought through. For now at least a toolbox (and the functionality of course) with a hint of what should I do now ("Want to create a rule for this selector?") should popup. Or we just don't allow selecting the elements outside of the add-new-rule process.
  • Why do overlays with Diazo help and new rule have such a tiny font-size?
  • If I tried to add a new rule and then changed my mind there has to be a way to cancel the creation like Esc, or some button or click-event outside of the panels.
  • If I click "Cancel" on the final stage of adding the new rule I don't need the same "Flash" effect as when I have added the rule successfully. This makes me stare in the rules panel thinking I have actually added something. Harsh stop without any animation or flash is more suitable in this case.
  • On the other hand, when I click "Save" for the rules file, I would like to see some feedback from the preview panel like that flash we have after adding a rule. Just local for the preview panel. Otherwise, if I work with an element in the footer I have no idea whether preview has been updated or not — the element I care about is not visible in this case.
  • Nothing tells me that by changing and saving the rules I make permanent changes immediately available on the site. In this case we should get rid of all "preview" labels and titles since there is no preview — there is an end result in any case. Or I would prefer to somehow keep the changes I make and then have a large button "Update the site" or something like that that would push the changes to the site.
  • I would eliminate "preview" from "preview/source" toggle and would make just a simple 'source' button instead. Preview is the default view anyway and it is preview at any moment when it is not source.
  • Is it possible to save selector in the panels on click and not on Enter? This would be much more intuitive way of doing things. When I am working with applying rules I don't need to interact with content. If I need to check other pages I go to the site (that has the theme already applied by now) and check it there. Or we can have another button like "Interactive mode" for example. It should be disabled by default and no interaction should happen.

Conclusion

From the technical point of view it is a really good option to provide for the Plone theme integrators and fantastic job has been done for this PLIP. But from the UI point of view implementation is raw and not very user-friendly. Moreover some moments like absence of "your site is updated right now" information might make it even dangerous if used on the live sites. And it is not about styling of the interface but more about user experience while working with this editor, interface elements in general, consistency in presentation of the interface elements, interactions and so on. I would not vote against inclusion of the PLIP. But I would strongly encourage to re-think the usability and user experience stories and have a clear understanding of how the user should interact with the tool. Right now, there is a high chance of users getting lost in the tool. And if we position this as the ground-breaking solution for people only starting with theming Plone, current state of the UX and UI doesn't deliver that message.

Last edited 2 years ago by spliter (previous) (diff)

comment:13 Changed 2 years ago by optilude

A shortened to-do list based on Denys' feedback:

Create theme tab

  • When on "Create theme" tab it should allow me to upload the theme
    • optilude: You can do this through the 'import' tab. Do we really want to duplicate this? The reason they are different is that on the 'Create' tab you enter a new title/description, and the theme is always unique. On the 'import' tab you have other options, like immediately enabling the theme and replacing an existing theme in case a theme with the same name already exists.
  • Better deafult theme

Theme mapper

  • When choosing the theme, prefer 'index.html' or 'theme.html' file before falling back on first HTML file
  • Merge file manager and theme mapper (see mockup)
    • Rules is always open (important for wizard)
    • Currently open theme is shown in both editor and file manager
    • optilude: This has failed in practice: there is not enough space for the file manager and file tree, and more modal approaches seem to break down too. For now, we will keep the separate file manager and mapper, but work to incorporate the other elements of these recommendations into the mapper. We may also add a preview for the file manager so you can view the files you are working on.
  • Text and font size consistency in mapper
  • Full screen switch for editors/iframes
  • The title of the "Preview" panel should be changed. Having "Preview" as the title and "preview" as an action is confusing
  • "Hover over an element to see its selector." information should be above the panel, not below. Before noticing that, I was wondering whether I should constantly switch back and forth between the "Preview" and "Source".
  • "Last saved:" information should be much more prominent after one has saved a selector. Something like color highlight that dims down after some time.
  • Ability to create rules from saved selectors
    • optilude: I think this may need to be a v2 feature. It's probably not essential.
  • Help/new rule overlay font size too small
  • Cancel option during rule selection
    • optilude: Esc is used to move the selection 'up' one container (important since it can be hard to click on an exact container element). Clicking outside is hard to detect and feels brittle. I've added an explicit Cancel button and made the wizard prompt more visible instead.
  • Reverse wizard order: do theme before content
  • Visual feedback for updated result when saving rules
  • Make it more clear when editing is 'live'
  • Add button to apply theme to live site in the mapper
  • Save selector on click, not just enter
    • optilude: Are we sure? You save on click during the rules wizard, but I think it's important to be able to navigate the content or theme otherwise. You're likely to need to theme pages that are not the front page, for example. Having some kind of 'live' mode is lame, IMHO.
Last edited 2 years ago by optilude (previous) (diff)

comment:14 Changed 2 years ago by optilude

I've just pushed a new template theme based on Twitter Bootstrap. It's not quite polished enough to be a 'production' theme, but at the same time I'm keen not to over-complete so that it can serve as a useful template/example and not to be too complex.

Feel free to test/improve!

Changed 2 years ago by optilude

Mockup from Denys

comment:15 Changed 2 years ago by optilude

Ok, I've just pushed some updates. Let me try to explain the philosophy behind them briefly.

Firstly, I assume people will want to create and manage themes entirely through the web. This is more discoverable and lower-impedance than filesystem development. With themes in plone.resource directories, we in any case have a pretty smooth path to move between filesystem and ZODB in both directions.

This may go something like this:

  • User goes to Diazo theme control panel, clicks 'Create new theme'
  • User enters a title and description and picks a theme to start from. This can be one uploaded earlier, or "Example theme" which comes with p.a.theming (other themes you may see during PLIP testing are in the test buildout only)
  • User is now taken into the file manager. This is all about building the HTML for the raw theme before doing any rule mapping, though of course the Diazo control files (manifest.cfg and rules.xml) remain editable
  • This UI is optimised for editing of multiple, related files of HTML, CSS and JavaScript
  • To get back here, the user can go to the 'Manage themes' tab of the control panel and click 'Manage files' for the relevant theme
  • A 'live' preview of any opened HTML file appears underneath the editor
  • Once the user is happy with the theme, he can move to the 'Preview and map theme' tab
  • This UI is optimised for discovering rule selectors (via the point-and-click rule builder) and editing the rules file

Note: The theme mapper can also be used for filesystem themes, but here it is in read-only mode. The file manager is not available.

Changed 2 years ago by optilude

Denys has provided the following mock-up. Whilst I am still sceptical that putting the file manager and the theme mapper on the same page will work (it still looks mighty squished) I do quite like some of the styling.

comment:16 Changed 2 years ago by optilude

I've just made a ton of changes to improve the UI and overall experience. See also the comments above.

I think it would be good to get some more review at this stage, as most if not all of the 'v1' features are in place.

comment:17 Changed 23 months ago by eleddy

we think this is in a state where this is ready to merge into 4.3 - do you think it is ready? our target is to merge everything for 4.3 by July 11.

comment:18 Changed 23 months ago by davisagli

And in particular with this PLIP, we'd love it if you could merge the branch and make a pre-release of the next major revision of plone.app.theming so that more people can try out the UI.

comment:19 Changed 22 months ago by optilude

As you've probably noticed, my available free time has massively tanked recently, but I will endeavour to do the merge and try to get an alpha of p.a.theming out.

There are still tweaks to be done to the UI (see follow up comment shortly), but I don't want to let perfect be the enemy of good so I think we should try to do those improvements incrementally and let whatever we can get done reasonably come through.

Martin

Changed 22 months ago by optilude

Feedback from Alice Tseng-Planas & her team

comment:20 Changed 22 months ago by optilude

Thanks to Alice Tseng-Planas and her team for lots of review and feedback! I'm going to try to summarise some of the actionable suggestions here.

Note: I'll disregard feedback on installation (since it'll ship with Plone)

1) Main control panel

  • Suggestion that "manage themes should be the default tab (optimises for creating theme; maybe not for using existing themes?)
  • "Preview" link for both filesystem and ZODB themes
  • Don't show 'select theme' option if there is only one theme installed ("example theme")
  • Unify the "basic settings", "upload theme" and "create theme" functions - all are necessary to get a first theme up and running. Could go on the first tab you see.
  • "Edit themes" is more useful than "manage themes", or just keep a theme list in a primary tab.
  • Treat "create theme" as more of a "from scratch" operation - it's confusing to select a base theme (maybe hide this by default, at least), because it implies you really need to do an import first and then create from there. Probably best to unify under a single place, with a "duplicate" option serving the purpose of the "create theme with non-default base theme" functionality, and have "new theme" as using a hardcoded base theme. Create an even more minimal base theme (no example styles) for this purpose, but keep the example theme (for use via the 'duplicate' action. Base theme should not be selectable as a real theme.
  • Allow upload of a zip file with a theme but not rules.xml/manifest.cfg and supply a default instead (brilliant idea, by the way)

2) Theme mapper

  • Let "preview" be in a new window/tab or modal dialogue? (Is it possible to refresh this with JS from spawning window on theme mapper change?). Would allow more real-estate, and would make a unified "preview" link from "manage themes" in the control panel more logical (since it really means "read-only theme mapper" for filesystem themes)
  • Allow individual resizing of panels in the theme mapper
  • Feedback: "Too many steps for new rule" (this is not terribly actionable)
  • Make it clearer where rules will be inserted after the new rule wizard (how?)
  • Feedback: "Also ‘insert new rule” button placement is confusing." (not terribly actionable)
  • Theme file dropdown in "raw theme" panel is confusing - only show if there are multiple theme files and label more clearly
  • Rename "raw theme" to "HTML mockup"
  • Make sure global actions are placed globally, not next to windows (a bit unclear from feedback which icons/butons this is referring to, but definitely a problem with 'new rule' - could be all actions next to rules.xml editor)

3) Buttons

  • Need clearer icons, probably with labels
  • Purpose of the 'highlight' option needs to be made more clear, or just find a sensible default (maybe we want to switch it around, so the icon turns 'follow links' on or off)
  • Eye icon in particular is confusing
  • Change icon behaviour so the icon that's shown is the future state, not current state

4) Bugs

  • Seems to be a caching issue with 'new rule' that means first rule gets inserted each time? (This may be caused by the recent change where we re-use saved selections from the theme and content panels to create a rule; should be cleared after new rule insert, probably).

From feedback: "We noticed that themes uploaded as a zip file (i.e. a mockup I created) don’t have access to the mapper in the same way as file system build themes (the file structure isn’t revealed) – this is a shame. We figured that people who cannot develop “on the file system” would be the exact same people who would most benefit from the “Theme Mapper” and the “Though the Plone.App.Theming Interface Way”."

If this is the case, it must be a (recent) bug. In-ZODB (zip-uploaded) themes should have the most complete experience, with on-filesystem themes being readonly. Needs investigation.

5) Help

  • Make it clearer which files do what in the mapper and file manager (e.g. highlight rules.xml and theme html file)
  • Discoverability of p.a.theming and Diazo documentation low (needs to go on plone.org)
  • Make sure documentation is action-oriented and does not assume developer knowledge
  • Make in-place documentation more standalone (e.g. no links to other documents for core knowledge; specific to Plone)
  • Improve usefulness of example theme

Changed 22 months ago by optilude

Mock-ups of current state and suggested changes based on Alice's team's feedback

comment:21 Changed 22 months ago by optilude

The mockup uploaded above tries to address most of the concerns from the survey. Feedback welcome! There are also a few open questions in the notes in the preview.

comment:22 Changed 22 months ago by kleist

Confirming, just to clean up the report "Untriaged Tickets".

comment:23 Changed 22 months ago by kleist

  • Status changed from new to confirmed
  • Component changed from Unknown to General

comment:24 Changed 21 months ago by jonstahl

  • Version changed from 4.1 to 4.3
  • Description modified (diff)

comment:25 Changed 20 months ago by esteele

  • Status changed from confirmed to closed
  • Resolution set to fixed
Note: See TracTickets for help on using tickets.