Make a New Plugin

We'll take notes as we make a new plugin. We've made a few so this represents the best approach so far.

We'd like to make a date calculator that captures a sequence of dates and makes them available as named quantities.

We revisit this page as we work on the sanitized html plugin. We'll write revision notes as New Tips then work over this page to make it simple.

Get Started

Make up a name for the plugin. Names will become complicated someday. Now they are simple. We'll call ours Calendar. We check that this is not abusing the term. dictionary

Try the Make Plugin Script then skip to Experiment below.

Create an item of this type. Create a new page. Add a simple item, like Factory. Then text edit the page's json to change the new item's type to 'calendar'. See that the page shows an error.

Tip: remember to change the item in the journal too.

Create a plugin. Copy a simple example like PageFold plugin to get started. github We save the new file in 'client/plugins/calendar/' changing every 'pagefold' to 'calendar'.

Tip: remember to change the name in the assignment that publishes the plugin. Otherwise it won't be found.

Tip: our text formatting convention is to indent by two spaces using spaces, not tabs.

New Tip: create a new npm package for your plugin. Make a folder; copy and edit package.json; npm install

Build the javascript. For simple plugins the coffee compiler will do the job. When you have test cases you will use to recompile everything.

Tip: the command 'coffee -wc plugins/' will compile plugin source each time one is changed. Watch it to look for compile errors.

New Tip: copy and edit gruntfile.js; create client/{plugin-name}.coffee;grunt build; grunt watch; npm link; create a wiki-node-server; npm link wiki-plugin-{plugin-name}; launch the server; view localhost;

Experiment. Change emit to use different html. Add functions to parse parameters out of image.text and substitute them into the html different ways.

Tip: place your utility functions above the emit and bind functions.

Tip: use your browser's debugging tools to examine when your plugin is loaded and where its html ends up in the page.

Tip: use wiki.textEditor to provide a user-editable text field to your item.

Tip: report errors by emitting p.error tags.

Tip: use your browser's debugging tools to examine when your plugin is loaded and where its html ends up in the page.

Keep Building

Factor Logic from emit/bind functions and expose them as a node.js style module. We copy the Report plugin.

Tip: use conditions to export the right functions the right way at the right time.

Write Tests that passes in the simplest way copying from 'plugins/report/'

Tip: use 'perl' to make 'testrunner.html' each time you save the plugin or its tests.

Tip: Make a link to run your tests: tests

Work Examples using other plugins for input or output or event sources and sinks.

Tip: Study the input and output protocols of other plugins, especially recently created ones. There is not yet a standard but there are emerging practices.

Tip: Look to emerging practices in Node.js for models of distributed computation. We do.

New Tip: Look for other system interactions. Sitemap/search pulls text out of items. If this isn't html safe then somehow emit has to get involved. How?

Build Server-Side

Open Connections using WebSocket servers ( that are launched when the Express server launches. These are built as their own npm applications with their own package.json files.

Tip: Program the client plugin to look to remote servers for connections.

$page = $item.parents('.page:first') host = $'site') or socket = new WebSocket("ws://#{host}/plugin/...")

Tip: Show connection status in the emitted dom. Find a way to be useful even when connections are not available.

Tip: Test the code that interprets data moving back and forth. Share all but the code that touches the dom.

Finish Up

Add to Menu that the Factory plugin offers as alternatives to paragraphs. Create a factory.json file to describe your plugin. The server rolls these up into factories.json fetched by the Factory plugin. See Factory Plugin Menu

Write Documentation as one or more wiki pages. Command-I in the editor will look for a page following our "about" convention. See Plugin Documentation

Share Your Source as a community project with a public repository. We prefer GitHub where we save our plugins as projects named wiki-plugin-{name}. github

Publish on which allows your plugin to be included in other servers by name using the node package manager. npm