JXS - JavaScript CSS Processor
JXS is a processor and for cascading stylesheets and is transparently integrated into the JaxCore full-stack JavaScript framework, but can also run entirely client-side in the browser (inline or externally loaded), in NodeJS as an NPM module jaxcore-jxs, or by using the command-line utility jxs.
JXS is similar to SASS and LESS, but unlike them, is not a language of its own. JXS is the combination of a CSS-to-JS pre-processor and a JS-to-CSS post-processor. The pre-processor converts hybrid JavaScript+CSS syntax into compiled JavaScript functions, the post-processor runs the functions to output clean, valid, processed CSS. The compiled functions are cached internally by the JaxCore framework for fast dynamic CSS processing that is not possible with other CSS processors.
JXS Example:
var size = 10;
var paddings = {
top : 5,
bottom : 10
};
var bg = red.lighten(0.8).desaturate(0.7);
DIV.test {
color: customcolor.darken(0.5);
background: bg;
LI {
font-size : size * 2;
padding : paddings;
+:hover {
color : red.lighten(0.3);
text-decoration : underline;
}
}
}
Output CSS:
DIV.test {
color : #B19A28;
background : #EDDEDE
}
DIV.test LI {
font-size : 20px;
padding-top : 5px;
padding-bottom : 10px
}
DIV.test LI:hover {
color : #FF4D4D;
text-decoration : underline
}
Why Not SASS or LESS?
Fast
Both SASS and LESS are too slow to run dynamically from a webserver. JXS is FAST!
JXS is fast enough to generate CSS theme variations in real-time:
http://www.jaxcore.com/jxs/examples/client-swatch.html
The preprocessor is also fast enough to do real-time client-side editing and compilation of JXS:
http://www.jaxcore.com/jxs/editor/
Dynamic
Both SASS and LESS must be processed by external command-line utilities to produce static CSS. JXS is dynamic! In a JaxCore application you can create dynamic server-side CSS themes by supplying colors as URL parameters to .jxss files:
http://example.com/theme.jxss?foregroundColor=red&backgroundColor=white
JavaScript
Both SASS and LESS are custom languages with bizarre and incompatible syntax that is difficult to learn and even harder to debug. JXS is not a language! It transforms your CSS+JS hybrid code into pure JavaScript functions, all JavaScript developers will be instantly familiar with its syntax and be productive immediately with syntax they already understand.
Getting Started
Install JXS
To install the JXS NPM module:
npm install jaxcore-jxs
To install the JXS command line utility, also install JXS globally using the -g option:
sudo npm install jaxcore-jxs -g
The utility can be run system wide as jxs
Download Examples
git clone https://github.com/jaxcore/jaxcore-jxs.git
cd jaxcore-jxs/examples/web
To run the sample web files, install jaxserver a simple webserver with JXS support.
sudo npm install jaxserver -g
Run the webserver:
jaxserver . --port=8000
Visit the server at:
Create a new JXSS file
Now try creating a new JXS file named myfirstjxs.jxss:
BODY {
background: red.darken(0.5);
}
And view the outputted CSS code by visiting:
http://localhost:8000/myfirstjxs.jxss
Make the JXS dynamic by creating a variable called color, the type check is there to prevent an error:
var color;
if (!jax.type.isColor(color)) color = red;
BODY {
background: color.lighten(0.3);
}
Set the color variable with a URL parameter:
http://localhost:8000/myfirstjxs.jxss?color=brown
Create A JaxCore App With JXS Support
Install the JaxCore NPM module:
npm install jaxcore
Install the JaxCore command line utility:
sudo npm install jaxcore -g
Create a new JaxCore application:
jaxcore create MyApp ./myapp
cd ./myapp
Edit the app.js file and add the jxs plugin:
exports.config = {
...
app : {
...
plugins : ['jxt', 'directoryindexes', 'jxs']
}
};
Start the application:
node run.js
See http://www.jaxcore.com for more information about the framework.
File Formats
The JaxCore framework provides 3 mechanisms to serve and process JXS stylesheets. It is conceivable that all 3 could be used together in an application to separate the dynamic and static portions of your CSS.
Server-Side Dynamic ( JXSS )
The example above used myfirstjxs.jxss as the file-extension. .jxss are processed by the JaxCore application server, meaning the processing of the JXS code happens inside NodeJS and only the resulting CSS is sent to the browser. .jxss are fully dynamic, can accept input variables from URL parameters (eg. myfile.jxss?color=#68a40f), and do not produce static files.
Server-Side Static ( CSS.JXS )
By using the .css.jxss extension, the JaxCore framework will generate static CSS files automatically. In development mode (jax.config.env='dev'), all .css files will first check for the existence of a corresponding .css.jxss file, and serve its result in place of the static CSS file.
<link rel="stylesheet" type="text/css" href="mystyle.css" />
< !-- mystyle.css.jxss will be processed -->
The static CSS file is generated but is not used until the server is set back to production mode (jax.config.env='prod'). The generated CSS file can also be copied out into mobile applications. Beware .css.jxss will overwrite the .css file without warning. To avoid confusion it is recommended to place css.jxss files in a directory separate from existing CSS files.
Client-Side ( JXS )
If a JXS file is saved with the .jxs extension, it will be served as text/plain format. It is with this format that JXS processing can happen entirely client-side. The client-side version of JXS is slower (compilation must finish before the CSS can be loaded), and (currently) lacks the powerful include/import features of JXS, not supported are:
- @import
- include()
- dataURI()
- font()
Complete Language Reference
See all functions, properties, and colors:
JXS is internally converted to a JXT template. JXT is the template engine used in the JaxCore framework, and most of JXT can be utilized inside JXS by escaping:
// this is JXS
%>
this is JXT
1 plus 2 is <%= 1+2 %>
<%
// this is JXS again
Color Processing
All colors in JXS are processed as instances of the JaxCore Color() class. All CSS color names are predefined but new colors can also be created. The Color class has a variety of functions to modify and combine colors together to create new ones. Defining colors as hexidecimal code should never be necessary in a JXS stylesheet.
var mycolor = new Color(100, 0, 200);
var darkerColor = mycolor.darker(0.3);
var transparentColor = mycolor.alpha(0.8);
// also supports chaining:
var purplish = red.tint(blue, 0.2).alpha(0.3).lighten(0.4)
// the resulting JavaScript Color() objects can be used as CSS properties:
BODY {
background-color : transparentColor;
color : myolor;
border-color: purplish;
}
For a complete list of Color methods, see:
Client-Side JavaScript Library
Build Libraries
To produce static minified version of the JXS libraries, use the jaxcore command line utility:
jaxcore build . --buildplugins=true
That will create the jaxcore.min.js, jaxcore-jxt.min.js, and jaxcore-jxs.min.js libraries to the current directory.
Inline SCRIPT tag
When the JaxCore, JXT and JXS libraries are included in a webpage, JXS will process all inline JXS script tags with type="text/jxs" to create style blocks from the resulting CSS:
<script type="text/javascript" src="jaxcore.min.js"></script>
<script type="text/javascript" src="jaxcore-jxt.min.js"></script>
<script type="text/javascript" src="jaxcore-jxs.min.js"></script>
<script type="text/jxs">/* your JXS here */</script>
External JXS files
Use the jax.jxs client-side library to load an external .jxs file, process it, and insert the results into a new STYLE tag;
var input = {mycolor:'#FF0000'};
// load "jxs/test.jxs" and load results into a new style tag with id="myjxs"
jax.jxs.loadJXS('jxs/test.jxs', input, 'myjxs', function() {
// jxs loaded
});
NodeJS Module
JXS support can be integrated into any NodeJS project by loading the jaxcore-jxs module.
var jax = require('jaxcore-jxs').jax;
var input = {}; // variables to be passed into JXS
var debug = false; // include error information if the JXS compilation fails
var css = jax.jxs.process(__dirname+'../styles.jxs', input, debug);
console.log(css);
Command Line Utility
The command line utility can be used independently of the JaxCore web framework, allowing the use of JXS in web/mobile development using any technology stack.
Process .jxss
Output CSS to the terminal:
jxs test1.jxss
Output white-space optimized CSS to the terminal:
jxs test1.jxss --optimize=true
Send variables in from the command-line as a string-escaped json object:
jxs test1.jxss --input="{\"color\":\"orange\"}"
Send variables in from a json file:
jxs test1.jxss --input=color.json
Output CSS to file:
jxs test1.jxss --outfile=./test.css
Process .css.jxss
.css.jxss files are used to generate static css files and do not accept input objects
Generate the corresponding test2.css CSS file:
jxs test2.css.jxss
Generate a white-space optimized CSS file:
jxs test2.css.jxss --optimize=true
Instead of writing a file, output CSS to console:
jxs test2.css.jxss --stdout=true
Write to a different filename:
jxs test2.css.jxss --outfile=./test2custom.css
Error Handling
Should a compile or runtime error occur, the debug information can be saved in the css file
Show debug information in the terminal:
jxs test3.jxss --debug=true
Include debug information in the generated CSS file:
jxs test3.jxss --outfile=./test3.css --debug=true
Process Directories
JXS can process all .css.jxss files in an directory,
Process the .css.jxss files in the current directory:
jxs .
Process a different directory and optimize:
jxs ../my/other/jxsdir/ --optimize=true
Use the --force option to disregard timestamps:
jxs ../my/other/jxsdir/ --optimize --force=true