Documentation

Create a code generator
- Create your extension
  - Choose an extension identifier
  - Create files and folders
  - Structure the JavaScript file
  - Define user inputs
  - Implement generate()
  - Use a template library (example with mustache.js)
- Share your Code Generator
- Use ES6 & webpack
- Use CoffeeScript

Create a code generator¶

Extensions
Create a code generator

You can make Paw generate custom code for making HTTP requests in any language or framework; it can be also used to export data to 3rd party file formats.

You can export generated code to a file: File ‣ Export Selection or File ‣ Export All. Also, generated code will be previewed in the Code Inspector (⇧⌘C to show/hide).

Create your extension¶

Choose an extension identifier

Choose an extension identifier¶

The extension identifier should be a reverse domain name and have a unique and meaningful name (e.g. com.mycompany.MyImporter).

Create files and folders

Create files and folders¶

Open the Extensions Directory: you can find it in the Preferences ‣ Extensions ‣ Open Extensions Directory.

Create a new folder and name it after your extension identifier.
Create a .js JavaScript file named after the last component of the identifier (e.g. MyCodeGenerator.js).
Additionally you can have a README file, or anything else.

Your file tree should look like:

Extensions/
- com.mycompany.MyCodeGenerator/
  MyCodeGenerator.js
  
  README.md

Structure the JavaScript file

Structure the JavaScript file¶

An Extension is represented as a JavaScript class.

Methods¶

Code Generators must have one method:

generate(context, requests, options) Required: generates the code
- context: a Context instance
- requests: an array of Request items
- options:
  inputs: the dictionary with all user inputs
  
  file:
  
  name: file name, if exported to file
  
  path: file path, if exported to file
  
  hideCredentials whether user opted to obfuscate credentials

Static properties¶

Also, the class object have these properties:

identifier Required: the extension identifier
title Required: the extension display name
fileExtension Optional: a file extension (excluding the dot .) for the output file
languageHighlighter Optional: a keyword identifying the language highlighter for the output (bash, coffeescript, css, go, http, java, javascript, json, markdown, objectivec, perl, php, python, ruby, scala, swift, xml, yaml)
inputs Optional: the inputs the extension will have (if any)
help Optional: a URI pointing to the dynamic value documentation (if any)

Example¶

// Extensions are implemented as JavaScript classes
var MyCodeGenerator = function() {

   // implement the generate() method to generate code
   this.generate = function(context, requests, options) {
       var client_code = ""; // generate the code
       return client_code;
   }
}

// set the extension identifier (must be same as the directory name)
MyCodeGenerator.identifier = "com.mycompany.MyCodeGenerator";

// give a display name to your Code Generator
MyCodeGenerator.title = "My Code Generator";

// call to register function is required
registerCodeGenerator(MyCodeGenerator)

Define user inputs

Define user inputs¶

You can let the users of your Exporter enter inputs that you’ll get the value during the generate() call.

Learn how to add input fields to your extension.

Implement generate()

Implement generate()¶

Implement the generate(context, requests, options) method and return the code you want to generate. It gets:

context: a Context instance

requests: an array of Request items

options:

inputs: the dictionary with all user inputs

file:

name: file name, if exported to file

path: file path, if exported to file

hideCredentials whether user opted to obfuscate credentials

Also, all available classes and functions are in the Reference.

Here’s an example:

this.generate = function(context, requests, options) {
     var generated = "";

     // iterate requests (`Request` objects)
     for (var i in requests) {
         var request = requests[i];

         // iterate on request headers
         var headers = request.headers;
         for (var header_name in headers) {
             var header_value = headers[header_name];
             // do something
         }

         // get the latest response status code
         var status_code = request.getLastExchange().responseStatusCode;

         // get the latest response body
         var body = request.getLastExchange().responseBody;

         generated += status_code + "\n" + body + "\n\n";
     }

     // return the generated string
     return generated;
}

Use a template library (example with mustache.js)

Use a template library (example with mustache.js)¶

While you don’t have to, it’s easier to use a template library to generate the client code. Here’s an example with mustache.js.

First of all, you need to add the mustache.js script into your extension directory. It’s available on GitHub.
Use require() or loadScript() functions to import ./mustache.
Create a mustache template file.
Import the template file in your JavaScript code, using the readFile() function.
Render template.

Here’s an example JavaScript file:

var mustache = require('./mustache')
// legacy, import the mustache.js script (to Paw 2.2.2)
// require("mustache.js");

var MyCodeGenerator = function() {

 this.generate = function(context, requests, options) {
         var generated = "";

        // import the mustache template
        var template = readFile("my-template.mustache");

        // iterate requests (`Request` objects)
        for (var i in requests) {
             var request = requests[i];

             // define your view
             var view = {
                "request": request,
                "content_type": request.getHeaderByName('Content-Type'),
             };

             // render the template
             generated += Mustache.render(template, view) + "\n\n";
         }

         return generated;
    }
}

MyCodeGenerator.identifier = "com.mycompany.MyCodeGenerator";
MyCodeGenerator.title = "My Code Generator";
registerCodeGenerator(MyCodeGenerator)

And an example of mustache template file:

var send_request = function() {
    var url = "{{{request.url}}}";
    var content_type = "{{{content_type}}}";
}

Use ES6 & webpack¶

We encourage you to write your extensions in ES6, using Babel to convert to the version of EcmaScript the JavaScript Code engine (same as Safari) supports. See the cURL importer available on GitHub as an example of extension written in ES6, compiled with Babel, and using webpack as builder. It also have unit tests if you’re interested in making your extension rock solid!

Use CoffeeScript¶

That’s a matter of personal preference, but if you prefer to write your extension using CoffeeScript, it’s possible.

Write your extension code in a .coffee file (e.g. MyCodeGenerator.coffee)
Add a Cakefile that compiles your code into JavaScript (here’s an example: Cakefile)
Share/commit the compiled JavaScript file along with the other files. (We’re in the process of using GitHub Releases to live compile files).