Uploaded image for project: 'Confluence Data Center'
  1. Confluence Data Center
  2. CONFSERVER-7409

Allow plugins to include Javascript and CSS resources in the HTML header

    • We collect Confluence feedback from various sources, and we evaluate what we've collected when planning our product roadmap. To understand how this piece of feedback will be reviewed, see our Implementation of New Features Policy.

      Plugins often want to include Javascript or CSS resources such as Prototype, which need to be included just once in a page. Putting them inline doesn't work for some resources, so we need a way of letting plugins specify what resources should be put in the HTML header.

      They should be able to declare a resource in their atlassian-plugin.xml, then use a simple Velocity macro to have it appear in the HTML header as a script or link tag.

            [CONFSERVER-7409] Allow plugins to include Javascript and CSS resources in the HTML header

            This is done and the documentation has been finalised for 2.8.

            Prototype and Scriptaculous are somewhat deprecated in Confluence now, even though they're unlikely to be removed for a while. The best JS library to use for new plugins is JQuery, which we're standardising on for Confluence front-end code. Thus, we won't be improving access to these libraries.

            Plugin developers should not use YUI, and this has been removed from the documentation. YUI will be removed from Confluence in 2.9.

            The documentation also covers how to add web resources to your plugin so you can include custom resources. This should be used for your plugin's custom JavaScript and CSS, to separate it from your HTML.

            There are two limitations with the current work:

            • styles requested by macros will not be included in notifications or exports
            • styles requested by macros will not be used in the editor preview.

            We hope to address these shortcomings in Confluence 2.9. The relevant issue is CONF-11540.

            Matt Ryall added a comment - This is done and the documentation has been finalised for 2.8. Prototype and Scriptaculous are somewhat deprecated in Confluence now, even though they're unlikely to be removed for a while. The best JS library to use for new plugins is JQuery, which we're standardising on for Confluence front-end code. Thus, we won't be improving access to these libraries. Plugin developers should not use YUI, and this has been removed from the documentation. YUI will be removed from Confluence in 2.9. The documentation also covers how to add web resources to your plugin so you can include custom resources. This should be used for your plugin's custom JavaScript and CSS, to separate it from your HTML. There are two limitations with the current work: styles requested by macros will not be included in notifications or exports styles requested by macros will not be used in the editor preview. We hope to address these shortcomings in Confluence 2.9. The relevant issue is CONF-11540 .

            Matt Ryall added a comment -

            Okay, thanks. I'll have a look into it.

            Matt Ryall added a comment - Okay, thanks. I'll have a look into it.

            Excellent. Glad we're on the same page.

            On the issue of Prototype/Scriptaculous = Prototype is just the one file, but Scriptaculous has at least five optional files that you can include/exclude. See docs here:

            http://wiki.script.aculo.us/scriptaculous/show/Usage

            Including the whole package by default ends up with a lot of wasted bytes.

            Jonathan Nolen (Inactive) added a comment - Excellent. Glad we're on the same page. On the issue of Prototype/Scriptaculous = Prototype is just the one file, but Scriptaculous has at least five optional files that you can include/exclude. See docs here: http://wiki.script.aculo.us/scriptaculous/show/Usage Including the whole package by default ends up with a lot of wasted bytes.

            Yep, we'll be expanding that list before 2.8 gets released.

            It won't be possible for plugin authors to explicitly exclude anything, given other content on the page might request it. It's an inclusive mechanism only.

            Some of the libraries like scriptaculous and prototype don't make sense to break down further. If broken down, each template would then require more includes (making them more fragile for changes), and since all the files will be cached by our static caching layer, there's not that much benefit to the removal of these small scripts. Having them in one 'web-resource' also means we can ensure the prerequisites are included in the right order (for instance, prototype.js needs to come before domready.js).

            The large libraries, however, will be broken down as you suggest. For example, the current YUI one is just "YUI core", which includes the events and DOM manipulation stuff. The YUI controls like menus and tree views will be in their own web resource.

            Matt Ryall added a comment - Yep, we'll be expanding that list before 2.8 gets released. It won't be possible for plugin authors to explicitly exclude anything, given other content on the page might request it. It's an inclusive mechanism only. Some of the libraries like scriptaculous and prototype don't make sense to break down further. If broken down, each template would then require more includes (making them more fragile for changes), and since all the files will be cached by our static caching layer, there's not that much benefit to the removal of these small scripts. Having them in one 'web-resource' also means we can ensure the prerequisites are included in the right order (for instance, prototype.js needs to come before domready.js). The large libraries, however, will be broken down as you suggest. For example, the current YUI one is just "YUI core", which includes the events and DOM manipulation stuff. The YUI controls like menus and tree views will be in their own web resource.

            Great start, Matt. However, the Javascript Libraries provided by Confluence section doesn't go quite far enough. It's important to allow plugin developers to include or exclude each individual file from of the javascript libraries we support.

            For example, when I was building the JIRA labels plugin, we were using bits of scriptaculous and prototype. So I tried to use the ones included with JIRA, but saying "include scriptaculous" ended up giving just the subset of files that JIRA had needed when they set up scriptaculous (just the autocomplete stuff, as I recall). So it was missing files that should have been part of the distribution, and including ones that I didn't need.

            We need to give plugin devs full granularity, so they don't end up a) including all files in their plugin and killing performance, or b) bundling their own JS libraries b/c ours don't do what they want.

            Jonathan Nolen (Inactive) added a comment - Great start, Matt. However, the Javascript Libraries provided by Confluence section doesn't go quite far enough. It's important to allow plugin developers to include or exclude each individual file from of the javascript libraries we support. For example, when I was building the JIRA labels plugin, we were using bits of scriptaculous and prototype. So I tried to use the ones included with JIRA, but saying "include scriptaculous" ended up giving just the subset of files that JIRA had needed when they set up scriptaculous (just the autocomplete stuff, as I recall). So it was missing files that should have been part of the distribution, and including ones that I didn't need. We need to give plugin devs full granularity, so they don't end up a) including all files in their plugin and killing performance, or b) bundling their own JS libraries b/c ours don't do what they want.

            Matt Ryall added a comment -

            Draft documentation after the initial implementation:

            http://confluence.atlassian.com/display/DOC/Including+Javascript+and+CSS+resources

            Comments welcome.

            Matt Ryall added a comment - Draft documentation after the initial implementation: http://confluence.atlassian.com/display/DOC/Including+Javascript+and+CSS+resources Comments welcome.

            Matt Ryall added a comment -

            I agree totally, Jonathan. This feature would help with the internals of Confluence a lot.

            Currently there's not a good way for the low-level Velocity templates to register dependencies on a particular JS library or stylesheet so that it gets included by a higher-level template (our 'decorators'). Using the same method for internal code and plugins seems the obvious solution.

            Matt Ryall added a comment - I agree totally, Jonathan. This feature would help with the internals of Confluence a lot. Currently there's not a good way for the low-level Velocity templates to register dependencies on a particular JS library or stylesheet so that it gets included by a higher-level template (our 'decorators'). Using the same method for internal code and plugins seems the obvious solution.

            It is also important that recognize overlap, so that we load a library like prototype once and only once.

            Which means, I would imagine, that our own libraries will need to be included as plugins to make this really work.

            Jonathan Nolen (Inactive) added a comment - It is also important that recognize overlap, so that we load a library like prototype once and only once. Which means, I would imagine, that our own libraries will need to be included as plugins to make this really work.

              matt@atlassian.com Matt Ryall
              matt@atlassian.com Matt Ryall
              Votes:
              4 Vote for this issue
              Watchers:
              4 Start watching this issue

                Created:
                Updated:
                Resolved: