nkjmkzk.net

powered by Kazuki Nakajima

Archive for 8月, 2014

AngularJSからForce.com REST APIにアクセスするためのツールキット、forcetk4ng

概要

forcetk4ngはAngularJSのモジュールで、このモジュールを利用することでVisualforce内のJavascriptから簡単にForce.comのREST APIをコールできるようになります。

すでに世の中にはJavascriptからForce.com REST APIにアクセスするためForce.com Javascript REST Toolkitjsforceというすばらしいライブラリが存在するわけですが、forcetk4ngはよりAngularJSの記法に忠実にAPIコールをおこなうことができます。

より具体的にはforcetk4ngはAngularJS標準のpromise/deferred実装である$qを使用しているため、$qのpromiseを利用してAPIコールを含む処理を連続的に記述することができます。

また、forcetk4ngはAngularJS以外に依存するライブラリはありませんのでシンプルな構成となります。

要件

  • AngularJS
  • Force.com Visualforce (現在forcetk4ngはVisualforce上でのみ動作します。)

サンプルコード

どんなふうに記述できるのか、まずはサンプルコードをみておきましょう。

<apex:page standardStylesheets="false" showHeader="false" applyHtmlTag="false" applyBodyTag="false" docType="html-5.0">
<html ng-app="ngbootcamp">
<head>
<script src="{!$Resource.angular_min_js}"></script>
<script src="{!$Resource.forcetk4ng_js}"></script>

<script>
angular.module('ngbootcamp', ['forcetk4ng'])
.controller('guestCtl', function($scope, force){

    force.setAccessToken('{!$Api.Session_ID}');
    $scope.guest = {};

    $scope.getGuests = function(){
        force.query("select Id, Name from guest__c")
        .then(
            function(records){
                $scope.guest.records = records;
            },
            function(event){
                console.log(event);
            }
        );
    }
});
</script>
</head>

<body>
    <div ng-controller="guestCtl">
        <button ng-click="getGuests()">Retrieve Guests</button>
        <div ng-repeat="record in guest.records">
            {{record.Name}}
        </div>
    </div>
</body>
</html>
</apex:page>

使い方

Sample Codeを順に追いかけながら使い方を見ていきます。

ライブラリの入手

Githubのレポジトリからforcetk4ng.jsをダウンロードします。
https://github.com/nkjm/forcetk4ng

静的リソースへアップロード

AngularJS本体とforcetk4ngをForce.comの静的リソースにアップロードします。CDNを利用してもかまいませんが、その場合の後のscriptのパスは適宜読み替えてください。

angular.min.js
- 名前: angular_min_js
- キャッシュコントロール: 公開

forcetk4ng.js
- 名前: forcetk4ng_js
- キャッシュコントロール: 公開

ライブラリの読み込み

新しいVisualforceページを作成するか既存のVisualforceページを開きます。そしてライブラリファイルを読み込みます。

<script src="{!$Resource.angular_min_js"></script>  
<script src="{!$Resource.forcetk4ng_js"></script>

モジュールのInjection

forcetk4ngを利用するモジュールに差し込みます。

angular.module('ngbootcamp', ['forcetk4ng'])

forceサービス利用の宣言

forcetk4ngの関数群は”force”というサービス名で利用できます。 コントローラーでforceサービスの使用を宣言します。

.controller('guestCtl', funciton($scope, force){

アクセストークンのセット

forcetk4ngはForce.com REST APIを利用するため、明示的にアクセストークンをセットする必要があります。Visualforce上では簡単にセッションIDを取得でき、これがアクセストークンとして利用できます。このセッションIDをそのままforce.setAccessToken()関数に渡すことでアクセストークンのセットが完了します。

force.setAccessToken('{!$Api.Session_ID}');

forceサービスの実行

コントローラー内でforceサービスを実行します。forceサービスが提供するAPIをコールする関数群(ajax/query/retrieve/create/update/upsert/delete/describe)はすべて$qサービスが提供するPromiseインスタンスを返します。このPromiseインスタンスではthen()、catch()、finally()といったメソッドが提供されており、APIコールの結果に応じて次の処理を脈々と記述することが可能です。

force.query("select Id, Name from guest__c")
.then(
    // 成功時のコールバック
    function(records){
        $scope.guest.records = records;
    },
    // 失敗時のコールバック
    function(event){
        console.log(event);
    }
);

提供されている関数

現在forcetk4ngでは下記の関数が提供されています。

  • force.setAccessToken(ACCESS_TOKEN)
  • force.setApiVersion(API_VERSION)
  • force.ajax(PATH, METHOD, RESPONSE_TYPE)
  • force.query(SOQL)
  • force.retrieve(OBJECT_TYPE, RECORD_ID, FIELDS)
  • force.create(OBJECT_TYPE, RECORD)
  • force.update(OBJECT_TYPE, RECORD)
  • force.upsert(OBJECT_TYPE, EXTERNAL_ID_FIELD, EXTERNAL_ID, RECORD)
  • force.delete(OBJECT_TYPE, RECORD_ID)
  • force.describe(OBJECT_TYPE)

Enjoy.

without comments

Written by 中嶋 一樹

8月 7th, 2014 at 4:07 pm

Posted in Uncategorized

Tagged with ,