Title: ウィジェットの作り方(新しいウィジェットの追加方法)

ウィジェット(トークン)の基本的な構造や動作 では、ウィジェット(トークン)を作成するに当たって必要となる基本知識について解説しました。ここでは、「Google Docs ウィジェット」という新しいウィジェットを実際に作ります。オリジナルなウィジェット作成の参考にしてください。



ウィジェットの基本構想



まずは、ウィジェットがどのような動作をするのか、基本的な仕様を思い描きましょう。次のような簡単なスケッチで構いません。



以上のようなスケッチから、実際にどのような設定ファイルや SDL プログラミングをするのかを考えていきます。

プラグインの作成



この新しい「Google Docs ウィジェット」は、プラグインとして TeamPage に組み込むことにします。つまり、「Google Docs ウィジェット機能を提供するプラグイン」を新しく作成します。

プラグインの基本については FAQ1683: TeamPage プラグイン概要 を参照してください。

プラグインのフォルダ



プラグイン作成は、TeamPage がインストールされた server 下の plugins フォルダに、そのプラグイン専用のフォルダを新しく作ることから始めます。

プラグインの名前を「com.traction.googledocs」とすることにして、この名前のフォルダを plugins フォルダに作成します。

プラグインの名前(フォルダ名)は、原則的に、作成者のドメイン名を逆にしたものになります。例えば、example.co.jp 社が「foobar」プラグインを作る場合、プラグインの名前は「jp.co.example.foobar」になります。

プラグインのフォルダを作成する

プラグインの設定ファイル



この com.traction.googledocs フォルダの中に plugin.properties ファイルを作成します。

プラグインの設定ファイルを作る

plugin.properties は、プラグイン全体の基本設定ファイルです。プラグインの名称やバージョン番号などを記載します。

テキストエディタで開いて次のように記述し、上書き保存します。

display_name=Google Docs Widget
description=This plugin lets you put your Google Document in the body text of your article.
name=com.traction.googledocs
version=1.0.0
buildnum=0


動作確認



[サーバー セットアップ] > [一般] > [サーバー管理] ページの [キャッシュのクリア] をクリックします。

[サーバー セットアップ] > [プラグイン] ページのインストール済みプラグインの一覧に [Google Docs Widget] プラグインが表示されることを確認します。これで新しいプラグイン「com.traction.googledocs」が TeamPage に認識されました。

プラグインが認識された

Google ドキュメントの ID を確認する



ここでは「WidgetTest」というテスト用のスプレッドシート(下図)を Google Drive に作成しました。

サンプルのスプレッドシート

[ファイル] > [ウェブに公開...] を選択します。

Webに公開

公開設定を行い、[埋め込む] タブを選択すると、<iframe>...</iframe> タグを使った埋め込み用の HTML コードが表示されます。

iframeを使った埋め込みコード

埋め込み用の <iframe> タグの src= で指定する URL は、次のようになることがわかります。

https://docs.google.com/a/自社ドメイン名/種類/d/ドキュメントID/pubhtml?widget=true&headers=false


つまり、次のことがわかれば、<iframe>...</iframe> の HTML コードを生成できることになります。



これから作る Google Docs ウィジェットでは、これらをパラメーターとして次のように指定することにします。

[[ /googledocs domain="自社ドメイン" doctype="ドキュメントの種類" docid="ドキュメントのID" ]]


このドキュメント ID は、ドキュメントを開いた時の URL でも確認できます。



ウィジェットを作る



プラグインの用意はできました。ここからが本番、ウィジェットそのものを作ります。

ウィジェットは、次の3部構成となっています。

  1. ウィジェットの定義ファイル ... ウィジェットがどのような名前なのか、どのようなラピッドセレクタで呼び出せるようにするか、HTML レンダリングを行う SDL はどこにあるのか等を決めるファイルです。
  2. ウィジェットの HTML レンダリング用ファイル ... 実際に HTML として画面(記事本文)に出力されるときに使われるテンプレート用 SDL ファイルで、「ウィジェットが実際にどのように動作するか」を決めます。
  3. ウィジェット一覧に表示するための定義ファイル ... リッチテキスト エディタの [ウィジェットの挿入/編集] のウィジェット一覧に表示するための定義ファイルです。


