DocSDK115: ウィジェット（トークン）の基本的な構造や動作

Title: ウィジェット（トークン）の基本的な構造や動作

TeamPage のパーサー（構文解析機能）は、エントリー（記事）の内容をジャーナルに保存する前に「トークン (tokens)」と呼ばれるブロックに分割します。この分割の作業を「トークナイズする (tokenizing)」と言います。トークンの内容は、単純なテキストのブロックかもしれませんし、Traction ID (記事、段落、添付ファイルなどへの参照、例えば "FAQ123") かもしれませんし、URL かもしれませんし、特定の数値の連続（例えば電話番号）かもしれません。

しかし、ユーザーは、半角の2重の角括弧でテキストを囲むことで、トークナイザー（トークンを実行する機能、tokenizer）に対して「括弧内のテキストをトークンとして扱え」と指示できます。

例えば、画像トークン（image トークン）は次のように表されます。

[[ /image Public123@7 400x400x0 ]]

この例では、初めの半角スラッシュ記号は、続くテキストがラピッドセレクタのトークンであることを表します。テキストの「image」はトークンの種類を示しています。１番目のパラメーターは、「Public スペースの 123 番の記事に添付されている第 7 番目の添付ファイル」という Traction ID です。2番目は、「横 400 ピクセル、縦 400 ピクセル、境界線なし」を意味し、実際に HTML としてレンダリング（表示）されるときに <img> タグの width, height, border の値として使われます。

トークンとウィジェット

「トークン」と「ウィジェット」は、コインの裏表の関係にあります。「トークン」とは、あるデータを内部的に表すための技術的な呼び名です。「ウィジェット」とは、Web ページや PDF ドキュメントなどに実際に表示されるトークンのレンダリング（表示）のことを言います。ウィジェットには、ツールのように、ユーザーが変更可能な属性や機能を組み込めます。そのため、「ウィジェット」という名前が付けられています（参照: ja.wikipedia.org/… ）。つまり、「トークン」と「ウィジェット」は同じ意味であり、実際、このサポートサイトでは同じ意味で使っています。

レンダラー

一般的に、ウィジェットの内容は HTML として、Web ページの一部として表示されます。しかし、中には他のレンダラー（表示する機能、renders）を必要とするウィジェットもあります。

Java や SDL を使用して、トークンの代替レンダリングを作成できます。

TeamPage がインストールされた server ディレクトリ下の config/entry/renderers を開くと、TeamPage のレンダラーのビルトイン設定ファイル（.properties ファイル）を確認できます。これらの設定ファイルは、TeamPage のシステムにレンダラーの異なる種類（families）の名前を伝えます。それぞれの種類は、主に、そのレンダラー用の特別なレンダリングを使うトークンの一覧で構成されます。

例として「html」トークンのレンダラーを見てみましょう。これは、いくつかのトークンによって使用されます。ファイル名は html.properties で、config/entry/tokens/html にある「html」レンダラーのトークンレンダラー設定ファイルに対応します。

トークンレンダラーの設定ファイル

トークンレンダラーも、他の TeamPage の機能と同じように、名前および属性の名前と値のペアを持ち、カスタマイズや拡張ができるように設計されています。カスタムレンダリングができるそれぞれの種類のトークンに設定ファイルが必要です。TeamPage サーバーの標準のトークンの種類は、config/entry/tokens/html フォルダ内の設定ファイルとして確認できます。

SDL トークンレンダリング

いくつかのトークンは、単純に SDL でレンダリングされます。クラス名「SDLTokenRenderer」は、トークンとその属性が SDL レンダラーで使えるように、それらをスコープの中に入れ、SDL を評価するために使われるスコープを変更します。カスタムトークンを作成するときにこれを行うには、レンダラーの設定ファイルで class= 属性を省略し、sdl= 属性だけを記述します。この sdl= 属性は、トークンの HTML レンダリングに使われる特定のテンプレート、関数、またはブロックへの参照を表し、次のように記述されます。

sdl=com.traction.sdl.token.filelist

ドット記号はフォルダの階層を表し、最後は .sdl ファイルの名前で、拡張子 .sdl は省略されます。上記の例は、「com フォルダの中の、traction フォルダの中の、sdl フォルダの中の、token フォルダの中にある、filelist.sdl ファイル」と意味します。

ラピッドセレクタのキーワード

トークンを使用するには、半角の2重の角括弧内に /token に続けてトークン名（例えば「filelist」）を指定します。例えば、「hoge」という名前のトークンを使用するには次のようにします。

[[ /token hoge ]]

トークンの名前（あるいはその代わりになるもの）をラピッドセレクタのキーワードとして登録すると、トークン名を半角スラッシュ記号に続けて直接指定できるようになります（「/token」が不要になります）。

[[ /hoge ]]

ラピッドセレクタのキーワードは、トークンの設定ファイルで rskeywords= 属性として指定します。下記は「hoge」というラピッドセレクタキーワードを登録する例です。

rskeywords=hoge

