iPaper Javascript API

While most users have no need to customize iPaper, we've implemented a robust set of tools for integrating iPaper with your web application. If you'd like to dive right in, you can skip to the examples section for useful code snippets.

Contents

1. Getting Started
2. Constructors
3. Properties
4. Methods
5. Events
6. addParam() Parameters
7. Keyword Highlighting in iPaper
8. Search Engine Support
9. Examples

Getting Started

 

Using iPaper's Javascript API is easy. To get started, most users can follow these steps:

1. Include Scribd's View.js
2. Create a document object
3. Add the 'jsapi_version' parameter
4. Define an iPaperReady event listener, and add it to the document object
5. Call the document object's write method

You can use the following code to create a bare-bones iPaper installation with API support:

<script type='text/javascript' src='http://www.scribd.com/javascripts/view.js'></script>

<div id='embedded_flash'><a href="http://www.scribd.com"></a></div>

<script type="text/javascript">
var scribd_doc = scribd.Document.getDoc( 2659, 'key-6vhdaqehjkeob' );

var oniPaperReady = function(e){
// scribd_doc.api.setPage(3);
}

scribd_doc.addParam( 'jsapi_version', 1 );
scribd_doc.addEventListener( 'iPaperReady', oniPaperReady );
scribd_doc.write( 'embedded_flash' );
</script>

 

Constructors

scribd.Document.getDoc ( document_id , access_key )

This constructor gets an existing iPaper document. You'll need the document_id and access_key to embed the document. You can get these from the Scribd API if you're using it or from the doc's page on Scribd.

scribd.Document.getDocFromUrl ( url , scribd_publisher_id )

This constructor creates an iPaper from the URL of a document. To get the required scribd_publisher_id, you'll need to create a Scribd API account. The URL needs to be a document type supported by Scribd, like a PDF, not a normal HTML webpage.

 

Properties

api

Only available once iPaper has signaled it's ready. This property is a reference to iPaper's javascript interface. View the available api methods in the following section.

 

Methods

write( element_id:Number )

Builds the appropriate embed code, which is written to the specified target's innerHTML. We recommend using a DIV tag or other block-level element with this method.

addParam( key:Number, value:String )

Used to specify iPaper attributes and behavior. Must be called before write(). See the parameter section below for supported parameters.

addEventListener ( eventType:String, callback:Function )

Used to assign a listener to iPaper events. See the events section for supported event types, and the examples section for relevant sample code.

removeEventListener ( eventType:String, callback:Function )

Used to remove an iPaper event listener. See the events section for supported event types, and the examples section for relevant sample code.

 

api.getPageCount( ):Number

Returns the total number of pages in the document.

api.getPage( ):Number

Returns the current page as displayed in the toolbar.

api.setPage( pageNumber:Number )

Jumps to the specified page. Input is bound between 0 and the current page count.

api.getZoom( ):Number

Returns the current zoom factor, where a value of 1 is equal to a zoom factor of 100%.

api.setZoom( zoomFactor:Number )

Accepts a zoom factor, where a value of 1 is equal to a zoom factor of 100%.

api.getVerticalScroll( ):Number

Returns a position value, in the format required by api.setVerticalScroll().

api.setVerticalScroll( scrollPosition:Number )

Parameter should be in the format of page.fraction, where the integer represents which page to scroll to and the fraction represents how far down that page to scroll. For example, a value of 7.5 will scroll the viewport's upper edge to the second half of page seven.

api.getHorizontalScroll( ):Number

Returns a position value, in the format required by api.setHorizotalScroll().

api.setHorizontalScroll( scrollPosition:Number )

A number between 0 and 1 which specifies where to align the left edge of the viewport. For example, a value of .5 will scroll the viewport so the left edge is aligned with the center of the current page. Input is sensibly bound between 0 and 1.

api.getDocumentId( ):String

Returns the document ID of the most recently loaded document.

api.loadDocument( document_id:String, access_key:String )

Loads a document using its document id and access key.

api.loadDocumentFromUrl( url:String, publisher_id:String )

Converts and loads the document located at the remote URL.

api.getViewMode( ):String

Returns the current view mode of iPaper as one of the following strings: "list", "book", "slide", "tile".

api.getFullscreen( ):Boolean

Returns true if iPaper is currently in fullscreen mode, false if not.

api.setFullscreen( fullscreen:Boolean )

If fullscreen is true, iPaper is switched into the fullscreen state. If false, iPaper will return to its normal state.

api.getEmbedCode( ):String

Returns the current document's embed code.

 

Events

See addEventListener() or examples for more information.

iPaperReady

Signals when it's safe to begin using the api object methods. Fired when iPaper has finished successfully loading the first page of the current document.

pageChanged

Fired whenever a user has moved to a new page. Use api.getPage() to get the new page.

viewModeChanged

Fired when iPaper has changed view modes. Use api.getViewMode() to get the current view mode.

zoomChanged

Fired when the zoom level has changed. Use api.getZoom() to get the current zoom level.

 

addParam() Parameters

The following are keys that can be passed to the addParam instance method.

"height" => integer

The height of iPaper, in pixels. If this is not sepecified, iPaper will attempt to size itself correctly for the webpage it's embedded in.

"width" => integer

