Warning: this is a proposal, and references code not yet pushed in the main repository. Current scripts and tools can be found on the statistics GSoC branch, the following are links to provisional refactored code in melange.js and melange.graph.js
With more Javascript code being written and deployed, global namespace pollution is going to be a risk. So, we have two options: handle Java-like packages and dependencies between modules with projects like Jingo or keep Python to handle all this stuff, just giving it the potential to handle dependencies.
To run jsLint and check melange.js and melange.graph.js files, you need java installed in your local computer, just run
./jslint.sh
in scripts/
directory. The check is based on a slightly modified source of jsLint rhino version. Following the defaults:
bitwise:false, eqeqeq:true, immed:true, laxbreak:false, newcap:false, nomen:false, onevar:false, plusplus:false, regexp:false, browser:true, undef:true, white:true, indent:2, predef:['window','jQuery','google']
In practice:
window
, jQuery
and google
being global variableseval
statementfor...in
statementsIf you want to check your code, copying and pasting in the online version of jsLint (you will receive more useful infos as output), set the following jsLint options:
==
and !=
Provisional tests for melange.js and melange.graph.js can be found in tests/javascript/melange.tests.html
, source code for tests in the repository can be found here.
To run jsUnit, you need to point your browser to this file:
./thirdparty/jsunit/testRunner.html
In the input line that will be shown, insert the path (URL style) of
./tests/javascript/melangeTestSuite.html
starting from your root directory. Then you just need to click “Run”, and it will run the test against the code. Fill free to set “Test level” to “debug (highest)” to see more details.
To work, jsCoverage needs to modify the source code of the scripts to “instrument” it. As the code will be modified and copied to another directory, also tests that points to the former code needs to be redirected to point to the instrumented code. This could be avoided by moving the original code to another directory first, but, at the moment, it just keeps things as they are.
So, to instrument the code and modify the melange.tests.html file just run
./jscoverage_on.sh
from ./scripts
directory.
It will create a ./app/soc/content/js_coverage
directory and will modify, as said, ./tests/javascript/melange.tests.html
file. It ignores, at the moment, slot-allocator-090320.js
, because it seems not to be compatible for some reasons.
Then you just need to run jsUnit as described above, and click on the “JSCoverage” button. In that way, you can see the code lines covered by the tests.
After this, you need to rollback the previous changes, by running
./jscoverage_off.sh
script from ./scripts
directory.
It will delete the ./app/soc/content/js_coverage
directory and rollback the changes in ./tests/javascript/melange.tests.html
file.
JSDocToolkit is present under
./thirdparty/jsdoctoolkit
directory. To run it against the Javascript code, just run
./jsdoctoolkit.sh
from the ./scripts
directory.
It will generate a directory
./app/soc/content/js/documentation
and two subdirectories under it, called private
and public
, which contain documentation for developers and documentation for public API of the Javascript files. Documentation in public
directory will also ignore undocumented files, which can lead to incorrect output.
More info on how to document Melange Javascript code when the refactoring will be on place.
Outputs of many javascript compressors have been tested, using this online Javascript compressor rater. Although Packer seems to be more efficient, it seems that it can lead to unpredictable output in older browsers, so we might want to use Shrinksafe to minify our code, as it seems more conservative.
To run shrinksafe, which is in ./thirdparty/shrinksafe
directory, just run
./shrinksafe.sh
from ./scripts
directory.
It will generate a
./app/soc/content/js_min
subdirectory, in which you can find all minified files, postfixed with a “min.js”.
This is just a test to see if it would be of any use to us.
In any way, we need:
To separate Javascript code in modules, and use Javascript language features to namespace correctly those modules.
To keep as much Javascript code as possible outside Django templates.
To put HTML strings outside Javascript code, eventually developing a little function to load those templates and then, for templating, something that emulates sprintf()
or begin to use jQuery Template plugin.
Use jQuery.noConflict()
(after loading any library/plugin) and giving jQuery a different namespace like $j
to avoid conflicts if we ever want to integrate other libraries ($
namespace is very well overused)
The proposal is to create a melange
namespace and begin adding sub-namespace to it for every feature we need. We might want to add models
, logic
and templates
subdirectories to the content/js
as well, to keep an homogeneous structure with the python code.