A Javascript client library for CKAN designed for both the browser and NodeJS.
The library provides full support for accessing both the CKAN Catalog and CKAN DataStore API.
It also provides a Recline compatible backend.
The JQuery library is required for use in the browser. After that, just add the ckan.js script to your page.
<script src="jquery-2.1.4.min.js"></script>
<script src="ckan.js"></script>
You can also use our hosted one:
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="http://okfnlabs.org/ckan.js/ckan.js"></script>
Using the JsDelivr CDN you can get everything you need with this webpacked bundle:
<script src="https://cdn.jsdelivr.net/gh/okfn/ckan.js@master/dist/ckan.bundle.js"></script>
npm install ckan
Then in your code:
var CKAN = require('ckan')
Usage is generally similar across Node and Browser versions.
Callback structure follows Node conventions, that is:
function(err, data)
Set it up:
var client = new CKAN.Client('http://my-ckan-site.com');
// You can also provide an API key (for operations that require one)
var client = new CKAN.Client('http://my-ckan-site.com', 'my-api-key');
// If your portal disallows POST requests (note: limited support in browser module)
client.requestType = 'GET';
You can now use any part of the action API:
client.action('action_name', data, callback)
For example, to create a dataset using dataset_create action you would do:
client.action('dataset_create', { name: 'my-dataset' }, function(err, result) {
console.log(err);
console.log(result);
})
Here's a more complex example showing several commands to do a Dataset upsert (create if not exists, otherwise update):
var datasetInfo = {
name: 'ckan.js-example',
title: 'CKAN.JS Example',
tags: ['amazing']
};
client.action('dataset_show', { id: datasetInfo.name }, function(err, out) {
// dataset exists
if (!err) {
// TODO: you'd really want to extend the existing dataset object returned
// in out with the datasetInfo we have but we are being simple here
client.action('dataset_update', datasetInfo, cb);
} else {
client.action('dataset_create', datasetInfo, cb);
}
});
The DataStore feature of CKAN allows you to store structured data in CKAN and to create a rich API for it. It is also accessible via the action API - details in the docs here - and and you can therefore access using the CKAN client. Here are a few examples:
Store data into the DataStore for an existing resource
// 2 rows or data (with columns/fields named 'A' and 'B'
var data = [
{ A: 1, B: 2 },
{ A: 10, B: 16}
];
// the id of a CKAN DataSet resource (the data that we store will be associated with that resource)
// this resource will need to already exist
resourceId = 'abc-efg';
client.action('datastore_create', {
resource_id: resourceId,
records: data
},
function(err) {
if (err) console.log(err);
console.log('All done');
})
Store data into a new DataStore resource:
// the id of a CKAN dataset that already exists
packageId = 'the-best-dataset-ever';
client.action('datastore_create', {
resource: {package_id: packageId},
records: data
},
function(err) {
if (err) console.log(err);
console.log('All done');
})
Here's an example of loading data from a CSV file into the DataStore:
// npm's csv file
var csv = require('csv');
csv()
.from('path/to/csv-file.csv', {columns: true})
.to.array(function(data, count) {
client.action('datastore_create', {
resource_id: resourceId,
records: data
},
function(err) {
if (err) console.log(err);
console.log('All done');
})
})
;
Search data using the Data API - see datastore_search for
details of options:
client.action('datastore_search', {
resource_id: '...',
q: '...'
},
function(err, out) {
if (err) console.log(err);
console.log(out);
})
});
Or using SQL support:
client.action('datastore_search_sql', {
sql: '...'
},
function(err, out) {
if (err) console.log(err);
console.log(out);
})
});
There are also a couple of nice wrapper methods:
// queryObj should be like the Recline Query structure
// http://okfnlabs.org/recline/docs/models.html#query
client.datastoreQuery(queryObj, function(err, out) {
// out will follow recline structure, viz
{
total: ..
fields: ... (fields will have Recline / JSON Table Schema types)
hits: array of results ...
}
});
And for SQL
client.datastoreSqlQuery(sql, function(err, out) {
// out will follow recline structure, viz
{
total: ..
fields: ... (fields will have Recline / JSON Table Schema types)
hits: array of results ...
}
});
This module also provides a Recline compatible backend available as:
recline.backend.Ckan
The backend supports fetch and query but does not provide write support at
the present time.
We are using QUnit for unit testing the webpack'ed version.
npm install -D
To install developer libraries, then:
npm run dev
To update the dist version of the library. Start a local web server, e.g.:
python -m http.server
And in your web browser, open http://0.0.0.0:8000/test/
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent