Grasshopper

Getting started

You will find that many concepts that modern applications need are built right into Grasshopper. User management, flexible data storage, permissions, plus much more are bundled into the framework.

Grasshopper is modular and built on top of a modern web development stack. It was written entirely in JavaScript and it uses a NoSQL database system. File storage can either be local or in the cloud on a CDN. As the project matures, more database systems and CDN options will become available.

Currently, Grasshopper will run in any environment that supports Node.js and MongoDB. This is great news since loading Node.js apps into modern cloud containers is very simple. Users hosting the application themselves or using services like Heroku, Engine Yard or any other PaaS (Platform as a Service) are fully supported.

Every implementation of the system is different but keep reading and you will start to get a sense of how the project is organized.

Grasshopper Stack

Typical Grasshopper Application Stack

Requirements

The Grasshopper framework uses all of the below software/services:

• Git version control system.

• Node.js, a platform for easily building fast, scalable network applications.

• MongoDB, an open-source document database that Grasshopper uses for data storage.

• Grunt, the JavaScript task runner

• bower, a package manager for the web

• Sass, Syntactically Awesome Style Sheets.

• Bundler: Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.

• Sass Globbing Plugin (used to compile the admin), Sass globbing allows you to import many sass or scss files in a single import statement.

• Sass CSS Importer (used to compile the admin): The Sass CSS Importer allows you to import a CSS file into Sass.

• Access to local file system or CDN like Amazon S3.

Installation

Installing Grasshopper is super simple. Once your machine is configured, creating a new project is as easy as typing grasshopper fly.

The installation process fully configures working instances of core, api and admin for you.

See the example of how to install the NPM and setup a new project. We assume that all of the prerequisite software is already installed.

Watch a video of an installation (less than a minute):

Configuring your project

When you run the grasshopper fly command, you get a fully functional application, but you may want to change some of the configuration values. The configuration values are passed into grasshopper-api.

Api / Core

Start grasshopper api is done by requiring it in and passing in an options object. A convenient way to do this is to create a JSON config file and use it as the options object as follows:

var ghapi = require('grasshopper-api'),
    options = require('./grasshopper-config.json'),
    ghcore,
    ghapiRouter,
    returnedObject;

returnedObject = ghapi(options);

// the router should be used in conjunction with express
// it can be added directly to the app or piggy backed on another router
// e.g. expressApp.use('/api', ghapiRouter);
ghapiRouter = returnedObject.router;

// ghcore can be used to make queries, etc.
ghcore = returnedObject.core;

Here is an example file:

{
    "server": {
        "https":{
            "key":"{full path to key}",
            "cert":"{full path to cert}"
        },
        "proxy" : false,
        "maxFilesSize": 2000000,
        "maxFieldsSize": 2000000,
        "maxFields": 1000
    },
    "crypto": {
       "secret_passphrase" : "{unique term per project}"
    },
    "db": {
       "type": "mongodb",
       "host": "mongodb://localhost/{database name}",
       "shorthost":"localhost",
       "database": "{database name}",
       "username": "",
       "password": "",
       "defaultPageSize" : "10000",
       "debug": false
    },
    "assets": {
       "default" : "local",
       "tmpdir" : "{absolute path to tmp directory}",
       "engines": {
            "local":{
                "path":"{absolute path to public asset folder from the root of your comp}",
                "urlbase":"{full url base to serve files from}"
            }
       }
    },
    "logger" : {
       "adapters": [{
            "type":"console",
            "application":"{application name}",
            "machine":"{machine name}"
       }]
    },
    "identities" : {
        "google" : {
            "appId" : "{ your google app id }",
            "secret" : "{ your google secret id }",
            "scopes" : [ "{ array of scopes you want to authorize }" ],
            "redirectUrl" : "{ the url you want to redirect to after successful auth, the users token will be appended to this route ex. '/login' entered here will send the user to '/login/googleToken' }"
        }
    },
    "bodyParser" : {
        "limit" : "5m"
    }
}

Authentication

Membership is a critical component to almost all applications. Grasshopper's authentication methods are fully extensible, and it contains a robust permissions mechanism that allows you to protect data based off of the application’s requirements.

Supported Authentication Methods

• Basic: This is the typical username and password method
• Google: Allows you to authenticate with your Gmail account.

Setup Google Login

