A JavaScript (browser) library facilitating interaction with The Groundwork Platform.

Learn more about our platform APIs.

1. Overview
2. Configure
3. Profiles
4. Authentication
5. Donations
6. Subscriptions
7. Supporters
8. Events

Production (minified)

https://cdn.thegroundwork.com/groundworkjs/1.1.1/groundwork.min.js

Development (additional logging)

https://cdn.thegroundwork.com/groundworkjs/1.1.1/groundwork.js

Check out the repository and build a stand-alone distributable:

$ npm install
$ npm run dist

The compiled files will be in the /dist folder.

You can read the API documentation for the client itself here.

There are some examples of the client itself here.

import Groundwork from 'groundwork.js';

// Create a new Groundwork client using your client id
let gw = new Groundwork({
  'apiKey': 'abc123'
});

// Collect user information from a form
let signUpData = {
  email: form.emailAddress,
  givenName: form.firstName,
  familyName: form.lastName,
  phone: form.phone,
  postalCode: form.postalCode,
  source: "form_frontpage_campaignXYZ"
};

let handleSuccess = function(res) { /* Handle successful signup */}
let handleErrors = function(err) { /* Handle error during signup */}

// Create a new supporter using the collected data and handle success or error states
gw.supporter.create(signUpData)
  .then(handleSuccess)
  .catch(handleErrors);

A+ Grade browsers

Before working with the library source, you'll need to install some reqiured packages:

npm install

To build a standalone library file and documentation:

npm run dist

This will create a minified and non-minified file in dist and updated documentation will be in doc. Note: when making a release (see below) the dist files are built and pushed up for you.

Documentation is generated using ESDoc:

npm run docs

This library is written in ES2015 and compiled to ES5 via Babel. Tests are written with Jasmine and run with Karma.

This project uses GitHub Flow (longer explanation) as a deployment model. Please make feature branches from master and then PR them for review.

Setup your environment:

You need NodeJS and npm installed.

npm install

Run the development environment:

npm run dev

A compiled groundwork.js is served from localhost:8080.

Run the examples:

npm run examples

This will rewrite the files in /examples to use the current locally compiled version of groundwork.js instead of the CDN version. Useful for testing your work in an HTML page. The files are served from localhost:3030

Run the tests:

npm test # starts a watcher that runs automated tests in multiple browsers
npm run test-ci # runs automated tests in PhantomJS & Firefox just once

There are an additional set of integration tests which hit the live Dev API. These should only be run if:

1. You have access to the dev environment
2. You don't mind waiting for live requests to go through

To run them, copy the contents of /integration_test into /test and then run npm run test-phantom. You will get some fails from existing tests during this run.

Make a release:

Once you have a working release ready to go it needs to be tagged. Update the version property in package.json and commit the file. Then run the release script:

npm run release

This will create a tag with the version number, build the dist files and push them up to the repo.

Groundwork.js

Copyright © 2016 - Timshel / The Groundwork, all rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.