[xwiki-devs] [Proposal] Canonical Javascript/CSS code organization

Hi devs, I’d like to propose the following official future organization for our javascript/CSS code. Note1: When I say “javascript” below, it should be understood as js + css (possibly less too). Note2: I started writing this email and then I realized Marius had already implemented it for 2 Extensions/Modules: the Platform Tree and the Platform Job modules. I was happy to discover this since it validated the idea I had ;) Maybe Marius has already sent an email to propose all this, in which cas I apologize for the duplication! So here’s the idea: * We should locate Java, REST and Javascript APIs in the Extension they relate to. For example the Model Module should hold the current Reference API but also the Javascript API to create, resolve and serialize references (i.e. what’s currently in entityReference.js). * Thus when an Extension adds or modify its Java API, it should keep in sync the other APIs too. And these APIs should be made available to the XWiki runtime only when those Extensions are loaded into the runtime. * The Javascript APIs should be packaged as webjar resources inside the JAR for the Extension (i.e. located in META-INF/resources/webjars/* in the JAR). Note: An Extension could deliver a singe JAR or several if we wish to separate the Java API from the Javascript API for example (this is what we currently have for the Platform Job and Platform Tree Webjars for ex). * The Javascript APIs should be declared using requirejs, using a define(), as in: define(['jquery', 'JobRunner', 'jsTree', 'tree-finder'], function($, JobRunner) { … } Note: In order to pass simple names to the define() and handle conditional minification, Marius has created a require-config.js in the tree webjar’s module: /*! #set ($minified = '.min') #if ($request.minify == 'false')   #set ($minified = '') #end */ require.config({   paths: {     jsTree: "$!services.webjars.url('jstree', 'jstree.min')",     JobRunner: '$!services.webjars.url("org.xwiki.platform:xwiki-platform-job-webjar", "jobRunner${minified}")',     'tree-finder': '$!services.webjars.url("org.xwiki.platform:xwiki-platform-tree-webjar", "finder${minified}")',     tree: '$!services.webjars.url("org.xwiki.platform:xwiki-platform-tree-webjar", "tree${minified}")'   },   shim: {     jsTree: {       deps: ['jquery']     }   } }); * The Javascript APIs should be accessed using requirejs, using a require(), as in: require(["$!services.webjars.url('org.xwiki.platform:xwiki-platform-tree-webjar', 'require-config.min.js', {'evaluate': true})"], function() { … } Note: We’ll need to better handle the minification part in this example so that it’s optional and can be controlled by minify=true|false in the query string, but that’s easy to do. * Unit tests should be provided using Jasmine inside the Extension * The requireJS deps should be kept in sync with the Maven deps. WDYT? If we agree about this then I’m proposing that we document it in the DevGuide at http://platform.xwiki.org/xwiki/bin/view/DevGuide/FrontendResources (which will need to be rewritten as it’s currently aging). The next step would be to find a way to move all our JS code under requirejs. I’ve been researching this but I’m far from being able to propose a solution at this time. I’ll need to brainstorm with our JS experts ;) Thanks -Vincent