This driver provides connectivity between a JavaScript application and Cloud CMS.
The JavaScript application can be running within the browser or on the server. The driver supports the browser, Node.js and other server-side / CommonJS runtimes.
To use this driver within your browser application, you first download the driver and then pull into your page like so:
<script type="text/javascript" src="gitana.min.js"></script>
And then you connect to Cloud CMS by identifying your client key/secret and authentication username and password.
Gitana.connect({
"clientKey": "<clientKey>",
"clientSecret": "<clientSecret>"
"username": "<username>",
"password": "<password>"
}, function(err) {
// this = platform
});
Where clientKey and clientSecret are used to identify your client application. You can use the client key/secret combination generated by default for your platform or you can create a new client. Ideally, you will have one client per JS/HTML5 or Node.js application running out in the wild.
You can provide the username and password for any valid user on your platform. Make sure that this user has sufficient CONNECT privileges to the platform and that they have sufficient rights to any resources you attempt to use (otherwise, you will see 401 authentication errors).
You may also opt to take advantage of Authentication Grants to generate private application user key/secret in lieu of username/password credentials.
The driver also supports AMD. If you're using a module loader like RequireJS, you can load the gitana
module and utilize it within your code. Kind of like this:
define(["gitana"], function(Gitana) {
Gitana.connect({
"clientKey": "<clientKey>",
"clientSecret": "<clientSecret>"
"username": "<username>",
"password": "<password>"
}, function(err) {
// this = platform
});
});
This driver is available via the NPM Registry as 'gitana'.
Using it in Node JS is pretty easy. You can do something like the following:
var Gitana = require("gitana");
Gitana.connect({
"clientKey": "<clientKey>",
"clientSecret": "<clientSecret>"
"username": "<username>",
"password": "<password>"
}, function(err) {
// this = platform
});
This driver makes it really simple to work with Cloud CMS data stores and objects as though they were local objects right within your JS application. The driver lets you get at all of the runtime and authoring capabilities of the system.
In addition, this driver features asynchronous method chaining. This lets you chain together commands that go over the wire and avoid a lot of the headache of manually managing callbacks. As a result, your code is smaller, there is less to manage and it's easier to read.
Here is an example:
platform.createRepository().readBranch("master").createNode({"title": "Hello World"});
We've published our documentation for the JavaScript driver as well as other drivers to our Documentation Site.
In addition, we've published JavaScript-level API documentation.
We've collected a few developer notes here:
The driver relies on XHR under the hood for communication with Cloud CMS. You can plug in your own XHR implementations by overriding the following:
Gitana.HTTP_XR_FACTORY = function() {
...
};
The driver supports HTTP and HTTPS proxy servers if you're running in Node.js. Simply set the following variable in your environment:
HTTP_PROXY
For example -
export HTTP_PROXY=http://proxyserver:proxyport
node app
The HTTP_PROXY environment variable can point to an HTTP or HTTPS proxy server.
To build locally, you must first sync the code to your local GitHub repository and also install Node.js. Then, run the following:
npm install
This will install all Node.js dependencies for build and test. Then, to build, run the following:
npm run build
This will produce the latest gitana.js and gitana.min.js files in your dist
directory.
The build is a small Node script (build/build.mjs) that concatenates the driver sources in the order
given by build/manifest.json, wraps the result as a UMD module and minifies it with esbuild. If you
add a new source file to js/gitana, you must also add it to build/manifest.json in the
position where it should be loaded.
To build the API documentation into dist/jsdoc:
npm run docs
Wherever possible, please try to follow the code conventions utilized by the project. For the most part, these include spacing and line breaks that are generous so as to improve code readability.
| Script | What it does |
|---|---|
npm run build |
Builds dist/gitana.js and dist/gitana.min.js |
npm test |
Builds, then runs the headless test suite |
npm run test:integration |
Builds, then runs the tests that need a live Cloud CMS server |
npm run docs |
Builds the API documentation into dist/jsdoc |
npm run bump |
Bumps the patch version in package.json |
npm run cdn |
Publishes dist to S3 and invalidates CloudFront |
The build dependencies are esbuild, used for minification, and jsdoc with the clean-jsdoc-theme template, used for the API documentation. There is no Grunt, no Ant and no Java in the toolchain.
The generated documentation includes a client-side search index, which needs to be served over HTTP rather than opened from the filesystem:
npm run docs
npx serve dist/jsdoc
release.sh drives a release: it builds the driver and the docs, commits dist on a release
branch, publishes to the CDN, tags the repository and then publishes to npm.
The CDN step (npm run cdn, implemented in build/publish.mjs) uploads dist to
s3://<bucket>/gitana-javascript-driver/ under both the current version and latest,
then invalidates CloudFront. It shells out to the AWS CLI and reads its
settings from ../settings/__aws.json:
{
"key": "...",
"secret": "...",
"region": "...",
"bucket": "...",
"cloudfrontDistributionIds": { "gitana-javascript-driver": "..." }
}If that file is absent, the ambient AWS environment (profile, environment variables or instance role) is used
instead, and the bucket can be supplied with GITANA_CDN_BUCKET. Pass --dry-run to print
the commands without running them:
node build/publish.mjs --dry-run
To run the headless test suite:
npm test
This builds the driver and runs the tests using Node's built-in test runner. There is no browser, no QUnit and no jQuery. Two suites run today:
tests/node/http.test.mjsexercises the driver's HTTP layer against a local servertests/node/unit.test.mjsruns the tests fromtests/jsthat need no Cloud CMS server
The tests in tests/js are plain ES modules using node:test directly:
import { describe, it } from "node:test";
import { Gitana, GitanaTest } from "../support.mjs";
describe("authentication1", function() {
it("Authentication 1", { "timeout": 120000 }, function(t) {
Gitana.reset();
t.plan(2);
return new Promise(function(start) {
GitanaTest.authenticateFullOAuth().then(function() {
t.assert.ok(true, "Authenticated");
start();
});
});
});
});t.plan(n) asserts that exactly n assertions run, and start is the promise's resolve
function, so an asynchronous test finishes when it calls start().
tests/support.mjs gives every test the driver and the shared helpers, and installs the Node shims:
node/support/xhr.mjsprovides theXMLHttpRequestNode lacks, backed byfetchnode/support/storage.mjsprovides in-memorylocalStorage/sessionStoragenode/support/gitana-test.mjsprovides the shared authentication helpers
To add a test to the headless suite, list it in tests/node/unit.test.mjs.
Most of the files in tests/js authenticate against a live Cloud CMS instance. These are not part of
npm test. To run them:
npm run test:integration
This needs a tests/gitana.json holding the credentials to use:
{
"clientKey": "...",
"clientSecret": "...",
"username": "...",
"password": "..."
}
The file is git-ignored. If it is missing, the suite skips instead of failing. The server defaults to
http://localhost:8080 and can be pointed elsewhere with GITANA_BASE_URL:
GITANA_BASE_URL=http://localhost:9090 npm run test:integration
These tests create real data - users, tenants, repositories - so point them at a disposable instance.
The file list and its order live in tests/node/integration/manifest.json. Order is significant: the
suite was written to run in sequence and some tests build on state left by earlier ones. To add a test, put its
filename in that manifest at the position where it should run.
node --test tests/js/testDomainPrincipal3.mjs
node --test --test-name-pattern="Domain Principal 3" "tests/node/integration/*.test.mjs"
You can learn more about Cloud CMS by visiting our web site at http://gitana.io.