Ticket #13476 (confirmed PLIP)

Opened 2 years ago

Last modified 19 months ago

New widgets for Plone (plone.app.widgets) and separated admin (plone.app.toolbar)

Reported by: garbas Owned by: garbas
Priority: minor Milestone: 5.0
Component: JavaScript Version:
Keywords: Cc:

Description (last modified by pbdiode) (diff)

Proposer: Rok Garbas
Seconder: Nathan Van Gheem

Motivation for plone.app.widgets

  • Make javascript testable
  • Make javascript components able to be encapsulated
  • Make it simple for front-end developers to work on front-end Plone

Resulting from those primary motivations, the following are some secondary motivations:

  • Override a collection of widgets currently found in Plone with widgets developed in a modular, testable, and feature compatible manner
  • Front-end developers should never have to deal with Python, buildout, or Plone
  • Make hearing the word 'Javascript' and 'Plone' in the same sentence not cringe-worthy
  • Make working with Plone and Javascript fun again.
  • Tap into the larger Javascript community to use modern, commonly used Javascript tools for developing Javascript
    • RequireJS/Almond for providing modularization/encapsulation
    • Yeoman (Yo, Grunt, Bower) for a javascript development workflow (scaffolding, task management, and package management)
    • Karma + Mocha for testing
    • Node + NPM for installing and running the javascript tooling
  • Provide a smaller set of versitile widgets that can be use consistently throughout the core of future Plone, and other packages, such as plone.app.toolbar and plone.app.deco

Motivation for plone.app.toolbar

  • Move the admin toolbar currently found in the content of a page (when logged in) to a separate, encapsulated, bar at the top of the page.
  • Make it so themer's do not need to handle or manage admin specific UI, unless it is something they are are intentionally doing

Proposal & Implementation

  • Develop javascript code outside python packages and provide bundled and compiled version of javascript. Why? Because tools that help you work with javascipt will never be as good in python as they are in javascript. For this Plone Mockup project was created:  http://plone.github.io/mockup
  • plone.app.widgets will provide an implementation layer between the javascript developed in mockup and archetypes/dexterity
  • plone.app.toolbar will provide an implementation layer between the javascript developed in mockup, and Plone core
  • update archetypes to utilize plone.app.widgets provided widgets instead of the currently implemented archetypes.schemaextender integration.

Deliverables

Risks

  • Totally new way of developing javascript which we will have to document extensively (not that current way is documented).
  • We might end up with tested javascript :)
  • New *location* of the interface for interacting with admin-related UI components, with a new skin

Documentation

Widgets Delivered

  • Adjust Text Size -- Easily change text size on a page.
  • Cookie Directive -- A pattern that checks cookies enabled and asks permission for the user to allow cookies or not.
  • Expose -- Exposes the focused element by darkening everything else on the page. Useful to focus the user attention on a particular area.
  • Form Unload Alert -- A pattern to warn user when changes are unsaved and they try to navigate away from page.
  • Live Search -- Dynamically query the server and display results.
  • Modal -- Creates a modal dialog (also called overlay).
  • Pick A Date -- Allows the user to select a date (with or without time) through a calendar.
  • Picture -- A responsive image widget.
  • Prevent Double Submit -- A pattern to prevent submitting a form twice.
  • Query String for Collections -- A widget for creating query's for collections
  • Related Items -- An advanced widget for selecting related items.
  • Select2 -- Autocompletes, multiple or single selections from any kind of data source (with search!).
  • Table Sorter -- A pattern you can apply to a table so it can have its items rearranged when clicking the header.
  • TinyMCE (v4!!!!) -- Rich text editor.
  • Table of Contents -- Automatically generate a table of contents.
  • Tooltip -- A pattern to show a tooltip on hover.
  • DropZone -- Drag 'n drop file upload

Change History

comment:1 Changed 2 years ago by garbas

  • Type changed from Bug to PLIP
  • Milestone changed from 4.x to 4.4

comment:2 Changed 2 years ago by garbas

  • Version 4.3 deleted
  • Description modified (diff)

comment:3 Changed 2 years ago by garbas

  • Description modified (diff)

comment:4 Changed 2 years ago by garbas

  • Description modified (diff)

comment:5 Changed 2 years ago by garbas

  • Description modified (diff)

comment:6 Changed 2 years ago by saily

  • Description modified (diff)

mockups are available on  http://plone.github.com/mockup, so i removed the https.

comment:7 Changed 2 years ago by kleist

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

comment:8 Changed 2 years ago by vangheem

  • Description modified (diff)

comment:9 Changed 22 months ago by davisagli

