structr-4-tasks v0.1.9
structr-4-tasks
-- A library that provides simplified access to a Structr's REST interfaces. it also can help streamline some of your maintenanc needs by streamlining the process of making backups and publishing them to a remote location (currenty implemented with AWS S3. Hopefully you find this library useful for standalone operations as well as for use in conjunction with other libraries (like Gulp)
Example - Getting Started
//a variable to hold the structr utility object
var structr;
//simultaneously require and initialize the connection
require('structr-4-tasks').init("notyourusername", "notyoursmypassword")
.then(function(newStructrObject){
structr = newStructrObject;
})
.then(yourStuff) //<--the entry point into your work that ensures that a valid connection will be available
.catch(function(e){
//Oops! you ended up here if connection failed or you have an untrapped error in yourStuff();
JSON.stringify(e, null, '\t')
//some automation/scheduling systems like a proper error to correctly understand that this process failed.
process.exit(-1);
});
var yourStuff = function(){
//lets get to work
//requests the json-schema definition of an entity in your structr
structr.rest.getSchema("MyEntity", "default").then(function(response){
//if you specify an optional logger (like with gulp-utils), it is available throught the structr.log member;
//this is handy if you're using the library with gulp and would like get the pretty logging
structr.log(response.result.result_count)
})
};
Dependencies
structr-4-tasks uses the following NPM packages internally
argv
lodash
minimist
q
request
request-promise
s3
simple-publishers
Interfaces
.init(username, password, logger, options)
the logger input
structr-4-tasks.rest
.get(entity, view, urlOptions)
simple get function, optionally allow you specify additional argument
.post(entity, data)
post data to the
.put(entity, id, data)
note: not yet implmeented //todo
.delete
performs a delete post against a single ID. will not allow you to delete all nodes at onces
.getSchema(entity, optionalView)
Backup structr-4-tasks.backup[...]
.run(fileName, publishOptions)
.move(fromFile, toFile) //note to rename these
By omitting an options object, you are implicitly accepting the following defaults;
var defaultOptions = {
protocol : ['http://', 'https://'].indexOf(argv['protocol']) > -1 ? argv['protocol'] : "http://",
server : argv['server'] || "127.0.0.1",
port : argv['port'] || undefined,
loginResource : "structr/rest/login",
maintenanceResource : "structr/rest/maintenance/sync",
restBase : "structr/rest",
installLocation : argv['structr-install'] || '/usr/lib/structr-ui',
verbose: false,
logger: console
};
This means that you can provide command line options to overrise the following properties
- protocol
- server
- port
- installLocation typically
/usr/lib/structr-ui
on most linux systems
Optionally you can set the logger to be your preferred logging function. if you don't provide a value, the default console logger will be used. this is helpful if you are using another library which uses a specialised logging function, as is commonly done when using Gulp.
You can provide a reference to any the top level object, in so much as it has a log()
function. For example if used in a regular node context, if you omit the logger argument, providing console
or console.log
(either will work).
the following are functionally equivalent
alternatively, if you're using structr-4-tasks with a library like 'gulp-utils' you can provide your utils reference example
var structr = require('structr-4-tasks')
structr.init("myusername", "mypassword", console)
//Or all at once
var structr = require('structr-4-tasks').init("myusername", "mypassword", console)
//if you're using gulp-util
var gulp = require('gulp');
var gulpUtils = require('gulp-util');
var structr = require('structr-4-tasks').init("myusername", "mypassword", gulpUtils)
Best practice Use environment variables in your code to handle the username and password so that you don't have credentials in your code. example:
var structr = require('structr-4-tasks).init(process.env.username process.env.password)
Note:
the REST function in the library are not attached to the structr.rest until the library has successfully authenticated. this forces failure on premature RESTful calls to structr.
Known issues:
structr.rest.put
is not yet implemented