prawn-js 0.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+v0.1 (18th June 2009)
+- initial release

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 James Healy
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,73 @@
+# prawn-js
+
+## Overview
+
+This extension to the Prawn PDF generation library adds support for embedding javascript
+in your files. These Javascript fragments will be compiled and executed on supported
+viewers (like Adobe Acrobat Reader), usually in response to particular events (like the
+document opening, closing, etc).
+
+The Javascript syntax supported is fairly standard, although it includes a few extensions
+defined by Adobe. For more information on these extensions (and the capabilities of
+Javascript and PDF in general) visit Adobe's reference site, linked in the further reading
+section of this readme.
+
+## Installation
+
+    gem install prawn-js
+
+## Usage
+
+Prawn-JS depends on the core prawn library, and simply adds a few additional
+methods to the standard Prawn::Document object that allow your Javascript to be
+associated with certain events.
+
+Start by requiring the prawn library, then the prawn-js library. Build your PDF as usual,
+and use methods like add_docopen_js to register your code fragments.
+
+    require 'prawn'
+    require 'prawn/js'
+
+    Prawn::Document.generate "js_doc_open.pdf" do |pdf|
+      pdf.add_docopen_js("alert", "app.alert('open!',3)")
+      pdf.text "Javascript Prototype", :at => [150,720], :size => 32
+    end
+
+For further examples and documentation, check out the examples/ directory of this project
+and the code docs for the Prawn::JS module.
+
+For general information on the syntax of JavaScript, I highly recommend
+"JavaScript: The Good Parts" by Douglas Crockford, ISBN: 9780596517748.
+
+For specific information on Adobe's extensions to JavaScript, in particular the
+objects they provide for interacting with your document and the application
+(somewhat similar to the DOM provided to Javascript in web browsers) read the
+documents available on Adobe's JavaScript site (see links below). Look for
+"JavaScript for Acrobat API Reference" and "Developing Acrobat Applications
+Using JavaScript".
+
+## Disclaimer
+
+I haven't yet found a situation where I've wanted to embed JS in my documents.
+Most viewers ignore it and few users demand it.
+
+This extension was more or less thrown together as a proof of concept. I'm
+happy to review any patches that are submitted, but I not planning to actively
+develop it. I'm releasing it because the code was getting lonely sitting on my
+laptop. if there's one thing I hate it's lonely code.
+
+## Licensing
+
+This library is distributed under the terms of the MIT License. See the included file for
+more detail.
+
+## Contributing
+
+All suggestions and patches welcome, preferably via a git repository I can pull from.
+
+## Further Reading
+
+- The source: [http://github.com/yob/prawn-js/tree/master](http://github.com/yob/prawn-js/tree/master)
+- Prawn source: [http://github.com/sandal/prawn/tree/master](http://github.com/sandal/prawn/tree/master)
+- Rubyforge: [http://rubyforge.org/projects/prawn](http://rubyforge.org/projects/prawn)
+- Adobe Javascript Site: [http://www.adobe.com/devnet/acrobat/javascript.html](http://www.adobe.com/devnet/acrobat/javascript.html)

data/examples/autoprint.rb

@@ -0,0 +1,28 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'rubygems'
+require 'prawn'
+require 'prawn/js'
+
+# A simple example that demonstrates having a PDF document automatically
+# print itself when it's opened.
+#
+# For more detail on the options available when printing without
+# user interaction, see chapter 5 of "Developing Acrobat Applications Using
+# Javascript", available on the Adobe Javascript page.
+#
+Prawn::Document.generate "autoprint.pdf" do |pdf|
+  # Build the script we want to execute when the document opens
+  script = <<-EOF
+    var pp = this.getPrintParams();
+    pp.interactive = pp.constants.interactionLevel.silent;
+    this.print(pp);
+  EOF
+
+  # embed our script. The label is arbitary and can be anything
+  pdf.add_docopen_js("somelabel", script)
+
+  # finally add some real content to the page so something gets printed.
+  pdf.text "Javascript Prototype", :at => [150,720], :size => 32
+
+end

data/examples/doc_close.rb

@@ -0,0 +1,13 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'rubygems'
+require 'prawn'
+require 'prawn/js'
+
+Prawn::Document.generate "js_doc_close.pdf" do |pdf|
+
+  pdf.add_will_close_js("app.alert('closing',3)")
+
+  pdf.text "Javascript Prototype", :at => [150,720], :size => 32
+
+end

data/examples/doc_open.rb

@@ -0,0 +1,13 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'rubygems'
+require 'prawn'
+require 'prawn/js'
+
+Prawn::Document.generate "js_doc_open.pdf" do |pdf|
+
+  pdf.add_docopen_js("alert", "app.alert('open!',3)")
+
+  pdf.text "Javascript Prototype", :at => [150,720], :size => 32
+
+end

data/examples/doc_save.rb

@@ -0,0 +1,13 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'rubygems'
+require 'prawn'
+require 'prawn/js'
+
+Prawn::Document.generate "js_doc_save.pdf" do |pdf|
+
+  pdf.add_will_save_js("app.alert('saving',3)")
+
+  pdf.text "Javascript Prototype", :at => [150,720], :size => 32
+
+end

data/examples/manual.rb

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'prawn/core'
+
+# This is how you can add some JS to your PDF files using only prawn-core.
+# Kids, don't try this at home.
+
+NAME_TREE_CHILDREN_LIMIT = 20
+
+Prawn::Document.generate "autoprint.pdf" do |pdf|
+  # Build the script we want to execute when the document opens
+  script = <<-EOF
+    var pp = this.getPrintParams();
+    pp.interactive = pp.constants.interactionLevel.silent;
+    this.print(pp);
+  EOF
+
+  js_root = pdf.ref(Prawn::NameTree::Node.new(self, NAME_TREE_CHILDREN_LIMIT))
+  pdf.names.data[:JavaScript] ||= js_root 
+
+  # embed our script. The label is arbitary and can be anything
+  obj = pdf.ref(:S => :JavaScript, :JS => script)
+
+  # reference our JS fragment from the root javascript object
+  js_root.data.add("some_random_label_that_can_be_anything", obj)
+
+  # finally add some real content to the page so something gets printed.
+  pdf.text "Javascript Prototype", :at => [150,720], :size => 32
+
+end

data/lib/prawn/js.rb

@@ -0,0 +1,93 @@
+# encoding: utf-8
+#
+# js.rb : Implements embeddable Javascript support for PDF
+#
+# Copyright March 2009, James Healy. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE file for details.
+
+gem "prawn", ">= 0.5"
+
+module Prawn
+  module JS
+    # The maximum number of children to fit into a single node in the JavaScript tree.
+    NAME_TREE_CHILDREN_LIMIT = 20 #:nodoc:
+
+    # add a Javascript fragment that will execute after the document is saved.
+    #
+    # There can only be a single fragment. Calling this function multiple times
+    # will override earlier fragments.
+    #
+    def add_did_save_js(script)
+      aa[:DS] = ref(:S => :JavaScript, :JS => script)
+    end
+
+    # add a Javascript fragment that will execute after the document is printed.
+    #
+    # There can only be a single fragment. Calling this function multiple times
+    # will override earlier fragments.
+    #
+    def add_did_print_js(script)
+      aa[:DP] = ref(:S => :JavaScript, :JS => script)
+    end
+
+    # add a Javascript fragment that will execute when the document is opened.
+    #
+    # There can only be as many fragments as required. Calling this function
+    # multiple times will append the new fragment to the list.
+    #
+    def add_docopen_js(name, script)
+      obj = ref(:S => :JavaScript, :JS => script)
+      javascript.data.add(name, obj)
+    end
+
+    # add a Javascript fragment that will execute when the document is closed.
+    #
+    # There can only be a single fragment. Calling this function multiple times
+    # will override earlier fragments.
+    #
+    def add_will_close_js(script)
+      aa[:WC] = ref(:S => :JavaScript, :JS => script)
+    end
+
+    # add a Javascript fragment that will execute before the document is printed.
+    #
+    # There can only be a single fragment. Calling this function multiple times
+    # will override earlier fragments.
+    #
+    def add_will_print_js(script)
+      aa[:WP] = ref(:S => :JavaScript, :JS => script)
+    end
+
+    # add a Javascript fragment that will execute before the document is saved.
+    #
+    # There can only be a single fragment. Calling this function multiple times
+    # will override earlier fragments.
+    #
+    def add_will_save_js(script)
+      aa[:WS] = ref(:S => :JavaScript, :JS => script)
+    end
+
+    private
+
+    # create or access the Additional Actions dictionary in the document catalogue.
+    # See section 8.5.2 and table 8.47 of the PDF spec
+    #
+    def aa
+      # this entry is only valid in the document catalogue in PDF versions 1.4+.
+      min_version(1.4)
+      @root.data[:AA] ||= {}
+    end
+
+    # create or access the Javascript Name Tree in the document names dict.
+    # See section 3.6.3 and table 3.28 in the PDF spec.
+    #
+    def javascript
+      names.data[:JavaScript] ||= ref(Prawn::NameTree::Node.new(self, NAME_TREE_CHILDREN_LIMIT))
+    end
+
+  end
+end
+
+require 'prawn/document'
+Prawn::Document.send(:include, Prawn::JS)

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: prawn-js
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- James Healy
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-18 00:00:00 +10:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: prawn-core
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.5"
+    version: 
+description: A small extension to prawn that simplifies embedding JavaScript in your PDF files
+email: pat@freelancing-gods.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- examples/doc_open.rb
+- examples/doc_close.rb
+- examples/doc_save.rb
+- examples/autoprint.rb
+- examples/manual.rb
+- lib/prawn/js.rb
+- README.markdown
+- MIT-LICENSE
+- CHANGELOG
+has_rdoc: true
+homepage: http://ts.freelancing-gods.com
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --title
+- PrawnJS
+- --line-numbers
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: prawn
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: A small extension to prawn that makes it possible to embed JavaScript fragment in  your document that respond to events.
+test_files: []
+