Can you please provide a bit more information in the PLIP description:

  1. What widgets are currently provided?
  2. What is the plan for integrating this into core so that we aren't just adding another set of widgets without removing anything? Are there existing widgets that can go away? Are there parts of plone.app.widgets that should get moved into existing core packages?
  3. Are there known issues that need to be taken care of before this can be added to core?
  4. Where is the documentation of a) how to use these widgets and b) how to develop additional widgets? What existing documentation at developer.plone.org will need to be updated once this PLIP is merged?

comment:10 Changed 22 months ago by vangheem

  • Description modified (diff)

comment:11 Changed 22 months ago by vangheem

  • Description modified (diff)

I've updated the plip a bit davisagli. Couple more thoughts:

  • I don't think we can remove old widgets since archetypes and dexterity, with plone.app.widgets, are sharing the same js code--it might be more difficult to straight up replace existing widgets in archetypes. That being said, maybe we could do it that way--simply merge the plone.app.widgets code into archetypes and then plone.app.z3cform(or plone.app.form?)
  • no known issues... yet...
  • yes, we need docs on how you'd utilize these widgets
  • development of new widgets ideally will follow the mockup methodology.

comment:12 Changed 22 months ago by garbas

  • Description modified (diff)

comment:13 Changed 22 months ago by garbas

i've also updated PLIP a bit

  1. updated in plip by vangheem
  2. i'm +1 on merging code into P.Archetypes and p.a.(z3c)form.
  3. there are few issues open, but nothing really blocking us. i'm fixing them as they come.
  4. there was some documentation written on patterns at last PLOG by simone. all documentation is on first page here:  http://plone.github.io/mockup ... which i need to clean up a bit, i guess non working day like today might be just the right day to do it.

comment:14 Changed 22 months ago by davisagli

Framework team review

David Glick

