PaperScape Quick Developers Guide

PaperScape Quick Developers Guide

Fast path for building and testing custom .giraffe.js components inside PaperScape.

Environment Checklist

  • Ensure /OpenForum/Giraffe/giraffe.js is up to date; PaperScape relies on Canvas, Composite, Picture, Text, etc.
  • Open two tabs: /OpenForum/AddOn/PaperScape for runtime testing and /OpenForum/AddOn/PaperScape/Developer for scripts.
  • Keep a copy of paperScape.json in case you need to restore the default scene.

Create a Component

  1. Define your constructor: var MyWidget = function(x,y,canvas,htmlCanvas,controller) { ... };
  2. Inside, build a container (e.g., var container = new Composite(x,y);) and attach shapes, text, or child composites.
  3. Expose the required API: self.getName = function() { return "My Widget"; }; and self.getContainer = function() { return container; };.
  4. Optional extras: self.toJson(), self.fromJson(json), self.getForm() (return HTML fragment string), and self.getConfig() ({ layer: "view" | "control" | "overlay" }).
  5. Finish with target = MyWidget; so PaperScape knows which constructor to instantiate.

Test Loop

  1. Save the file under /OpenForum/AddOn/PaperScape/Apps/ or an accessible page path.
  2. Drag the .giraffe.js file onto the PaperScape canvas or call paperScape.load("/path/to/MyWidget.giraffe.js") from the console.
  3. Use the Developer console’s Run action to execute rapid patches without reloading the page.
  4. Open the Items menu entry to configure or remove the test instance.

IntraQ Hot Reload

  1. Load /OpenForum/AddOn/PaperScape/paperscape-queue.js (add a <script> tag or run OpenForum.loadScript from the console).
  2. Instantiate var psq = new PaperScapeQueue();—it binds to the shared PaperScape queue and targets the live canvas.
  3. psq.sendUrl("/OpenForum/AddOn/PaperScape/Apps/whiteboard.giraffe.js") or psq.sendFile(fileInput.files0) simulates drag/drop without leaving your editor tab.
  4. psq.sendCode(editor.getValue(), {name:"My Widget", replace:true}) instantly replaces a running app; omit replace (or set false) to spawn a parallel copy.
  5. Advanced: psq.sendMessage({action:"load-file", name:"scene.giraffe.json", data: jsonString, pointer:{x:250,y:250}}) hands you full control over the queue payload.
  • Supported actions: load-url, load-file/load-data, and load-code/replace-app.
  • pointer accepts either "center" (default) or absolute coordinates to steer the drop location.
  • Queued loads append to the scene—remove items or reload the page before replaying scenes.

Persist & Share

  • Add supporting fragments (forms, HTML) alongside the script (e.g., Apps/my-widget.html.fragment).
  • Provide sensible defaults in toJson()/fromJson() so users can save/load scenes.
  • Document usage in Quick Reference if the component is user-facing.
  • When exporting object-model scenes, keep filenames ending with .omv.json so downloads and drag/drop imports remain compatible.
  • Package seeds (.giraffe.json) for common arrangements to accelerate reuse.

Debugging Tips

  • Use canvas.log("message") or console.log (browser dev tools) to inspect state.
  • Leverage paperScape.setAllowDrag(false) when you need precise pointer interactions.
  • Register temporary file processors with paperScape.addFileProcessor() to handle custom imports during development.
  • Remember that dropped scripts execute immediately; wrap prototypes in try/catch during exploratory work.