On Sat, Aug 1, 2015 at 11:08 PM, [email protected] <[email protected]> wrote: > 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
"should be provided inside the Extension" (using Jasmine is a detail) > * The requireJS deps should be kept in sync with the Maven deps. > > WDYT? I agree this looks better from runtime/extension point of view. However it will make working on these resources a lot more painful (right now you modify it and just refresh). > > 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 > > > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs -- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
