Mockup is the JavaScript stack of the Plone Classic UI.
There are several options to integrate Mockup.
.zip from Mockup's releases page on GitHub.You can use a precompiled bundle from a CDN, like:
<script src="https://unpkg.com/@plone/mockup@latest/dist/bundle.min.js"></script>or:
<script src="https://cdn.jsdelivr.net/npm/@plone/mockup@latest/dist/bundle.min.js"></script>Have a current version of Node.js installed.
To install, run: make install.
To run the demo server, do: make serve.
This starts up the webpack build process in watch mode.
Any JavaScript changes are immediately compiled.
For some changes - like for adding new packages via yarn add and then using it you might need to restart.
The command also spins up a development server for our 11ty based documentation and demo pages.
If you don't need the docs running, you can run yarn start:webpack or npm run start:webpack instead, so that only the webpack devserver is running.
Go to http://localhost:8000:
On this port our demo and documentation pages are served.
Mockup is a JavaScript UI library which provides widgets, apps, and functionality for the Plone Classic UI frontend.
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.
For the related items pattern, it's an attribute called data-pat-relateditems.
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.
pat-relateditems configuration as JSON structure:
<input
type="text"
class="pat-relateditems"
data-pat-relateditems='{
"selectableTypes": ["Document"],
"vocabularyUrl": "relateditems-test.json"
}'
/>pat-relateditems configuration as CSS declarations:
<input
type="text"
class="pat-relateditems"
data-pat-relateditems="
selectableTypes: Document;
vocabularyUrl: relateditems-test.json;
"
/>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.
plone.app.portlets to manage portlets.Deprecated patterns:
pat-contentbrowser instead)You can directly develop with the 11ty based documentation / demo server by running make serve.
If you want to develop in Plone, you have two options:
1) Run make watch-plone. You need buildout to have plone.staticresources checked out next to Mockup.
Mockup will compile it's bundle directly into the ++plone++static directory of plone.staticresources and update it when you change something in Mockup.
2) Run npx yarn start:webpack, go to the resource registry ( http://localhost:8080/Plone/@@resourceregistry-controlpanel ) and add the URL http://localhost:8000/bundle.min.js to the JavaScript input field of the plone bundle instead of the other URL ++plone++static/bundle-plone/bundle.min.js.
For more commands inspect Makefile and the script part of the package.json.
Run make check to run all tests including eslint checks.
To run individual tests, run:
jest: Run all testsjest src/pat/PATH-TO-PATTERN: Run a specific test suitejest 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.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.
Still, you can connect to the Chrome debugging interface via:
node --inspect-brk node_modules/.bin/jest --runInBand ./src/pat/PATH-TO-PATTERN``Connect in chrome via (You need to click "continue" or "Resume script execution" in the inspector once to proceed):
chrome://inspectYou can pass Jest any parameter it accepts, like -t TESTPATTERN::
node --inspect-brk node_modules/.bin/jest --runInBand ./src/pat/PATH-TO-PATTERN -t test.nameYou can put some debugger; statements to the code to break the execution and investigate.
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.
Check out the external package you want to develop on.
Make sure you have installed the dependencies in the development package (e.g. by running yarn install). (TODO: verify that!)
Run yarn link in the external development package to register it with yarn.
Run yarn link "PACKAGE-NAME" in mockup to create the node_modules symlink.
After developing you might want to run yarn unlink "PACKAGE-NAME" to unlink the development package.
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.
https://survivejs.com/webpack/optimizing/build-analysis/ https://formidable.com/blog/2018/finding-webpack-duplicates-with-inspectpack-plugin/
Build the stats.json file:
npx yarn build:statsCheck dependency tree and why which package was included: https://www.npmjs.com/package/whybundled
npx whybundled stats.jsonVisualize dependency tree and analyze bundle size: https://www.npmjs.com/package/webpack-bundle-analyzer
npx webpack-bundle-analyzer stats.jsonTo update the translation file, the following needs to be done:
npx yarn run i18nOr just npm run i18n...
Assuming you are doing this from a buildout.coredev environment in the mockup folder:
cp widgets.pot ../plone.app.locales/plone/app/locales/locales/cd ../plone.app.locales/plone/app/locales/locales
i18ndude sync --pot widgets.pot */LC_MESSAGES/widgets.poTo test a translation, for example French:
Edit the po file src/plone.app.locales/plone/app/locales/locales/fr/LC_MESSAGES/widgets.po.
Restart your instance to rebuild the mo file from the po file.
Purge your localStorage and refresh the page to trigger a new download of the translations.
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.
We automatically generate the changelog from the commit messages following the Conventional Commits specification. Changelog generation is done by the conventional changelog plugin for release-it. This is enforced via a pre-commit hook managed by husky.
And this is how you use it:
We have 4 different types of changelog entries:
breaking),feat),fix),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.
src/pat.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, 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.
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.
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.