diff --git a/README.md b/README.md index bdd00bb..5b46f38 100644 --- a/README.md +++ b/README.md @@ -10,15 +10,14 @@ Our engagement is use the fewer dependencies and offer our experiences with Node To install a new instance of ZENserver only you have to run this command: -``` +```bash npm install zenserver --save ``` Another option is modify the package.json including this new dependence: -``` +```json { - "name" : "zen-server-instance", "version" : "1.0.0", "dependencies": { @@ -27,8 +26,8 @@ Another option is modify the package.json including this new dependence: "scripts" : {"start": "node zen.js"}, "engines" : {"node": "*"} } - ``` + We include **coffee-script** package too, because we go to do all examples in this language. But if you want to develop in JavaScript, you can. We believe that CoffeeScript is more maintainable and legible, so if you want to learn more of CoffeeScript you can download this free book . @@ -37,34 +36,38 @@ We believe that CoffeeScript is more maintainable and legible, so if you want to It is easy to configure ZEN because everything you need is in the configuration file **zen.yml**. We are goint to analyze these options: -> +```yaml protocol: http # or https host : localhost port : 8888 timezone: Europe/Amsterdam +``` In this section you can set your server configuration, the protocol that you use (http or https), host name, port and timezone. -> +```yaml environment: development - +``` + With this attribute you can create different configuration files to use in different environments (development, preproduction, production...). In this example we have established environment so when the server is started searches a file in **environments/development.yml** route to overwrite the previous configuration on **/zen.yml**. -> +```yaml api: - index -> +``` +```yaml www: - index +``` The attributes **api** and **www** contain the endpoints of your server. The *api* is for REST services and the *www* for others results (HTML, images...). In this example, ZENserver searches the endpoints **/api/index.coffee** and **/www/index.coffee** and will load on the router for further proccesing. -> +```yaml statics: - url : /temp/resources folder : /static @@ -76,11 +79,12 @@ In this example, ZENserver searches the endpoints **/api/index.coffee** and **/w maxage : 3600 - file : robots.txt folder : /static - +``` + This attribute gives us a simple way to provide static files on our server. We can offer complete directories with the **url** attribute or a specific file by **file**. In both cases we set the path relative to the project directory using the **folder** attribute. In case we need to have cache resources we have to set the number of seconds using the attribute **maxage**. -> +```yaml session: # Cookie Request cookie: zencookie @@ -89,26 +93,29 @@ We can offer complete directories with the **url** attribute or a specific file expire: 3600 #seconds # HTTP Header authorization: zenauth +``` With this attribute we can establish and get easily the session variable for a particular customer. This variable we can get with the attribute **cookie**. -> +```yaml audit: interval: 60000 #miliseconds +``` With this attribute we can create an audit to control what happens in our server when it is running. This audit creates a file per day in **/logs** directory with this information: -> +```yaml - Requested endpoint - Method (GET, POST, PUT, DELETE) - Processing time in milliseconds - Response HTPP code - Response size in bytes - Client (comming soon) +``` With this information you can analize all requests of your clients. -> +```yaml headers: Access-Control-Allow-Origin: "*" Access-Control-Allow-Credentials: true @@ -132,6 +139,7 @@ With this information you can analize all requests of your clients. - date - request-id - response-time +``` Finally we set the type of response from our endpoints, to limit access to the same with typical parameters for cross-origin control filtering methods, etc ... @@ -140,7 +148,7 @@ Finally we set the type of response from our endpoints, to limit access to the s #### 1.4 Commands To initialize server the command is: -``` +```nash $node zen.js zen ``` @@ -153,11 +161,11 @@ $node zen config production 1980 ``` In this example we established that run *zen.js* file with these attributes: -> - config: Is the configuration file, replacing *zen.yml* that it is the default file (must be passed without extension *yml*). - production: The name of the file of environment for replace the existing environment attribute in the configuration file zen.yml. - 1980: The new port, replacing the declared in zen.yml - + +**config:** Is the configuration file, replacing *zen.yml* that it is the default file (must be passed without extension *yml*). +**production:** The name of the file of environment for replace the existing environment attribute in the configuration file zen.yml. +**1980:** The new port, replacing the declared in zen.yml + Note that it is not mandatory to set all parameters but respect the order thereof. With this, in case you want to assign a new port number, you must pass the following arguments. # 2. API server @@ -165,17 +173,17 @@ Note that it is not mandatory to set all parameters but respect the order thereo ## 2.1 Our first API endpoint We go to create a new file called *hello.coffee* in **/api** folder with this code: -> +```coffeescript "use strict" module.exports = (zen) -> zen.get "/hello", (request, response) -> response.json hello: "world" +``` In this case the exported file *hello.coffee* GET a single endpoint type and whose has path /hello, the callback that runs whenever you access it gives us two parameters: -> - request: It is the native object NodeJS but powered with zenserver. In later sections we will see the extras options that zenserver offers on this item. - response: Like the above is the native object, but as we can see with the (nonexistent in NodeJS) json function comes with extra features. +**request:** It is the native object NodeJS but powered with zenserver. In later sections we will see the extras options that zenserver offers on this item. +**response:** Like the above is the native object, but as we can see with the (nonexistent in NodeJS) json function comes with extra features. In this endpoint we are only returning a json object {"hello", "world"} thanks to **.json()** method of zenserver. @@ -183,7 +191,7 @@ En el caso de que quisiesemos capturar otros métodos http podríamos hacerlo en If we want to capture other methods http we could do it in the same file hello.coffee: -> +```coffeescript "use strict" module.exports = (zen) -> zen.get "/hello", (request, response) -> @@ -198,6 +206,7 @@ If we want to capture other methods http we could do it in the same file hello.c response.json method: "HEAD" zen.options "/api", (request, response) -> response.json method: "OPTIONS" +``` ## 2.2 URLs If we need have conditional URLs and that it is managed by the same endpoint, we might to use the conditional router of ZENserver. @@ -207,52 +216,56 @@ For example, we need an endpoint to get when access to an user and a determinate ## 2.3 Parameters With **request.parameters** we have an object with sended parameters. For example, with the URL: -> http://domain.com/user/soyjavi/messages?order_by=date&page=20 +**http://domain.com/user/soyjavi/messages?order_by=date&page=20** We have an object like this: -> + +```json { id : "soyjavi", context : "messages", order_by: "date", page : 20 - } - + } +``` + ## 2.4 Session control In case you want to control whether requests that have come to our meeting endpoint can use the request.session which in the case there will return the value of the session object. This may be via cookie or authentication via http. If we want to control if the requests have session, we could use the object **request.session**. This migth be via cookie or HTTP authentication. In the following example show how to established the cookie and how to do logout: -> +```coffeescript zen.get "/login", (request, response) -> response.session "10293sjad092a" response.json "cookie": true - zen.get "/logout", (request, response) -> response.logout() response.json "cookie": false - +``` ## 2.5 HTTP Status Messages For now we only know the json method superficially, besides setting the object that we want to return, we can indicate a HttpStatusCode (default 200) and a HTTPHeaders. For example: -> +```coffeescript values = username: "cataflu", name : "Catalina" headers = domain : "http://domain.com" response.json values, 201, headers +``` As you can see it's really simple, but to further facilitate the zenserver things HTTPStatus offers predefined. For example if a given endpoint want to return the client does not have permission just have to call response.badRequest () method and will handle zenserver create a 401 response with the message "Bad Request". ZENserver offers HTTPStatus predefined: -> response.badRequest() + +```json response.badRequest()``` Then list all HTTPStatus: -> + +```json 2xx Successful 200: "ok" 201: "created" @@ -276,12 +289,14 @@ Then list all HTTPStatus: 503: "serviceUnavailable" 504: "gatewayTimeout" 505: "HTTPVersionNotSupported" - 3. Servidor Páginas +```json + +### 3. Page server ## 3.1 Our firts www endpoint We are goint to create *form.coffee* file in **/www** directory and with this code: -> +```coffeescript zen.get "/form", (request, response) -> response.html """
@@ -291,13 +306,16 @@ We are goint to create *form.coffee* file in **/www** directory and with this co
""" +``` + We use **.html()** method to render all HTML code; it is similar to *.json()*. ## 3.2 Mustache template You've learned how to return HTML code in a particular endpoint, but really, this is not efficient option. Now you will learn to use the Mustache templates that are included in zenserver to facilitate reuse and management of your pages correctly. We are goint to create a file *base.mustache* in **/www/mustache** directory with this code: -> + +```html @@ -312,11 +330,13 @@ We are goint to create a file *base.mustache* in **/www/mustache** directory wit - +``` Now we create a new endpoint (index.coffee) that render create template when access to */*: -> + +```coffeescript zen.get "/", (request, response) -> response.page "base" +``` With the method **.page()** we indicate to ZENserver that search a file with name "base" in /www/mustache directory. @@ -326,24 +346,27 @@ If this file not exists, ZENserver search a 404.mustache file to render. And if In the previous chapter we have seen a simple page rendering by a Mustache file. Anyway we have not used any of the features Mustache offers. We will send details to our staff so that renderize, this is known as data binding. To do this we will modify our base.mustache template: -> + +```html ...

Hello World! {{title}}

... - +``` Now, we send through our enpoints the bingin "title": -> +```coffeescript zen.get "/", (request, response) -> bindings = title : "ZENserver" session: request.session response.page "base", bindings +``` ## 3.4 Blocks Imagine that we will use a section of HTML in multiple pages, it would be better to insulate this HTML code and to include it in all the templates you need, right?. Well let's see what we can do with our mustache template: -``` +```html + @@ -363,14 +386,13 @@ Imagine that we will use a section of HTML in multiple pages, it would be better We have created two references to mustache block *{{> partial.example}}* and *{{> partial.session}}*. We are goint to create in the same level of the rest of mustaches with **partial.example.mustache** name: -``` +```html

partial.example

subdomain: {{user.name}} mobile: {{mobile}}
partial.session.mustache -

partial.session

Session: {{session}} @@ -379,12 +401,12 @@ We have created two references to mustache block *{{> partial.example}}* and *{{ Logout
- ``` Now, from our endpoint we completed the new binding: -``` zen.get "/", (request, response, next) -> +```coffeescript + zen.get "/", (request, response, next) -> bindings = title : "zenserver" user: @@ -392,14 +414,13 @@ Now, from our endpoint we completed the new binding: session: request.session mobile : request.mobile partials = ["partial.example", "partial.session"] - response.page "base", bindings, partials ``` ## 3.5 Redirections If we need to do redirection to an another endpoint, we use the following method (**.redirect()**): -``` +```coffeescript zen.get "/dashboard", (request, response) -> if response.session response.page "dashboard", bindings, partials @@ -413,7 +434,7 @@ Although NodeJS is not the best way to serve static files zenserver provides a s Only we shall have to use the response.file method which will analyze the file type you want to serve and provide the best method of transmission. For example if we are trying to serve some sort of multimedia files such as video or audio, zenserver automatically performs a streaming it. Here's an example: -``` +```coffeescript zen.get "/vídeo/:id", (request, response) -> response.file "/assets/vídeo/#{request.parameters.id}.avi" ``` @@ -421,7 +442,7 @@ Only we shall have to use the response.file method which will analyze the file t As you can see it is very simple, since all zenserver responsibility to decide how to transmit the file is delegated. Noted that in the event that the file did not exist zenserver /assets/vídeo/?.id return a HttpStatusCode 404. The response.file method will make a small caching on the client, by default 60 seconds, in case you want to increase or decrease the caching, we just have to pass in the second parameter: -``` +```coffeescript url_file = "/assets/image/tapquo.jpg" response.file url_file, maxage = 3600 ```