第 1 回 kintone JavaScript API のイジりかた
初めて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は、即時関数パターンで書いた方がよいです。
耳慣れない言葉かもしれませんが、実際に見れば「ああ、これね」っていう感じのものなのではないでしょうか。
具体的にはこんな感じです。
|
|
理由を書くと専門用語とかややこしい話になってしまうのですが、平たくいえばこういう書き方をしておけばkintoneの動作を邪魔する心配をしなくて済みます。
他にも重要なことが記載されていますので、 kintone コーディングガイドラインもぜひ参照してください。
kintone JavaScript の書き方 その 2
もうひとつ確認しておくべき情報があります
kintone セキュアコーディングガイドラインです。
いろいろ書かれていますが、今回は1点だけ紹介します。
strict モードの使用
処理内容の先頭に'use strict';
という文字列を記述しましょう。
|
|
これは平たくいうなら、気付かず大きなミスをしてしまったりしないためのおまじないって感じでしょうか。
なんかややこしいなーとか思ってしまった方も、気にしなくて結構です。
即時関数パターンだとかstrictモードだとかそういう小難しい名前はとりあえず置いといて、今はこう書くのがお作法なんだ、くらいに思っておいてください。
詳しく知りたい方は、ぜひ即時関数やstrictモードについて調べてみることをおすすめします。
JavaScript ファイルを作成する
それでは、JavaScriptファイルを作成してみましょう。
エディタは使い慣れたものならなんでもかまいません。
ここまでの話しを踏まえた上で、簡単なアラートメッセージを出すスクリプトを作成してみましょう。
|
|
このJavaScriptを「welcome.js」という名前で保存しましょう。
作成したファイルを kintone に取り込む
それでは、先ほど作成したJavaScriptをkintoneに取り込んでみましょう。
手順については、以下のページに詳しい説明があります。
手順にしたがって先ほどのJavaScriptファイルをアップロードします。
この手順はそれほど難しくないと思いますので、ちょっとした注意点だけ紹介します。
拡張子は .js
ファイル名が不正な場合は、以下のような画面が出力されます。
「設定完了」を忘れずに
ファイルをアップロードし「保存」ボタンを押しただけでは、kintoneにJavaScriptファイルが適用されません。
結構忘れがちなことなのですが、「保存」ボタンを押したあとのアプリの設定画面で右上にある「アプリを更新」ボタンを押すと下図のようなポップアップメッセージが出ますので、ここで「OK」ボタンを押してください。
これを忘れてしまうといくら待っても適用されませんので、くれぐれもご注意くださいね。
私も忙しいときたまにやってしまいます。
文字コードは UTF-8
おっと!やってしまいました。
UTF-8以外の文字コードで保存したファイルをアップロードしてしまったようです。
もう一度ファイルの作成からやり直して、今度は確実にUTF-8で保存し、再度kintoneに取り込みましょう。
取り込みができた方は、以下の画面でアラートが出たことを確認できるかと思います。
- レコードの一覧画面
- レコードの登録画面
- レコードの編集画面
- レコードの詳細画面
- レコードの集計結果画面(PCのみ)
しかし、このままではどの画面でも同じものが出るだけです。
これでは、一覧画面だけで処理を行いたい場合などには適していません。どうすればよいでしょうか?
kintone のイベント処理に触れてみる
ここで登場するのが「イベント」です。
イベント処理の記述方法については、
イベントハンドラーを登録するに記述されています。
|
|
これが、イベントハンドラーを登録するための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へ取り込み、実際の動きを見てみましょう。
|
|
どのイベントのときにどのメッセージが表示されたかを確認しましょう。
詳しいことは、
イベント処理の記述方法と各イベントの説明ページを参考にしてみてください。
最後に
今回は基本の「き」ということで、JavaScriptの記述ルールや、JavaScriptをkintoneへアップロードして動作させるまでの手順を紹介しました。
また、イベントについても紹介しました。
なんとなくkintoneでできることがイメージできたのではないでしょうか?
「cybozu developer network」では、JavaScriptを使ったカスタマイズのサンプルも豊富にそろえていますので、ぜひ確かめてみることをおすすめします。
デモ環境
デモ環境で実際に動作を確認できます。
https://dev-demo.cybozu.com/k/1/
ログイン情報は cybozu developer network デモ環境で確認してください。