Hi,
On Sun, Aug 2, 2015 at 12:08 AM, [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() {
> …
> }
>
What I don`t fully understand when using some javascript code that is
presented this way is if the caller would have to use 2 nested require()
calls, like:
require(["$!services.webjars.url('org.xwiki.platform:xwiki-platform-tree-webjar',
'require-config.min.js', {'evaluate': true})"], function() {
// At this point, require-config.min.js is executed and I can now use the
short versions that consider the minify parameter.
require(['tree',
"$services.webjars.url('some.other:module-I-may-need-that-is-not-configured',
'file')"], function(tree) {
// Finally, I can use the js code available in the tree variable.
tree.profit();
});
}
I`m not sure what exactly we get by doing this and if it`s worth the effort.
Thanks,
Eduard
>
> 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
>
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
