xipframe

MVC Framework for Express

npm install xipframe
61 downloads in the last week
78 downloads in the last month

Build Status NPM version

New Release 1.x.x

Xipframe has been redesigned from the ground up. If you followed along with the concept project, you know a lot of ideas were thrown at that version. The idea was to see what we liked and what we thought were vestigial. The all new version is greatly simplified but with many improvements. Again the focus is on RESTful apis and in particular Angular although Xipframe is perfectly compatible with many other client-side frameworks.

The conventions are similar to the depreciated version of Xipframe however some of the configuration has changed along with a few new properties. If you're interested in seeing to what degree they've changed you might want to look at the "Configuration.js" class under /lib/core in the project.

NOTE: License Change

The license has been changed to MIT from GPLv3 to better accommodate developers and add greater flexibility.

Features

  • No need for Global vars, context is maintained through all objects e.g. Controllers, Middleware, Models and more.
  • Generate Models, Controllers, Middleware, Views and more.
  • Extensive View Engine support using consolidate.js
  • Configuration automatically backed up on install and each start/load.
  • No third party router. Uses default Express router. Updating Express/Connect will not break your api.
  • Asset Linker makes linking resources to any view automatically very easy. You can link all resources to single or multiple views or link asset to specific view.
  • Automatic minification and concatination.
  • Highly configurable logger. Log to file and console individually or collectively. See detailed stack information for offending file or even the full stack.
  • Custom external template location for generating platform specific app. e.g mobile vs desktop.
  • Load predefined configuration file to be merged in on install (saves time, good in conjunction with custom templates).
  • Middlware ignore static paths improves routing negotiation.
  • Socket.io integration with pub/sub.

View Change Log

view here

Documentation

Please visit http://www.xipframe.com for complete documentation include Api Documentation.

If you care to drill down into the details you can checkout the Api Documentation. It is commented well and will be updated frequently including photos and videos as time permits.

In the meantime see below to get you up and running.

Installing Xipframe

Note when installing if on Windows you may wish to use the --msvs_version=2012 where 2012 is the version of Visual Studio you have installed. Always install Xipframe globally.

npm install xipframe -g

Install an App

From a command line run the below where "AppName" is the name of your application:

xipframe install AppName

Run an App

xipframe start
xipframe start AppName (if not in current directory name the app you want to start)

Uninstall App

This will uninstall the application reference and all folders and files.

xipframe uninstall AppName

Remove App Reference

Xipframe stores application path references. If you delete your app manually you may need to tell Xipframe to remove its reference.

xipframe remove AppName

Generate Controller

Generates the controller and template actions. The below would create a get action, get by id a create action, update action and destroy or delete action.

xipframe generate controller get getById create update destroy

Generate Model

xipframe generate model user firstName lastName email age:integer
(valid types: string, text, integer, float, date, time, datetime, boolean, binary, array, json)

Generate Middleware or View

Both simply create a template for you to work with no real options, although you can create multiple types of templates for views and call them by name. Say if you had a mobile layout vs desktop layout. View templates must have the extension ".tpl". View templates have access to the global configuration object so any configuration option if you needed it can be rendered on generation. Generation uses hogan.js for its generation internally. However Xipframe can use just about any view engine available when views are actually rendered in your app. See consolidate.js. Define your view engine in the server.js file under configuration in your app. More on this to come.

xipframe generate view ViewName (gen view in sub folder "user" you might do xipframe generate view /user/profile).
xipframe generate middleware MyMiddleware

Configure Controller

Every middleware, security filter and controller have access to the full Xipframe object including models. No globals needed.

module.exports = {

    action: function (req, res, next){

        var Model = this.models[model_name] // where "model_name" is the name of your model.

        // req.data - contains all of your params, body post data, query params etc.
        // req.data.query - all the query string params.
        // req.data.body - all the form data posted.
        // req.data.pagination - properties such as "sort", "limit" and "skip".
        // req.data.where - properties for where finds.

        // all properties are avail singularly as well so if you have a query param
        // called "userid" you could access it by req.data.userid.

        Model.findOne({ id: req.data.id }).done(function(err, model) {

            if(err || !model) {

                // want to pass along validation messages in the error?
                // Do next(new ValidationError('custom message', err)
                // where err would contain the codes failed from the orm.

                // just pass it along and Xipframe will handle logging and
                // passing on to your handler or the default.
                if(err) next(err);

                // helper responses make it very easy res.denied(),
                // res.badRequest(), res.serverError(). you can also pass a custom message
                // to any res.notFound('my custom message').
                else res.notFound();


            } else {

                // returning json.
                res.json(model.toObject());

                // return view.
                // res.render('view_name', { some: 'local' });

            }

        });

    }

};

Configure Route

Routes can be specified either by defining controller and action in an object, a single dot notation string or an array of strings.

moduel.exports = {

    'get /user': {
        controller: 'user',
        action: 'showAll'
    }

    // same as above but with string notation.
    'get /user': 'user.showAll'

    // same as above but with security filter prior to routing to controller.
   'get /user': [ 'authenticated', 'user.showAll' ]

    // redirecting to another route.
    'redirect /users': 'user.showAll'

    // render a view.
    '/new/user': 'view /user/create' // where user is a sub folder and create is the view (no extension needed)

};

Configure Security Policy

Policies protect controller resources. Even those generated by Xipframe. You can create multiple "Policy" files however they are merge at runtim so Object keys must be unique. For example if you have a model called "user" and you have Xipframe generating routes based on models, then you'll be able to generate a policy as below:

module.exports = {

    user: {
        '*': true // allows true for all controller actions, false requires authentication.
        show: 'authenticated' // specify the security filter or array of filters to protect this resource.
    }

};

Configure Security Filter

module.exports = function authenticated (req, res, next) {

    if(!req.session.authenticated){

        // not authenticated so deny access or more likely redirect to login.
        res.denied();

    } else

        // all is well continue down stack.
        next();

    }

};

Using the Linker

The linker is a very powerful tool in Xipframe. You can set resources to be applied to multiple views or you can set a specific resource to multiple views. It is very flexible. In the original concept version of Xipframe many of these resources were applied to he linker automatically. Through feedback we've decided not to add these automatically. There are just too many variations of how you might need this setup. The biggest change from the concept version is that CSS and Scripts are in separate objects. Otherwise it is very similar.

module.exports = {

    enabled: true,  // enables or disables the linker feature.

    views: ['index.html'], // can be just a string, or an array of strings. if array all sources will be applied to these views.

    sources: {

        // sources options:
        // source: the path to the source to be linked. (required)
        // enabled: whether or not the item is enabled, yes you could just comment out. (optional)
        // view: can be string or array. this resource will be linked to the specified view or views (optional).
        // replace: replaces text in your source. good for versioning. can be string or array of string. if array replaces by index. think of it like string format. (optional)

        // NOTE: replace uses hogan syntax ex: source: '/path/to/{{version}}/style.css', replace: '2.1'

        css: [
            { source: '/path/to/style.css' }
        ],

        js: []

    }

};

Context within Xipframe

It's good to note that Xipframe maintains the context throughout. Hence any middleware, filter, controller and so on will contain proper reference to "this". What does that mean? Well it means that your models for example are readily available from anywhere. By doing this it prevents the need to expose a bunch of global vars. Which in some cases might be preferred by some however to me this way just feels better to us.

Perhaps you want to grab something in your configuration within a middlware you might do the following:

var server = this.configuration.server;

var port = server.port;

// do something with the port.

Where's Depreciated Version 0.3.9

If you are looking for the depreciated concept version of Xipframe you can find it here.

License

see

npm loves you