humanity-js-sdk

Humanity JavaScript SDK

This package provides easy access to the Humanity API and IFrame SDK.

Before using, you will need to create your application and get the Application ID at the Humanity Developers Portal.

Refer to the Humanity API Docs for the available resources.

Installation

For NodeJS

npm install humanity-js-sdk

For browsers

bower install humanity-js-sdk

Usage

NodeJS

var Humanity = require('humanity-js-sdk');
 
// Instantiate auth class
var auth = new Humanity.Auth('your_client_id', 'your_redirect_uri', null, ['company.view'], 'your_secret');
 
// Generate SignIn URI
var signInUri = auth.generateSigninUri(); // https://accounts.humanity.com/oauth2/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri%2F&company_id=&scope=company.view&response_type=code
 
// Redirect to the signInUri, and then depending on the http framework, set up a route for your redirect_uri
// The following example is for the express framework
app.get('/auth', function (req, res) {
    var authorizationCode = req.query.code;
 
    // Get the token
    Humanity.getToken(authorizationCode, function (token) {
        // Make a request using the token
        Humanity.get('companies', {}, token.access_token, function (response) {
            console.log(response);
        });
    });
});

Browser

Using the API

// Import the library using your desired module loader (AMD/CommonJS/ES6)
// Using CommonJS as an example
var Humanity = require('humanity-js-sdk');
 
// Instantiate auth class
var auth = new Humanity.Auth('your_client_id', 'your_redirect_uri', null, ['company.view']);
 
// Obtain auth data from hash if it's set
var authData = Humanity.deparam(window.location.hash.substr(1));
 
if (authData.access_token) {
    Humanity.get('companies', {}, authData.access_token, function (response) {
        console.log(response);
    });
} else {
    // Redirect to the OAuth2 service
    window.location.href = auth.generateSigninUri('token');
}
 

Using the Application framework

We developed a way for your app to communicate with the Humanity app in an unique way, allowing it to modify parts of the Humanity app and utilize core modules functionality.

// Using CommonJS as an example
var Humanity = require('humanity-js-sdk');
 
/*
* Get Company Id
*
* Obtain company_id so the application doesn't need to ask the user for the company
*/
Humanity.IFrame.getCompanyId(function (companyId) {
    // Use the companyId here
});
 
 
/*
* Populating the 3 dots Menu
*
* This menu is used for navigating the application pages
*/
 
// First set a listener for the event, so we are able to act when menu item is clicked
Humanity.IFrame.listen('eventName', function () {
    alert('Menu Item is clicked');
});
 
Humanity.IFrame.setMenuItems([
    {
        title: 'Menu Item',
        page: 'eventName',
        icon: 'list'
    }
]);
 
 
/*
* Close subpage
*
* Closes the subpage. Note this only works when called from the subpage.
*/
 
Humanity.IFrame.closeSubPage();
 
 
/*
* Post to main
*
* Use this to post messages to the main frame. Useful when you want to notify
* the main application about some changes from the subpage.
*/
 
// First set a listener for the event on the main frame.
Humanity.IFrame.listen('eventName', function (data) {
    alert(data); // Alerts 'Message from the subpage'
});
 
// Then call it from the subpage
Humanity.IFrame.postToMain({
    method: 'eventName',
    data: 'Message from the subpage'
});
 
 
/*
* Open Subpage
*
* Open a subpage from your app in the native Humanity subpage
*/
 
// Path is relative to the application root
Humanity.IFrame.openSubpage('/some/path');
 
 
/*
* Notification
*
* Displays native Humanity notification
*/
 
Humanity.IFrame.notification(
    'Notification Text',	// Text
    5,						// Timeout (Seconds)
    'undoEvent',			// Event to call when undo is clicked. Undo will not
                            // be shown if this is null
    'ok',					// Type, can be 'ok', 'error', 'info'
    true,					// Suppress other notifications
    'ENTITY_ID'				// Id of the deleted entity, in case undo is used,
                            // it's going to be recieved as the undoEvent data
);
 
 
/*
* Set Controls
*
* Set the Humanity header controls
*/
 
Humanity.IFrame.setControls([
    {
        type: 'Title',					// Title Type
        style: {
            className: 'fl mr10 px5'	// Classes, feel free to inspect the
                                        // Humanity app to find the ones to use
        },
        text: "Title Text"				// Text
    },
    {
        type: 'Actions',				// Action button, turns to a dropdown if
                                        // there are multiple actions
        actions: [
            {
                handler: 'actionEvent',	// Action event, set up a listener for it
                label: "Button Label",  // Button label
                icon: 'addSmall'		// Icon
            }
        ];
    },
    {
        type: 'Back',					// Back button
        text: 'Back',					// Button text
        handler: 'backEvent'			// Back button event
    },
]);
 
 
/*
* Set Subpage Controls
*
* Set the subpage header and footer
*/
 
Humanity.IFrame.setSubPageControls({
    header: { 										// Header controls
        title: 'SubPage Title',						// SubPage title
        visible: true,								// Header is visible
        controls: [
            {
                type: 'Actions',					// Action button
                actions: [
                    {
                        handler: 'closeSubPage',	// Close handler (built in),
                                                    // you can use custom handler too
                        label: null,				// No label
                        icon: 'closeSmall'			// Icon
 
                    }
                ],
                style: {
                    className: 'fr',
                    group: {
                        className: ''
                    },
                    primary: {
                        className: 'btn btn-clean btn-drop fr'
                    }
                }
            },
        ]
    },
    footer: {											// Footer controls
        visible: true,									// Footer is visible
        controls: [
            {
                type: 'Actions',
                actions: [
                    {
                        handler: 'greenButtonEvent',
                        label: 'Green Button'
 
                    }
                ],
                style: {
                    className: 'fr',
                    group: {
                        className: ''
                    },
                    primary: {
                        className: 'btn btn-green fr'
                    }
                }
            },
            {
                type: 'Actions',
                actions: [
                    {
                        handler: 'closeSubPage',
                        label: 'Cancel'
 
                    }
                ],
                style: {
                    className: 'fr',
                    group: {
                        className: ''
                    },
                    primary: {
                        className: 'btn btn-link fr'
                    }
                }
            }
        ]
    }
});
 
 
 
 

Building

npm install
bower install
grunt build