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.