ウィジェットの定義ファイル



設置場所



プラグインのフォルダに config/entry/tokens/html フォルダ階層を作成し、html フォルダ内に googledocs.properties という名前のファイルを作成します。

フォルダ階層と定義ファイルの作成

定義ファイルの記述



googledocs.properties をテキストエディタで開いて次のように記述し、上書き保存します。

sdl=com.traction.sdl.token.googledocs
rskeywords=googledocs,gdocs


定義ファイルの記述

sdl= 行で、ウィジェットの HTML レンダリングに使用する SDL ファイル(後述)の場所を指定します。

ドット記号はフォルダの階層を表し、最後のドット記号以降は SDL ファイルの名前です。「com.traction.sdl.token.googledocs」は、com フォルダの中の、traction フォルダの中の、sdl フォルダの中の、token フォルダの中の、googledocs.sdl ファイルという意味です。

rskeywords= 行は、トークン(ウィジェット)を呼び出すためのラピッドセレクタを指定します。トークンは、記事本文に [[ /TokenName param1='foo' param2='bar' ... ]] のように書いて実行する(記事に埋め込む)のですが、このときの「TokenName」として使うキーワードを指定するのがこの rskeywords= 行です。

rskeywords=googledocs,gdocs は、このトークンを [[ /googledocs ]] または [[ /gdocs ]] と書くことで実行できることを意味しています。

ウィジェットの HTML 表示用ファイル



設置場所



プラグインのフォルダに、com/traction/sdl/token フォルダ階層を作成し、token フォルダ内に googledocs.sdl という名前のファイルを作成します。

このフォルダ階層は、上記の googledocs.properties ファイルの sdl= 行で指定したものです。

SDLファイルの階層

SDL プログラミング



Google ドキュメントの [ファイル] > [ウェブに公開...] > [埋め込み] から(上述)、HTML のコードは次のようになることがわかっていますので、これをそのまま googledocs.sdl に記述しましょう。

<iframe src="https://docs.google.com/a/ドメイン名/種類/d/ドキュメントID/pubhtml?widget=true&amp;headers=false"></iframe>


パラメーターの指定と値の取得


ウィジェットを [[ /googledocs param1="foo" param2="bar" ]] と実行すると、このパラメーター param1 と param2 は、SDL ファイル内で <property.value name="param1" /><property.value name="param2" /> で参照できます。

<property.value name="param1" />
<property.value name="param2" />


前述したとおり、今回作成するウィジェットは、実際には [[ /googledocs domain="自社ドメイン" doctype="ドキュメントの種類" docid="ドキュメントのID" ]] として使うので、SDL ファイル内で次のようにしてパラメーターの値を取得できます。

<property.value name="domain" />
<property.value name="doctype" />
<property.value name="docid" />


これを <iframe> の src= に組み込むと次のようになります。

src= の値がダブルクオーテーション記号で囲まれているため、そこに含まれるローカル変数の名前はシングルクォーテーション記号で囲んでいることに注意してください。(name="変数名" ではなく name='変数名' としている)

<iframe src="https://docs.google.com/a/<property.value name='domain' />/<property.value name='doctype' />/d/<property.value name='docid' />/pubhtml?widget=true&amp;headers=false">
</iframe>


上記のコードを googledocs.sdl に記述して保存します。

動作テスト



ここで動作テストしてみましょう。

[サーバーセットアップ] > [一般] > [サーバー管理] ページの [キャッシュのクリア] をクリックして変更を反映させます。

記事の本文に [[ /googledocs domain="ドメイン名" doctype="spreadsheets" docid="ドキュメントID" ]] と記入します。



