Gulp Plugin

artoo.js ships with a gulp task enabling you to create custom bookmarklets.

Those are especially useful when you need precise settings for the library or when you need to inject your own code using the library as a kind of framework.

This also makes possible the creation of bookmarklet scripts or applications that even non-developers can use.

• Installation
• Usage
• Options
• Recommandations
• Examples

Installation

# Last stable version
npm install gulp-artoo

# Dev version
npm install git+https://github.com/medialab/gulp-artoo.git

The task repository can be found there.

Usage

To use the plugin, simply require it and add it in your gulp workflow.

var gulp = require('gulp'),
    artoo = require('gulp-artoo');

gulp.task('your-task', function() {
  return gulp.src('./index.js')
    .pipe(artoo(options))
    .pipe(gulp.dest('./build'));
});

Creating a blank bookmarklet

If you just need a custom artoo.js bookmarklet with custom settings but do not need to load any custom scripts, you’ll have to start gulp from a blank stream.

To do so, you can use the artoo.blank helper:

artoo.blank('name-of-the-file.bookmark.js')
  .pipe(artoo())
  .pipe(gulp.dest('./build'));

Loading templates and stylesheets

If you need to encapsulates templates and/or stylesheets for a bookmarklet providing a UI to its user, the gulp plugin ships with two helpers: artoo.template and artoo.stylesheet.

Those will simply transform any template or stylesheet into javascript variables containing json-encoded strings for artoo to use and you to access in your scripts.

You can optionally pass as sole argument the base directory of your templates or stylesheets relative to your gulpfile.js so you keep a relevant name in variables set to artoo.template and artoo.stylesheet.

Note that, by default, base directories are stylesheets and templates.

// Templates
gulp.src('./templates/*.tpl')
  .pipe(artoo.template())
  .pipe(gulp.dest('./build'));

// Stylesheets
gulp.src('./stylesheets/*.css')
  .pipe(artoo.stylesheet())
  .pipe(gulp.dest('./build'));

// Example of custom base directory
gulp.src('./stylesheets/*.css')
  .pipe(artoo.stylesheet('./static/css'))
  .pipe(gulp.dest('./build'));

Options

• url ?string : artoo.js’ url if you want to serve it by your own means rather than through the official url.
• loadingText ?string : a custom loading text to be written when artoo is loading.
• random ?boolean [false] : should we load artoo with a random GET parameter in its url to shunt some cache systems?
• settings ?object : a configuration object containing settings. A list of the available settings can be found here.
• version ?string ['latest'] : artoo’s version you want to load.

Recommandations

To respect gulp guidelines, the artoo.js plugin does only atomic tasks. You might therefore find the following plugins useful to achieve your goals:

• gulp-rename
• gulp-if
• gulp-header
• gulp-concat
• gulp-uglify
• gulp-clipboard
• gulp-webserver

You should see how artoo.js itself handle its gulp workflow and how gulpfiles generated by the Yeoman generator work to inspire yourself.

Examples

A custom blank bookmarklet

var gulp = require('gulp'),
    artoo = require('gulp-artoo');

gulp.task('bookmarklet', function() {
  return artoo.blank('my-artoo.bookmark.js')
    .pipe(artoo({
      random: true,
      version: 'edge',
      settings: {
        log: {
          beeping: true
        }
      }
    }))
    .pipe(gulp.dest('./build'));
});

A bookmarklet executing a single .js file

var gulp = require('gulp'),
    rename = require('gulp-rename'),
    artoo = require('gulp-artoo');

gulp.task('bookmarklet', function() {
  return gulp.src('./index.js')
    .pipe(artoo())
    .pipe(rename('my-bookmark.js'))
    .pipe(gulp.dest('./build'));
});

A complex bookmarklet executing multiple .js files

var gulp = require('gulp'),
    concat = require('gulp-concat'),
    uglify = require('gulp-uglify'),
    artoo = require('gulp-artoo');

gulp.task('bookmarklet', function() {
  return gulp.src('./src/*.js')
    .pipe(concat('my-bookmark.js'))
    .pipe(uglify())
    .pipe(artoo())
    .pipe(gulp.dest('./build'));
});

A bookmarklet executing a remote concatenated .js file

var gulp = require('gulp'),
    artoo = require('gulp-artoo');

gulp.task('bookmarklet', function() {
  return artoo.blank('my-artoo.bookmark.js')
    .pipe(artoo({
      settings: {
        scriptUrl: 'http://localhost:8000/build/my-script.concat.js'
      }
    }))
    .pipe(gulp.dest('./build'));
});

A bookmarklet needing a UI

var gulp = require('gulp'),
    gulpif = require('gulp-if'),
    concat = require('gulp-concat'),
    uglify = require('gulp-uglify'),
    artoo = require('gulp-artoo');

var files = [
  './src/*.js',
  './templates/*.tpl',
  './stylesheets/*.css'
];

gulp.task('bookmarklet', function() {
  return gulp.src(files)
    .pipe(gulpif('*.css'), artoo.stylesheet())
    .pipe(gulpif('*.tpl'), artoo.template())
    .pipe(concat('my-bookmark.js'))
    .pipe(uglify())
    .pipe(artoo())
    .pipe(gulp.dest('./build'));
});

A full example

Want to see a simple but full example of what you can do with artoo.js bookmarklets?

Check out this gist containing a project to scrape and download Hacker News data.

The library usage of the gulp plugin

The library itself uses the gulp plugin to compile its bookmarklets. You can find an example of this here.