gulp-contensis-sync

contensis plugin for gulp

Usage

First, install gulp-contensis-sync as a development dependency:

npm install --save-dev gulp-contensis-sync

Then, add it to your gulpfile.js:

var gulpContensisSync = require('gulp-contensis-sync');

gulp.task('sync-contensis', function() {

  // create a new contensisSync using options
  var contensisSync = gulpContensisSync.create({
	"user": "user",
	"password": "pass",
	"cmsUrl": "http://contensis-cms-url",
	"project": "Project Name"
    });

  var options = { simulate: true, prefix: 'atlas'}

  return gulp.src('./public/*.js')
    .pipe(contensisSync.transfer(options))

    // create a cache file to speed up consecutive uploads
    .pipe(contensisSync.cache())

     // Sync Directories, this will delete files at the other end.
    .pipe(contensisSync.sync(options))

     // print updates to console
    .pipe(gulpContensisSync.reporter());
});

// output
// [gulp] [create] file1.js
// [gulp] [create] file2.js
// [gulp] [update] file3.js
// [gulp] [cache]  file3.js
// ...

To run the deploy:

gulp sync-contensis

API

gulpContensisSync.create(Config, cacheOptions)

Create a Contensis Sync Instance.

The Config object is used to create a REST connection to Contensis. The cacheOptions object allows you to define the location of the cached hash digests. By default, they will be saved in your projects root folder in a hidden file called '.contensissync-' + 'name-of-your-project'.

For best practice you should add your contensis credentials to a json file:

{
	"user": "user",
	"password": "pass",
	"cmsUrl": "http://full-cms-url",
	"project": "Project Name"
}

You can then read it in with:

var fs = require('fs')
//Remember to add your contensis-credentials.json to your .gitignore, so no one else can use your details!
var credentials = JSON.parse(fs.readFileSync('../contensis-credentials.json', 'utf8'))
//Now you can create the object using the credentials
var contensisSync = gulpContensisSync.create(credentials);

contensisSync.transfer([options])

Create a through stream, that transfers files to Contensis.

• options: optional additional transfer options
  • force: bypass cache / skip
  • simulate: debugging option to simulate Contensis upload
  • prefix: The destination path to send the files
  • createOnly: skip file updates
  • submit: Boolean to indicate if you want the content submitted for approved.
  • approve: Boolean to indicate if you want the content pushlished live and approved. You must submit it first though!

Files that go through the stream receive extra properties:

• info.path: contensis path
• info.ETag: file ETag (this is the MD5 has of the file, use to determine if changes have occured to the file)
• info.state: publication state (create, update, delete, cache or skip)

Note: transfer will never delete files remotely. To clean up unused remote files use sync.

contensisSync.cache()

Create a through stream that create or update a cache file using file path and file ETag.

Consecutive runs of transfer and sync will use this file to avoid uploading identical files over and over.

Cache file is save in the current working dir and is named .contensissync-<projectName>. The cache file is flushed to disk every 10 files just to be safe.

Bear inb mind you may not want to use this if there are multiple people working, The sync is intelligent and will only upload changed files regardless of the cache.

contensisSync.sync([prefix], [whitelistedFiles])

create a transform stream that delete old files from Contensis.

• options: optional additional sync options
  • simulate: debugging option to simulate Contensis upload (if you dot specify this it will default to simulate to prevent disasters)
  • prefix: prefix to sync a specific directory, if this is not provided you could delete an entire project!
• whitelistedFiles: array that can contain regular expressions or strings that match against filenames that should never be deleted from Contensis.

e.g.

// only directory bar will be synced
// files in folder /foo/bar and file baz.txt will not be removed from Contensis despite not being in your local folder
var options = { simulate: false, prefix: 'atlas'}
gulp.src('./public/*')
  .pipe(contensisSync.transfer(options))
  .pipe(contensisSync.sync(options, [/^foo\/bar/, 'baz.txt']))
  .pipe(gulpContensisSync.reporter());

warning sync will delete files in your Contensis instance that are not on your local folder unless they're whitelisted.

// this will transfer and sync files with the files in your public directory
// note that in Contensis the files in /public/ would end up directly in the root as we have provided no prefix.
var options = { simulate: false, prefix: ''}
gulp.src('./public/*')
  .pipe(contensisSync.transfer(options))
  .pipe(contensisSync.sync(options))
  .pipe(gulpContensisSync.reporter());

// output
// [gulp] [create] file1.js
// [gulp] [update] file2.js
// [gulp] [delete] file3.js
// ...

contensissync.reporter([options])

Create a reporter that logs info.path and info.state (delete, create, update, cache, skip).

Available options:

• states: list of state to log (default to all)

// this will transfer local files and then sync to Contensis and print created, updated and deleted files
var options = { simulate: false, prefix: 'atlas'}
gulp.src('./public/*')
  .pipe(contensisSync.transfer(options))
  .pipe(contensisSync.sync(options))
  .pipe(gulpContensisSync.reporter({
      states: ['create', 'update', 'delete']
    }));

License

MIT License