Blog

デザイナーさんも必見、concrete5のヘルパーの使い方まとめ

Posted by admin at 22:05 日時 2014/03/25

ヘルパーとは

ヘルパーとは、その名の通り、よく使う処理の記述を助けてくれるものです。concrete5の様々なオブジェクト(Page, File, Userなど)にはそれぞれのオブジェクトごとにメソッドが用意されており、オブジェクトからデータを取り出したり、オブジェクトを操作することができますが、特定のオブジェクトのメソッドでは完結しない処理がヘルパーとして実装されていますので、別途呼び出して使用することができます。

…と、ここまで読んで関係ないなと思ったデザイナーのあなた!関係あります。例えば、ページリストブロックのテンプレートのこんな記述を見たことがありますよね。

$title = $th->entities($page->getCollectionName());  $url = $nh->getLinkToCollection($page);

ここで、ヘルパーを使っています。
1行目は、Textヘルパーを使って、ページ名を無害化するために文字をエンティティに変換しています。
2行目は、Navigationヘルパーを使って、ページオブジェクトからページのURLを取得しています。

こんな風に、ヘルパーはブロックテンプレートでよく目にします。ちなみに、ヘルパーを使うにはあらかじめヘルパーの読み込みが必要です。もし

Fatal error: Call to a member function entities() on a non-object in …

のようなエラーが表示されたら、ヘルパーが読み込まれていないことを疑ってください。また、下記の例の通りに読み込んでから使いましょう。

Textヘルパー

文字列の処理を助けてくれる。

読み込み方

$th = Loader::helper('text');

文字列をエンティティ化して無害化する

< を &lt; に変換するなどの処理がエンティティ化です。こうすることで、不要なJavascriptが実行されることを防ぎつつ、HTMLコードの記載などを画面に表示することができます。PHPのhtmlentitiesと同じですが、文字コードの指定を省いて短く書くことができます。

$text = '&lt;script&gt;';  echo $th-&gt;entities($text); // &amp;lt;script&amp;gt;

特殊な文字列をエンティティ化して無害化する

entitiesとほぼ同じですが、エンティティ化されるのは <, >, &, ‘, ” に限られます。entitiesではエンティティ化可能な全ての文字が変換されます。PHPのhtmlspecialcharsと同じですが、文字コードの指定を省いて短く書くことができます。また、concrete5.6.1以降は h() という短いショートカット関数が用意されました。

$text = '&lt;script&gt;';  echo $th-&gt;specialchars($text); // &amp;lt;script&amp;gt;

このエンティティ化はセキュリティ対策なのですが、デザイナーさんだと、どのようなときにこのセキュリティ対策が必要なのか、悩まれるかもしれません。ひとつ言えることは、どこかからか取得してきた文字列を画面に表示するときは、とりあえず h() で括っとけ!ということです。

最大文字数を指定して文字列を丸める

$text = 'ほげほげ';  // 初期設定は先頭から255文字で切り取られ、後ろに … がつく  echo $th-&gt;shortText($text);  // 文字数と後ろにつく文字の指定  echo $th-&gt;shortText($text, 60, '・・・');  // shortTextとほぼ同じだが、単語を途中で切らないように配慮する(スペースで区切らない日本語では無意味)  echo $th-&gt;shortenTextWord($text, 60); 

リンクをaタグに変換する

httpsに対応していないのですが、この修正コミットは5.7に見送られました。なので現状あまり使えない。

$text = 'http://www.example.com/';  echo $th-&gt;autolink($text);  /* 変換結果:  &lt;a href=&quot;http://www.example.com/&quot;  rel=&quot;nofollow&quot;&gt;http://www.example.com/&lt;/a&gt;  */

リンクをaタグに変換し、HTMLタグを除去し、改行をbrタグに変換する

意外と便利。

echo $th-&gt;makenice($text);

メールアドレスだけを抜き出す

RFC準拠なメールアドレスだけを抜き出す。ガラケーのメールアドレスははじかれるだろうな…

$text = 'メール: info@example.com';  echo $th-&gt;email($text); // info@example.com

半角英数字だけを抜き出す

$text = 'メール: info@example.com';  echo $th-&gt;alphanum($text); // infoexamplecom

Navigationヘルパー

concrete5のページへのリンク作成を助けてくれる。

読み込み方

$nh = Loader::helper('navigation');

ページのURLを取得

concrete5のURLはプリティURLのあるなしなどいくつか変化するため、単純にページのパスを表示するのではなく、ヘルパーを通して表示するのがお約束になっています。また、concrete5内部のリンクはスラッシュから始まりドメインを含みませんが、第2引数をtrueにすると http://〜 からのURLを取得できます。ツイートボタンなどで使います。

$c = Page::getCurrentPage(); // ページオブジェクトを取得  echo $nh-&gt;getLinkToCollection($c);  echo $nh-&gt;getLinkToCollection($c, true); // BaseURLをつける

祖先ページをさかのぼって取得

親ページを順に辿っていって情報を取得したい時が少なからずありますが、ちゃんと用意されてるんですね〜。「ページ名 | 親ページ名 | 祖父ページ名 | 曾祖父ページ名」のように、現在のページからさかのぼって表示する例。