複数指定するにはコンマ記号で区切ります。例えば、記事内に動画オブジェクトを埋め込むための設定ファイル movie.properties を作成する場合、次のように記述することで、「movie」だけでなく「video」や「presentation」というラピッドセレクタキーワードも使用できるようになります。

rskeywords=movie,video,presentation

ウィジェットのレンダリングに SDL を使う

ここでは、例として、「Google カレンダー」ウィジェットの設定や動作を見てみましょう。

YouTube ウィジェットの設定ファイルは config/entry/tokens/html にある googlecalendar.properties ファイルです。このファイルをテキストエディタで開くと、次のように書かれていることがわかります。

sdl=com.traction.sdl.token.googlecalendar
rskeywords=googlecalendar

1行目の sdl= は、HTML レンダリングに使うテンプレートを示しています。そのテンプレートは、com フォルダの中の、traction フォルダの中の、sdl フォルダの中の、token フォルダの中にある、googlecalendar.sdl ファイルです。（com フォルダは server ディレクトリの「src」フォルダの中にあり、googlecalendar.sdl の拡張子 .sdl は省略します。）

2行目の rskeywords= は、ラピッドセレクタのキーワードです。（前述）

1行目の sdl= で指定されたテンプレート（googlecalendar.sdl）で、Google カレンダーの画面を埋め込んで表示するための HTML （を生成するための SDL コード）を確認できます。

<variable.local.set name="url">
  <property.value name="url" />
  <compare.equals a="<property.value name='title' default='' />" b="" trim="true" not>
    &amp;title=<url.encode><property.value name="title" /></url.encode>
  </compare.equals>
  <compare.equals a="<property.value name='controls' default='all' />" b="navigation">
    &amp;chrome=NAVIGATION
  <else><compare.equals a="<property.value name='controls' default='all' />" b="none">
    &amp;chrome=NONE
  </compare.equals></compare.equals>
  <compare.equals a="<property.value name='mode' default='month' />" b="agenda">
    &amp;mode=AGENDA
  </compare.equals>
  &amp;height=<property.value name="height" default="640" />
  &amp;epr=<property.value name="eventsperday" default="5" />
  <compare.equals a="<property.value name='weekstart' default='0' />" b="0" not>
    &amp;wkst=<property.value name="weekstart" />
  </compare.equals>
  <compare.equals a="<property.value name='bgcolor' default='#FFFFFF' />" b="" trim="true" not>
    &amp;bgcolor=<url.encode><property.value name="bgcolor" default="#FFFFFF" /></url.encode>
  </compare.equals>
  &amp;hl=#{core_locale}
</variable.local.set>
<iframe src="#$url$" style="<property.boolean name='showborder'>border: solid 1px #777;<else>border-width: 0;" width="<property.value name='width' default='640' />" frameborder="0" height="<property.value name='height' default='614' />"></iframe>

最下行を見ると、<iframe> タグの src= の値として、Google カレンダーの URL が「url」という変数 ( #$url$ ) で指定されることがわかります。

その変数「url」の値は、1 行目から 24 行目（<iframe> タグの上の行まで）の <variable.local.set name="url">〜</variable.local.set> で設定されています。

メモ: <variable.local.set> タグを使ってローカル変数に値を代入するには次のようにします。

<variable.local.set name="変数名" value="値" />
<variable.local.set name="変数名">値</variable.local.set>

この「googlecalendar」トークンを使うには、記事の本文に次のように記入します。

[[ /googlecalendar url='カレンダーのURL' ]]

投稿すると下図のように Google カレンダーが表示されます。

挿入したウィジェットのアイコン表示

Google カレンダーを [[ /googlecalendar url='カレンダーのURL' ]] と書いて埋め込んで投稿した記事（上図）を編集すると、下図のように、 [[ /googlecalendar url='カレンダーのURL' ]] がアイコンで表示されます。

これは、「googlecalendar」という名前のトークン（ウィジェット）を、リッチテキストエディタ (TinyMCE) でアイコンとして表示し、[ウィジェットの挿入/編集] ダイアログから選択できるようにするための設定ファイル googlecalendar.properties が config/entry/tokens/htmledit に存在するためです。

ウィジェット（トークン）をリッチテキストエディタ上でアイコン表示したり [ウィジェットの挿入/編集] から選択できるようにする方法については、ウィジェットをリッチテキストエディタに挿入できるようにする方法を参照してください。

Attachments:

20141102-050524.png
20141102-050641.png
insert_widget.png
write_googlecalendar_token.png
inserted_calendar.png
widget_icon.png
htmledit.png

参照されている (3)

DocSDK175: ウィジェットの作り方（新しいウィジェットの追加方法）DocSDK151: 新しい記事の種類と投稿/編集フォームを作ってみよう（旧バージョン）DocSDK2: カスタマイズ版プロジェクトの投稿/編集フォームの作成方法

Article: DocSDK115 (permalink)
Categories: :FAQ:カスタマイズ, :FAQ:TP機能, :DocSDK:ウィジェット, :DocSDK:カスタマイズ, :DocSDK:トークン
Date: 2014/11/02; 6時14分21秒 JST

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