2013-05-28

  • Please add a PLIP buildout to make it easier to test this against Plone master.
  • Why no autoinclude entry point?
  • Needs a newer p.a.jquery than Plone uses. We should probably update it for 4.4.
  • Includes precompiled set of CSS and Javascript. Presumably this is generated from the mockup project? The package needs documentation of how to update these. And documentation of how to get a non-packed version for debugging js conflicts.
  • Included js libs are: patterns, jquery.event.{drag,drop}, textext, pickadate. Others? It would be nice if the PLIP included a discussion of why the packages used were chosen, what alternatives were considered and why they were ruled out, known limitations of the chosen libs, etc.
  • Widget for tags:
    • Shows weird icons on right of input while typing ( https://github.com/plone/plone.app.widgets/issues/16)
    • There is a missing feature compared to the Archetypes tags widget: being able to browse a list of the tags. Can we have something more like the Languages field which includes a list, but that also allows adding new values?
    • It says "No matches found" when I focus the input. This is confusing since I haven't tried to search for anything yet.
    • Does it support the feature of only allowing users with a particular permission to add new tags?
  • Widget for dates:
    • The date components are not showing in the same order as my site's date format.
  • Widget for creators & contributors:
    • This is nice!
    • It should store the user id, not the fullname, so that it is still connected to the user if they change their full name.
  • Disables the date picker on content_status_history…why?
  • Has integration tests of some of the widgets, could use more.

Work needed to integrate this:

  • Fix issues in github tracker
  • Configure the appropriate widgets for standard metadata directly in ATContentTypes and plone.app.dexterity rather than by overriding.
  • I think the widgets themselves probably belong in Products.Archetypes and plone.app.z3cform, with plone.app.widgets remaining merely as a package to hold the static resources. But the important thing is that the direction of the dependencies is correct so that using plone.app.widgets doesn't necessarily pull in either Dexterity or Archetypes.
  • Update CMFPlone to include plone.app.widgets and use patterns where appropriate (i.e. calendar macros, remove old form_tabbing code, etc.)
  • Document each widget's options
  • Document how to maintain the javascripts and css used in plone.app.widgets
  • Document how to add new widgets / patterns

Conclusion: I like the direction this is going. It makes some needed improvements, particularly to our select widget, and does so in a way that decouples particular choices of javascript libraries from the options configured on the backend and from the integration with particular form libraries. More work is needed though, particularly to make sure this is properly integrated rather than existing as an add-on package, and to make sure that use of the widgets is adequately documented. I'm +0 for now, but will be +1 for including this if that work is completed.

Feedback on mockup:

  • The example site ( http://plone.github.io/) is great, but each pattern needs more detailed documentation. It's not necessarily obvious what the data attributes mean.
  • I like the basic approach of building functionality that's attached to a CSS class and configured using data attributes. Looks like it does a good job of separating frontend concerns from backend.
  • Using the autotoc pattern to make tabs is nonintuitive.
  • You really really need docs on how to add a new pattern. It's okay if it's a short summary for starters.
  • Please add documentation of how to run the tests. And the tests use various libraries that I'm not familiar with…mocha, chai, sinon, buster…can you give a justification of what adding these dependencies does for us? Why jam as a js package manager?

comment:15 Changed 21 months ago by thet

this PLIP is quite important for the user experience for Plone. i'm already using plone.app.widgets in production.

rok discussed the reasoning behind some of the libraries in:  http://garbas.si/blog/2013/patternslib-plone-mockup-ok-time-to-explain-it

there is also an ongoing discussion on plone-dev about the use of require.js and the AMD concept in plone.app.widgets.

but still, i have some concerns using some of the libraries, especially patternslib. i believe the seperation of widgets from backend code to frontend code via so-called patterns is a great thing! but the library has something which reminds me of KSS - it's used mainly by Plone people in the Plone ecosystem and did not gain wide spread adoption until now. it also introduces a new approach of doing Javascript development. i'm not sure if understood everything and i'm also unsure if my concerns are important enough to be a stopper on this PLIP.

when the situation clarifies for me, i'm totally happily +1 - but until then i'm more comfortable with being -1.

comment:16 Changed 21 months ago by thet

IMO we should also help in marketing patternslib if it goes into core.

comment:17 Changed 21 months ago by thet

Please note the updated plone.app.jquerytools with backports of jquerytools pull-requests. This makes it compatible with JQuery 1.8 - at least as far as I can tell.

See the changenote of 1.5.6:  https://github.com/plone/plone.app.jquerytools/blob/master/CHANGES.rst

comment:18 Changed 21 months ago by toutpt

Don't know why but the demo page is so slow on a phone so I guess there are some performance issues. Mobile browser are great to detect this kind of issues.

I have no idea why and how to measure performance of JS but this should be verified. Remember plone3 was slow because of kss. We should also try tags widget with 2500 keywords (look at #plone on twitter)

 http://plone.github.io/mockup/patterns.html

comment:19 Changed 21 months ago by garbas

patterns.html page was split into several sites in master. showing more demos for each pattern. its not done yet but its a start. once we polish it a bit we'll push the changes to plone.github.io. help more then welcome.

tags with +800 tags work fine (that's what i've tested until now).

but i agree with you that widgets/patterns should be tested with mobile devices as well. i've created a ticket for this just so we dont forget it:  https://github.com/plone/plone.app.widgets/issues/36

comment:20 Changed 21 months ago by esteele

  • Milestone changed from 4.4 to 5.0

The Framework Team has decided to move on to Plone 5. Updating milestones accordingly.

comment:21 Changed 20 months ago by timo

How are we going to integrate the new JS unit tests into our Jenkins setup and/or zope testrunner? If I understand this correctly, we are not going to use BusterJS any longer (which has been integrated into zope.testrunner by Ross at the Sea Sprint).

comment:22 Changed 20 months ago by pbdiode

  • Description modified (diff)

comment:23 Changed 20 months ago by pbdiode

  • Description modified (diff)

comment:24 Changed 20 months ago by pbdiode

  • Description modified (diff)

comment:25 Changed 20 months ago by pbdiode

  • Description modified (diff)
  • Summary changed from new set of widgets for Plone (plone.app.widgets) to New widgets for Plone (plone.app.widgets) and separated admin (plone.app.toolbar)

comment:26 Changed 20 months ago by garbas

@timo: sorry for late response but i was busy at Bastille Sprint.

to run javascript tests we can create a new project on jenkins, listen for each commit coming from mockup project and run:

% make bootstrap test-ci

currently test-ci opens chrome and runs tests once and reports back test results in junit style and coverage in covertura style. i haven't had the time to yet to play with SauceLabs intergation, but from what i read that shouldn't be more then an day of work to integrate  https://github.com/karma-runner/karma-webdriver-launcher which supports running tests in SeleniumGrid (which is SauceLabs).

comment:27 Changed 20 months ago by timo

@garbas: No problem. I did not expect a reply so soon. Impressive list of new widgets btw!

So the JS unit tests live in the mockup repo? Do we need a Jenkins job for mockup then or shall we integrate it into plone.app.widgets?

We already have Chrome installed on our Jenkins machines, so we should be able to create a Jenkins job that runs those tests even without the SauceLabs integration, right?

comment:28 Changed 20 months ago by garbas

@timo: i would create mockup job. p.a.widgets/toolbar jobs will get removed once we get them into core, but mockup job will stay "forever" :)

i'll try to find some time soon to get saucelabs integration done and then lets setup the jenkins job. until then we'll be manually checking that tests are passing.

comment:29 Changed 19 months ago by thet

i revert my vote to +1 and i'm happily accept the proposal. my concerns about implementation details can be discussed later on. but i'm already sold to the patterns idea, AFAICT.

Note: See TracTickets for help on using tickets.