Utils

Domingo Ernesto Savoretti edited this page Apr 2, 2014 · 26 revisions
Clone this wiki locally

Non routing-related methods and properties

Listing, in no particular order and by no means complete of the support tools that NSR has to offer

Stand-alone utilities

  • mk-server: tiny tool that constructs a web server (server. coffee, or server.js if invoked adding js argument, like so: mk-server js; stay tuned though, because the order of precedence, i.e. making js the default may change upon feedback received). It's also planned to add it the capability of generating a full web app, not just a server. If you install NSR globally this tool will be available system wide.

router.utils

  • router.utils.mime_types: a dictionary of mime types, initially devised to be used in NSR inner workings, it became - as happened to other constituents of NSR, you'll see more of this - a handy element by itself.

  • router.utils.uuid: unique identifier returning utility, initially devised to be used for cookie related activities, specifically session handling, may be invoked like so: var uid = router.utils.uuid(); // '1644197d-97ae-4ba1-e6bc-18200f00fb31' It is inspired in code found here and it's hopefully random enough. However, should it prove not, as everything else in NSR, it is pluggable-unpluggable, so you can, for instance write function great-uuid-gen() and then use it: router.utils.uuid = great-uuid-gen

  • router.utils.isEmptyObj: as the name implies, may be used to determine if a given object lacks 'own' properties, for example:

     router.utils.isEmptyObj({})  // true

     router.utils.isEmptyObj({name: 'Joe'}) // false 
  • router.utils.extendObj(destObj, srcObj): method that extends the destination object (first argument) with the properties of the source object (second argument), overwriting those that are present in both objects and adding those that are lacking in the destination object, for example:
    var srcObj = {age: 60, titles: 34};
    var destObj = {name: 'Joe', age: 59};
    router.utils.extendObj(destObj, srcObj); // returns {name: 'Joe', age: 60, titles: 34} which is the value now destObj has.
  • router.utils.cookie2obj(cookieString) and router.utils.obj2cookie(obj): mostly self explanatory, like this:
    var cookie = "name=Joe; age=60; titles=34";
    var obj = router.utils.cookie2obj(cookie); // returns {name: "Joe", age: 60, titles: 34}
    obj.city = 'Rosario';
    var newCookie = router.utils.obj2cookie(obj); // returns "name=Joe; age=60; titles=34; city=Rosario"
  • router.getCookie(request, cookie_name): retrieves the current request.headers.cookie as a javascript object, unless the argument cookie_name is provided, in which case the object returned has only one property, this is cookie_name if it is present in the cookie, or an empty object if not. For example:
    //The original cookie: "preferredColor=red; nsr_id=1644197d-97ae-4ba1-e6bc-18200f00fb31"
    router.getCookie(request); // returns {preferredColor: "red", nsr_id: "1644197d-97ae-4ba1-e6bc-18200f00fb31"}
    router.getCookie(request, "nsr_id"); // returns {nsr_id: "1644197d-97ae-4ba1-e6bc-18200f00fb31"}
    router.getCookie(request, "times_here"); // returns {} 
  • router.setCookie(response, cookie_obj, max_age): on the other hand, setting cookies server side implies setting a header in the response object. The second argument is an object, not a cookie string; optional max-age sets an expiration time. If it isn't provided the cookie will be a session one, that is it will last until the browser is closed. In case max-age is provided, it may be 0, thus in proactice deleting the corresponding cookie key. Example:
    router.setCookie(response, {useExternalReader: true}); // session cookie
    // or
    router.setCookie(response, {useExternalReader: true}, 60 * 60); // cookie will last an hour
    // or
    router.setCookie(response, {useExternalReader: true}, 0); // deletes "useExternalReader cookie value
  • router.get_icon(x, y): this method retrieves a string representing a DOM fragment that can be included in the response, for example:
    var image1 = router.get_icon(0, 0); 
    // the former retrieves '<img src="/pixel.gif" style="width: 30px; height: 30px; 
    // vertical-align: middle; background-image: url(/icons.png); background-position: -5px -8px;" />'
    response.end(image1);

This deserves a little explanation: NSR provides 3 "stock" images: favicon.ico, which has been explained elsewhere, pixel.gif, a 1x1 pixel transparent image and icons.png, an image containing a variety of icons. You can try the 3 of them by launching a NSR powered server and then pointing your browser to, for instance: http://localhost:8000/favicon.ico and http://localhost:8000/pixel.gif and http://localhost:8000/icons.png. The present method uses a well-known technique to show a "sprite", using icons.png as base and retrieving an image having a background which is an offset into icons.png. An example of this in action can be seen in any static directory listing returned by NSR.

  • router.utils.stock_icons: container object for sugar methods that wrap a call to router.utils.get_icon Right now, there are two of them: directory and file that retrieve a folder icon and a generic file icon respectively. Example:

    var directory_icon = router.utils.stock_icons.directory(); // same as calling router.utils.get_icon(13, 3);
    var file_icon = router.utils.stock_icons.file(); // same as calling router.utils.get_icon(20, 3);

More of these soon...

router.gallery

router method that renders a directory performing a slide show with the images it contains, using a template that includes CDN downloading of reveal.js, the great library by Hakim El Hattab

Its signature is router.gallery(full_directory_path, shown_path, response, list_func) To be used in code like this:

    router.get('/slideshow', function(request, response) {
        router.gallery('' + router.static_route + '/slides', '/slides', response);
        // Never mind the missing last argument, as NSR provides a reasonable default.
        // Furthermore, it's best not to mess with it.
    }); 

You can see it in action at NSR demo site

control flow (async programming)

this issue deserves a chapter by itself (or rather, a book), see Async