1 | This module can be used to serve up a Cordova application in the browser. It has no command-line, but rather is intended
|
2 | to be called using the following API:
|
3 |
|
4 | ``` js
|
5 | var serve = require('cordova-serve');
|
6 | serve.launchServer(opts);
|
7 | serve.servePlatform(opts);
|
8 | serve.launchBrowser(target, url);
|
9 | serve.sendStream(filePath, request, response[, readStream]);
|
10 | ```
|
11 |
|
12 | ##launchServer()
|
13 |
|
14 | ``` js
|
15 | launchServer(opts);
|
16 | ```
|
17 |
|
18 | Launches a server with the specified options. Parameters:
|
19 |
|
20 | * **opts**: Options, as described below.
|
21 |
|
22 | ##servePlatform()
|
23 |
|
24 | ``` js
|
25 | servePlatform(opts);
|
26 | ```
|
27 |
|
28 | Launches a server that serves up any Cordova platform (e.g. `browser`, `android` etc) from the current project.
|
29 | Parameters:
|
30 |
|
31 | * **opts**: Options, as described below.
|
32 |
|
33 | ##launchBrowser()
|
34 |
|
35 | ``` js
|
36 | launchBrowser(target, url);
|
37 | ```
|
38 |
|
39 | Launches a browser window pointing to the specified URL. Parameters:
|
40 |
|
41 | * **target**: The name of the browser to launch. Can be any of the following: `chrome`, `chromium`, `firefox`, `ie`,
|
42 | `opera`, `safari`.
|
43 | * **url**: The URL to open in the browser.
|
44 |
|
45 | ##sendStream()
|
46 |
|
47 | ``` js
|
48 | sendStream(filePath, request, response[, readStream]);
|
49 | ```
|
50 |
|
51 | The server uses this method to stream files, and it is provided as a convenience method you can use if you are
|
52 | customizing the stream by specifying `opts.streamHandler`. Parameters:
|
53 |
|
54 | * **filePath**: The absolute path to the file to be served (which will have been passed to your `streamHandler`).
|
55 | * **request**: The request object (which will have been passed to your `streamHandler`).
|
56 | * **response**: The response object (which will have been passed to your `streamHandler`).
|
57 | * **readStream**: A custom read stream, if required.
|
58 |
|
59 | ##The *opts* Options Object
|
60 | The opts object passed to `launchServer()` and `servePlatform()` supports the following values:
|
61 |
|
62 | * **root**: The file path on the local file system that is used as the root for the server, for default mapping of URL
|
63 | path to local file system path. For `servePlatform()`, this value should be the Cordova project's root folder, or any
|
64 | folder within it - `servePlatform()` will replace it with the platform's `www_dir` folder.
|
65 | * **port**: The port for the server. Note that if this port is already in use, it will be incremented until a free port
|
66 | is found.
|
67 | * **urlPathProcessor**: An optional method to handle special case URLs - `cordova-serve` will by default
|
68 | treat the URL as relative to the platform's `www_dir`, but will first call this method, if provided, to support
|
69 | custom handling.
|
70 | * **streamHandler**: An optional custom stream handler - `cordova-serve` will by default stream files using
|
71 | `sendStream()`, described above, which just streams files, but will first call this method, if provided, to
|
72 | support custom streaming. This method is described in more detail below.
|
73 | * **serverExtender**: This method is called as soon as the server is created, so that the caller can do
|
74 | additional things with the server (like attach to certain events, for example). This method is described in more
|
75 | detail below.
|
76 |
|
77 | ##urlPathProcessor()
|
78 | Provide this method if you need to do custom processing of URL paths. That is, custom mapping of URL path to local file path.
|
79 | The signature of this method is as follows:
|
80 |
|
81 | ``` js
|
82 | urlPathProcessor(urlPath, request, response, do302, do404)
|
83 | ```
|
84 |
|
85 | Parameters:
|
86 |
|
87 | * **urlPath**: The URL path to process. It is the value of `url.parse(request.url).pathname`.
|
88 | * **request**: The server request object.
|
89 | * **response**: The server response object.
|
90 | * **do302**: A helper method to do a 302 HTTP response (redirection). It takes a single parameter - the URL to redirect to.
|
91 | * **do404**: A helper method to do a 404 HTTP response (not found).
|
92 |
|
93 | Return value:
|
94 |
|
95 | Broadly, there are three possible actions you can take in your `urlPathProcessor` handler:
|
96 |
|
97 | 1. You completely handle the request (presumably by doing some sort of response and ultimately calling `response.end()`.
|
98 | In this scenario, you should return `null`.
|
99 | 2. You have mapped the URL path to a custom local file path. In this scenario, you should return `{filePath: <value>}`,
|
100 | where `<value>` is the local file path.
|
101 | 3. You have determined you don't need to do any custom processing and will let cordova-serve to its default mapping. In
|
102 | this scenario, you should return `{filePath: null}`.
|
103 |
|
104 | ##streamHandler()
|
105 | Provide this method if you wish to perform custom stream handling. The signature of this method is as follows:
|
106 |
|
107 | ``` js
|
108 | streamHandler(filePath, request, response)
|
109 | ```
|
110 |
|
111 | Parameters:
|
112 |
|
113 | * **filePath**: This is the path to the local file that will be streamed. It might be the value you returned from
|
114 | urlPathProcessor(), in which case it doesn't necessarily have to reference an actual file: it might just be an
|
115 | identifier string that your custom stream handler will recognize. If you are going to end up calling `sendStream()`,
|
116 | it is useful if even a fake file name has a file extension, as that is used for mime type lookup.
|
117 | * **request**: The server request object.
|
118 | * **response**: The serve response object.
|
119 |
|
120 | Return value:
|
121 |
|
122 | Return `true` if you have handled the stream request, otherwise `false`.
|
123 |
|
124 | ##serverExtender()
|
125 |
|
126 | If you provide this method, it will be called as soon as the server is created. It allows you to attach additional
|
127 | functionality to the server, such has event handlers, web sockets etc. The signature of this method is as follows:
|
128 |
|
129 | ``` js
|
130 | serverExtender(server, root)
|
131 | ```
|
132 |
|
133 | Parameters:
|
134 |
|
135 | * **server**: A reference to the server (the result of calling `http.createServer()`).
|
136 | * **root**: The file path on the local file system that is used as the root for the server (if it was provided), for
|
137 | default mapping of URL path to local file system path.
|
138 |
|