Documentation

Create a dynamic value
- Create your extension
  - Choose an Extension Identifier
  - Create files and folders
  - Create your dynamic value class
  - Define user inputs
  - Implement evaluate()
  - Implement title() and text()
  - Register the extension
- Share your new Dynamic Value
- Use ES6 & webpack
- Use CoffeeScript

Create a dynamic value¶

Extensions
Create a dynamic value

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. MyDynamicValue.js).
Additionally you can have a README file, or anything else.

Your file tree should look like:

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

Create your dynamic value class

Create your dynamic value class¶

An Extension is represented as a JavaScript class.

Methods¶

Dynamic Values must have three methods:

evaluate(context) Required: evaluates the result of the Dynamic Value evaluation
- context: a Context instance
title(context) Required: returns the title to show in the Dynamic Value token
- context: a Context instance
text(context) Required: returns the text to show in the Dynamic Value token
- context: a Context instance

Static properties¶

Also, the class object have these properties:

identifier Required: the extension identifier
title Required: the extension display name
inputs Optional: the inputs the dynamic value will have (if any)
help Optional: a URI pointing to the dynamic value documentation (if any)

Example¶

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

  // implement the evaluate() method to generate the dynamic value
  this.evaluate = function() {
    var dynamicValue = ""; // generate some dynamic value
    return dynamicValue;
  }
}

// set the Extension Identifier (must be same as the directory name)
MyDynamicValue.identifier = "com.mycompany.MyDynamicValue";

// give a display name to your Dynamic Value
MyDynamicValue.title = "My Dynamic Value";

// link to the Dynamic Value documentation
MyDynamicValue.help = "https://paw.cloud/doc/";

// call to register function is required
registerDynamicValueClass(MyDynamicValue)

Define user inputs

Define user inputs¶

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

Learn how to add input fields to your extension.

Implement evaluate()

Implement evaluate()¶

Implement the evaluate(context) method and return the value you want to generate:

Here’s how you’d do to implement a dynamic value that returns the factorial of a number:

this.evaluate = function(context) {
  var f = function(x) {
    if (x == 0) {
      return 1;
    }
    else {
      return x * f(x - 1);
    }
  }

  // get the user input(s)
  var myNumber = this.number;

  // return the result value
  return f(myNumber);
}

Implement title() and text()

Implement title() and text()¶

These methods return the text to be displayed in the dynamic value token.

this.title = function(context) {
  return "Factorial";
}

this.text = function(context) {
  return this.number.toString() + "!";
}

Register the extension¶

Finally register this extension, by calling registerDynamicValueClass(cls).

registerDynamicValueClass(MyDynamicValue);

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 Digest Auth dynamic value available on GitHub as an example of a dynamic value extension written in ES6, compiled with Babel, and using webpack as builder.

If you are interested in building unit tests to make your extension rock solid, you can have a look at the tests for the cURL importer available on GitHub <https://github.com/luckymarmot/Paw-cURLImporter/>.

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. MyDynamicValue.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. Or use GitHub releases (along with Travis CI or similar) to keep built sources (e.g. the Regex Dynamic Value release history).

The Regex Dynamic Value (available on GitHub) is a great example.