The width of iPaper, in pixels. If this parameter is not sepecified, iPaper will attempt to size itself correctly for the webpage it's embedded in.

"public" => boolean

Whether to make the document public on Scribd. This parameter is only for iPapers created with the getDocFromUrl constructor. iPapers created with the getDoc constructor will ignore this parameter.

"page" => integer

You can use this to scroll iPaper to a default start page. Defaults to 1.

"my_user_id" => string

If you run a user-generated content site, you can use this parameter to very easily integrate your user authentication system into Scribd. For a full explanation of how this works, please see the Scribd API documentation.

"extension" => string

This parameter is only for iPapers created from the getDocFromUrl constructor.

When Scribd processes a file it will try to identify the filetype using the contents of the file and various heuristics. If Scribd is guessing wrong on one of your files, you can override this behavior and set the extension directly with this parameter (e.g., "docx").

"title" => string

This parameter is only for iPapers created from the getDocFromUrl constructor.

Sets the title of the new file uploaded.

"transferCookie" => boolean

This parameter is only for iPapers created from the getDocFromUrl constructor.

If your documents are stored at URLs that are not accessible on the public internet, you can use this parameter to allow iPaper to read them. If transferCookie is true, iPaper will access the given URL using the browser cookies of the user who is using iPaper at that moment. This will allow iPaper to bypass cookie-based authentication mechanisms. It should not otherwise be used as it will cause a performance impact.

"search_query" => string

A string of keywords to highlight in iPaper. If the user is coming from a search engine, this parameter should contain the user's raw search query. The user's query will be stripped of stopwords and delimeted by spaces before highlighting.

"jsapi_version" => integer

Specify the interface version you're targeting. We require this parameter so we can add new API features without breaking existing installations. The most current supported interface is version 1.

"disable_related_docs" => boolean

Disables the related documents tab in List Mode.

"mode" => string

Sets the default view mode for the document, overriding the document's default. Parameter must be added before the document is written. Valid values are: "list", "book", "slide", and "tile".

"auto_size" => boolean

When false, this parameter forces iPaper to use the provided width and height rather than using a width multiplier of 85/110.

"hide_full_screen_button" => boolean

Hides the fullscreen button and disables switching to fullscreen mode, if set.

"full_screen_type" =>string

Sets the type of the fullscreen mode iPaper will switch to when fullscreen button is pressed. Valid values are: "js", "flash", "url":
flash: Display true fullscreen mode of Flash Player.
js: Maximize iPaper within the browser window.
url: Go to fullscreen url of the document on scribd.com.

"disable_resume_reading" => boolean

If set, does not display the toolbar message "Click here to continue reading on page X".

 

Keyword Highlighting in iPaper

To help users arriving at Scribd from a search engine, we've implemented the ability to highlight a user's search query whereever it appears in a document. If query keywords are provided before the document has loaded, iPaper will scroll to the first occurance of a query term. (This is accomplished by adding the search query and, optionally, keywords as iPaper parameters).

 

Search Engine Support

If you're using iPaper on your website, you may well want to have the full text of your documents indexed by search engines. Having the full text indexed can be quite effective at bringing additional traffic to your site. To get the text of an iPaper indexed, you use an alternate embed code, one which contains the full text in the embed code itself. It looks like this:

<script type="text/javascript" src='http://www.scribd.com/javascripts/view.js'></script> 

<div style='display:none' >
<!-- REPLACE THIS COMMENT WITH THE DOCUMENT'S TEXT -->
</div>

<div id='embedded_flash'><a href='http://www.scribd.com'>Scribd</a></div>

<script type="text/javascript">
var scribd_doc = scribd.Document.getDoc(2659, 'key-6vhdaqehjkeob'); 

var oniPaperReady = function(e){
// scribd_doc.api.setPage(3);
}

scribd_doc.addParam( 'jsapi_version', 1 );
scribd_doc.addEventListener( 'iPaperReady', oniPaperReady );
scribd_doc.write('embedded_flash');
</script>
		

To get the full text of the documents, we recommend downloading Scribd's extracted text using the docs.getDownloadUrl API method and storing it in a database.

 

Examples

Here's another example of an iPaper embed with more options set.

<script type="text/javascript" src='http://www.scribd.com/javascripts/view.js'></script>

<div id='embedded_flash' > 
<a href='http://www.scribd.com'>Scribd</a>
</div>

<script type="text/javascript">
var scribd_doc = scribd.Document.getDocFromUrl('http://lib.store.yahoo.net/lib/paulgraham/onlisp.ps', 'PUT-YOUR-SCRIBD-PUBLISHER-ID-HERE'); 

var oniPaperReady = function(e){
// scribd_doc.api.setPage(3);
}

scribd_doc.addEventListener( 'iPaperReady', oniPaperReady );
scribd_doc.addParam('jsapi_version', 1);
scribd_doc.addParam('height', 600);
scribd_doc.addParam('width', 400);
scribd_doc.addParam('page', 10);
scribd_doc.addParam('public', true);

scribd_doc.write('embedded_flash'); 
</script>
		

This final example demonstrates the power of the iPaper javascript API. In full sample application below, you can see how to create a rich document viewer with page notes and deep linking.

See the full sample application