From 3eaae7b6f18dfdad035b65aa1f8e2b9596ed51a2 Mon Sep 17 00:00:00 2001 From: Peter Mathis Date: Wed, 30 Oct 2024 12:04:32 +0100 Subject: [PATCH 1/5] Explain how to create a custom pattern --- docs/classic-ui/mockup.md | 78 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/docs/classic-ui/mockup.md b/docs/classic-ui/mockup.md index a68167cd3..a3bc5e873 100644 --- a/docs/classic-ui/mockup.md +++ b/docs/classic-ui/mockup.md @@ -30,7 +30,7 @@ pip install plonecli --user Create an add-on package with `plonecli`. ```shell -plonecli add project.addon +plonecli create addon project.addon ``` This will create a package `project.addon`, which you can install in your Plone site. @@ -52,6 +52,82 @@ You can check the full list of available features using the `-l` parameter: plonecli -l ``` +## Create a custom pattern + +To create a custom pattern in your addon use the `mockup_pattern` bobtemplate: + +```shell +cd project.addon +plonecli add mockup_pattern +``` + +Now enter your pattern name without *pat-* prefix: + +```shell +--> Pattern name (without “pat-” prefix) [my-pattern]: testpattern +``` + +This creates the necessary JS resources and webpack configuration for you: + +```text +... +├── resources +| ├── pat-testpattern +| | ├── documentation.md +| | ├── testpattern.js +| | ├── testpattern.scss +| | ├── testpattern.test.js +│ ├── bundle.js +│ ├── index.html +│ ├── index.js +├── package.json +├── webpack.config.js +... +``` + +All your pattern JS code goes into `resources/pat-testpattern/testpattern.js`. +SCSS files can be imported too since webpack provides the `sass-loader` module. + +Next step is to install the npm packages (yarn recommended): + +```shell +yarn install +``` + +When you have finished your JS code you have to build the bundle with: + +```shell +yarn build +``` + +This creates the webpack chunks and the JS bundle files in your addon package: + +```text +... +├── src +| ├── project +| | ├── addon +| | | ├── browser +| | | | ├── static +| | | | | ├── bundles +| | | | | | ├── chunks +| | | | | | ├── addon-remote.min.js +| | | | | | ├── addon-remote.min.js.map +| | | | | | ├── addon.min.js +| | | | | | ├── addon.min.js.map +``` + +Note that `plonecli` also creates a XML file in `src/project/addon/profiles/default/registry/bundles.xml` +which registers the `addon-remote.min.js` in the resources registry. + +```{important} +You have to re-import your profile with an upgrade step if you have installed +your addon in Plone before adding the pattern. +``` + +You can test your pattern now with the browser view `@@addon-pattern-demo` (see /src/project/addon/browser/pattern-demo.pt) +or implement it in your own templates by adding the CSS class `pat-testpattern` to a tag. + ## References From 5805380e4408b765ef9805a6f6e4fd4d99458528 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 4 Nov 2024 03:43:12 -0800 Subject: [PATCH 2/5] Tidy up mockup.md. - Add more glossary terms and references. --- docs/classic-ui/mockup.md | 26 ++++++++++++-------------- docs/glossary.md | 11 +++++++++++ 2 files changed, 23 insertions(+), 14 deletions(-) diff --git a/docs/classic-ui/mockup.md b/docs/classic-ui/mockup.md index a3bc5e873..809a1979c 100644 --- a/docs/classic-ui/mockup.md +++ b/docs/classic-ui/mockup.md @@ -54,20 +54,20 @@ plonecli -l ## Create a custom pattern -To create a custom pattern in your addon use the `mockup_pattern` bobtemplate: +To create a custom {term}`pattern` in your add-on, use the `mockup_pattern` {term}`bobtemplate`: ```shell cd project.addon plonecli add mockup_pattern ``` -Now enter your pattern name without *pat-* prefix: +Next, enter your pattern name without the `pat-` prefix. ```shell --> Pattern name (without “pat-” prefix) [my-pattern]: testpattern ``` -This creates the necessary JS resources and webpack configuration for you: +This creates the necessary JavaScript resources and webpack configuration for you, as shown in the following file system tree diagram. ```text ... @@ -85,22 +85,22 @@ This creates the necessary JS resources and webpack configuration for you: ... ``` -All your pattern JS code goes into `resources/pat-testpattern/testpattern.js`. -SCSS files can be imported too since webpack provides the `sass-loader` module. +All your pattern JavaScript code goes into {file}`resources/pat-testpattern/testpattern.js`. +SCSS files can be imported, too, since webpack provides the `sass-loader` module. -Next step is to install the npm packages (yarn recommended): +Next, install the npm packages using {term}`yarn`. ```shell yarn install ``` -When you have finished your JS code you have to build the bundle with: +When you finish writing your JavaScript code, you have to build the bundle with the following command. ```shell yarn build ``` -This creates the webpack chunks and the JS bundle files in your addon package: +This creates the webpack chunks and the JavaScript bundle files in your add-on package. ```text ... @@ -117,16 +117,14 @@ This creates the webpack chunks and the JS bundle files in your addon package: | | | | | | ├── addon.min.js.map ``` -Note that `plonecli` also creates a XML file in `src/project/addon/profiles/default/registry/bundles.xml` -which registers the `addon-remote.min.js` in the resources registry. +Note that `plonecli` also creates an XML file in {file}`src/project/addon/profiles/default/registry/bundles.xml`, which registers the {file}`addon-remote.min.js` file in the resource registry. ```{important} -You have to re-import your profile with an upgrade step if you have installed -your addon in Plone before adding the pattern. +You must re-import your profile with an upgrade step if you installed your add-on in Plone before adding the pattern. ``` -You can test your pattern now with the browser view `@@addon-pattern-demo` (see /src/project/addon/browser/pattern-demo.pt) -or implement it in your own templates by adding the CSS class `pat-testpattern` to a tag. +You can test your pattern now with the browser view `@@addon-pattern-demo` (see {file}`/src/project/addon/browser/pattern-demo.pt`) +Alternatively you can implement it in your own templates by adding the CSS class `pat-testpattern` to a tag. ## References diff --git a/docs/glossary.md b/docs/glossary.md index 412e3eccb..1639e1339 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -437,6 +437,17 @@ Mockup Mockup provides the JavaScript stack for Classic UI. [View Mockup's patterns](https://plone.github.io/mockup/), based on Patternslib. +bobtemplate +bobtemplates +bobtemplates.plone + `bobtemplates.plone` provides {term}`mr.bob` templates to generate packages for Plone projects. + The {term}`plonecli` command line client provides a developer-friendly interface to `bobtemplates.plone`. + +mr.bob + [`mr.bob`](https://mrbob.readthedocs.io/en/latest/) is a tool that takes a directory skeleton, copies over its directory structure to a target folder, and can use the Jinja2 (or some other) templating engine to dynamically generate the files. + Additionally, it can ask you questions needed to render the structure, or provide a configuration file to answer them. + +Pattern Patterns Patternslib [Patterns](https://patternslib.com/), or Patternslib, is a toolkit that enables designers to build rich interactive prototypes without the need for writing any JavaScript. From 2e0e275897d4f6e6881c2d6c13ce721322be33b4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 4 Nov 2024 04:13:21 -0800 Subject: [PATCH 3/5] Provide clarification of HTML tag --- docs/classic-ui/mockup.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/classic-ui/mockup.md b/docs/classic-ui/mockup.md index 809a1979c..5f2f5fde9 100644 --- a/docs/classic-ui/mockup.md +++ b/docs/classic-ui/mockup.md @@ -61,7 +61,8 @@ cd project.addon plonecli add mockup_pattern ``` -Next, enter your pattern name without the `pat-` prefix. +Next, enter your pattern name without the `pat-` prefix +In the following example, its name is `testpattern`. ```shell --> Pattern name (without “pat-” prefix) [my-pattern]: testpattern @@ -124,7 +125,11 @@ You must re-import your profile with an upgrade step if you installed your add-o ``` You can test your pattern now with the browser view `@@addon-pattern-demo` (see {file}`/src/project/addon/browser/pattern-demo.pt`) -Alternatively you can implement it in your own templates by adding the CSS class `pat-testpattern` to a tag. +Alternatively you can implement it in your own templates by adding the CSS class `pat-testpattern` to an HTML tag, such as an `img` tag. + +```html + +``` ## References From b25cf80328a3fbcc911d702a7d2195a4a2858456 Mon Sep 17 00:00:00 2001 From: Peter Mathis Date: Mon, 4 Nov 2024 13:44:40 +0100 Subject: [PATCH 4/5] update info for pattern demo browser view --- docs/classic-ui/mockup.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/classic-ui/mockup.md b/docs/classic-ui/mockup.md index 5f2f5fde9..bf10081c7 100644 --- a/docs/classic-ui/mockup.md +++ b/docs/classic-ui/mockup.md @@ -101,7 +101,7 @@ When you finish writing your JavaScript code, you have to build the bundle with yarn build ``` -This creates the webpack chunks and the JavaScript bundle files in your add-on package. +This creates the webpack chunks, the JS bundle files, a demo browser view in your addon package: ```text ... @@ -116,15 +116,16 @@ This creates the webpack chunks and the JavaScript bundle files in your add-on p | | | | | | ├── addon-remote.min.js.map | | | | | | ├── addon.min.js | | | | | | ├── addon.min.js.map +| | | | ├── pattern-demo.pt ``` -Note that `plonecli` also creates an XML file in {file}`src/project/addon/profiles/default/registry/bundles.xml`, which registers the {file}`addon-remote.min.js` file in the resource registry. +There is also a XML file in `src/project/addon/profiles/default/registry/bundles.xml` which registers the `addon-remote.min.js` in the resources registry. ```{important} -You must re-import your profile with an upgrade step if you installed your add-on in Plone before adding the pattern. +You must re-import your profile with an upgrade step if you installed your add-on in Plone before adding the pattern by uninstall/install the addon in the controlpanel or writing a genericsetup upgrade step. ``` -You can test your pattern now with the browser view `@@addon-pattern-demo` (see {file}`/src/project/addon/browser/pattern-demo.pt`) +You can access the demo browser view in your browser with `http://localhost:8080/Plone/@@addon-pattern-demo` Alternatively you can implement it in your own templates by adding the CSS class `pat-testpattern` to an HTML tag, such as an `img` tag. ```html From 04da3ee98aaf223db9ebe3c7b3f4482cb5bee148 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 5 Nov 2024 02:38:17 -0800 Subject: [PATCH 5/5] Apply suggestions from code review --- docs/classic-ui/mockup.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/classic-ui/mockup.md b/docs/classic-ui/mockup.md index bf10081c7..1ec463f1a 100644 --- a/docs/classic-ui/mockup.md +++ b/docs/classic-ui/mockup.md @@ -54,7 +54,7 @@ plonecli -l ## Create a custom pattern -To create a custom {term}`pattern` in your add-on, use the `mockup_pattern` {term}`bobtemplate`: +To create a custom {term}`pattern` in your add-on, use the `mockup_pattern` {term}`bobtemplate`. ```shell cd project.addon @@ -101,7 +101,7 @@ When you finish writing your JavaScript code, you have to build the bundle with yarn build ``` -This creates the webpack chunks, the JS bundle files, a demo browser view in your addon package: +This creates the webpack chunks, the JavaScript bundle files, and a demo browser view in your add-on package. ```text ... @@ -119,13 +119,15 @@ This creates the webpack chunks, the JS bundle files, a demo browser view in you | | | | ├── pattern-demo.pt ``` -There is also a XML file in `src/project/addon/profiles/default/registry/bundles.xml` which registers the `addon-remote.min.js` in the resources registry. +There is also an XML file in {file}`src/project/addon/profiles/default/registry/bundles.xml` which registers the {file}`addon-remote.min.js` in the resources registry. ```{important} -You must re-import your profile with an upgrade step if you installed your add-on in Plone before adding the pattern by uninstall/install the addon in the controlpanel or writing a genericsetup upgrade step. +You must re-import your profile with an upgrade step if you installed your add-on in Plone before adding the pattern. +Uninstall, then re-install, the add-on in the control panel. +Alternatively you can write a GenericSetup upgrade step. ``` -You can access the demo browser view in your browser with `http://localhost:8080/Plone/@@addon-pattern-demo` +You can access the demo browser view in your browser with `http://localhost:8080/Plone/@@addon-pattern-demo`. Alternatively you can implement it in your own templates by adding the CSS class `pat-testpattern` to an HTML tag, such as an `img` tag. ```html