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
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
