| 1 | Helma NG |
| 2 | ======== |
| 3 | |
| 4 | Helma NG is a general purpose Javascript runtime and web application framework. |
| 5 | "NG" stands for "next generation", meaning that it is more of a rewrite of |
| 6 | Helma 1 than simply a new version. |
| 7 | |
| 8 | Helma NG consists of several components that can be used together or alone: |
| 9 | |
| 10 | 1. A compact JavaScript runtime environment based on Mozilla Rhino. It adds |
| 11 | to Rhino a reloading module system that is compatible to the ServerJS |
| 12 | Securable Module proposal. |
| 13 | |
| 14 | 2. An interactive shell with support for autocompletion and history. |
| 15 | |
| 16 | 3. A module library implemented in JavaScript, covering basic functionality |
| 17 | such as extensions to the built-in objects, file I/O, logging, persistence, |
| 18 | client and server side HTTP support and more. |
| 19 | |
| 20 | For more information, check out the Helma NG homepage and wiki at |
| 21 | <http://helma.org/wiki/Helma+NG/> |
| 22 | |
| 23 | Building Helma |
| 24 | -------------- |
| 25 | |
| 26 | Helma requires Java 1.5 and uses Apache Ant as its build environment. If you have |
| 27 | these installed, building Helma NG is straightforward: |
| 28 | |
| 29 | Check out Helma NG from Git: |
| 30 | |
| 31 | git clone git://github.com/hns/helma-ng.git |
| 32 | |
| 33 | Change to the helma-ng directory and run ant to compile: |
| 34 | |
| 35 | ant jar |
| 36 | |
| 37 | If this succeeds you should now have a file called run.jar and be ready to go. |
| 38 | |
| 39 | JavaScript Runtime and Shell |
| 40 | ---------------------------- |
| 41 | |
| 42 | The Helma JavaScript runtime is based on [Mozilla Rhino][rhino] and supports |
| 43 | JavaScript 1.7 with partial support for JavaScript 1.8 features. |
| 44 | |
| 45 | [rhino]: http://www.mozilla.org/rhino/ |
| 46 | |
| 47 | To run Helma NG, add the helma-ng/bin directory to your PATH environment |
| 48 | variable: |
| 49 | |
| 50 | export PATH=$PATH:/path/to/helma-ng/bin |
| 51 | |
| 52 | To start a shell session, just run the helma command without any arguments: |
| 53 | |
| 54 | helma |
| 55 | |
| 56 | To run a script simply pass it to helma on the command line: |
| 57 | |
| 58 | helma apps/demo/main.js |
| 59 | |
| 60 | If you run a script that is contained in Helma's module path you can also |
| 61 | use the simpler abstract module name instead of the file name. For example, |
| 62 | to run the helma test suite: |
| 63 | |
| 64 | helma test/all |
| 65 | |
| 66 | To create a new web application, use the admin/create script. This will copy |
| 67 | an simple skeleton app to the location you define. You can pass the |
| 68 | application directory as command line argument, or the script will prompt you |
| 69 | for it. |
| 70 | |
| 71 | helma admin/create [appdir] |
| 72 | |
| 73 | Run helma with the -h or --help switch to get more information about available |
| 74 | command line options. For example, the -i or --interactive option allows you |
| 75 | to run an application and use the shell at the same time, which can be really |
| 76 | handy. |
| 77 | |
| 78 | Module Path Setup |
| 79 | ----------------- |
| 80 | |
| 81 | Helma NG loads JavaScript resources using a module loader that is compliant with |
| 82 | the ServerJS Securable Modules proposal: |
| 83 | |
| 84 | <https://wiki.mozilla.org/ServerJS/Modules/SecurableModules> |
| 85 | |
| 86 | Helma NG actually goes one step further and makes sure every module has its own |
| 87 | top level scope, so modules are fully isolated from each other, providing a |
| 88 | programming environment that resembles that of Python environment more than |
| 89 | the one of ordinary client-side JavaScript runtime. |
| 90 | |
| 91 | Helma uses the concept of a module path to look up and load modules that is |
| 92 | similar to the PATH environment variable used to find executables on most |
| 93 | operating systems. By default, the module path consists of two entries: |
| 94 | |
| 95 | 1. The application root, which is the parent directory of the command line |
| 96 | script, or the current working directory if called without script |
| 97 | argument. |
| 98 | |
| 99 | 2. The system modules root, which corresponds to the modules directory in |
| 100 | the Helma NG home directory. |
| 101 | |
| 102 | Helma NG provides several ways to access and set the module path. The simplest |
| 103 | is to set the HELMA_MODULE_PATH environment variable, separating multiple entries |
| 104 | with ':' or whatever character is used to separate PATH entries on your system: |
| 105 | |
| 106 | export HELMA_MODULE_PATH=../foo/lib:../my/lib |
| 107 | |
| 108 | Alternatively, you can define the module path using the helma.modulepath Java |
| 109 | system property, and you can add entries to the module path using the |
| 110 | addRepository() method in the helma/system module. |
| 111 | |
| 112 | Module and Resource Loading |
| 113 | --------------------------- |
| 114 | |
| 115 | Helma NG provides three functions with different semantics to load modules: |
| 116 | |
| 117 | `require(moduleName)` |
| 118 | |
| 119 | > The require function provides the functionality defined in the ServerJS |
| 120 | > Securable Modules proposal. It tries to locate a module in the module path, |
| 121 | > loads it and returns its exports object. |
| 122 | |
| 123 | `import(moduleName)` |
| 124 | |
| 125 | > The import function builds on top of require, additionally setting a |
| 126 | > property in the calling module scope whose name is the name of the |
| 127 | > loaded module and whose value is the loaded module's exports object. |
| 128 | |
| 129 | `include(moduleName)` |
| 130 | |
| 131 | > The include function builds on top of require, additionally copying |
| 132 | > all exported properties of the loaded module to the calling module scope. |
| 133 | |
| 134 | `export(propertyName[, ...])` |
| 135 | |
| 136 | > The export function provides an alternative method to the exports object |
| 137 | > to define exported properties in a module by passing the names of exported |
| 138 | > properties as arguments. |
| 139 | |
| 140 | `addToClasspath(pathName)` |
| 141 | |
| 142 | > This function adds a jar file or directory to the classpath. By default, |
| 143 | > all jar files in the Helma NG lib directory are included in the classpath. |
| 144 | |
| 145 | `getResource(pathName)` |
| 146 | |
| 147 | > This looks for a file with the given path name in the module path and |
| 148 | > returns a resource object. This can be used to load resources other than |
| 149 | > JavaScript files using the same lookup rules as the module loader. |
| 150 | |
| 151 | Web Framework |
| 152 | ------------- |
| 153 | |
| 154 | The Helma Web Framework is a web application framework written mostly in JavaScript |
| 155 | built on top of the Helma Runtime. |
| 156 | |
| 157 | To run the demo application that is part of Helma NG run the following command: |
| 158 | |
| 159 | helma apps/demo/main.js |
| 160 | |
| 161 | This starts and serves the demo web app on port 8080: |
| 162 | |
| 163 | <http://localhost:8080/> |
| 164 | |
| 165 | The demo app showcases a number of tools and libraries to build web apps. |
| 166 | As Helma NG is still pretty young, many features found in Helma 1.6 are still |
| 167 | missing, most notably a persistence layer. These features are currently being |
| 168 | implemented. |
| 169 | |
| 170 | The exciting thing is that it will be possible to implement much of it in |
| 171 | Javascript, meaning you can help doing so without hacking on helma core. |
| 172 | The new modular concept will even allow to use Helma NG with several |
| 173 | frameworks, even on the same server instance. |
| 174 | |
| 175 | Visit <http://helma.org/wiki/Helma+NG/> and join the Helma NG mailing list to keep up |
| 176 | with Helma NG core and module development! |
| 177 | |
RSS feed for site updates