From 1226087462e1e7b66efb31d6bac7d3e0959970cb Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sat, 7 Oct 2023 19:03:51 +0200 Subject: [PATCH 01/10] maint(docs): Improve the documentation. --- README.md | 161 +++++++++++++++++++++++++++--------------------------- 1 file changed, 82 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 032ad8e1e..992a29cd7 100644 --- a/README.md +++ b/README.md @@ -2,78 +2,6 @@ Mockup is the JavaScript stack of the Plone Classic UI. -## Styleguide - -- Tab: 4 spaces for everything except for HTML and XML files (2 Spaces) and the Makefile (TAB). - This rule is defined in the [.editorconfig file](./.editorconfig). - -## Commit style guide - -We automatically generate the changelog from the commit messages following the [Conventional Commits specification](https://www.conventionalcommits.org/). -Changelog generation is done by the [conventional changelog plugin](https://github.com/release-it/conventional-changelog/) for [release-it](https://github.com/release-it/release-it). -This is enforced via a pre-commit hook managed by [husky](https://github.com/typicode/husky). - -### And this is how you use it - -We have 4 different types of changelog entries: - -- Breaking Changes (type: `breaking`), -- Features (type: `feat`), -- Bug Fixes (type: `fix`), -- Maintenance (type: `maint`). - -We can group commits in the changelog via a scope - or grouping. -Let's follow a convention and use these groupings - but the grouping is optional and any other group name can be used. - -- "Dependencies" for upgrading package.json dependencies. -- "Docs" for documentation. -- "Build" for everything related to the release workflow, Webpack and building bundles. -- "Cleanup" for cleaning up or reformatting code. -- "pat PATTERNNAME" for changes to individual patterns in src/pat. -- "core MODULENAME" for changes to core modules in src/core. - -A commit message with a changelog-grouping must be structured like so: `TYPE(GROUP): MESSAGE`. -Without grouping: `TYPE: MESSAGE` - -If the commit message doesn't follow this convention it won't be included in the changelog. -To bypass the pre-commit hook, use the git `-n` switch. -Example: `git commit yarn.lock -m"yarn install." -n`. - -If you are working on a component like the structure pattern (pat-structure), use `pat structure` as a group. - -Examples: - -Add a feature to the structure pattern: - -``` -git commit src/pat/structure -m"feat(pat structure): Add feature to cook some coffee" -``` - -Cleanup task: - -``` -git commit -am"maint(Cleanup): Remove whitespace from documentation." - -``` - -or without a grouping: - -``` -git commit -am"maint: Remove unnecessary file from root directory." -``` - ---- - -** Note ** - -Please keep commits on the `yarn.lock` file or any other auto-generated code seperate. - -Just commit them seperately with `git commit yarn.lock -m"yarn install" -n`. - -Having them seperately reduces the effort when merging or rebasing branches where a merge conflict can easily happen. -In such cases you can just withdraw your changes on the yarn.lock file or remove those commits and re-install with `yarn install` at the end of a successful merge or rebase. - ---- ## Install @@ -93,7 +21,7 @@ In such cases you can just withdraw your changes on the yarn.lock file or remove On this port our demo and documentation pages are served. -# Development +## Development You can directly develop with the 11ty based documentation / demo server by running ``make serve``. @@ -107,7 +35,7 @@ If you want to develop in Plone, you have two options: For more commands inspect Makefile and the script part of the package.json. -## Running tests +### Running tests Run `make check` to run all tests including `eslint` checks. @@ -118,7 +46,7 @@ To run individual tests, run: - `jest src/pat/PATH-TO-PATTERN -t "Test name"`: Run a specific test matching "Test name" from a specific test suite. - `jest --watch`: Run the interactive test runner. -## Debugging tests +### Debugging tests The tests are based on jsdom - a library mocking DOM and HTML standards in JavaScript. No real browsers are involved, which make the tests run really fast. @@ -143,7 +71,7 @@ node --inspect-brk node_modules/.bin/jest --runInBand ./src/pat/PATH-TO-PATTERN You can put some `debugger;` statements to the code to break the execution and investigate. -## Developing external Packages +### Developing external Packages If you want to work on ony external package like Patternslib or any external Mockup pattern you can do so by linking those packages into the node_modules folder via `yarn link`. @@ -166,7 +94,7 @@ For more information see: **Please note:**: Make sure to unlink and reinstall development pacakges before building a production bundle. In doubt, remove the node_modules directory and re-install. -## Bundle build analyzation +### Bundle build analyzation https://survivejs.com/webpack/optimizing/build-analysis/ https://formidable.com/blog/2018/finding-webpack-duplicates-with-inspectpack-plugin/ @@ -192,7 +120,7 @@ npx webpack-bundle-analyzer stats.json ``` -## i18n message extraction +### i18n message extraction To update the translation file, the following needs to be done: @@ -218,7 +146,7 @@ cd ../plone.app.locales/plone/app/locales/locales i18ndude sync --pot widgets.pot */LC_MESSAGES/widgets.po ``` -## i18n message handling in Plone +### i18n message handling in Plone To test a translation, for example French: @@ -232,3 +160,78 @@ The translations are handled by ``src/core/i18n.js``. This translation helper that calls the ``@@plonejsi18n`` view defined in plone.app.content to generate a JSON of the translations from the mo file. The ``@@plonejsi18n`` view is called one time for a given domain and language and the result is cached in localStorage for 24 hours. The only way to test the new translations is to restart the instance to update the mo file from the po file, and then to purge the localStorage to trigger a new download of the translations. + + +### Styleguide + +- Tab: 4 spaces for everything except for HTML and XML files (2 Spaces) and the Makefile (TAB). + This rule is defined in the [.editorconfig file](./.editorconfig). + +### Commit style guide + +We automatically generate the changelog from the commit messages following the [Conventional Commits specification](https://www.conventionalcommits.org/). +Changelog generation is done by the [conventional changelog plugin](https://github.com/release-it/conventional-changelog/) for [release-it](https://github.com/release-it/release-it). +This is enforced via a pre-commit hook managed by [husky](https://github.com/typicode/husky). + +**And this is how you use it:** + +We have 4 different types of changelog entries: + +- Breaking Changes (type: `breaking`), +- Features (type: `feat`), +- Bug Fixes (type: `fix`), +- Maintenance (type: `maint`). + +We can group commits in the changelog via a scope - or grouping. +Let's follow a convention and use these groupings - but the grouping is optional and any other group name can be used. + +- "Dependencies" for upgrading package.json dependencies. +- "Docs" for documentation. +- "Build" for everything related to the release workflow, Webpack and building bundles. +- "Cleanup" for cleaning up or reformatting code. +- "pat PATTERNNAME" for changes to individual patterns in src/pat. +- "core MODULENAME" for changes to core modules in src/core. + +A commit message with a changelog-grouping must be structured like so: `TYPE(GROUP): MESSAGE`. +Without grouping: `TYPE: MESSAGE` + +If the commit message doesn't follow this convention it won't be included in the changelog. +To bypass the pre-commit hook, use the git `-n` switch. +Example: `git commit yarn.lock -m"yarn install." -n`. + +If you are working on a component like the structure pattern (pat-structure), use `pat structure` as a group. + +Examples: + +Add a feature to the structure pattern: + +``` +git commit src/pat/structure -m"feat(pat structure): Add feature to cook some coffee" +``` + +Cleanup task: + +``` +git commit -am"maint(Cleanup): Remove whitespace from documentation." + +``` + +or without a grouping: + +``` +git commit -am"maint: Remove unnecessary file from root directory." +``` + +--- + +**Note** + +Please keep commits on the `yarn.lock` file or any other auto-generated code seperate. + +Just commit them seperately with `git commit yarn.lock -m"yarn install" -n`. + +Having them seperately reduces the effort when merging or rebasing branches where a merge conflict can easily happen. +In such cases you can just withdraw your changes on the yarn.lock file or remove those commits and re-install with `yarn install` at the end of a successful merge or rebase. + +--- + From 3b706810f344ab9f3c497a924a4400e0d22fa227 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sat, 7 Oct 2023 19:55:45 +0200 Subject: [PATCH 02/10] maint(docs): Add a Pattern overview page. --- README.md | 74 ++++++++++++++++++++++ src/pat/backdrop/README.md | 9 +++ src/pat/contentloader/README.md | 7 ++ src/pat/formautofocus/README.md | 3 + src/pat/formunloadalert/README.md | 3 +- src/pat/livesearch/README.md | 2 + src/pat/markspeciallinks/README.md | 2 + src/pat/modal/README.md | 3 +- src/pat/navigationmarker/README.md | 2 + src/pat/passwordstrength/README.md | 3 + src/pat/preventdoublesubmit/README.md | 2 + src/pat/querystring/README.md | 2 + src/pat/recurrence/README.md | 2 + src/pat/relateditems/README.md | 3 +- src/pat/select2/README.md | 3 +- src/pat/sortable/README.md | 3 + src/pat/structure-updater/README.md | 2 + src/pat/structure/README.md | 3 + src/pat/textareamimetypeselector/README.md | 5 +- src/pat/texteditor/README.md | 9 +++ src/pat/tinymce/README.md | 4 +- src/pat/toggle/README.md | 3 +- src/pat/toolbar/README.md | 3 + src/pat/tree/README.md | 2 + src/pat/upload/README.md | 3 + 25 files changed, 150 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 992a29cd7..fecc6d2d4 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,80 @@ Mockup is the JavaScript stack of the Plone Classic UI. On this port our demo and documentation pages are served. +## Mockup overview + +Mockup is a JavaScrip UI library which provides widgets, apps and functionality for the Plone Classic UI variant. +It is based on Patternslib(XXX) and provides it's functionality through so-called Patterns which are initialized and get active if a triggering CSS selector is found in the DOM tree. +For example, the related items widget is initialized on a form input field with the CSS class `pat-relateditems`. +The configuration is done via data attributes, in case of the related items pattern it's an attribute called `data-pat-relateditems`. +The data strucutre of the configuration can be a JSON string or CSS declaration like key-value pairs separated by a semicolon. +Defining a JSON structure is more flexible though. + +Here are two examples. + +`pat-relateditems` configuration as JSON structure: +```html + +``` + +`pat-relateditems` configuration as CSS declarations: +```html + +``` + +Because of historic reasons the Mockup Pattern attributes are written in "camelCase" like the `vocabularyUrl`. +But in order to resemble the CSS syntax new Patterns should rather separate each word with a dash, like `vocabulary-url`. + + +## Mockup Patterns + +- [pat-autotoc](src/pat/autotoc/README.md): Automatically create a table of contents. +- [pat-cookietrigger](src/pat/cookietrigger/README.md): Show a DOM element if browser cookies are disabled. +- [pat-datatables](src/pat/datatables/README.md): This pattern provides the functionality from https://datatables.net/ +- [pat-formautofocus](src/pat/formautofocus/README.md): Automatically set the focus on a form input field. +- [pat-formunloadalert](src/pat/formunloadalert/README.md): Show a warning if the user leaves an unsaved form. +- [pat-livesearch](src/pat/livesearch/README.md): Provide Plone's live search functionality. +- [pat-manage-portlets](src/pat/manageportlets/README.md): Used by plone.app.portlets to manage portlets. +- [pat-markspeciallinks](src/pat/markspeciallinks/README.md): Add a special class to links in certain conditions. +- [pat-modal](src/pat/modal/README.md): Show content in a modal. +- [pat-navigationmarker](src/pat/navigationmarker/README.md): Add classes to the main navigation. +- [pat-passwordstrength](src/pat/passwordstrength/README.md): Check the strength of a password. +- [pat-preventdoublesubmit](src/pat/preventdoublesubmit/README.md): Prevent multiple submissions of the same forn. +- [pat-querystring](src/pat/querystring/README.md): Show the querystring selection app. +- [pat-recurrence](src/pat/recurrence/README.md): Show the recurrence widget. +- [pat-relateditems](src/pat/relateditems/README.md): Show a widget to select related items. +- [pat-select2](src/pat/select2/README.md): Show a widget which enhances dropdown selections with automatic suggestions, search and tagging functionality. +- [pat-sortable](src/pat/sortable/README.md): A pattern to make listings sortable. +- [pat-structure](src/pat/structure/README.md): Plone's folder contents app. +- [pat-structureupdater](src/pat/structure-updater/README.md): Update title and description based on the current folder contents location. +- [pat-textareamimetypeselector](src/pat/textareamimetypeselector/README.md): Display the mime type selection widget for textareas. +- [pat-tinymce](src/pat/tinymce/README.md): Use the TinyMCE editor for HTML editing. +- [pat-toggle](src/pat/toggle/README.md): A pattern to toggle classes on HTML elements. +- [pat-toolbar](src/pat/toolbar/README.md): Render the Plone toolbar. +- [pat-tree](src/pat/tree/README.md): Renders a navigatable tree from a data structure. +- [pat-upload](src/pat/upload/README.md): Upload files to Plone. + +Deprecated patterns: + +- [pat-backdrop](src/pat/backdrop/README.md) (_deprecated_): Renders a dark background. +- [pat-contentloader](src/pat/contentloader/README.md) (_deprecated_): Load remote or local content into a target. +- [pat-texteditor](src/pat/texteditor/README.md) (_deprecated_): Show a code editor. + + ## Development You can directly develop with the 11ty based documentation / demo server by running ``make serve``. diff --git a/src/pat/backdrop/README.md b/src/pat/backdrop/README.md index 1bf483ede..019a3cfb1 100644 --- a/src/pat/backdrop/README.md +++ b/src/pat/backdrop/README.md @@ -5,6 +5,15 @@ title: Backdrop # Backdrop pattern. +Renders a dark background. + +--- +**Deprecated** + +This pattern is deprecated. Just use plain CSS instead. + +--- + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/contentloader/README.md b/src/pat/contentloader/README.md index 512b39d33..14fcc7ba5 100644 --- a/src/pat/contentloader/README.md +++ b/src/pat/contentloader/README.md @@ -7,6 +7,13 @@ title: Content loader Load remote or local content into a target. +--- +**Deprecated** + +Please use `pat-inject` from Patternslib instead. + +--- + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/formautofocus/README.md b/src/pat/formautofocus/README.md index 9bed05728..528f0495e 100644 --- a/src/pat/formautofocus/README.md +++ b/src/pat/formautofocus/README.md @@ -5,6 +5,9 @@ title: Formautofocus # Formautofocus pattern. +Automatically set the focus on a form input field. + + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/formunloadalert/README.md b/src/pat/formunloadalert/README.md index a1e0eb731..e10888d8e 100644 --- a/src/pat/formunloadalert/README.md +++ b/src/pat/formunloadalert/README.md @@ -5,7 +5,8 @@ title: Formunloadalert # Formunloadalert pattern. -PATTERN description +Show a warning if the user leaves an unsaved form. + ## Configuration diff --git a/src/pat/livesearch/README.md b/src/pat/livesearch/README.md index f7d743506..b7b5e2ad0 100644 --- a/src/pat/livesearch/README.md +++ b/src/pat/livesearch/README.md @@ -5,6 +5,8 @@ title: Livesearch # Livesearch pattern. +Provide Plone's live search functionality. + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/markspeciallinks/README.md b/src/pat/markspeciallinks/README.md index e39e27727..63d061202 100644 --- a/src/pat/markspeciallinks/README.md +++ b/src/pat/markspeciallinks/README.md @@ -5,6 +5,8 @@ title: MarkSpecialLinks # MarkSpecialLinks pattern. +Add a special class to links in certain conditions. + Scan all links in the container and mark external links with class if they point outside the site, or are special protocols. Also implements new window opening for external links. To disable this effect for links on a one-by-one-basis, give them a class of 'link-plain' diff --git a/src/pat/modal/README.md b/src/pat/modal/README.md index 58f7f9faf..9c03c321f 100644 --- a/src/pat/modal/README.md +++ b/src/pat/modal/README.md @@ -5,7 +5,8 @@ title: Modal # Modal -This is the modal pattern. +Show content in a modal. + ## Basic Modal diff --git a/src/pat/navigationmarker/README.md b/src/pat/navigationmarker/README.md index e2485dc81..9984fc8c5 100644 --- a/src/pat/navigationmarker/README.md +++ b/src/pat/navigationmarker/README.md @@ -5,5 +5,7 @@ title: Navigation marker # Navigation marker pattern. +Add classes to the main navigation. + This pattern adds `inPath` and `current` classes to the navigation to allow a different style on selected navigation items or navigation items which are in the current path. This is done in JavaScript, so that the navigation pattern can be cached for the whole site. diff --git a/src/pat/passwordstrength/README.md b/src/pat/passwordstrength/README.md index 065af890b..691d56b2b 100644 --- a/src/pat/passwordstrength/README.md +++ b/src/pat/passwordstrength/README.md @@ -5,6 +5,9 @@ title: Password strength # Password strength pattern. +Check the strength of a password. + + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/preventdoublesubmit/README.md b/src/pat/preventdoublesubmit/README.md index 71b37e817..e3d1b2197 100644 --- a/src/pat/preventdoublesubmit/README.md +++ b/src/pat/preventdoublesubmit/README.md @@ -5,6 +5,8 @@ title: Prevent double submit # Prevent double submit pattern. +Prevent multiple submissions of the same forn. + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/querystring/README.md b/src/pat/querystring/README.md index 5f68819d0..951260078 100644 --- a/src/pat/querystring/README.md +++ b/src/pat/querystring/README.md @@ -5,6 +5,8 @@ title: Querystring # Querystring +Show the querystring selection app. + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/recurrence/README.md b/src/pat/recurrence/README.md index 06f8119f5..c926ec4f3 100644 --- a/src/pat/recurrence/README.md +++ b/src/pat/recurrence/README.md @@ -5,6 +5,8 @@ title: Recurrence # Recurrence pattern. +Show the recurrence widget. + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/relateditems/README.md b/src/pat/relateditems/README.md index 067730024..00e8c82ef 100644 --- a/src/pat/relateditems/README.md +++ b/src/pat/relateditems/README.md @@ -5,7 +5,8 @@ title: Related items # Related items -This is the related items pattern. +Show a widget to select related items. + ## Configuration diff --git a/src/pat/select2/README.md b/src/pat/select2/README.md index d5c4ca481..ce8af38e1 100644 --- a/src/pat/select2/README.md +++ b/src/pat/select2/README.md @@ -5,7 +5,8 @@ title: Select2 # Select2 pattern. -Autoselection widget. +Show a widget which enhances dropdown selections with automatic suggestions, search and tagging functionality. + ## Configuration diff --git a/src/pat/sortable/README.md b/src/pat/sortable/README.md index 2b8e53679..fc5dba961 100644 --- a/src/pat/sortable/README.md +++ b/src/pat/sortable/README.md @@ -5,6 +5,9 @@ title: Sortable # Sortable pattern. +A pattern to make listings sortable. + + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/structure-updater/README.md b/src/pat/structure-updater/README.md index d7e988bb4..f10c5d254 100644 --- a/src/pat/structure-updater/README.md +++ b/src/pat/structure-updater/README.md @@ -5,6 +5,8 @@ title: Structure Updater # Structure updater pattern. +Update title and description based on the current folder contents location. + The Structure Updater pattern updates the information of the current context after a user navigated to a new folder. ## Configuration diff --git a/src/pat/structure/README.md b/src/pat/structure/README.md index dba8e918b..6a793349b 100644 --- a/src/pat/structure/README.md +++ b/src/pat/structure/README.md @@ -5,6 +5,9 @@ title: Structure # Structure pattern. +Plone's folder contents app. + + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/textareamimetypeselector/README.md b/src/pat/textareamimetypeselector/README.md index 0328f881e..116ab40d5 100644 --- a/src/pat/textareamimetypeselector/README.md +++ b/src/pat/textareamimetypeselector/README.md @@ -5,7 +5,10 @@ title: Textarea Mimetype Selector # Textarea Mimetype Selector pattern. -This pattern displays a mimetype selection widget for textareas. It switches the widget according to the selected mimetype. +Display the mime type selection widget for textareas. + +This pattern displays a mimetype selection widget for textareas. +It switches the widget according to the selected mimetype. ## widgets option Structure diff --git a/src/pat/texteditor/README.md b/src/pat/texteditor/README.md index 280c5e9fe..0b19de4de 100644 --- a/src/pat/texteditor/README.md +++ b/src/pat/texteditor/README.md @@ -5,6 +5,15 @@ title: Text Editor # Text Editor pattern. +Show a code editor. + +--- +**Deprecated** + +This pattern is deprecated. Use Patternslib' pat-code-editor instead. + +--- + ## Configuration | Option | Type | Default | Description | diff --git a/src/pat/tinymce/README.md b/src/pat/tinymce/README.md index 74f46297a..e3863246a 100644 --- a/src/pat/tinymce/README.md +++ b/src/pat/tinymce/README.md @@ -3,7 +3,9 @@ permalink: "pat/tinymce/" title: tinyMCE --- -# tinyMCE pattern. +# TinyMCE pattern. + +Use the TinyMCE editor for HTML editing. ## Configuration diff --git a/src/pat/toggle/README.md b/src/pat/toggle/README.md index 0215d54a3..f232d49be 100644 --- a/src/pat/toggle/README.md +++ b/src/pat/toggle/README.md @@ -5,7 +5,8 @@ title: Toggle # Toggle pattern -Toggles things. +A pattern to toggle classes on HTML elements. + ## Migration note (Plone 6) diff --git a/src/pat/toolbar/README.md b/src/pat/toolbar/README.md index 4cb568aa4..42290f5f2 100644 --- a/src/pat/toolbar/README.md +++ b/src/pat/toolbar/README.md @@ -5,6 +5,9 @@ title: Toolbar # Toolbar pattern. +Render the Plone toolbar. + + ## Example ```html diff --git a/src/pat/tree/README.md b/src/pat/tree/README.md index 89dec6738..8cae9f5f9 100644 --- a/src/pat/tree/README.md +++ b/src/pat/tree/README.md @@ -5,6 +5,8 @@ title: Tree # Tree +Renders a navigatable tree from a data structure. + Tree pattern. ## Configuration diff --git a/src/pat/upload/README.md b/src/pat/upload/README.md index 63e41237c..589ef3502 100644 --- a/src/pat/upload/README.md +++ b/src/pat/upload/README.md @@ -5,6 +5,9 @@ title: Upload # Upload pattern. +Upload files to Plone. + + ## Configuration | Option | Type | Default | Description | From f7988b261729c62a3324c899a3d042b956bf5988 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sat, 7 Oct 2023 20:26:12 +0200 Subject: [PATCH 03/10] maint(docs): Add chapter about Mockup usage. --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index fecc6d2d4..724e175fe 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,24 @@ Mockup is the JavaScript stack of the Plone Classic UI. +## Usage + +There are several options to integrate Mockup. + +- First, it comes pre-installed with Plone 6 Classic UI. +- Second, you can install and compile a bundle. See below. +- Third you can download a ZIP from Mockup's release pages on GitHub. +- Fourth, you can use a precompiled bundle from a CDN, like: + + ``` + + ``` + or: + ``` + + ``` + + ## Install - Have a current version of Node.js installed. From 7199a6407834e2cee5561bb9d774823e6bf1dd98 Mon Sep 17 00:00:00 2001 From: Peter Mathis Date: Tue, 10 Oct 2023 16:27:11 +0200 Subject: [PATCH 04/10] Apply suggestions Co-authored-by: Steve Piercy --- README.md | 76 +++++++++++----------- src/pat/preventdoublesubmit/README.md | 2 +- src/pat/select2/README.md | 2 +- src/pat/textareamimetypeselector/README.md | 6 +- src/pat/texteditor/README.md | 2 +- src/pat/tinymce/README.md | 2 +- src/pat/tree/README.md | 2 +- 7 files changed, 47 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 724e175fe..7bfcab205 100644 --- a/README.md +++ b/README.md @@ -7,18 +7,18 @@ Mockup is the JavaScript stack of the Plone Classic UI. There are several options to integrate Mockup. -- First, it comes pre-installed with Plone 6 Classic UI. -- Second, you can install and compile a bundle. See below. -- Third you can download a ZIP from Mockup's release pages on GitHub. -- Fourth, you can use a precompiled bundle from a CDN, like: +1. It comes pre-installed with Plone 6 Classic UI. +2. You can install and compile a bundle. See [insert anchor to specific section, as "below" is vague]. +3. You can download a `.zip` from [Mockup's releases page on GitHub](https://github.com/plone/mockup/releases). +4. You can use a precompiled bundle from a CDN, like: - ``` - - ``` - or: - ``` - - ``` + ```html + + ``` + or: + ```html + + ``` ## Install @@ -41,10 +41,12 @@ There are several options to integrate Mockup. ## Mockup overview -Mockup is a JavaScrip UI library which provides widgets, apps and functionality for the Plone Classic UI variant. -It is based on Patternslib(XXX) and provides it's functionality through so-called Patterns which are initialized and get active if a triggering CSS selector is found in the DOM tree. +Mockup is a JavaScript UI library which provides widgets, apps, and functionality for the Plone Classic UI frontend. +It is based on Patternslib(XXX), and provides its functionality through patterns. +Patterns are initialized and activated when a triggering CSS selector is found in the DOM tree. For example, the related items widget is initialized on a form input field with the CSS class `pat-relateditems`. -The configuration is done via data attributes, in case of the related items pattern it's an attribute called `data-pat-relateditems`. +The configuration is done via data attributes. +For the related items pattern, it's an attribute called `data-pat-relateditems`. The data strucutre of the configuration can be a JSON string or CSS declaration like key-value pairs separated by a semicolon. Defining a JSON structure is more flexible though. @@ -74,8 +76,8 @@ Here are two examples. /> ``` -Because of historic reasons the Mockup Pattern attributes are written in "camelCase" like the `vocabularyUrl`. -But in order to resemble the CSS syntax new Patterns should rather separate each word with a dash, like `vocabulary-url`. +Because of historic reasons, the Mockup pattern attributes are written in "camelCase", for example `vocabularyUrl`. +But to resemble the CSS syntax, new patterns should instead separate each word with a dash, for example `vocabulary-url`. ## Mockup Patterns @@ -86,7 +88,7 @@ But in order to resemble the CSS syntax new Patterns should rather separate each - [pat-formautofocus](src/pat/formautofocus/README.md): Automatically set the focus on a form input field. - [pat-formunloadalert](src/pat/formunloadalert/README.md): Show a warning if the user leaves an unsaved form. - [pat-livesearch](src/pat/livesearch/README.md): Provide Plone's live search functionality. -- [pat-manage-portlets](src/pat/manageportlets/README.md): Used by plone.app.portlets to manage portlets. +- [pat-manage-portlets](src/pat/manageportlets/README.md): Used by `plone.app.portlets` to manage portlets. - [pat-markspeciallinks](src/pat/markspeciallinks/README.md): Add a special class to links in certain conditions. - [pat-modal](src/pat/modal/README.md): Show content in a modal. - [pat-navigationmarker](src/pat/navigationmarker/README.md): Add classes to the main navigation. @@ -99,11 +101,11 @@ But in order to resemble the CSS syntax new Patterns should rather separate each - [pat-sortable](src/pat/sortable/README.md): A pattern to make listings sortable. - [pat-structure](src/pat/structure/README.md): Plone's folder contents app. - [pat-structureupdater](src/pat/structure-updater/README.md): Update title and description based on the current folder contents location. -- [pat-textareamimetypeselector](src/pat/textareamimetypeselector/README.md): Display the mime type selection widget for textareas. +- [pat-textareamimetypeselector](src/pat/textareamimetypeselector/README.md): Display the MIME type selection widget for textareas. - [pat-tinymce](src/pat/tinymce/README.md): Use the TinyMCE editor for HTML editing. - [pat-toggle](src/pat/toggle/README.md): A pattern to toggle classes on HTML elements. - [pat-toolbar](src/pat/toolbar/README.md): Render the Plone toolbar. -- [pat-tree](src/pat/tree/README.md): Renders a navigatable tree from a data structure. +- [pat-tree](src/pat/tree/README.md): Renders a navigable tree from a data structure. - [pat-upload](src/pat/upload/README.md): Upload files to Plone. Deprecated patterns: @@ -254,9 +256,9 @@ The ``@@plonejsi18n`` view is called one time for a given domain and language an The only way to test the new translations is to restart the instance to update the mo file from the po file, and then to purge the localStorage to trigger a new download of the translations. -### Styleguide +## Style guide -- Tab: 4 spaces for everything except for HTML and XML files (2 Spaces) and the Makefile (TAB). +- Tab: 4 spaces for everything, except for HTML and XML files which must use 2 spaces, and the Makefile which must use tabs. This rule is defined in the [.editorconfig file](./.editorconfig). ### Commit style guide @@ -274,22 +276,22 @@ We have 4 different types of changelog entries: - Bug Fixes (type: `fix`), - Maintenance (type: `maint`). -We can group commits in the changelog via a scope - or grouping. -Let's follow a convention and use these groupings - but the grouping is optional and any other group name can be used. +We can group commits in the changelog via a scope or grouping. +Let's follow a convention and use these groupings, but the grouping is optional and any other group name can be used. - "Dependencies" for upgrading package.json dependencies. - "Docs" for documentation. - "Build" for everything related to the release workflow, Webpack and building bundles. - "Cleanup" for cleaning up or reformatting code. -- "pat PATTERNNAME" for changes to individual patterns in src/pat. -- "core MODULENAME" for changes to core modules in src/core. +- "pat PATTERNNAME" for changes to individual patterns in `src/pat`. +- "core MODULENAME" for changes to core modules in `src/core`. -A commit message with a changelog-grouping must be structured like so: `TYPE(GROUP): MESSAGE`. +A commit message with a changelog grouping must be structured like so: `TYPE(GROUP): MESSAGE`. Without grouping: `TYPE: MESSAGE` -If the commit message doesn't follow this convention it won't be included in the changelog. +If the commit message doesn't follow this convention, then it won't be included in the changelog. To bypass the pre-commit hook, use the git `-n` switch. -Example: `git commit yarn.lock -m"yarn install." -n`. +Example: `git commit yarn.lock -m "yarn install." -n`. If you are working on a component like the structure pattern (pat-structure), use `pat structure` as a group. @@ -297,21 +299,21 @@ Examples: Add a feature to the structure pattern: -``` -git commit src/pat/structure -m"feat(pat structure): Add feature to cook some coffee" +```shell +git commit src/pat/structure -m "feat(pat structure): Add feature to cook some coffee" ``` Cleanup task: -``` -git commit -am"maint(Cleanup): Remove whitespace from documentation." +```shell +git commit -am "maint(Cleanup): Remove whitespace from documentation." ``` or without a grouping: -``` -git commit -am"maint: Remove unnecessary file from root directory." +```shell +git commit -am "maint: Remove unnecessary file from root directory." ``` --- @@ -320,10 +322,10 @@ git commit -am"maint: Remove unnecessary file from root directory." Please keep commits on the `yarn.lock` file or any other auto-generated code seperate. -Just commit them seperately with `git commit yarn.lock -m"yarn install" -n`. +Just commit them seperately with `git commit yarn.lock -m "yarn install" -n`. -Having them seperately reduces the effort when merging or rebasing branches where a merge conflict can easily happen. -In such cases you can just withdraw your changes on the yarn.lock file or remove those commits and re-install with `yarn install` at the end of a successful merge or rebase. +Keeping them seperate reduces the effort when merging or rebasing branches where a merge conflict can easily happen. +In such cases you can just withdraw your changes on the `yarn.lock` file, or remove those commits and reinstall with `yarn install` at the end of a successful merge or rebase. --- diff --git a/src/pat/preventdoublesubmit/README.md b/src/pat/preventdoublesubmit/README.md index e3d1b2197..607f523a5 100644 --- a/src/pat/preventdoublesubmit/README.md +++ b/src/pat/preventdoublesubmit/README.md @@ -5,7 +5,7 @@ title: Prevent double submit # Prevent double submit pattern. -Prevent multiple submissions of the same forn. +Prevent multiple submissions of the same form. ## Configuration diff --git a/src/pat/select2/README.md b/src/pat/select2/README.md index ce8af38e1..ef825eded 100644 --- a/src/pat/select2/README.md +++ b/src/pat/select2/README.md @@ -5,7 +5,7 @@ title: Select2 # Select2 pattern. -Show a widget which enhances dropdown selections with automatic suggestions, search and tagging functionality. +Show a widget which enhances dropdown selections with automatic suggestions, search, and tagging functionality. ## Configuration diff --git a/src/pat/textareamimetypeselector/README.md b/src/pat/textareamimetypeselector/README.md index 116ab40d5..680c0881d 100644 --- a/src/pat/textareamimetypeselector/README.md +++ b/src/pat/textareamimetypeselector/README.md @@ -5,10 +5,10 @@ title: Textarea Mimetype Selector # Textarea Mimetype Selector pattern. -Display the mime type selection widget for textareas. +Display the MIME type selection widget for textareas. -This pattern displays a mimetype selection widget for textareas. -It switches the widget according to the selected mimetype. +This pattern displays a MIME type selection widget for textareas. +It switches the widget according to the selected MIME type. ## widgets option Structure diff --git a/src/pat/texteditor/README.md b/src/pat/texteditor/README.md index 0b19de4de..a64eb1c9a 100644 --- a/src/pat/texteditor/README.md +++ b/src/pat/texteditor/README.md @@ -10,7 +10,7 @@ Show a code editor. --- **Deprecated** -This pattern is deprecated. Use Patternslib' pat-code-editor instead. +This pattern is deprecated. Use Patternslib's pat-code-editor instead. --- diff --git a/src/pat/tinymce/README.md b/src/pat/tinymce/README.md index e3863246a..3619acbf4 100644 --- a/src/pat/tinymce/README.md +++ b/src/pat/tinymce/README.md @@ -3,7 +3,7 @@ permalink: "pat/tinymce/" title: tinyMCE --- -# TinyMCE pattern. +# TinyMCE pattern Use the TinyMCE editor for HTML editing. diff --git a/src/pat/tree/README.md b/src/pat/tree/README.md index 8cae9f5f9..84e54961b 100644 --- a/src/pat/tree/README.md +++ b/src/pat/tree/README.md @@ -5,7 +5,7 @@ title: Tree # Tree -Renders a navigatable tree from a data structure. +Renders a navigable tree from a data structure. Tree pattern. From eb9eb2b7a6db14bb426e1518c12b84b7ced904f4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 1 Nov 2023 01:02:12 -0700 Subject: [PATCH 05/10] Better define structure of configuration --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7bfcab205..1b59e12d9 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Patterns are initialized and activated when a triggering CSS selector is found i For example, the related items widget is initialized on a form input field with the CSS class `pat-relateditems`. The configuration is done via data attributes. For the related items pattern, it's an attribute called `data-pat-relateditems`. -The data strucutre of the configuration can be a JSON string or CSS declaration like key-value pairs separated by a semicolon. +The data structure of the configuration can be a JSON string or CSS declaration as key-value pairs, with the key and value separated by a colon (`:`), and the pairs separated by a semicolon (`;`). Defining a JSON structure is more flexible though. Here are two examples. From f6505beb5a31a85ceb9cf789bb8f437c813c428e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 1 Nov 2023 01:08:58 -0700 Subject: [PATCH 06/10] Align code fences --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1b59e12d9..2f608e7fc 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ There are several options to integrate Mockup. ``` or: - ```html + ```html ``` From 7f6183011e809cefba60bdddf9308166d9819bbb Mon Sep 17 00:00:00 2001 From: Peter Mathis Date: Thu, 2 Nov 2023 09:42:34 +0100 Subject: [PATCH 07/10] fix tinymce README --- src/pat/tinymce/README.md | 34 +++++++++++++++++----------------- src/pat/tinymce/tinymce.js | 2 +- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/src/pat/tinymce/README.md b/src/pat/tinymce/README.md index 3619acbf4..9302cc2ac 100644 --- a/src/pat/tinymce/README.md +++ b/src/pat/tinymce/README.md @@ -9,23 +9,23 @@ Use the TinyMCE editor for HTML editing. ## Configuration -| Option | Type | Default | Description | -| :----------------: | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ----------- | --------------------------------------------- | ------------------------------ | ----------------------------------------------------------- | ---- | -| relatedItems | object | { attributes: ["UID", "Title", "Description", "getURL", "portal_type", "path", "ModificationDate"], batchSize: 20, basePath: "/", vocabularyUrl: null, width: 500, maximumSelectionSize: 1, placeholder: "Search for item on site..." } | Related items pattern options. | -| upload | object | { attributes: look at upload pattern for getting the options list } | Upload pattern options. | -| text | object | { insertBtn: "Insert", cancelBtn: "Cancel", insertHeading: "Insert link", title: "Title", internal: "Internal", external: "External", email: "Email", anchor: "Anchor", subject: "Subject" image: "Image", imageAlign: "Align", scale: "Size", alt: "Alternative Text", captionFromDescription: "Show Image Caption from Image Description", caption: "Image Caption", externalImage: "External Image URI"} | Translation strings | -| imageScales | string | | Image scale name/value object-array or JSON string for use in the image dialog. | -| targetList | array | [ {text: "Open in this window / frame", value: ""}, {text: "Open in new window", value: "_blank"}, {text: "Open in parent window / frame", value: "_parent"}, {text: "Open in top frame (replaces all frames)", value: "_top"}] | TODO | -| imageTypes | string | 'Image' | TODO | -| folderTypes | string | 'Folder,Plone Site' | TODO | -| tiny | object | { plugins: [ "advlist autolink lists charmap print preview anchor", "usearchreplace visualblocks code fullscreen autoresize", "insertdatetime media table contextmenu paste plonelink ploneimage" ], menubar: "edit table format tools view insert", toolbar: "undo redo | styleselect | bold italic | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | unlink plonelink ploneimage", autoresize_max_height: 1500 } | TODO | -| prependToUrl | string | "" | Text to prepend to generated internal urls. | -| appendToUrl | string | "" | Text to append to generated internal urls. | -| prependToScalePart | string | "/imagescale/" | Text to prepend to generated image scale url part. | -| appendToScalePart | string | "" | Text to append to generated image scale url part. | -| linkAttribute | string | "path" | Ajax response data attribute to use for url. | -| defaultScale | string | "Original" | Scale name to default to. | -| inline | boolean | false | Show tinyMCE editor inline instead in an iframe. Use this on textarea inputs. If you want to use this pattern directly on a contenteditable, pass "inline: true" to the "tiny" options object. | +| Option | Type | Default | Description | +| :----------------: | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| relatedItems | object | { attributes: ["UID", "Title", "Description", "getURL", "portal_type", "path", "ModificationDate"], batchSize: 20, basePath: "/", vocabularyUrl: null, width: 500, maximumSelectionSize: 1, placeholder: "Search for item on site..." } | Related items pattern options. | +| upload | object | { attributes: look at upload pattern for getting the options list } | Upload pattern options. | +| text | object | { insertBtn: "Insert", cancelBtn: "Cancel", insertHeading: "Insert link", title: "Title", internal: "Internal", external: "External", email: "Email", anchor: "Anchor", subject: "Subject" image: "Image", imageAlign: "Align", scale: "Size", alt: "Alternative Text", captionFromDescription: "Show Image Caption from Image Description", caption: "Image Caption", externalImage: "External Image URI"} | Translation strings | +| imageScales | string | | Image scale name/value object-array or JSON string for use in the image dialog. | +| targetList | array | [ {text: "Open in this window / frame", value: ""}, {text: "Open in new window", value: "_blank"}, {text: "Open in parent window / frame", value: "_parent"}, {text: "Open in top frame (replaces all frames)", value: "_top"}] | Possible targets for plonelink plugin | +| imageTypes | string | 'Image' | Selectable Image types. Used in `ploneimage` plugin. | +| folderTypes | string | 'Folder,Plone Site' | Browseable folderish types. Used for `pat-relateditems` in `ploneimage` and `plonelink` plugin. | +| tiny | object | { plugins: [ "advlist", "autolink", "lists", "charmap", "print", "preview", "anchor", "searchreplace", "visualblocks", "code", "fullscreen", "insertdatetime", "media", "table", "contextmenu", "paste", "plonelink", "ploneimage" ], menubar: "edit table format tools view insert", toolbar: "undo redo \| styles \| bold italic \| alignleft aligncenter alignright alignjustify \| bullist numlist outdent indent \| unlink plonelink ploneimage", autoresize_max_height: 1500 } | Default TinyMCE configuration options. These are set via configuration registry. | +| prependToUrl | string | "" | Text to prepend to generated internal urls. | +| appendToUrl | string | "" | Text to append to generated internal urls. | +| prependToScalePart | string | "/imagescale/" | Text to prepend to generated image scale url part. | +| appendToScalePart | string | "" | Text to append to generated image scale url part. | +| linkAttribute | string | "path" | Ajax response data attribute to use for url. | +| defaultScale | string | "Original" | Scale name to default to. | +| inline | boolean | false | Show tinyMCE editor inline instead in an iframe. Use this on textarea inputs. If you want to use this pattern directly on a contenteditable, pass "inline: true" to the "tiny" options object. | ## Examples diff --git a/src/pat/tinymce/tinymce.js b/src/pat/tinymce/tinymce.js index aeb319a48..3c391efd5 100644 --- a/src/pat/tinymce/tinymce.js +++ b/src/pat/tinymce/tinymce.js @@ -111,7 +111,7 @@ export default Base.extend({ ], menubar: "edit table format tools view insert", toolbar: - "undo redo | styleselect | bold italic | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | unlink plonelink ploneimage", + "undo redo | styles | bold italic | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | unlink plonelink ploneimage", //'autoresize_max_height': 900, height: 400, language: "en", From 5d0545da49bb5b69025af0ba035f8b67351328d1 Mon Sep 17 00:00:00 2001 From: Peter Mathis Date: Thu, 2 Nov 2023 10:02:43 +0100 Subject: [PATCH 08/10] Internal link to development section --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f608e7fc..bb749b1c7 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Mockup is the JavaScript stack of the Plone Classic UI. There are several options to integrate Mockup. 1. It comes pre-installed with Plone 6 Classic UI. -2. You can install and compile a bundle. See [insert anchor to specific section, as "below" is vague]. +2. You can install and compile a bundle. See [Development Section](#development) below. 3. You can download a `.zip` from [Mockup's releases page on GitHub](https://github.com/plone/mockup/releases). 4. You can use a precompiled bundle from a CDN, like: From 5f5e8223f98574ce7d34c5437fecf4e2729e904d Mon Sep 17 00:00:00 2001 From: Peter Mathis Date: Thu, 2 Nov 2023 10:44:49 +0100 Subject: [PATCH 09/10] Update README.md Co-authored-by: Steve Piercy --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index bb749b1c7..3d424816f 100644 --- a/README.md +++ b/README.md @@ -307,7 +307,6 @@ Cleanup task: ```shell git commit -am "maint(Cleanup): Remove whitespace from documentation." - ``` or without a grouping: From 5f5f92f5dd9168540356ee0eb92874400d23c0b5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Feb 2024 02:47:06 -0800 Subject: [PATCH 10/10] Remove unknown version from PatternsLib to avoid maintenance --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3d424816f..fe11fdc4e 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ There are several options to integrate Mockup. ## Mockup overview Mockup is a JavaScript UI library which provides widgets, apps, and functionality for the Plone Classic UI frontend. -It is based on Patternslib(XXX), and provides its functionality through patterns. +It is based on Patternslib, and provides its functionality through patterns. Patterns are initialized and activated when a triggering CSS selector is found in the DOM tree. For example, the related items widget is initialized on a form input field with the CSS class `pat-relateditems`. The configuration is done via data attributes.