Build From Source

We will describe one of the many workflows that are available to federated wiki developers. We'll use git, github and npm features to customize, deploy and contribute new versions of wiki.

See How To Download Source for client and server.

Fork and download wiki. This assembles the other packages for client, server and plugin javascript. github

Enter the downloaded package to load its dependents.

cd wiki npm install

Use the npm start script to launch the server.

npm start

This may not start if you have other wiki running on the same port. To pass parameters to wiki you will want to launch the core javascript with desired parameters.

node index.js -p 3030

# Client

Fork and download wiki-client. This includes html, css and javascript for the single-page wiki application. github

Enter the downloaded package and load its dependents. Build this with grunt to produce a replica of code already loaded above as a dependent of wiki.

cd wiki-client npm install grunt build

The wiki server is serving client javascript from its node_packages in its directory while we are building new client javascript in the wiki-client directory.

Connect the javascript we are building with the javascript we are serving using npm link. Subsequent refreshes will get our most recently built application.

cd wiki-client npm link cd ../wiki npm link wiki-client

# Coding

We will make modifications to the client code and then test them interactively from the browser at localhost:3030.

Open a programming editor on the wiki-client directory. Then launch grunt to watch for and rebuild when files change. Links will connect this to the wiki project

cd wiki-client edit . grunt watch

Edit the source for the text editor in file lib/editor.coffee. Save this without changes. This should trigger a grunt build even though there are no changes.

Find the entry point for the text editor and log its arguments. Their may be logging there already. Add yours.

textEditor = ($item, item, option={}) -> console.log 'item', $item, item

Refresh your browser viewing localhost:3030.

Open the inspector viewing the javascript console.

Double-click to edit any paragraph.

Notice the editor arguments. Edit another paragraph. Compare the textEditor arguments.

# Debugging

Grunt builds minified and unminified versions of wiki-client. Edit views/static.html to include the unminified version when debugging.

<script src='/client.max.js' type='text/javascript'>

Try replacing the console.log suggested above with a call into the debugger.

This will halt like a breakpoint in the inspector's debugger. Make sure you can find the $item and item parameters in the debugger's stack inspector.

debugger

Normally hidden variables are available in the console when stopped at a breakpoint. Try some jQuery methods.

$item.parents('.page')

Note: CoffeeScript has helped us coding but adds some friction debugging. We expect to convert to ES6 once it can be assumed without its own transpilation issues.

# Reflection

The wiki is made of many modules only a few of which need be downloaded to develop new software.

Each module has its own development tooling. Node's two-step linking will distribute changes to the server which is then available to the refreshed browser.

We can explore how wiki works by making temporary changes and observing their effects immediately.