hithercontent v0.2.1

hithercontent

A Node.js package for interacting with GatherContent's API.

Usage

Create a JSON file containing an object with the following properties:

• user: the value should be your username for your GatherContent account
• akey: the value should be the API key -- you will need to generate this if you haven't already

Let's say your JSON file is called _auth.json. The following code will initiate the hithercontent for use with your project.

var fs = require("fs"),
    auth = JSON.parse(fs.readFileSync(`_auth.json`, { "encoding": "utf8" })),
    hithercontent = require("hithercontent");

hithercontent.init(auth);

You can then use the initiated hithercontent object to fetch content from the GatherContent API.

(Tip: If using Git to version your code, add _auth.js or your equivalent filename to your .gitignore file. Storing your username and API key in a separate JSON file means you can version your code and share it without worrying about releasing the details to the public. By adding the authentication details filename to .gitignore, you remove the risk of accidentally commiting the details to your repository.)

Example

Assuming you have a string called request containing the API call details, for example, where project is the project ID or number:

var request = "/items?project_id=" + project;

You can then use the following to access and work with the content.

hithercontent.getJSONfromAPI(request, function(data) {
    console.log(data);
});

Functions

getJSONfromAPI

Arguments

• request: String. Required. The path you are making a request to.
• callback: Function. Required. Should have one argument, which represents the data that you expect to receive, as an object. You can use this function to act on the data asynchronously.

Returns

Nothing. Acts asynchronously using the callback argument.

getProjectBranch

Arguments

• project_id: String. Required. The project ID for the project you want to fetch from.
• item_id: String. Optional. The item ID for the branch you want to fetch. This will then get any items below this in the structure. If omitted, the whole project will be fetched.
• iterator: Function. Optional. Should have one argument, which represents the item data that you expect to receive. You can use the iterator to determine how you want to receive each item in the branch you are retrieving. For example, you can use hithercontent.reduceItemToKVPairs (see below) to have your branch return with simplified values for use in a template. Or you can use an identity function (i => i) to return each item as it is. If this argument is not given, at present, each branch item's data property will be extracted (the equivalent of i => i.data).

• callback: Function. Required. Should have one argument, which represents the branch you are retrieving, as an object. You can use this function to act on the branch asynchronously.

  Any item that sits under a parent item on GatherContent will be found in the items property of its parent item. If you specify an item_id, this means you will get your item at the top-level but it will feature an items property containing any items containing any child items from GatherContent, which in turn will each have their own items properties containing any children they have, and so on. If you do not specify item_id or set it to 0, you will receive an object containing an items array within which you will find all the top-level items of the project, each with their own items property containing any children and so on.

  Each item will have a bonus tier property to show how far below the parent or root item it sits. The requested item has a tier of 1, its children will have a tier of 2, their children will have a tier of 3, and so on.

Returns

Nothing. Acts asynchronously using the callback argument.

getProjectBranchWithFileInfo

Note: This differs from getProjectBranch in that it makes an additional call to the API for any item within the branch that contains files or attachments based elements. If there are many file fields in a project, this could at most double number of requests made to the API, which is why getProjectBranch still stands.

Arguments

• project_id: String. Required. The project ID for the project you want to fetch from.
• item_id: String. Optional. The item ID for the branch you want to fetch. This will then get any items below this in the structure. If omitted, the whole project will be fetched.
• iterator: Function. Optional. Should have one argument, which represents the item data that you expect to receive. You can use the iterator to determine how you want to receive each item in the branch you are retrieving. For example, you can use hithercontent.reduceItemToKVPairs (see below) to have your branch return with simplified values for use in a template. Or you can use an identity function (i => i) to return each item as it is. If this argument is not given, at present, each branch item's data property will be extracted (the equivalent of i => i.data).

• callback: Function. Required. Should have one argument, which represents the branch you are retrieving, as an object. You can use this function to act on the branch asynchronously.

  Any item that sits under a parent item on GatherContent will be found in the items property of its parent item. If you specify an item_id, this means you will get your item at the top-level but it will feature an items property containing any items containing any child items from GatherContent, which in turn will each have their own items properties containing any children they have, and so on. If you do not specify item_id or set it to 0, you will receive an object containing an items array within which you will find all the top-level items of the project, each with their own items property containing any children and so on.

  Each item will have a bonus tier property to show how far below the parent or root item it sits. The requested item has a tier of 1, its children will have a tier of 2, their children will have a tier of 3, and so on.

Returns

Nothing. Acts asynchronously using the callback argument.

getFilesForItem

Arguments

• item: Object. Required. The item data returned by GatherContent that you want to append file details to.
• callback: Function. Required. Should have one argument representing the item originally provided but with the file details added.

Any item given to the callback function should contain url and filename arrays with the elements in each corresponding to files related to the fields on GatherContent.

Returns

Nothing. Acts asynchronously using the callback argument.

reduceItemToKVPairs

Arguments

• data: Object. Required. The object you want to reduce.

Returns

An object containing key-value pairs for each of the properties on a GatherContent page. This flattens everything in config and prefixes all the other data that the API gives you and simply gives you the properties and content for a page in a label and content format. The labels are formed by taking the label name from the page and prefixing it with the tab name, separated by an underscore. General properties for the page are simply prefixed with an underscore as they don't belong under a specific tab.