helma.org/wiki/Helma NG/Modules and Scopes

Version 16

hannes — Wed, 13 May 2009 12:53:30 +0000

19	Module names are derived from a module's file name by removing the ".js" extension and replacing the using "/" as path separators with dotsitem separator. Thus, a module residing in file helma/http.js can be referred to as 'helma.httphelma/http'. When a module is loaded, Helma NG defines a property called <code>__name__</code> and sets it to the module name.
21	Helma NG uses a module path to resolve module names. By default, the module path consists of the application directory and the modules directory in the Helma NG installation. It is possible to add directories and zip archives to the module path through using the HELMA_MODULE_PATH environment variable or command line arguments to the Helma NG runtime and shell. When asked to import a module, Helma walks along the module path until it finds a module matching the name. If no matching module can be found, an error is thrown.
27	The global <code>import()</code> function loads a module into a module scope and creates a reference in the caller's scope pointing to the imported scope. The imported module's name is used as property name in the calling module. For instance, the following statement will load the <code>helma.http</code> <code>helma/http</code> module and add it as <code>helma.http</code> to the scope of the calling module.
29	import('helma.httphelma/http');
35	var http = require('helma.httphelma/http');
41	include('helma.skinhelma/skin');
45	If a function imported using include() wants to access properties or functions of its importing scope, it can do by either accepting the scope as an argument to the function, or by using the <code>this</code> keyword, which contains the object the function was called on. In fact, the render() function in module helma.skin helma/skin uses this to load a skin resource from a location relative to the importing module's file rather than itself.

Version 15

hannes — Fri, 30 Jan 2009 16:08:39 +0000

13	<!-- diagram is outdated/wrong! == Module ScopeScope -->
15	<% <!-- % this.image 'scopes-ng-small.png' %>% -->

Version 14

hannes — Sun, 25 Jan 2009 20:04:41 +0000

27	The global <code>import()</code> function allows to load loads a module into a namespace of module scope and creates a reference in the calling modulecaller's scope pointing to the imported scope. By default, the namespace The imported module's name is the same used as property name in the module namecalling module. For instance, the following statement will load the <code>helma.http</code> module and add it as <code>helma.http</code> to the scope of the calling module.
30
31	== require()
32
33	The global <code>require()</code> function loads a module into a module scope and returns the scope object to the caller.
34
35	var http = require('helma.http');

Version 13

hannes — Sun, 25 Jan 2009 19:58:02 +0000

One of the cornerstones of Helma NG, and one that distinguishes it from every other JavaScript runtime out there, is how it handles modules and scopes. See */wiki/Modules *Modules and in Helma NG* NG|http://dev.helma.org/wiki/Modules+and+Scopes+in+Helma+NG/* for a higher level overview of the module system in Helma NG.

Version 12

hannes — Sun, 25 Jan 2009 19:57:38 +0000

1	One of the cornerstones of Helma NG, and one that distinguishes it from every other JavaScript runtime out there, is how it handles modules and scopes. See Modules /wiki/Modules and in Helma NG* for a higher level overview of the module system in Helma NG.

Version 11

hannes — Sun, 25 Jan 2009 19:57:19 +0000

1	One of the cornerstones of Helma NG, and one that distinguishes it from every other JavaScript runtime out there, is how it handles modules and scopes. See Modules and in Helma NG for a higher level overview of the module system in Helma NG.

Version 10

hannes — Sun, 25 Jan 2009 19:55:27 +0000

51	== The shared global scope
52
53	== The per-thread global scope
54
55	== Metaprogramming
56
57	Modules automatically recognize functions following the JSAdapter\|http://blogs.sun.com/sundararajan/entry/self_javascript_and_jsadapter syntax and will invoke these functions for property access if they are defined. For instance, if you define a function called <code>__get__</code> in your module, it will be called to lookup properties. You can access the "raw" properties defined in your modules in your JSAdapter functions.
58
59	var bar = "BAR";
60
61	function __get__(name) {
62	if (name == "foobar") {
63	return "foo" + bar;
64	}
65	// leave this away if you don't want to expose "raw" properties
66	return this[name];
67	}

Version 9

hannes — Sun, 25 Jan 2009 19:51:13 +0000