$c = Page::getCurrentPage(); // ページオブジェクトを取得  $titles = array(); // 空の配列を作成  $titles[] = $c-&gt;getCollectionName(); // 現在のページ名を追加    $trail = $nh-&gt;getTrailToCollection($c); // 祖先ページを配列で取得  foreach ($trail as $page) {  	// ホームを除いて配列にページ名を追加  	if ($page-&gt;getCollectionID() != HOME_CID) {  		$titles[] = $page-&gt;getCollectionName();  	}  }  // 配列を結合  $title = implode(' | ', $titles);  echo h($title);

Imageヘルパー

画像のリサイズを助けてくれる。

読み込み方

$ih = Loader::helper('image');

画像をリサイズした結果をオブジェクトで取得

// Imageオブジェクトの取得。下記はページリストのコメントと同じ、ページの属性から取得する方法。  $img = $page-&gt;getAttribute('example_image_attribute_handle');    // 幅64px, 高さ9999pxで、縦横比を保ってリサイズ(9999pxは、実質高さ制限なしということ)  $thumb = $ih-&gt;getThumbnail($img, 64, 9999, false);    // 表示する  if ($thumb) : ?&gt;  &lt;img src=&quot;&lt;?php echo $thumb-&gt;src ?&gt;&quot; width=&quot;&lt;?php echo $thumb-&gt;width ?&gt;&quot; height=&quot;&lt;?php echo $thumb-&gt;height ?&gt;&quot; alt=&quot;&quot; /&gt;  &lt;?php  endif;    // 幅64px, 高さ64pxでリサイズして切り抜き  $thumb = $ih-&gt;getThumbnail($img, 64, 64, true);

画像をリサイズして、imgタグを出力、または取得

$img = $page-&gt;getAttribute('example_image_attribute_handle');  if ($img) {    /* 引数:   * Imageオブジェクト(必須)   * 幅(数値/必須)   * 高さ(数値/必須)   * Alt属性(文字列/任意)   * 出力せずにタグを返すかどうか(true or false/初期値はfalse/任意)   * 切り抜くかどうか(true or false/初期値はfalse/任意)   * /    // 64x64pxで切り抜いたサムネイル画像をAlt属性を「サムネイル」として出力する  $ih-&gt;outputThumbnail($img, 64, 64, 'サムネイル', false, true);    // 出力せずにimgタグを取得する  $thumb = $ih-&gt;outputThumbnail($img, 64, 64, true);  echo $thumb;  }

原寸でimgタグを出力(リサイズしない)

$img = $page-&gt;getAttribute('example_image_attribute_handle');  if ($img) {    /* 引数:   * Imageオブジェクト(必須)   * Alt属性(文字列/任意)   * 出力せずにタグを返すかどうか(true or false/初期値はfalse/任意)   * /  $ih-&gt;output($img);  }

圧縮率を指定

$img = $page-&gt;getAttribute('example_image_attribute_handle');  if ($img) {  $ih-&gt;setJpegCompression(100); // 0%〜100%、初期値は80%  $ih-&gt;outputThumbnail($img, 64, 64);  }

Dateヘルパー

日付の表示を助けてくれる。

読み込み方

$dh = Loader::helper('date');

使い方

// strtotimeは文字列からUnixタイムスタンプを取得するPHPの関数。  $time = strtotime($c-&gt;getCollectionDatePublic());    echo $dh-&gt;date('Y-m-d', $time); // Y-m-d 書式で日付を取得    echo $dh-&gt;date(DATE_APP_GENERIC_MDY_FULL, $time); // concrete5の定数を使う方法    // ここからは5.6.3.2以降で可能  echo $dh-&gt;formatCustom('Y.m.d', $c-&gt;getCollectionDatePublic());

Dateヘルパーについてはconcrete5で日付を表示するときはDate Helperを使いましょうという記事も書いたのでそちらを参考にしてください。

DATE_APP_GENERIC_MDY_FULL などの定数は、concrete5の翻訳ファイルにしたがって、各言語に最適な書式になりますので、オススメの設定です。

例えば、DATE_APP_GENERIC_MDY_FULL は、英語では ‘F j, Y’ (March 10, 2014) ですが、日本語訳は ‘Y年n月j日’(2014年3月10日)になっています。他にも

DATE_APP_GENERIC_MDYT_FULL:年月日時
DATE_APP_GENERIC_MDYT_FULL_SECONDS:年月日時秒
DATE_APP_GENERIC_MDYT:年月日時短縮版
DATE_APP_GENERIC_T:時
DATE_APP_GENERIC_TS:時秒

などの定数があります。

その他のヘルパー

その他にも、Ajax, Encryption, Feed, Form, HTML, Json, Mail, Mine, Pagenation, Rating, Validation, XMLなどのヘルパーがありますが、いずれも開発者向けなので、そちらに関しては

_人人人人人人_
> ソース嫁 <
 ̄Y^Y^Y^Y^Y ̄


Share this entry