1. Ensure that the identities.google object on your ghapi.json is correctly setup.
2. Ensure that you have added both a a redirect uri and a javascript origin to your Google Developer Console OAuth configuration.
   • The javascript origin is the root of your website. For example:
     • http://localhost:3000
     • https://www.grasshopper-admin-sample.herokuapp.com
   • The redirect uri should be the root of your website with the following append to the end /oauth2callback. This endpoint is where google will send the authenticated users temporary token. This endpoint already exists in Grasshopper-Api. This would create the following url's from the examples mentioned above:
     • http://localhost:3000/auth2Callback
     • https://www.grasshopper-admin-sample.herokuapp.com/oauth2callback
3. Setup the methods to get the googleAuthUrl from API then send the user there. The GET /googleurl endpoint is already available on Api.
   • This endpoint is not authenticated.
   • This endpoint can also take an override redirect url. If you use this override, it will redirect the user back to that url with the grasshopper token in the url after all auth work is done.
4. Modify your applications routes to collect the grasshopper token from the redirected route. Grasshopper API will redirect the user back to your app with the grasshopper token appended to the redirectUrl you specified in your config. If you overrode this by passing it as a header in the /geturl request, then it will be appended to that url.
   • If your redirectUrl in your config was: /login, then the user is redirected to /login/{ grasshopperToken }.
   • If you overrode your redirectUrl then you will see: /someOtherPage/{ grasshopperToken }.
   • Your route will need to be able to accept the returned url, in backbone, this might look like: 'login(/:token)'. Where the () signifies an optional param. Then a /. Then a :token. The word 'token' in the example is important as this will be passed the the route function as a parameter.
5. Once you have a handle on the grasshopper token, save it to local storage, prepended with 'Google '.

Check out our sample projects for examples of both of these authentication methods in working applications.

Users

User Properties

    {
        _id: 12345657,
        role: 'admin',
        enabled: true,
        firstname: 'firstname',
        lastname: 'lastname',
        identities: {
            basic: {
                username: 'admin',
                salt: '111111111',
                hash: '282828282828282828'
            },
            google: {
                id: '292929292929292',
                accessToken: '474747474747'
                refreshToken: '4098409874'
            }
        },
        displayname : 'admin',
        linkedidentities : ['basic'],
        email: 'apitestuser@thinksolid.com',
        profile : {}
    }

User Roles

Roles (in order of power) :

1. Admin - Can do anything.
2. Editor - Can create and edit content and content types.
3. Author - Can only create content.
4. Reader - Can only read content.
5. External - Cannot access the admin in any way.

User methods

• users.query

  • middleware.identity,
  • middleware.role(roles.ADMIN),
  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.users.query,
  • middleware.event('out')

• users.insert

  • middleware.identity,
  • middleware.role(roles.ADMIN),
  • middleware.users.linkedidentities.create,
  • middleware.users.parse,
  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.users.validate,
  • middleware.users.insert,
  • middleware.event('out'),
  • middleware.event('save')

• users.update

  • middleware.identity,
  • setDefaultUser,
  • roleOrSelf(roles.ADMIN),
  • middleware.users.parse,
  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.users.validate,
  • middleware.users.update,
  • middleware.event('out'),
  • middleware.event('save')

• users.getById

  • middleware.identity,
  • setDefaultUser,
  • roleOrSelf(roles.ADMIN),
  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.users.getById,
  • middleware.event('out')

• users.getByEmail

  • middleware.identity,
  • middleware.role(roles.ADMIN),
  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.users.getByEmail,
  • middleware.event('out')

• users.deleteById

  • middleware.identity,
  • middleware.role(roles.ADMIN),
  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.users.deleteById,
  • middleware.event('out'),
  • middleware.event('delete')

• users.savePermissions

  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.identity,
  • middleware.role(roles.ADMIN)

• users.deletePermissions

  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.identity,
  • middleware.role(roles.ADMIN)

• users.linkIdentity

  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.identity,
  • middleware.users.linkIdentity,
  • middleware.event('out'),
  • middleware.event('save')

• users.unlinkIdentity

  • middleware.event('parse'),
  • middleware.event('validate'),
  • middleware.identity,
  • middleware.users.unLinkIdentity,
  • middleware.event('out'),
  • middleware.event('save')

Content

