Examples wanted: plone 5 addons registering js and css resources (as a bundle for the addon)

Hi all

I'm porting a few modules to plone 5.

The plone 5 resource registry and bundles history is still a mystery to me.
Code is better than words, so can you recommend plone 5 addons registering js and css?

/sune

1 Like

This is truly covered in depth with examples in the developer docs.

My experience with the documentation of the plone 5 js story is really bad. Broken links to old blog posts no longer existing, etc. etc.

You are not the only one

I have something 'simple' that maybe could help:
I think the important things are here:

And the css and js files are here

PS: I have never used the add-on myself, it was made as a favour to someone… ( Pop up images in Plone 5? - #48 by espenmn )

It would be helpful if people can open issues on GitHub and point out what is broken, by doing so the community may able to improve/fix the docs.

@svx link to issue tracker?

@sunew https://github.com/plone/documentation/issues

Thanks !

Code is better than words ? when dealing with complicated things, some background is not always unnecessary. These last days I have learned a few things about the resource registry dealing with an existing add-on:

The resource registry has no independent existence really. It is only a particular representation of the general Plone registry. You can see all there is of the resource registry by exporting the Plone registry. The concerned records in the Plone registry are:

  • resource records
  • bundle records
    The resource registry control panel is an interface to manage these Plone registry records and to do the corresponding actions in Plone of course.
    A bundle represents a set of Javascript and Css files. When you click on a bundle in the resource registry manager, it displays to the right the corresponding resources. If the bundle is managed by requirejs (checkbox), you will not get a 'build' button with your bundle and normally you don't include resources, only the main loader (I am hazy about requirejs stuff).
    The 'delete' button is destroying the bundle in the registry. If you want some fun, click delete on the resourceregistry bundle. Since the resourceregistry is a javascript module, you will lose the resource registry manager (you can get it back if you have made an export of the Plone registry, keep the resource registry records and import them back all will be well but don't try this in production it is stressing, the Plone message about deleting your customization should probably say 'your bundles' because you should never delete a Plone bundle even if rebuilding it has not been a success)
    What the 'build' button does:
  • it is calling Plone to get the dependencies informations
  • then it is using requireJS in the browser to build the minified files (the javascript that are doing this is
    Products/CMFPlone/static/components/r.js/build/jslib/build.js
  • it upload them back to Plone for saving them in the Zodb (under portal_registry/resource_overrides, there are 2 subdirectories production and static for reasons that are still mysterious for me)
    AFAIK when there are no entries in the ZODB portal_registry/resource_overrides directories, the resources are loaded from the file system (CMFPlone/static). For example the resourceregistry.js is loaded directly. The plone.js and plone-logged-in.js are loaded from the ZODB.
    The save button can do many things, including rebuilding stuff. It is not only saving the development mode checkbox state. It can cook the plone-legacy bundle as explained in the linked thread.

This said, where could go your bundle ? I have currently no idea. I know where 'classic' resources go (see my linked post about plone-legacy), but I am unsure about a new bundle, because I have never actually tried to create one. My guess is if it's based on requirejs the minified and built and bundled files would go under static subdirectory (in the ZODB, never under the file system) but that will for you to find I'm afraid.
How will you build your stuff if you are using requirejs ? My guess is that you will not use the browser build but rather directly Npm, node, grunt and all the zoo. I'm unclear about all this stuff. The Plone script compile_resources.py is doing all that for Plone resources an could possibly be interesting (you have to install it with buildout) but I had an issue with it, it was not getting results comparable with the browser build (see linked thread).

Hope all these words can be of some help to you; maybe all this is explained better somewhere but I did not notice it so I had to find all of this it the hard way (with a debugger)

Really,

https://docs.plone.org/adapt-and-extend/theming/resourceregistry.html

is fairly complete.

Anyway... I consider the resource registries in Plone 5 as broken-by-design but they work as documented.

Personally I never use them. Meanwhile I moved most of my add-ons which are supposed to work with Plone 4 and Plone 5 away from any kind of resources registry (in Plone 4 and 5). Usually I include CSS and JS directly within the view template where I need a specific JS functionality....

and the same code works for Plone 4 and Plone 5...this approach is the only safe, reliable and hassle free solution for custom JS modules within Plone nowadays.

-aj

2 Likes

@zopyx
Thank you - its very helpful.
I was using the documention for developing addons - https://docs.plone.org/develop/addons/javascript/intro.html

I have submitted a documentation PR for the broken links.

@espenmn thank you - exactly what I need to see. Most of the time working real life examples are the best.

@gp54321 " when dealing with complicated things, some background is not always unnecessary" - I agree, usually I do appreciate "words" also :slight_smile: But when fighting to make things work, a full, complete, example (other released addons used in real life) of what other people have made working is the best. So thank you all for that:)

I will update when I succeed.

what stumped me for a while was a quite simple concept, but wasn't made clear in the docs:

A bundle's jscompliation or css compliation file like ++plone++magneticpopup/magnetic-popup.css is not (necessarily) a file that exists in /your/static/file_compiled.css. It doesn't (normally) get checked in to source control. It's really only a URL to your minified and cached resource.

The example @espenmn gives is from a product that delivers a pre-compiled css. This is why the
<value key="compile">False</value>

However, the files mentioned in a IResourceRegistry entry are files that do exist and are checked in to source control. They contain lots of whitespace and comments and maybe are even a bunch of separate files. Those are the ones you edit.

My stuff now looks like:

<records prefix="plone.resources/rfa_add"
         interface='Products.CMFPlone.interfaces.IResourceRegistry'>
    <value key='js'> ++plone++rfa-resources/base.js</value>
    <value key="css">
      <element>++plone++rfa-resources/base.css</element>
      <element>++plone++rfa-resources/rfa_modules.css</element>
      <element>++plone++rfa-resources/rfa.css</element>
    </value>
</records>

<records prefix="plone.bundles/rfa_added"
         interface='Products.CMFPlone.interfaces.IBundleRegistry'>
    <value key="resources" purge="false">
      <element>rfa_add</element>
    </value>
    <value key="jscompilation">++plone++rfa-resources/rfa_bundle.js</value>
    <value key="csscompilation">++plone++rfa-resources/rfa_bundle.css</value>
    <value key="enabled">True</value>
    <value key="compile">True</value>
    <value key="depends"></value>
    <value key="last_compilation"></value>
    <value key="merge_with">default</value>
</records>

The three css resources are made part of a bundle, and then I use <value key="compile">True</value> so I get the 'build' button in the Resource Registries control panel.

the rfa_bundle.css file doesn't live on my filesystem.

But, If I wanted to package up my product and distribute it, I would indeed put rfa_bundle.css on my filesystem and change compile to false in the bundle. If I'm really mean I don't distribute the resources so you have to decrypt my minified files.

Now, I'm not so sure this is how it was meant to work, but it seems to fit the way the Resource Registries control panel UI works.

I think the docs for resource registries would be better if we laid them out like a user story starting with "I want css" through "I want minified css" and on to "I want to create a plone add-on". I also preferred when CSS and JS registries were separated. I don't like how they were coincidentally grouped together because they follow similar development and linking workflows.