node.jsexpresssails.jstemplate-engineejs

How to create global variables accessible in all views using Express / Node.JS?


Ok, so I have built a blog using Jekyll and you can define variables in a file _config.yml which are accessible in all of the templates/layouts. I am currently using Node.JS / Express with EJS templates and ejs-locals (for partials/layouts. I am looking to do something similar to the global variables like site.title that are found in _config.yml if anyone is familiar with Jekyll. I have variables like the site's title, (rather than page title), author/company name, which stay the same on all of my pages.

Here is an example of what I am currently doing.:

exports.index = function(req, res){
    res.render('index', { 
        siteTitle: 'My Website Title',
        pageTitle: 'The Root Splash Page',
        author: 'Cory Gross',
        description: 'My app description',
        indexSpecificData: someData
    });
};

exports.home = function (req, res) {
    res.render('home', {
        siteTitle: 'My Website Title',
        pageTitle: 'The Home Page',
        author: 'Cory Gross',
        description: 'My app description',
        homeSpecificData: someOtherData
    });
};

I would like to be able to define variables like my site's title, description, author, etc in one place and have them accessible in my layouts/templates through EJS without having to pass them as options to each call to res.render. Is there a way to do this and still allow me to pass in other variables specific to each page?


Solution

  • Update for Express Versions 4/5+:

    The best solution for handling this is still by using app.locals as documented in the Express API Reference. As some of the comments here note, the API was updated in Express 4 such that app.locals is no longer a function, but is now simply an object. So if you try to call it as a function you will get an error.

    To use app.locals in Express 4/5+ to accomplish the same thing as in my original example for Express 3 below, you could set app.locals like so anywhere in your application where you have access to the Express app object:

    app.locals = {
        site: {
            title: 'ExpressBootstrapEJS',
            description: 'A boilerplate for a simple web application with a Node.JS and Express backend, with an EJS template with using Twitter Bootstrap.'
        },
        author: {
            name: 'Cory Gross',
            contact: 'coryg89@gmail.com'
        }
    };
    

    This would make all of these values globally available within all views accessible as site.title, site.description, author.name, and author.contact respectively.

    NOTE: Alternatively, you can also set values on app.locals separately.

    For example, this would also work:

    app.locals.authorName = 'Cory Gross';
    app.locals.authorContact = 'coryg89@gmail.com';
    

    However, by default, this would not work, and would throw an error:

    app.locals.author.name = 'Cory Gross';
    app.locals.author.contact = 'coryg89@gmail.com';
    

    This happens because, while app.locals already exists as an object exposed by Express which you can define properties on, app.locals.author does not yet exist and so the above will throw an error complaining that you trying to set a property on an object that is undefined. In order to do the above you would first have to set app.locals.author = {} as an empty object or just set everything under app.locals or app.locals.author at the same time, similar to my first example above.

    Usage in Middleware

    Although, the values set on app.locals are made globally accessible in all views, one of the potential issues with using it in Express 3 was that those values were not necessarily accessible within middleware functions by default. Because of this limitation, one alternative, as originally suggested in Pickel's answer, was setting the values on res.locals in a top level middleware instead so that the values would be available in all lower middleware as well as in all views. However, this alternative came with the downside that the logic for setting all of these values would be executed over and over again for every single request/response rather than being set one time and persisting as long as the server is running as is the case with app.locals.

    In Express 4/5+, there is now a better solution if you want the values that you're setting on app.locals to be available within middleware functions as well as in all views. To solve this issue, the Express 4/5+ API now exposes the Express app object within all middleware functions, accessible as a property on the req parameter as req.app. So, by default, you can now easily access all of the global application scoped values set on app.locals within all middleware functions as well simply by accessing the object as req.app.locals within your middleware.

    Original Answer for Express Version 3:

    After having a chance to study the Express 3 API Reference a bit more I discovered what I was looking for. Specifically the entries for app.locals and then a bit farther down res.locals held the answers I needed.

    I discovered for myself that the function app.locals takes an object and stores all of its properties as global variables scoped to the application. These globals are passed as local variables to each view. The function res.locals, however, is scoped to the request and thus, response local variables are accessible only to the view(s) rendered during that particular request/response.

    So for my case in my app.js what I did was add:

    app.locals({
        site: {
            title: 'ExpressBootstrapEJS',
            description: 'A boilerplate for a simple web application with a Node.JS and Express backend, with an EJS template with using Twitter Bootstrap.'
        },
        author: {
            name: 'Cory Gross',
            contact: 'coryg89@gmail.com'
        }
    });
    

    Then all of these variables are accessible in my views as site.title, site.description, author.name, author.contact.

    I could also define local variables for each response to a request with res.locals, or simply pass variables like the page's title in as the optionsparameter in the render call.

    EDIT: This method will not allow you to use these locals in your middleware. I actually did run into this as Pickels suggests in the comment below. In this case you will need to create a middleware function as such in his alternative (and appreciated) answer. Your middleware function will need to add them to res.locals for each response and then call next. This middleware function will need to be placed above any other middleware which needs to use these locals.

    EDIT: Another difference between declaring locals via app.locals and res.locals is that with app.locals the variables are set a single time and persist throughout the life of the application. When you set locals with res.locals in your middleware, these are set everytime you get a request. You should basically prefer setting globals via app.locals unless the value depends on the request req variable passed into the middleware. If the value doesn't change then it will be more efficient for it to be set just once in app.locals.