第 1 回 kintone JavaScript API のイジりかた

著者名: 落合 雄一 (External link)

目次

information

初めて kintone をカスタマイズする人が kintone API の基礎知識を学べるよう、チュートリアルの内容を充実させてリニューアルしました。
リニューアル後のチュートリアルは次のページを参照してください。
はじめよう kintone API

はじめに

「はじめよう kintone JavaScript API」では、これから kintone を自分好みに便利にカッコ良くしていきたい!!という方向けに kintone JavaScript API の基本的な使い方を分かりやすく紹介していきます。

記念すべき第 1 回は、kintone をカスタマイズしていく上での基本の「き」です。
JavaScript の記述ルールや、JavaScript を kintone へアップロードして動作させるまでの手順を紹介します。
また、kintone JavaScript API を利用する上で非常に重要な「イベント」についても簡単に紹介します。

なお、この連載では HTML/JavaScript/CSS についての基礎的な技術知識がある方を対象にしています。
このあたりの情報については、Web サイトや書籍など世の中にたくさん資料が出回っていますので、ぜひそちらをご参考いただくようお願いします。

kintone JavaScript の書き方 その 1

kintone では、カスタマイズする際の JavaScript に関する kintone コーディングガイドライン というものを策定しています。
kintone をカスタマイズする前に、簡単に確認していきましょう。

拡張子は .js で保存

作成した JavaScript ファイルを拡張子 .js で保存してください。

文字コードは UTF-8(BOM なし)

BOM(バイトオーダーマーク)については、このせいで必ず不具合が出るって訳ではありませんが、だからこそやっかいでもあります。
あとでハマってしまったときに「なんでやねんっ!」とならないように、BOM なし UTF-8 でのファイル保存はぜひマスターしておいてくださいね。

即時関数パターンで記述

JavaScript は、即時関数パターンで書いた方がよいです。
耳慣れない言葉かもしれませんが、実際に見れば「ああ、これね」っていう感じのものなのではないでしょうか。
具体的にはこんな感じです。

1
2
3
(() => {
  // ここに処理したい内容を書いていく
})();

理由を書くと専門用語とかややこしい話になってしまうのですが、平たくいえばこういう書き方をしておけば kintone の動作を邪魔する心配をしなくて済みます。

他にも重要なことが記載されていますので、 kintone コーディングガイドライン もぜひ参照してください。

kintone JavaScript の書き方 その 2

もうひとつ確認しておくべき情報があります。 kintone セキュアコーディングガイドライン です。
いろいろ書かれていますが、今回は 1 点だけ紹介します。

strict モードの使用

処理内容の先頭に 'use strict'; という文字列を記述しましょう。

1
2
3
4
(() => {
  'use strict';
  // ここに処理したい内容を書いていく
})();

これは平たくいうなら、気付かず大きなミスをしてしまったりしないためのおまじないって感じでしょうか。
なんかややこしいなーとか思ってしまった方も、気にしなくて結構です。
即時関数パターンだとか strict モードだとかそういう小難しい名前はとりあえず置いといて、今はこう書くのがお作法なんだ、くらいに思っておいてください。
詳しく知りたい方は、ぜひ即時関数や strict モードについて調べてみることをおすすめします。

JavaScript ファイルを作成する

それでは、JavaScript ファイルを作成してみましょう。
エディタは使い慣れたものならなんでもかまいません。
ここまでの話しを踏まえた上で、簡単なアラートメッセージを出すスクリプトを作成してみましょう。

1
2
3
4
(() => {
  'use strict';
  alert('はじめようkintone JavaScript API');
})();

この JavaScript を「welcome.js」という名前で保存しましょう。

作成したファイルを kintone に取り込む

それでは、先ほど作成した JavaScript を kintone に取り込んでみましょう。
手順については、以下のページに詳しい説明があります。

手順にしたがって先ほどの JavaScript ファイルをアップロードします。
この手順はそれほど難しくないと思いますので、ちょっとした注意点だけ紹介します。

拡張子は .js

ファイル名が不正な場合は、以下のような画面が出力されます。

「設定完了」を忘れずに

ファイルをアップロードし「保存」ボタンを押しただけでは、kintone に JavaScript ファイルが適用されません。
結構忘れがちなことなのですが、「保存」ボタンを押したあとのアプリの設定画面で右上にある「アプリを更新」ボタンを押すと下図のようなポップアップメッセージが出ますので、ここで「OK」ボタンを押してください。
これを忘れてしまうといくら待っても適用されませんので、くれぐれもご注意くださいね。
私も忙しいときたまにやってしまいます。

文字コードは UTF-8

おっと!やってしまいました。
UTF-8 以外の文字コードで保存したファイルをアップロードしてしまったようです。

もう一度ファイルの作成からやり直して、今度は確実に UTF-8 で保存し、再度 kintone に取り込みましょう。
取り込みができた方は、以下の画面でアラートが出たことを確認できるかと思います。

  • レコードの一覧画面
  • レコードの登録画面
  • レコードの編集画面
  • レコードの詳細画面
  • レコードの集計結果画面(PC のみ)

しかし、このままではどの画面でも同じものが出るだけです。
これでは、一覧画面だけで処理を行いたい場合などには適していません。どうすればよいでしょうか?

kintone のイベント処理に触れてみる

ここで登場するのが「イベント」です。
イベント処理の記述方法については、 イベントハンドラーを登録する に記述されています。

1
kintone.events.on(event, handler)

これが、イベントハンドラーを登録するための kintone JavaScript API の関数になります。
なんか難しそうですね。

たとえば、「○○ が実行されたとき」に「×× の処理を実行」したいとします。
これを上の関数に当てはめると、次のようになります。

  • ○○ にあたるのが event
  • ×× にあたるのが handler

なんとなくイメージがつかめたのではないでしょうか?。
○○ にあたる event は、kintone JavaScript API では、例として以下のようなものが用意されています。

  • レコード一覧イベント:app.record.index.show
  • レコード表示イベント:app.record.detail.show
  • レコード追加イベント:app.record.create.show
  • レコード編集イベント:app.record.edit.show
  • グラフ表示イベント:app.report.show

×× の書き方は、言葉で説明するより実際の動きを見た方がわかりやすいのではと思います。
以下のコードを「welcome.js」に上書きし、再度 kintone へ取り込み、実際の動きを見てみましょう。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
(() => {
  'use strict';

  kintone.events.on('app.record.index.show', (event) => {
    alert('レコード一覧イベント');
  });

  kintone.events.on('app.record.detail.show', (event) => {
    alert('レコード表示イベント');
  });

  kintone.events.on('app.record.create.show', (event) => {
    alert('レコード追加イベント');
  });

  kintone.events.on('app.record.edit.show', (event) => {
    alert('レコード編集イベント');
  });

  kintone.events.on('app.report.show', (event) => {
    alert('グラフ表示イベント');
  });
})();

どのイベントのときにどのメッセージが表示されたかを確認しましょう。
詳しいことは、 イベント処理の記述方法 と各イベントの説明ページを参考にしてみてください。

最後に

今回は基本の「き」ということで、JavaScript の記述ルールや、JavaScript を kintone へアップロードして動作させるまでの手順を紹介しました。
また、イベントについても紹介しました。
なんとなく kintone でできることがイメージできたのではないでしょうか?

「cybozu developer network」では、JavaScript を使ったカスタマイズのサンプルも豊富にそろえていますので、ぜひ確かめてみることをおすすめします。

デモ環境

デモ環境で実際に動作を確認できます。
https://dev-demo.cybozu.com/k/1/ (External link)

ログイン情報は cybozu developer network デモ環境 で確認してください。