loop54-js-connector

JS-Connector

Javascript Wrapper for Loop54 JSON V3 API

How to install

Using <script> tag

1. Download loop54-js-connector.js (for development) from https://static.loop54.com/lib/js/loop54-js-connector.js or loop54-js-connector.min.js (for production) from https://static.loop54.com/lib/js/loop54-js-connector.min.js
2. Host the file on your own servers or the CDN on your choice
3. Include a <script> tag with an src attribute that points to your hosted file
4. You should now have access to the global variable Loop54.
5. Create and use a Loop54 client as explained below

Using Node Package Manager (NPM) as AMD (wg. RequireJS) or CJS (eg. NodeJS):

1. Install the package with npm install --save loop54-js-connector
2. Require it in your project with require('loop54-js-connector'); or with define(["loop54-js-connector"], function(getClient) { /* ... */ })
3. Create and use a Loop54 client as explained below

Using Node Package Manager (NPM) in a ESM environment (eg. Babel):

1. Install the package with npm install --save loop54-js-connector
2. Require it in your project with const getClient = require('loop54-js-connector'); or import getClient from 'loop54-js-connector';
3. Create and use a Loop54 client as explained below

How to use

Transpilation

If you're using NPM to include the connector in your build pipeline, (for instance using Rollup or Webpack), note that the module is exported as a pure ES6 module, and it is not bundled with dependencies, transpiled or otherwise prepared for live environment. You will need to make those preparations as part of your own pipeline.

Configure

When creating a client, you will need to set the endpoint to match the one you will get from Loop54.

If you included loop54-js-connector.js (or loop54-js-connector.min.js) in a script tag, you can get a configured client from the global Loop54 object:

Get client from global Loop54 object

var client = Loop54.getClient('URL_TO_YOUR_ENDPOINT');

If you imported the connector as an ECMAScript module (with require('loop54-js-connector') or equivalent), you can call the getClient function directly:

Get client from imported function

var client = getClient('URL_TO_YOUR_ENDPOINT');

Making API requests

Search example with promise

var options = {skip:0,take:20}; //this will take the first 20 results

client.search("R2 droids", options)
	.then(function(response){
		if(response.data.error) {
			console.log(response.data.error.title);
		} else {
			console.log("found " + response.data.results.count + " results");
		}
	});

Search example with callback

var options = {skip:0,take:20}; //this will take the first 20 results

var callback = function(response){
	if(response.data.error) {
		console.log(response.data.error.title);
	} else {
		console.log("found " + response.data.results.count + " results");
	}
}

client.search("R2 droids", options, callback);

The options and callback parameters are optional. As seen above, client.search will return a Promise.

All API operations work the same way with regards to options and callback.

Cancelling a request

All requests can be cancelled, which is useful when the user types fast.

Using promise:

const request = client.search("R2 droids", {}); //create request
request.then(response => if(!response.cancelled) console.log('done')); //attach continuation
request.cancel(); // cancel the request

Using callback:

var callback = function(response) { if(!response.cancelled) console.log('done'); } //create callback
const request = client.search("R2 droids", {}, callback);  //create request
request.cancel(); // cancel the request

Create events example

var entity = {type:"Product",id:"1234"};

var callback = function(response){
	if(response.data.error) {
		console.log(response.data.error.title);
	} else {
		console.log("success");
	}
}

client.createEvent("click",entity,null,null,null,callback);

See http://docs.loop54.com for more code samples.

But wait! I don't want the Connector to handle user ID:s for me!

If you for some reason want to handle user ID:s yourself instead of letting the Connector do it using cookies, you can set the user ID when retrieving a client like this:

Configuration example with custom user ID

var client = Loop54.getClient('URL_TO_YOUR_ENDPOINT','YOUR_USER_ID');

Features

The connector supports the following API operations:

• Search
• Autocomplete
• GetEntities
• GetEntitiesByAttribute
• GetRelatedEntities
• CreateEvent
• CreateEvents
• GetIndexedAttributes
• GetIndexedAttributeValues

It also aids in developing a Loop54 integration by:

• Taking care of user ID and cookies (note that you need to ask your users' consent)
• Setting required HTTP headers
• Serializing and deserializing requests and responses
• Friendlier error handling than HTTP error codes for common mistakes
• Tested in Chrome 69, Safari 12, Firefox 62, Opera 56, IE 11, and Edge 42

Developing the library

A Linux or MacOS environment is required. Windows is not supported and the npm commands below will fail on it.

Development

1. Git clone this repository
2. in the folder, run npm install to install all dependencies
3. run npm run dev to start the webserver, open up http://localhost:3001/#search and try out the basic features

Pull requests

Before creating a pull request:

• commit your changes
• update the package's version number in package.json
• run npm run sync-version
  • This synchronises the versions in package.json, package-lock.json and core.js.
• commit the version related changes with the new version number as the commit message, e.g. 1.14.
• push to remote and open pull request

Committing version related changes separately from implementation makes it easier to cherry-pick specific changes. Also, spotting version increments in the git history is much quicker.

Build

run npm run bundle to build the source code into /lib folder

Tests

npm run test to do check if the tests passes

All tests are located in the test folder

Contributors

Thanks to Doru Moisa for PR #1