mOxie is combined name for XHR2 and File API pollyfills that we've extracted from Plupload in order to make it more flexible and give it opportunity for further growth. But now that pollyfills are separate, they can be used independently.
XHR2 and File API pollyfills are multi-runtime, which means that they will fallback to Flash and SilverLight (additionally there's Java runtime in production) or even "good old" HTML4, when there are no HTML5 capabilities found in current browser.
Table of Contents
- Building Instructions
- Getting Started
- API Reference
It may sound a bit odd, but the best building environment for mOxie is Windows computer. Mainly because it is not currently possible to build Silverlight component on alternative platforms. There used to be a Moonlight project, which was meant to fill in the gap for *nix systems, but there was no noticeable activity on the site since 2009, its feature-set has freezed somewhere in the mid-Silverlight 4, and more importantly, a component that is produced after compilation is not exactly a Silverlight component, hence the alternative name and all the compatibility issues in the latest browsers.
So, although these instructions are quite generic, they still have Windows workstation in mind. If you do not have Windows workstation, you can easily virtualize one.
The best way to start is to clone the mOxie repository, with all it's submodules:
git clone --recursive https://github.com/moxiecode/moxie.git
In addtion to Node.js some additional modules are required, simply change your working directory to where you have extracted mOxie package and run:
npm install. All dependencies will be downloaded and installed automatically.
Note: currently for unknown reason, locally installed Node.js modules on Windows, may not be automatically added to the system PATH. So if
jake commands below are not recognized you will need to add them manually:
Plupload runtimes - the main source for these pollyfills historically came in monolithic state. Nothing could have been added to them or removed. This wasn't convenient enough, since not everybody required all the functionality and resulting JS file still got quite big for mere file uploader. Taking this into account we made pollyfills granular. There are still some internal dependencies that cannot be broken, but several big components (such as image manipulation logic, for example) can easily be separated now.
jake mkjs. It will compile all the components and runtimes into several versions of one monolithic
moxie.js file (minified and development versions among them). Results will be written to
jake mkjs[file/FileInput,xhr/XMLHttpRequest] runtimes=html5,flash
Currently there are only several major components that you should care about (the rest will be pulled in as dependecies automatically). These are:
And several runtimes (Java is in production right now):
Use combination of these in
To compile all available runtimes, run:
jake mkjs runtimes=all
To build Flash component you will also need Flex 4.x SDK, which is freely available from Adobe site. Flex SDK comes as a package, not binary. So you will have to manually extract it somewhere and ensure that compiler is available across the system. Depending on a platform you might also require to install Java Runtime Environment (JRE). To put Flex compiler (
mxmlc) into the system PATH, execute the following in your command-prompt window:
For Windows (we assume here that SDK was extracted to
Program Files\flex_sdk_4.x, use your own path if it was different):
*For nix (replace
/opt/flex_sdk_4.x with the path to extracted SDK)
Although be warned, as this will set the system PATH for current session only, in order to set it forever, check your platform specific documentation.
Once you have it, you can run
jake mkswf in your command-prompt, from mOxie directory and corresponding component files will get compiled and written to
bin/flash/ directory. There will be two versions:
Moxie.swf, which includes client-side image manipulation logic, and
Moxie.min.swf, twice as small, but without it.
To build Silverlight component you need .NET Framework 4 and Silverlight 4 SDK (and of course, as we mentioned above, a Windows PC). These are binary packages so you will not have to extract them manually, but you will still need to set the PATH to make compiler (
msbuild.exe) available across the system. So after you install both, open your command prompt and type in something like this:
Make sure that version suffix (v4.x) corresponds to actual .NET Framework version and physical folder where
msbuild executable resides. Again be warned, that this will set the system PATH for current session only, in order to set it forever, check documentation specific to your platform.
Once you have
msbuild.exe in the system PATH you can run
jake mkxap and two Silverlight components will be compiled to
Moxie.xap, a version with image manipulation logic compiled in and much smaller
Moxie.min.xap - without it.
Generate API Documentation
To get the documentation, execute:
jake docs. Reference will appear under
It is also possible to build fully packacged releases, customized or not, zipped and ready to be shared or shipped, containing JS files, Flash/Silverlight shims and documentation.
All of the following commands will generate packages under
jake release- Generates full user and development packages.
jake package- Generates full user package.
jake package[comma-separated-list-of-components-to-include] runtimes=comma-separated-list-of-runtimes-to-use(see all available options)
You can customize various parameters, such as the path the the Moxie.swf file by changing properties on
mOxie.Env after the script is loaded:
<script src="moxie.js"></script> <script>moxie.core.utils.Env.swf_url = './flash/Moxie.min.swf';</script>
Also see the File Picker example on the wiki.
We are actively standing behind our products. We ask you to file bug reports if you encounter any. We may not react to them instantly, but we constantly bear them in my mind as we extend the code base.
We are open to suggestions and code revisions, however there are some rules and limitations that you might want to consider first.
- Code that you contribute will automatically be licensed under the AGPLv3, but will not be limited to AGPLv3.
- Although all contributors will get the credit for their work, copyright notices will be changed to Ephox.
- Third party code will be reviewed, tested and possibly modified before being released.
These basic rules help us earn a living and ensure that code remains Open Source and compatible with AGPLv3 license. All contributions will be added to the changelog and appear in every release and on the site.