@tablelist/tablelist-js-sdk

#Javascript SDK

##Table of Contents

1. Getting Started
2. Usage
3. Contributing *Code Style Guidelines *Tests *Publishing *Code Quality *Versioning *JsDoc *Gulp *Demo App *Admin Only Functionality

---

###Getting Started

1. Clone the repo
2. Run npm install

###Usage

1. Add the NPM dependency tablelist-js-sdk to your package.json
2. Add the Js SDK script to your html file, and add Js SDK dependencies to your html file:

<script src="../node_modules/angular/angular.min.js"></script>
<script src="../node_modules/angular-resource/angular-resource.min.js"></script>
<script src="../node_modules/angular-cookies/angular-cookies.min.js"></script>

#Contributing ###Code Style Guidelines

1. Always add JSDoc attributes
2. Use ES6 wherever possible
3. Use single quotes instead of double quotes
4. Always use camel-case for file names and directories. Ex. jsSdk.js not js-sdk.js
5. Always namespace services, factories, etc... with jsdSdk. Ex. jsSdk.venueService or jsSdk.config
6. When using Angular's ng-resource always return the promise object Ex.

  login(email, password) {
    return auth.login().$promise;
  }

###Tests

• Run npm test

###Building

$ gulp release

###Publishing

To publish a new version of SDK to NPM follow these steps:

1. Make your changes the SDK
2. Bump the version number in package.json
3. Write Unit Tests to verify your new code is working properly.

You can also run the Demo App (gulp run-demo) and add new pages to the demo app if you'd like to test any code within an actual browser. Usually testing with Unit Tests will be sufficient, but sometimes it's nice to verify things are working in a real browser/app setting.

3. That's it! The build system will build and test your code. If the build passes your code will be deployed and published to NPM automagically. The JsDocs will also be regenerated and published to http://tablelist-js-sdk.herokuapp.com/

###Testing

$ gulp test

To run a subset of the tests, use fdescribe. This will skip all other tests.

Just put an f before the group of tests/test you want to run, such that the test block begins with fdescribe(...)

Files must have -test in the name. For example: create-test.js.

Alternatively, you can replace the function describe(.... with describe.only(.....

###Code Quality

• Run gulp jsquality - this will run jshint and jscs. The build will fail if this task fails.

###Naming Conventions

If an endpoint requires an ID/input of an object that isn't of the current service. Please specify that in the name. For example, to list all venues in a given city:

eventService.listByCityId(cityId)

However, we do not need to specify in the .read function, since it requires the ID of an event.

eventService.read(eventId)

###Versioning

• Use Semantic Versioning

Documentation

Use the JSDocs format for adding documentation

JsDocs can be generated to view all the classes and methods available in the project

• Run gulp jsdoc to generate the docs
• Run gulp open-jsdoc to open the results in your browser

Documenting Modules

Example:

/**
 * Booking Service
 *
 * @module booking
 * @submodule booking-service
 */

Documenting Methods

JSDocs format for methods:

Example:

/**
 * Read a booking object
 *
 * @param {String} id - Booking ID to read
 * @param {Object} options
 * @return {Promise}
 */

More info on JSDocs format for methods.

Example: Note the addition of optional fields and

/*
 * Create an organization member
 *
 * @param {Object} options
 * @param {String} options.organizationId - ID of organization to add member in
 * @param {String} options.email - email of member to add
 * @param {String} [options.name] - first name of member to add (optional)
 * @param {String[]} options.venueIds - array of venue IDs member has access to
 * @return {Promise<OrganizationMember>} newly created organization member
 */

You can define return types like Promise<Object> or in this example - a kind of a fake type Promise<OrganizationMember>

###Gulp

• Run gulp ? to list all Gulp tasks

###Demo App

• Run gulp run-demo to start a demo app. This can be helpful for debugging issues with the SDK and is a good starting point for applications using the SDK.

###Admin Only Functionality Multiple builds of the SDK are generated. 1 for non-admin, and 1 for admins. The build generated for admins includes functionality that is only available to Tablelist admins. The way this is controlled is by decorating functions with special comments to tell the build process to exclude/include depending on the build type.

Example:

//removeIf(NON_ADMIN_BUILD)

/** @method */
/**
 * @param {Object} options
 * @return {Promise}
 */
create(options) {
  if (!options) throw new Error('jsSdk.commonService - create() - options is required');

  return this._resource.create({}, options).$promise;
}

//endRemoveIf(NON_ADMIN_BUILD)

This function will only be included in the tablelist-js-sdk.admin.js build.

###Adding New Resources When adding new resources follow this pattern:

angular
  .module('jsSdk').service('jsSdk.venue.resource', [
    'jsSdk.resourceFactory', (resourceFactory) => {

      const ENDPOINT = '/venue/:id';
      const PARAM_DEFAULTS = {
        id: '@id'
      };

      let Venue = resourceFactory(ENDPOINT, PARAM_DEFAULTS, {});

      return Venue;
    }
  ]);

The endpoint for your resource should always include the id param, and be sure to specify the id param in PARAM_DEFAULTS.

###Caching

js-sdk includes support for caching API calls at the Angular.js Resource level. Use the cacheConfigProvider, and call .cacheResourceEndpoints to specify which endpoints to cache. Example:

angular.module('angularApp').config([
 'jsSdk.cacheConfigProvider',
 (cacheConfigProvider) => {
   cacheConfigProvider
     .cacheResourceEndpoints('jsSdk.venue.resource', [
       'list'
     ]);
 }
]);