Queries

Grasshopper's query builder accepts a query object that contains several parameters, some optional.

The returned object is an array with limit, skip and total. The total is the value of all content matched by query, not just returned objects.

Definitions for all possible query parameters/options

• filters: An array of optional filter objects for the query.
  • key: The key of the content being filtered.
  • cmp: The comparison operator for the filter value. Currently supported operators (Query accepts symbol or string value):
    • '=': equals
    • '!=' or 'not' or 'notequal' or 'notequals': not equal to
    • '>=' or 'gte': greater than or equals
    • '>' or 'gt': greater than
    • '<=' or 'lte': less than or equals
    • '<' or 'lt': less than
    • 'in' or 'contains': contains
    • '!in' or 'notin' or 'notcontains': does not contain
    • '%' or 'like': like (Allows for 'fuzzy matching')
    • '!%' or 'notlike': not like (Allows for 'fuzzy matching')
    • 'between': between
    • 'notbetween': not between
    • 'size': size
    • 'exists': exists
  • value: Then value the filter will be compared with.
• types: An optional array of content type ids.
• nodes: An optional array of node ids.
• options: Object. Possible key/value pairs are:
  • * limit : Limit number of results. String or number.
  • * skip : Skip specified number of results. String or number. (limit and skip support pagination)
  • * distinct : return distinct results within a find. Can include types.
  • * exclude : array of fields to be excluded from query.
  • * include : array of fields to be included in query.

Important Notes:

• The options object can have include or exclude parameters, but not both in the same query.
• When using 'options.distinct', filters can't be used. This means paging is not available.

Contributing

Grasshopper is an open source project that is available on Github and it has been sponsored by Solid Digital. We fully appreciate the contributions that have been made so far and we are excited for future development of this platform.

If you find bugs or have issues please submit them to github issues:

• Issues for Grasshopper Core
• Issues for Grasshopper API
• Issues for Grasshopper Admin
• Issues for Grasshopper CLI

To contribute back to the project, you should fork the projects make your changes and submit merge requests back to us.

Setting up your development environment

If you are doing full stack development on Grasshopper you should setup all projects in the solution to work locally.

The grasshopper-admin project comes with a server directory that can run grasshopper-api and the grasshopper-api project loads in grasshopper-core.

It is really easy to setup local versions of each of the projects so that you can do all of your development without publishing npms.

The key is to link your local grasshopper-core and grasshopper-api npms to be treated as globals.

More information on the technique using NPM LINK can be found here.

Before you start

Make sure that you development machine meets the minimum REQUIREMENTS

To test locally, you will be running a node app from /server. This app will run an instance of grasshopper-api. The app must be configured to serve the correct data (local or remote).

The configs are pulled from the environmental variable GRASSHOPPER_CONFIG if available or the fallback ghapi.json file.

Setup ghapi.json in the /server directory of the grasshopper-admin project. This is the config file that has the server and database info for your local dev work and it is .gitignored.

For an example of what this should look like, see CONFIGURING YOUR PROJECT.

Development server

The grunt server task will start a local express server running the API. It will also start a watch for the files in the admin project. If you save a file then it will be updates and the page will be refreshed.

If you make changes to your local core or api projects. This just restart the node server process to apply your changes.

When you finished

Once you are have finished your dev work on grasshopper-api or grasshopper-core, you should publish the npm or submit a merge request.

To test the new npm, you should unlink grasshopper-api and/or grasshopper-core and pull the dependency in from npm:

cd ~/workspace/grasshopper-admin/server
npm uninstall grasshopper-api
npm install --save grasshopper-api@[the newly published version]

Documentation around removing npm dependencies is available at:

https://www.npmjs.org/doc/cli/npm-uninstall.html

https://www.npmjs.org/doc/cli/npm-rm.html (npm unlink -h)

Deploy to a test environment

If you have a heroku account, then you can deploy to it using the grunt deploy:heroku command .

What you need

• Your development environment should already be setup (see above)
• A ghapi.json file that includes your application configuration at {proj-root}/ghapi.json
• Set heroku environment variables (so you don't commit your private info). `
• Publish to heroku grunt deploy:heroku

Once the environmental variables are on heroku there is no need to load them again, unless you want to change them. If you ever need to update your environment variables just re-run grunt deploy:heroku:setupConfigs