artoo.js The client-side scraping companion.

Grunt Task


Note: The grunt task is now deprecated. You should now use the gulp plugin.


artoo.js ships with a grunt 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

# Last stable version
npm install grunt-artoo

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

The task repository can be found there.


Getting Started

This plugin requires Grunt ~0.4.5

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-artoo');

The task

Overview

In your project's Gruntfile, add a section named artoo to the data object passed into grunt.initConfig() and create as many targets as you need.

grunt.initConfig({
  artoo: {
    dev_target: {
      options: {
        // Your options there...
      },
      dest: 'path/to/bookmarklet.min.js'
    },
    prod_target: ...
  },
});

Settings

Root

  • options ?object : an object of options for the task.
  • src ?string | ?array : files to compile with the bookmarklet.
  • dest ?string [./targetName.bookmarklet.min.js] : destination for the created bookmarklet.

Options

  • url ?string : artoo.js' url if you want to serve it by your own means rather than through the official url.
  • clipboard ?boolean  [true] : should the ouptput bookmarklet be automatically copied to your clipboard when generated?
  • 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.

Executing files through the bookmarklet

If you need the bookmarklet to execute some of your scripts, you can either specify a distant url from where you are going to serve said script through options.settings.scriptUrl or let the task concatenate and minify the src files into the bookmarklet.


Examples

A basic bookmarklet

grunt.initConfig({
  artoo: {
    basic: {
      src: ['./src/file1.js', './src/file2.js'],
      dest: 'basic.bookmarklet.min.js'
    }
  },
});

A complex bookmarklet

grunt.initConfig({
  artoo: {
    complex: {
      options: {
        url: 'http://localhost:8000/artoo.js',
        clipboard: false,
        random: true,
        settings: {
          log: {
            enabled: false
          },
          autoInit: false
        }
      },
      src: ['./src/file1.js', './src/file2.js'],
      dest: 'complex.bookmarklet.min.js'
    }
  },
});

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.


Note finally that artoo.js' standard bookmarklets are generated through this task and can be another useful example.