NOT Calling the REST API from JavaScript in Visualforce Pages!

The RemoteTK Visualforce Custom Component (comprising RemoteTK.component and RemoteTKController.cls) provides an abstraction very similar to the Force.com REST API, implemented via @RemoteAction methods in the component's controller. RemoteTK offers similar functionality to forcetk.js, without consuming API calls.

UPDATE (December 2014) – Visualforce Remote Objects (VRO) are a better, more secure way to access Force.com from Visualforce. Use VRO rather than RemoteTK. See this blog entry for more details.

Back in Spring 2011 (the season, not the release!), I wrote the Force.com JavaScript REST Toolkit (or ForceTK for short, after forcetk.js, its core JavaScript library), wrapping the Force.com REST API for easy access from JavaScript running on Visualforce pages, external servers, and hybrid mobile apps. Since then, the toolkit has seen wide adoption, most notably as part of the Salesforce Mobile SDK, but it has always bugged me that JavaScript on Visualforce pages would consume API calls (a limited resource), limiting the usefulness of the toolkit somewhat.

Coincidentally, in Spring ’11 (the release this time), JavaScript Remoting, a mechanism for calling Apex controller methods (annotated with @RemoteAction) from JavaScript, debuted as a developer preview. I’ve used Remoting a few times, writing @RemoteAction methods for each specific situation, but it wasn’t until I read Don Robins’ second article on Developing Mobile Applications with Force.com and Sencha Touch, with its mention of the Sencha proxy for binding JavaScript controller logic to @RemoteAction methods in an Apex controller, that I realised that I could write a set of @RemoteAction methods for general purpose data access and a corresponding set of JavaScript wrappers exposing the same interface as ForceTK, all conveniently wrapped in a Custom Component – RemoteTK.

Quoting from the updated toolkit README:

The RemoteTK Visualforce Custom Component (comprising RemoteTK.component and RemoteTKController.cls) provides an abstraction very similar to the REST API, implemented via @RemoteAction methods in the component’s controller. The advantage of this mechanism is that no API calls are consumed. A disadvantage is that upsert is not currently implemented. [UPDATE – Spring ’13 added the ability to pass sobject type variables to Database.upsert]

[…]

Add RemoteTKController.cls and RemoteTK.component to your org by creating an Apex Class and a Component and pasting in the respective content, pasting the files into a Force.com IDE project, or by using the Force.com Migration Tool.

Your Visualforce page will need to include the component and create a client object. An absolutely minimal sample is:

<apex:page>
    <!-- Include the RemoteTK component -->
    <c:RemoteTK />
    <apex:includeScript value="https://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js" />
    <script type="text/javascript">
        // Get a reference to jQuery that we can work with
        $j = jQuery.noConflict();

        // Get an instance of the RemoteTK client
        var client = new remotetk.Client();
        client.query("SELECT Name FROM Account LIMIT 1", function(response){
            $j('#accountname').html(response.records[0].Name);
        });
    </script>
    <p>The first account I see is <span id="accountname"></span>.</p>
</apex:page>

More fully featured samples are provided in RemoteTKExample.page and RemoteTKMobile.page.

Since I started work on RemoteTK just last Friday it’s probably best described as ’embryonic’, but I ported the two ForceTK sample apps to RemoteTK with just three changes (include the RemoteTK component, get an instance of the RemoteTK client, rather than ForceTK, and delete the call to setSessionToken()) and they seem to work well.

A few known issues at present:

  • Upsert is not supported – I haven’t figured out how to do this with a dynamic external field ID name. It might not be possible.
  • describe() is a very minimal implementation – just enough to get the sample apps working.
  • 0% test coverage – this prevents me from creating an unmanaged package. Much more soluble than the upsert issue!
So, if you’ve been using forcetk.js from Visualforce, give RemoteTK a try (it’s part of the expanded Force.com JavaScript REST Toolkit), send me a pull request if you fix any of the above, and/or file issues on the GitHub project.

Leave your comments...

NOT Calling the REST API from JavaScript in Visualforce Pages!