記事を投稿すると下図のように表示されました。幅や高さを指定していないので小さく表示されていますが、「パラメーターで指定されたドメイン名、種類、ID から特定の Google ドキュメントを表示する」という基本的な動作には問題ないことがわかります。



幅と高さのパラメーターを追加する



上の動作テストで幅と高さの指定が必要なことがわかりました。

googledocs.sdl<iframe>width="<property.value name='width' default='600' />"height="<property.value name='height' default='400' />" を追加して次のようにします。

<iframe src="https://docs.google.com/a/<property.value name='domain' />/<property.value name='doctype' />/d/<property.value name='docid' />/pubhtml?widget=true&amp;headers=false" width="<property.value name='width' default='600' />" height="<property.value name='height' default='400' />">
</iframe>


ここで default='NNN' という既定値を指定していることに注目してください。

これは、「もし width (または height) パラメーターの値が指定されていなければ、デフォルトで 600 (または 400) の値を使う」という意味です。ユーザーがウィジェットを使用するときに幅や高さを指定しない場合、ウィジェットは自動的に既定の高さ 600px 幅 400px で表示されます。

サーバーセットアップで [キャッシュのクリア] を実行し、先ほどのテスト記事を再読み込みしてみましょう。幅や高さを指定していないにもかかわらず、下図のように高さ 600px 幅 400px で表示されます。



既定値を使わずに幅や高さを手動で指定するには、記事本文に [[ /googledocs domain="ドメイン名" doctype="spreadsheets" docid="ドキュメントID" width="幅" height="高さ" ]] と記述します。

ドキュメントの種類によって異なる URL に対応させる



実は、上記で作成したウィジェットは、スプレッドシート (doctype="spreadsheets") でしか動作しません。他の種類(ドキュメントとプレゼンテーション)では <iframe>src= で指定する URL が異なるためです。

ウィジェットをスプレッドシートでもドキュメントでもプレゼンテーションでも動作するようにするには、ウィジェットのパラメーターの doctype="spreadsheets"doctype="document"doctype="presentation" かに応じて、SDL の URL 生成を変化させる必要があるということです。

doctype= パラメーターの値は、SDL 内で <property.value name="doctype" /> として取得できるので、これに応じた条件分岐を行います。

が、その前に、URL の生成部分が長くなりそうなので、この部分を「url」という名前の関数に分離しておきましょう。関数は、<sdl.function name="関数名">...</sdl.function> として定義します。関数を呼び出すには <#関数名 /> とします。googledocs.sdl は次のようになります。

参照: DocSDK290: SDL Lesson 14 - 独自の関数を定義して呼び出す

<iframe src="<#url />" width="<property.value name='width' default='600' />" height="<property.value name='height' default='400' />">
</iframe>

<sdl.function name="url">
https://docs.google.com/a/<property.value name='domain' />/<property.value name='doctype' />/d/<property.value name='docid' />/pubhtml?widget=true&amp;headers=false
</sdl.function>


それでは「url」関数の内容を変更(編集)します。次のように、<switch>...</switch> タグを使って <property.value name="doctype" /> の値に応じて マッチする <case>...</case> へ分岐するようにします。

参照: DocSDK282: SDL Lesson 12 - 値による多分岐処理を行う

