3.12. JavaScript API (examples subset)

3.12.1. Configuring a custom JavaScript file

The JavaScript custom file must contain a function such as:

function arenderjs_init(arenderjs_){ ... }

This function is called by ARender at startup, the arenderjs_ argument is the JavaScript object collecting all the API functions, as provided by ARender.

You can configure the Javascript custom file to use within ARender by two different ways :

3.12.1.1. Using property arenderjs.startupScript

The property arenderjs.startupScript, if defined, will be used by ARender to fetch the custom Javascript file and execute it when the interface is ready.

This property can be set in the profile file,

arenderjs.startupScript=scripts/myarenderscript.js

Or directly in the URL parameters:

http://arender.arondor.com/ARender/ARender.html?url=http://arender.arondor.com/pdf/pdf/PDFReference15_v5.pdf&arenderjs.startupScript=scripts/arenderJSPAPITest.js

See the default profile jsapi-demo.properties (in the WEB-INF/classes folder of the ARender war) for an example profile. Note that the JavaScript URL can be provided :

  • as a relative URL: the URL is relative to the ARender HMI context root, for example http://arender.arondor.com/ARender
  • as an absolute URL: in this case, beware that most modern browsers forbid having queries from multiple sources, because of the XSS limitations.

3.12.1.2. The “Hollywood Principle

The other option is to define the init function arenderjs_init() in ARender’s parent context. Consider ARender in a IFrame inclusion; the calling application creates an IFrame with an URL pointing to ARender. In this case, the calling application only has to define the function :

function arenderjs_init(arenderjs_){ … }

ARender will look at this function in its parent context, and call it if it exists.

3.12.2. Using the Javascript API

3.12.2.1. Opening documents

  • Object: arender_js

    Function Description
    loadDocument(url , callback)

    Loads a document providing an URL. It will provide an ARender Id back. Arguments:

    • the URL to open
    • the callback function to call when the Id is provided by the server.

    Note: This is purely a server-side operation, asynchronous at client side.

    openDocument(id) Opens a document. Argument: - id: ARender id
    askChangePage(type , index)

    Changes the current page. Arguments:

    • type: ‘Relative’, ‘Index’ or ‘Absolute’
    • index: -1 or 1 for relative or absolute; otherwise the page number
    enablePDFDocumentHyperlinks(boolean)

    Activate/de-activate the internal hyperlinks of a document Arguments:

    • boolean : Load internal hyperlinks of a document if true, unload them otherwise.
    disallowClickOnHyperlinks(boolean)

    Allow/disallow clicks on a document hyperlink for ARender Arguments:

    • boolean : if true, disallow internal hyperlinks of a document, allow them otherwise.
  • Example

     // Loads the PDF reference document
     getARenderJS().loadDocument("http://arender.arondor.com/pdf/pdf/PDFReference15_v5.pdf",
    function(id)
    {
        getARenderJS().openDocument(id);
    });
    
     // Move to page 24 (note that first page is called 0)
     getARenderJS().askChangePage('Index',23);
    
     // Move to last page
     getARenderJS().askChangePage('Absolute',1);
    

3.12.2.2. Register to error events while loading documents

  • Object: arender_js

    Function Description
    registerNotifyLoadingErrorEvent(callback)

    Register a callback function that will be called when an error occurs when loading documents.

    Arguments: - the callback function to call when an error occur.
  • Example

 // Subscribe a function to the errors
 getARenderJS().registerNotifyLoadingErrorEvent(function(documentId,message) {console.log("error: "+message)});
 // Loads the PDF reference document
 // If an error occurs I am notified on the function defined before!
 getARenderJS().loadDocument("http://arender.arondor.com/pdf/pdf/PDFReference15_v5.pdf",
function(id)
{
    getARenderJS().openDocument(id);
});

3.12.2.3. Know when ARender finished to load its modules

  • Object: arender_js

    Function Description
    registerAllAsyncModulesStartedEvent(callback)

    Register a callback function that will be called when ARender finishes loading its modules.

    Arguments: - the callback function to call when asynchronous modules are loaded.
  • Example

    // Subscribe a function to the loading
getARenderJS().registerAllAsyncModulesStartedEvent(function() {console.log("modules are loaded")});
// When asynchronous modules are loaded I am notified on the function defined before!

3.12.2.4. Change zoom

  • Object: getARenderJS().getZoomJSAPI()

    Function Description
    askZoomIn() Zoom
    askZoomOut() Zoom out
    askZoomFullWidth() Zoom full width
    askZoomFullHeight() Zoom full height
    askZoomFullPage() Zoom full page: adapted to both width and height

3.12.2.5. Change document builder

  • Object: getARenderJS().getDocumentBuilder()

    Function Description
    close() Closes the document builder
    open() Open the document builder
    reset() Resets the document builder content