25	== importModule()import()
27	The global <code>importModule()</code> <code>import()</code> function allows to load a module into a namespace of the calling module. By default, the namespace is the same as the module name. For instance, the following statement will load the <code>helma.http</code> module and add it as <code>helma.http</code> to the scope of the calling module.
29	importModule(import('helma.http');
31	Optionally, importModule() takes a second argument that allows to override the namespace to place the imported module. The following call will put the imported module into <code>http</code>, dumping the 'helma'== prefix and making it more convenient to access:include()
33	importModule(Another way of using the functionality of a module is to add one or more properties or functions from the module to one'helmas own top level scope.http' For example, you could use the following statement to add the Client constructor to your local module'http');s top level scope:
35	== importFromModule() include('helma.skin');
37	Another way of using the functionality of a module is to add one or more properties or functions from the module to one's own top level scope. For example, if you only need the Client class from the helma.http module, you could use the following statement to add the Client constructor to your local module's top level scope:
38
39	importFromModule('helma.skin', 'render');
40
40	If a function imported using importFromModule() include() wants to access properties or functions of its importing scope, it can do by either accepting the scope as an argument to the function, or by using the <code>this</code> keyword, which contains the object the function was called on. In fact, the render() function in module helma.skin uses this to load a skin resource from a location relative to the importing module's file rather than itself.

Version 8

anton — Thu, 25 Sep 2008 22:00:17 +0000

By default, Helma NG creates earch each module once per request. This means that if a module is loaded from several other modules in the same application, you be sure that you deal with the actual same module instance and scope throughout each request, but are isolated from other requests that may be running at the same time.

Version 7

hannes — Fri, 23 May 2008 14:06:29 +0000

3	=== Modules
7	First, if one If a module wants to make use of another module, it needs to import the other module. Helma NG provides two global functions for this, one to import a module into a discrete namespace, and another to import some or all properties of a module into its own scope.
13	=== Module Scope
17	=== importModule()Module naming
19	Module names are derived from a module's file name by removing the ="=.js" extension and replacing the path separators with dots. Thus, a module residing in file helma/http.js can be referred to as ='helma.http'. importFromModule()When a module is loaded, Helma NG defines a property called <code>__name__</code> and sets it to the module name.
21	===Helma NG uses a module path to resolve module names. Module sharing By default, the module path consists of the application directory and cachingthe modules directory in the Helma NG installation. It is possible to add directories and zip archives to the module path through command line arguments to the Helma NG runtime and shell. When asked to import a module, Helma walks along the module path until it finds a module matching the name. If no matching module can be found, an error is thrown.
23	Usually, Helma modules consist of only one JavaScript file. In some cases, it is preferable to split a single module over multiple files. For these cases, Helma provides a feature to load all the JavaScript files contained in a directory into one single module. Use a module name ending with '.\' to use this, e.g. <code>'reallybigmodule.\'</code>.
24
25	== importModule()
26
27	The global <code>importModule()</code> function allows to load a module into a namespace of the calling module. By default, the namespace is the same as the module name. For instance, the following statement will load the <code>helma.http</code> module and add it as <code>helma.http</code> to the scope of the calling module.
28
29	importModule('helma.http');
30
31	Optionally, importModule() takes a second argument that allows to override the namespace to place the imported module. The following call will put the imported module into <code>http</code>, dumping the 'helma' prefix and making it more convenient to access:
32
33	importModule('helma.http', 'http');
34
35	== importFromModule()
36
37	Another way of using the functionality of a module is to add one or more properties or functions from the module to one's own top level scope. For example, if you only need the Client class from the helma.http module, you could use the following statement to add the Client constructor to your local module's top level scope:
38
39	importFromModule('helma.skin', 'render');
40
41	Now the really nice thing about this is that because of JavaScript's static scoping, the render function continues to 'live' in its original scope, which is the one defined by the helma.skin module. It can therefore call all global functions defined in the helma.skin module without using any prefix and without fear of unintentionally calling something defined elsewhere.
42
43	If a function imported using importFromModule() wants to access properties or functions of its importing scope, it can do by either accepting the scope as an argument to the function, or by using the <code>this</code> keyword, which contains the object the function was called on. In fact, the render() function in module helma.skin uses this to load a skin resource from a location relative to the importing module's file rather than itself.
44
45	== Module loading, sharing and caching
46
32	=== The shared global scope
34	=== The per-thread global scope
36	=== Metaprogramming

Version 6

hannes — Fri, 23 May 2008 13:07:28 +0000

Version 5

hannes — Fri, 23 May 2008 13:07:16 +0000

29	This will result in your module scope to be kept alive across and shared among requests.
30
33
34	=== Metaprogramming
35
36	Modules automatically recognize functions following the JSAdapter\|http://blogs.sun.com/sundararajan/entry/self_javascript_and_jsadapter syntax and will invoke these functions for property access if they are defined. For instance, if you define a function called <code>__get__</code> in your module, it will be called to lookup properties. You can access the "raw" properties defined in your modules in your JSAdapter functions.
37
38	var bar = "BAR";
39
40	function __get__(name) {
41	if (name == "foobar") {
42	return "foo" + bar;
43	}
44	// leave this away if you don't want to expose "raw" properties
45	return this[name];
46	}

Version 4

hannes — Fri, 23 May 2008 12:58:45 +0000

23	By default, Helma NG creates earch module once per request. This means that if a module is loaded from several other modules in the same application, you be sure that you deal with the actual same module instance and scope throughout each request, but are isolated from other requests that may be running at the same time.
24
25	Sometimes it is desirable to have a module instantiated only once, and shared among all requests. You can achieve this by defining a property called <code>__shared__</code> in your module and giving it the value <code>true</code>:
26
27	var __shared__ = true;
28

Version 3

hannes — Fri, 23 May 2008 12:52:36 +0000

15	<% this.image 'scopes-ng-small.png' %>
16
19
20	=== Module sharing and caching

Version 2

hannes — Fri, 23 May 2008 12:48:07 +0000

Deleted tags

Version 1

hannes — Fri, 23 May 2008 12:39:27 +0000

Set tags to helma ng

1	One of the cornerstones of Helma NG, and one that distinguishes it from every other JavaScript runtime out there, is how it handles modules and scopes.
3	=== Modules
4
5	Helma NG handles JavaScript resources as Modules. If this evokes associations to Python\|http://docs.python.org/tut/node8.html it is fully intentional, because NG Modules work and feel very much like Python Modules\|http://effbot.org/zone/import-confusion.htm.
6
7	First, if one module wants to make use of another module, it needs to import the other module. Helma NG provides two global functions for this, one to import a module into a discrete namespace, and another to import some or all properties of a module into its own scope.
8
9	Now the special thing about Helma NG is that the two modules (one doing the import, the other being imported) are fully isolated from each other. The imported module does not have any way at all to access the importing module, and the importing module can only access the imported one via the namespace into which it imported it, or the properties and functions it explicitly imported from it. And what's more, you don't have to do anything special to accomplish this. You just write scripts with global functions and properties and never worry about stuff that is defined in other scripts.
10
11	The way Helma NG does this is by giving each Module its own top-level scope.
12
13	=== Module Scope
14
15	=== importModule()
16
17	=== importFromModule()
18
19	=== The shared global scope
20
21	=== The per-thread global scope