<sdl.function name="url">
  <switch value="<property.value name='doctype' />">
    <case value="spreadsheets">
      https://docs.google.com/a/<property.value name='domain' />/spreadsheets/d/<property.value name='docid' />/pubhtml?widget=true&amp;headers=false
    </case>
    <case value="document">
      https://docs.google.com/a/<property.value name='domain' />/document/d/<property.value name='docid' />/pub?embedded=true
    </case>
    <case value="presentation">
      https://docs.google.com/a/<property.value name='domain' />/presentation/d/<property.value name='docid' />/embed?start=false&amp;loop=false&amp;delayms=3000
    </case>
    <case.default>
      Error! No doctype parameter or unknown doctype :-(
    </case.default>
  </switch>
</sdl.function>


もちろん、次のように <compare.equals>...</compare.equals> を入れ子にして条件分岐をすることもできますが、<switch>...</switch> を使ったほうが綺麗なコードが書けますね。

<sdl.function name="url">
  <compare.equals "<property.value name='doctype' />" "spreadsheets">
      https://docs.google.com/a/<property.value name='domain' />/spreadsheets/d/<property.value name='docid' />/pubhtml?widget=true&amp;headers=false
  <else>
    <compare.equals "<property.value name='doctype' />" "document">
      https://docs.google.com/a/<property.value name='domain' />/document/d/<property.value name='docid' />/pub?embedded=true
    <else>
      <compare.equals "<property.value name='doctype' />" "presentation">
        https://docs.google.com/a/<property.value name='domain' />/presentation/d/<property.value name='docid' />/embed?start=false&amp;loop=false&amp;delayms=3000
      <else>
        Error! No doctype parameter or unknown doctype :-(
      </compare.equals>
    </compare.equals>
  </compare.equals>
</sdl.function>


動作テスト



それではここで動作テストしてみましょう。キャッシュのクリアを行い、記事本文にスプレッドシート、ドキュメント、プレゼンテーションを埋め込んでみましょう。下図のように、うまく動作しますか?

ドキュメントを埋め込み



プレゼンテーションを埋め込み



これでウィジェットの基本的なプログラミングは完了ということにしましょう。(まだまだ改善の余地がありますが…)

ウィジェット一覧に表示するための定義ファイル



このウィジェットを使うには、記事本文にいちいち [[ /googledocs domain="ドメイン名" doctype="種類" docid="ドキュメントのID" ]] を書かなくてはなりません。これは面倒ですね。



そこで、[ウィジェットの挿入/編集] から選択して簡単に使えるようにしましょう。



定義ファイルの設置場所



プラグインのフォルダに config/entry/tokens/htmledit フォルダ階層を作成し、その中に googledocs.properties ファイルを作成します。

上記で作成した config/entry/tokens/html フォルダの googledocs.properties と名前が同じですが、別のフォルダの別のファイルですので注意してください。

htmledit フォルダと googledocs.properties ファイル

定義ファイルの記述



googledocs.properties ファイルをテキストエディタで開いて次のように記述します。

class=tsi.sdk.token.WidgetForHtmlEdit_
rskeywords=googledocs
display_name=Google Docs

# Supported tokenattr Settings
settings=googledocs_domain,googledocs_docid,googledocs_doctype,googledocs_width,googledocs_height

# Required tokenattr Settings
requiredsettings=googledocs_domain,googledocs_doctype,googledocs_docid
requiredsetting_message_googledocs_domain=Please fill in your domain name for Google Apps.
requiredsetting_message_googledocs_doctype=Please select a type of your document.
requiredsetting_message_googledocs_docid=Please fill in your document ID.

# Setting-Name-to-Attribute-Name Mappings (first attribute name
# is also preferred attribute name)
googledocs_domain_attributes=domain
googledocs_doctype_attributes=doctype
googledocs_docid_attributes=docid
googledocs_width_attributes=width
googledocs_height_attributes=height

# Default tokenattr setting values
default_googledocs_domain=tractionsoftware.com

# Widget Icon
icon=/images/widgets/googledocs.png


class=tsi.sdk.token.WidgetForHtmlEdit_


これは、ウィジェットを [ウィジェットの挿入/編集] の一覧に表示するための決まり文句です。

rskeywords=ラピッドセレクタ


[ウィジェットの挿入/編集] からウィジェットを挿入した時に、どのようなラピッドセレクタ名に変換するかを指定します。(ここで「googledocs」と指定しているので、挿入されるウィジェットは [[ /googledocs ]] になります。)

display_name=ウィジェットの名前


[ウィジェットの挿入/編集] の一覧に表示するウィジェットの名前を指定します。

settings=オプション名1,オプション名2,オプション名3 ...


ウィジェットの一覧から [Google Docs] を選択した時に表示されるオプション(設定項目)の名前をコンマ記号で区切って指定します。これらのオプションの名前は、config/settings/props/tokenattr フォルダに設置する .properties ファイルの名前です。

requiredsettings=オプション名1,オプション名2,オプション名3 ...


入力や選択を必須にしたいオプション(設定項目)の名前をコロン記号で区切って指定します。

requiredsetting_message_SettingName=注意メッセージ


requiredsetting_message_ に続けてオプションの名前を続けて、そのオプションが未選択(未記入)だった場合に表示する注意メッセージを指定します。

SettingName_attribute=パラメーター名


オプション(設定項目)の名前に _attribute を続けて、そのオプションをどのようなパラメーターとして埋め込むかを指定します。

例えば、googledocs_domain_attributes=domain は、「googledocs_domain オプションに入力された値を、domain="入力値" としてウィジェットに埋め込む」という意味になります。

default_SettingName=デフォルト値


default_ にオプション名(設定項目名)を続けることで、該当のオプションの既定値を設定できます。

icon=アイコンのパス


ウィジェットの一覧に表示するアイコンのファイルのパスを指定します。

設定項目の定義ファイルの作成



settings= で指定したオプション(設定項目)の定義ファイルを、プラグインのフォルダの中に作成した config/settings/props/tokenattr フォルダ階層の中に作成します。



それぞれのファイルをテキストエディタで開き、次のように記述して保存します。

googledocs_docid.properties



class=com.traction.settings.TextInput

display_name=Your Document ID
description=Fill in your document's ID.
tip=

sdleditor=com.traction.sdl.admin.settings#textinput_belowlabel
size=72

default=
usedefault=false


class=com.traction.settings.TextInput
sdleditor=com.traction.sdl.admin.settings#textinput_belowlabel


設定項目としてテキストボックスを使う場合の決まり文句です。

display_name=Your Document ID


設定項目の見出しを設定します。

description=Fill in your document's ID.


見出しの下に表示する説明分です。

tip=


見出しの右側に表示する注意書きです。今回は設定しません。(非表示になります)

default=


既定値(デフォルト値)の設定です。今回は設定しません。(空白のテキストボックスが表示されます)

usedefault=false


ここで "true" を指定すると、設定項目に [既定値を使う] のチェックボックスが表示され、チェックボックスをオンにして既定値に戻せるようになります。既定値は、上の default= で指定した値になります。

googledocs_doctype.properties



class=com.traction.settings.Select

display_name=Document Type
description=Select a type of your document.
#tip=

options=,spreadsheets,document,presentation
option_spreadsheets_label=Spreadsheet
option_document_label=Document
option_presentation_label=Presentation

sdleditor=com.traction.sdl.admin.settings#singleselect

default=
usedefault=false


class=com.traction.settings.Select
sdleditor=com.traction.sdl.admin.settings#singleselect


ドロップダウンリストを使う場合の決まり文句です。

options=,spreadsheets,document,presentation
option_spreadsheets_label=Spreadsheet
option_document_label=Document
option_presentation_label=Presentation


options= でドロップダウンリストに表示する選択肢を半角コロン記号で区切って指定します。そして、実際に選択肢をどのように表示するかを option_OptionName_label= で指定します。

例えば、上記の設定では、ドロップダウンリストには「空白」「Spreadsheet」「Document」「Presentation」の 4 つの選択肢が作られます。そして、「Spreadsheet」を選択すると、それは「spreadsheets」という値となり、doctype="spreadsheets" としてうジェットに埋め込まれます。(この設定ファイル googledocs_doctype.properties に対応するパラメーター名が doctype であるため)

googledocs_domain.properties



class=com.traction.settings.TextInput

display_name=Domain Name of Your Goodle Apps
description=Fill in your Google Apps' domain name, e.g. tractionsoftware.com.
tip=

sdleditor=com.traction.sdl.admin.settings#textinput_belowlabel
size=72

default=
usedefault=true


これは googledocs_docid.properties と同じようなテキストボックス型の設定項目です。

googledocs_height.properties



class=com.traction.settings.TextInput

display_name=Height
description=Fill in the height of this widget if you want to specify it.
tip=

sdleditor=com.traction.sdl.admin.settings#textinput_belowlabel
size=12
default=
usedefault=false
units=pixels
numeric=true
min=256
max=


これも googledocs_docid.properties と同じようなテキストボックス型の設定項目ですが、次のような設定が追加されています。

units=pixels


単位を指定するには units= を使います。ここで指定された単位は、テキストボックスに右側に表示されます。

numeric=true
min=256
max=


テキストボックスで受け付ける文字列を数値だけに制限するには numeric=true を指定します。また、min=max= でそれぞれ最小値と最大値を指定できます。

googledocs_width.properties



class=com.traction.settings.TextInput

display_name=Width
description=Fill in the width of this widget if you want to specify it.
tip=

sdleditor=com.traction.sdl.admin.settings#textinput_belowlabel
size=12
default=
usedefault=false
units=pixels
numeric=true
min=256
max=


googledocs_height.properties と同様の数値入力型のテキストボックスです。

アイコンの設置



ウィジェットの一覧に表示されるアイコンを、プラグインのフォルダ内に images/widgets というフォルダ階層を作り、その中に googledocs.png という名前で保存します。これは、config/entry/tokens/htmleditgoogledocs.propertiesicon= で指定したパスです。

アイコン用のPNGファイルを設置する

画像ファイルの大きさは、高さ 20px 幅 20px です。

今回は、iconfinder.com/ から適当な PNG 画像ファイルをダウンロードして縮小加工しました。

動作テスト



それでは最終的な動作確認をしてみましょう。

サーバーセットアップでキャッシュのクリアを実行し、リッチテキストエディタの [ウィジェットの挿入/編集] をクリックします。一覧にアイコン付きの [Google Docs] が表示されます。



その [Google Docs] をクリックすると、下図のように config/settings/props/tokenattr で定義した設定項目が表示されます。



設定項目に記入・選択して [OK] をクリックすると、下図のようにアイコン付きのウィジェットとして記事本文に挿入されます。



投稿すると、下図のように、ウィジェットで指定した Goodle ドキュメント(下図ではスプレッドシート)が表示されます。



ダウンロード



下のリンクをクリックして、上記で作成した「Google Docs」ウィジェットのプラグインをダウンロードできます。

Google Docs ウィジェット プラグイン /db/attachments/docsdk/175/share/
 7.7 KBcom.traction.googledocs-1.0.zip2015/01/2411:45:51 JST


メモ

このプラグインは、今回のレッスンで作成したものです。その後に改善を加えたものを下記リンク先ページで公開しています。





Attachments:
create_plugin_folder.png
plugin_properties.png
new_plugin.png
create_dirs_props.png
googledocs_properties.png
create_dirs_sdl.png
google_spreadsheet_01.png
google_spreadsheet_02.png
google_spreadsheet_03.png
google_spreadsheet_04.png
test_example1.png
test_example2.png
test_example3.png
test_document.png
test_presentation.png
create_dirs_htmledit.png
token_example1.png
token_example2.png
tokenattr_setting_files.png
put_png.png
test1.png
test2.png
test3.png
test4.png
Shared Files for DocSDK175
関連記事
Article: DocSDK175 (permalink)
Categories: :DocSDK:トークン, :DocSDK:ウィジェット, :DocSDK:カスタマイズ, :FAQ:カスタマイズ, :DocSDK:FAQ, :DocSDK:プラグイン
Date: 2014/12/27; 11時15分55秒 JST

Author Name: TeamPage サポート
Author ID: jpbo