3.12.2.6. Change the document navigator

  • Objet: getARenderJS().getThumbnailsJSAPI()

    Function Description
    resetNavigator() Reset the document navigator size
    hideNavigator() Hide the document navigator
    showNavigator() Show the document navigator
    expandNavigator(width) Enlarge the document navigator size (if width is superior to the current width)
    reduceNavigator(width) Reduce the document navigator size (if width is inferior to the current width)

3.12.2.7. Switch to Fullscreen

  • Object: getARenderJS().getFullScreenJSAPI()

    Function Description
    askOpenFullScreen() Activate fullscreen mode
    askCloseFullScreen() Deactivate fullscreen mode

3.12.2.8. Rotate pages

  • Object: getARenderJS().getRotateJSAPI()

    Function Description
    askRotateCurrentPageLeft() Rotate current page left (counter-clockwise)
    askRotateCurrentPageRight() Rotate current page right (clockwise)
    askRotateAllPageLeft() Rotate all pages of the current document left
    askRotateAllPageRight() Rotate all pages of the current document right

3.12.2.9. Search features

  • Object: getARenderJS().getSearchJSAPI()

    Function Description
    askSearchTextNext(word)

    Searching the next term : “word”

    Argument:

    • word: The word to search
    askSearchTextPrevious(word)

    Searching the previous term : “word”

    Argument:

    • word: The word to search
    clearSearchResults() Clear current search results

3.12.2.10. Download documents

  • Object: getARenderJS().getDownloadDocumentJSAPI()

    Function Description
    askDownloadDocumentPDF() Download the current document in PDF
    askDownloadDocumentSource() Download the current document in source format
    askDownloadAllDocuments() Download a single PDF with all opened documents

3.12.2.12. Setup plugin events and plugin parameters

  • Object: getARenderJS()

    Function Description
    preparePluginEvent(key,value,pluginName) Insert a (Key,Value) couple in the target URL of the next plugin Event of name pluginName
    clearPluginEvent(pluginName) Clear all couple (Key,Value) stored in for the name pluginName
    openPlugin(pluginName,openInMultiView) Open the plugin pluginName in ARender, in multiView or not with the boolean openInMultiView

Those functions allow to prepare an event before opening the plugin in order to setup a correct URL for parameterizing the plugin from ARender ahead of time.

function arenderjs_init(ajs)
{
    // this line prepare an URL such as http://plumeURL/?To=toto@tutu.com
    ajs.preparePluginEvent("To","toto@tutu.com","plume");
    // Here, we clear all stored values for this plugin, can be useful if called from a "clear" button
    ajs.clearPluginEvent("plume");
}

3.12.2.13. Register to the documentBuilder save event

  • Object: getARenderJS().getDocumentBuilderJSAPI()

    Function Description
    registerNotifyAlterDocumentContentEvent(callback)

    Trigger a callback function when a built document is saved

    Arguments: - The callback function to call
  • Exemple

function arenderjs_init(arenderjs_)
{
    arenderjs_.documentBuilder.registerSubmitAlterDocumentContentEvent(function(obj){armt_onSubmitAlterDocumentContentEvent(arenderjs_,obj);});
    arenderjs_.documentBuilder.registerNotifyAlterDocumentContentEvent(function(obj){armt_onNotifyAlterDocumentContentEvent(arenderjs_,obj);});
}

function armt_onSubmitAlterDocumentContentEvent(arenderjs_,obj)
{
    var desc = arenderjs_.documentBuilder.getSubmittedAlterDocumentContentDescription(obj);
    var meta = arenderjs_.documentBuilder.getDocumentMetadata(desc, 0);
    arenderjs_.documentBuilder.addDocumentMetadata(meta, "name", "value");
}

function armt_onNotifyAlterDocumentContentEvent(arenderjs_,obj)
{
    alert("Notify : " + obj);
    var docId = arenderjs_.documentBuilder.getResultDocumentId(obj);
    alert("Notify : " + docId);
    console.log("Notify : docId = " + docId);
}

3.12.2.14. Change notifications

  • Objet: getARenderJS()

    Function Description
    registerNotifyLogEvent(hook)

    Trigger a hook function when a notification is displayed

    Arguments: - The hook function to call

The following functions allow to alterate the received notification event caught by the hook function.

  • Object : getARenderJS()

    Function Description
    setLogEventMessage(event, message)

    Change the notification message by “message”

    Argument:

    • event: The notification event
    • message: the new message
    setLogEventDisplay(event, boolean)

    Allow the notification display

    Argument:

    • event: The notification event
    • boolean: Display the notification if true, hide it if false
    setLogEventLevel(event, level)

    Change the notification level

    Argument:

    • event: The notification event
    • level: the new level (“SEVERE”, “WARNING”, “INFO”, “CONFIG”, “FINE”, “FINER”, ou “FINEST”)
  • Example

getARenderJS().registerNotifyLogEvent(function(event, level, message){
   getARenderJS().setLogEventMessage(event, "Error : " + message);
   getARenderJS().setLogEventLevel(event, "SEVERE");
   getARenderJS().setLogEventDisplay(event, true);
});