Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 143 lines (91 sloc) 5.479 kB
44fbb7e @tj Initial commit
tj authored
1
2 # express-expose
3
4 Expose helpers and local variables to the client-side
5
4aa71bb @tj install docs
tj authored
6 ## Installation
7
8 $ npm install express-expose
9
10 ## Usage
11
12 var express = require('express')
13 , expose = require('expose');
14
15 app.expose(...);
16
ee56555 @tj docs
tj authored
17 ## Examples
18
9ec85f4 @tj docs
tj authored
19 ### Exposing Objects
20
ee56555 @tj docs
tj authored
21 A common use-case for exposing objects to the client-side would be exposing some properties, perhaps the express configuration. The call to `app.expose(obj)` below defaults to exposing the properties to `express.*`, so for example `express.views`, `express.title`, etc.
22
23 app.set('views', __dirname + '/views');
24 app.set('view engine', 'jade');
25 app.set('title', 'Example');
26 app.set('default language', 'en');
27
28 app.expose(app.settings);
29
30 Another use-case would be exposing helper methods, perhaps the same ones as you are currently exposing to templates. Below we expose the `math` object as utilities to our templates, as well as the client-side. Within a template we would call `add(1,2)`, and on the CS we would call `utils.add(1,2)`, since we have passed the namespace "utils".
31
32 var math = { add: function(a,b){ return a + b; } };
33 app.expose(math, 'utils').helpers(math);
34
35 Sometimes you might want to output to a different area, so for this we can pass an additional param "languages" which tells express which buffer to write to, which ends up providing us with the local variable "languages" in our template, where the default is "javascript".
36
37 app.expose({ en: 'English', fr: 'French' }, 'express', 'languages');
38
9ec85f4 @tj docs
tj authored
39 ### Raw JavaScript
ee56555 @tj docs
tj authored
40
41 It is also possible to expose "raw" javascript strings.
42
43 app.expose('var some = "variable";');
44
45 Optionally passing the destination buffer, providing us with the "head" local variable, instead of the default of "javascript".
46
47 app.expose('var some = "variable";', 'head');
48
9ec85f4 @tj docs
tj authored
49 ### Exposing Functions
50
ee56555 @tj docs
tj authored
51 Exposing a named function is easy too, simply pass it in with an optional buffer name for placement within a template much like above.
52
53 app.expose(function someFunction(){
54 return 'yay';
55 }, 'foot');
56
9ec85f4 @tj docs
tj authored
57 ### Self-Calling Functions
58
ee56555 @tj docs
tj authored
59 Another alternative is passing an anonymous function, which executes itself, creating a "wrapper" function.
60
61 app.expose(function(){
62 function notify() {
63 alert('this will execute right away :D');
64 }
65 notify();
66 });
67
9ec85f4 @tj docs
tj authored
68 ### Exposing Entire Modules
ee56555 @tj docs
tj authored
69
a68df70 @tj docs
tj authored
70 Exposing an entire module as-is is possible as well, this primarily
71 useful when the module relies on internal closures and state.
72
73 The following exposes "color.dark()", "color.light()" etc by default based
74 on the basename of the `path` given, however we pass "utils.color" as a custom namespace.
75
76 app.exposeModule(__dirname + '/color', 'utils.color');
77
9ec85f4 @tj docs
tj authored
78 ### Request-Level Exposure
79
80 Finally we can apply all of the above at the request-level as well, below we expose "express.current.user" as `{ name: 'tj' }`, for the specific request only.
81
82 app.get('/', function(req, res){
83 var user = { name: 'tj' };
84 res.expose(user, 'express.current.user');
85 res.render('index', { layout: false });
86 });
a68df70 @tj docs
tj authored
87
5e9f5f6 @tj docs
tj authored
88 ### CommonJS Modules
89
90 Similarly we can enable a light-weight commonjs require() implementation simply by calling:
91
92 app.exposeRequire();
93
94 From that point on, the `namespace` is no longer a dot-delimited property, but a slash-delimited path, for example the following would allow us to `require('utils/color')` within the browser.
95
96 app.exposeModule(__dirname + '/color', 'utils/color');
97
98 By default the path defaults to the basename of the path used to load the module's contents, so we could remove "utils/color", allowing us to `require('color')`.
99
100 The primary benefit of utilizing require() here, is that `color`, or any other module can use require() internally, and as long as we expose those modules as well, they will work in the browser.
101
102 This of course works for things a side from modules as well:
103
104 app.expose(app.settings, 'settings');
105
106 Which we can then require in our client:
107
108 require('settings')
109
110 // => {
111 default language: "en"
112 , env: "development"
113 , hints: true
114 , home: "/"
115 , title: "Example"
116 , view engine: "jade"
117 , views: "/Users/tj/Projects/express-expose/examples/views"
118 }
119
44fbb7e @tj Initial commit
tj authored
120 ## License
121
122 (The MIT License)
123
124 Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
125
126 Permission is hereby granted, free of charge, to any person obtaining
127 a copy of this software and associated documentation files (the
128 'Software'), to deal in the Software without restriction, including
129 without limitation the rights to use, copy, modify, merge, publish,
130 distribute, sublicense, and/or sell copies of the Software, and to
131 permit persons to whom the Software is furnished to do so, subject to
132 the following conditions:
133
134 The above copyright notice and this permission notice shall be
135 included in all copies or substantial portions of the Software.
136
137 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
138 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
139 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
140 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
141 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
142 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
143 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.