ethnamdoc/plugin-example.html at gh-pages · ethnamphp/ethnamdoc · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="utf-8">
    <title>Ethnamドキュメント</title>
    <link href="css/style.css" media="all" rel="stylesheet" />
    <link href="css/github.css" media="all" rel="stylesheet" />
</head>
<body>
  <p><a href=".">目次</a></p>
<div class="blob instapaper_body">
  <article class="markdown-body entry-content">
<h1>プラグイン導入の例</h1>
<ul>
<li>プラグイン導入の例
<ul>
<li>おおまかな仕様を決める </li>
<li>親クラスを作る </li>
<li>プラグインを作る </li>
<li>action formに入力フィルタを追加する </li>
<li>view classに出力フィルタを追加する </li>
<li>絵文字用の文字数カウント </li>
<li>アクション定義の例 </li>
<li>まとめ </li>
</ul></li>
</ul>
<p>このドキュメントでは、新しい種類のプラグインを導入するための全体的な流れの説明をします。具体例として、絵文字を扱うライブラリをプラグインとして用意することを考えます。(重要な注意: この内容はあくまで <strong>プラグイン導入のための概要的な例</strong> で、細かい実装や絵文字の話はかなりてきとうです!)</p>
<h3>おおまかな仕様を決める</h3>
<p>携帯電話とPCから見られるサイトで絵文字を導入したくなったとします。</p>
<ul>
<li>内部では絵文字の統一した符号体系を用意しておく (絵文字タグを作るとか)</li>
<li>キャリア/PCごとに分けずに同じアクションで入力、出力をする
<ul>
<li>action formでキャリアを判定して、filterで適切なencodingをする</li>
<li>view classでキャリアに応じたsmarty modfierをassignし、tplでdecodeをする</li>
</ul></li>
</ul>
<p>そこで $type = 'emoji' なるプラグインを導入することにします。emojiプラグインは $name = 'au', 'docomo', 'pc', 'softbank' *1 の 4 種類を用意します。</p>
<p>また、このプラグインは他のアプリケーションでも使いそうなので、プラグインとしてはアプリではなくEthna本体に付属させる形にします。もしアプリに付属させる場合は、以下のプラグインを作る場面で</p>
<ul>
<li>クラス名のprefixを 'Ethna<em>' ではなく 'Sample</em>' のようにアプリ名にする</li>
<li>ファイルを置く場所を $ETHNA_HOME/class/Plugin 以下ではなく、 app/plugin 以下に置く(親クラス含む) のようにしてください。</li>
</ul>
<h3>親クラスを作る</h3>
<p>プラグインの親クラスを作ります。$nameに共通したメソッドをここで定義しておきます。</p>
<ul>
<li>クラス名
<ul>
<li>Ethna_Plugin_Emoji</li>
</ul></li>
<li>
<p>ファイル</p>
<ul>
<li>$ETHNA_HOME/class/Plugin/Ethna_Plugin_Emoji.php</li>
</ul>
<p>class Ethna_Plugin_Emoji
{
function encode($text)
{
// abstract
}</p>
<p>function decode($text)
{
// abstract
}</p>
<p>function strlen($text)
{
// impl
...
}
}</p>
</li>
<li>
<p>abstractなメソッド</p>
<ul>
<li>encode()</li>
<li>各キャリアの絵文字をそのまま含むテキストから、絵文字タグを含むテキストに変換します</li>
<li>decode()</li>
<li>encode()の逆で、絵文字タグを含むテキストをキャリアごとの絵文字もしくはPCならば絵文字アイコンを表示する<img>タグに変換します。</li>
</ul>
</li>
<li>すべてのプラグインに共通なメソッド
<ul>
<li>strlen()</li>
<li>絵文字タグを含むテキストを、絵文字を1文字とみなして文字数をカウントします。これは$nameに依存しないので、ここに実装を書いてしまいます。</li>
</ul></li>
</ul>
<h3>プラグインを作る</h3>
<p>$name = 'pc' ならば次のような感じになります。親クラスのabstractなメソッドの実装をします。</p>
<ul>
<li>クラス名
<ul>
<li>Ethna_Plugin_Emoji_Pc</li>
</ul></li>
<li>
<p>ファイル名</p>
<ul>
<li>$ETHNA_HOME/class/Plugin/Emoji/Ethna_Plugin_Emoji_Pc.php</li>
</ul>
<p>class Ethna_Plugin_Emoji_Pc extends Ethna_Plugin_Emoji
{
function encode($text)
{
// impl
}</p>
<p>function decode($text)
{
// impl
}
}</p>
</li>
</ul>
<h3>action formに入力フィルタを追加する</h3>
<p>action formではフィルタとしてこのプラグインを使いたいので、アプリケーションのaction formの基底クラス app/Sample_ActionForm.php に次の内容を追加してフィルタ 'emoji_encode' を用意します。($this-&gt;ctl-&gt;getCareer()でキャリアが区別できるものとします)</p>
<pre><code>function _filter_emoji_encode($value)
{
    $emoji =&amp; $this-&gt;plugin-&gt;getPlugin('Emoji', $this-&gt;ctl-&gt;getCareer());
    return $emoji-&gt;encode($value);
}</code></pre>
<h3>view classに出力フィルタを追加する</h3>
<p>まるまる出力フィルタにしてしまってもいいですが、必要なところだけ絵文字のdecodeをするほうが効率がいいので、smartyのmodifierとして登録することにします。</p>
<p>アプリケーションのviewの基底クラス app/Sample_ViewClass.php に次の内容を追加して、{$text|emoji} というかんじのsmarty modifierを用意します。</p>
<pre><code>function _setDefault(&amp;$renderer)
{
    $smarty =&amp; $renderer-&gt;getEngine();

    $emoji =&amp; $this-&gt;plugin-&gt;getPlugin('Emoji', $this-&gt;ctl-&gt;getCareer());
    $smarty-&gt;register_modifier('emoji', array(&amp;$emoji, 'decode'));
}</code></pre>
<h3>絵文字用の文字数カウント</h3>
<p>action formのバリデータで、max, minは絵文字の場合に意味が違ってしまうので、絵文字用のバリデータプラグインを用意しておきます。(これは Emoji プラグインではなく Validator プラグインであることに注意してください。詳しくは <a href="form-validate_with_plugin.html#eebb5029">バリデータプラグインを作る</a>を参照)</p>
<ul>
<li>プラグイン名
<ul>
<li>$type = 'Validator', $name = 'Emojistrlen'</li>
</ul></li>
<li>クラス名
<ul>
<li>Ethna_Plugin_Validator_Emojistrlen</li>
</ul></li>
<li>
<p>ファイル名</p>
<ul>
<li>$ETHNA_HOME/class/Plugin/Validator/Ethna_Plugin_Validator_Emojistrlen.php</li>
</ul>
<p>class Ethna_Plugin_Validator_Emojistrlen extends Ethna_Plugin_Validator
{
function &amp;validate($name, $var, $params)
{
$max = $params['max'];
$min = $params['min'];</p>
<pre><code>   $plugin =&amp; $this-&gt;backend-&gt;getObject('plugin');
   $emoji =&amp; $plugin-&gt;getPlugin('Emoji', $this-&gt;ctl-&gt;getCareer());
   $length = $emoji-&gt;strlen($var);
   if ($min &lt;= $length &amp;&amp; $length &lt;= $max) {
       return $this-&gt;ok();
   } else {
       return $this-&gt;error('エラーだよ', E_APP_FORM_INVALIDVALUE);
   }
}</code></pre>
<p>}</p>
</li>
</ul>
<h3>アクション定義の例</h3>
<p>実際のアクションでは以下のように設定します。</p>
<ul>
<li>
<p>アクション定義の編集</p>
<p>class Sample_Form_Foo_Bar extends Sample_ActionForm
{
var $form = array(
'text' =&gt; array(
'type' =&gt; VAR_TYPE_STRING,
'form_type' =&gt; FORM_TYPE_TEXT,
'name' =&gt; 'テキスト',
'filter' =&gt; 'emoji_encode',
'required' =&gt; true,
'emojistrlen' =&gt; array('max' =&gt; 100, 'min' =&gt; 1),
),
);</p>
<pre><code>...</code></pre>
<p>}</p>
</li>
<li>
<p>smartyのテンプレート</p>
<p>入力テキスト: {$app.text|emoji}</p>
</li>
</ul>
<h3>まとめ</h3>
<p>プラグイン自体は非常に役割は小さいので、新たに自分でプラグインを作ろうとすると、プラグインの中身よりもプラグインを使う側のほうに手間取るかもしれません。</p>
<hr />
<p>*1あくまで例です!!  </p>  </article>
</div>

<div class="site-footer">
  @2015 <a href="https://twitter.com/DQNEO">DQNEO</a>
</div>
</body>
</html>