私家版 Sintags日本語ドキュメント

※このページはSintags, The Akelos Framework special syntax for view Templatesを勝手に翻訳したものです。
※原文の意を損なわない範囲で日本語としての通りのよさを心がけた *つもり* です。
※私の趣味で体裁を変更し、お節介な訳注を入れています。

Sintags, ViewテンプレートのためのAkelosフレームワーク特殊構文

Akelosフレームワークはテンプレート言語としてPHPを用いていますが、PHP変数のループや表示は往々にして繰り返しの多い作業になり、viewテンプレートの美観を損ねます。

Akelosフレームワークは別の余計なテンプレート言語の学習を強いることを求めません。テンプレートを作るためにはPHPで十分です。しかし場合によっては、グラフィックデザイナにviewテンプレートを作成して貰う必要もあるでしょう。Sintagsには極めて限られた構文しか加えていませんので、WYSISYGなHTMLエディターで単純かつパワフルなテンプレートを作成することができます。

この特殊な構文はSintags("Sin"は「～無しで」という意味のスペイン語に由来します)として知られており、 "?", "_", "{", "}", "end", ".", "-" の文字だけを用いる、viewにおける一連の約束事です。パースされたSintagはPHPのコードに変換され、パフォーマンス向上のため、.phpファイルとしてキャッシュされます。

【訳注】この記述には"loop"と"\"も付け加えるべきであろう。

動作確認がしたければ AkSintags.php のソースコードを入手できます。このコードはループ処理のマジックを実現するため、AkInflector.php に依存しています。

Sintags ドキュメント

Sintags の要素

{	Sintagブロックの開始。
}	Sintagブロックの終了。
{var_name?}	変数"var_name"が存在する場合のみ、その値を出力する宣言。【訳注】次のPHPコードと等価 <?php if(isset($var_name))echo $var_name; ?>
{?var_name}	変数"var_name"が空要素でない場合のみ、PHPブロックを開始する。次のPHPコードと等価。 <?php if(!empty($var_name)){ ?> 【重要】このブロックは "{end}" または "<?php } ?>"によって閉じなければならない
{end}	<?php } ?> を生成し、PHPブロックを閉じる
{object.attribute}	"."はオブジェクト属性にアクセスするために用いる。次のPHPコードと等価。 <?php echo $object->attribute; ?>
{array-key}	"-"は指定したキーを持つ配列要素にアクセスするために用いる。次のPHPコードと等価。 <?php echo $array['key']; ?>
_{Multilingual text}	"_{ }"は多言語化を行うテキストを囲みます。
{_Multilingual_var}	"{_ }"は国際化を行う変数を囲みます。この変数はロケールコードをキーとした配列として、実際に存在するものでなければなりません。

このテンプレート構文の殆どは、View上のアクティブレコードの表示や国際化処理を容易にするために加えられたものであり、次の基本ルールに立脚しています。

変数の表示

Sintags:
```
{comment}
```
PHP CODE:
```
<?php
  echo $comment;
?>
```

オブジェクト属性の表示

Sintags:

{post.Comments}
{post.Comments.latest}

PHP CODE:

<?php
  echo $post->Comments;
?>
<?php
  echo $post->Comments->latest;
?>

配列要素の表示

Sintags:

{people-members}
{people-0-member}

PHP CODE:

<?php
  echo $people['members'];
?>
<?php
  echo $people[0]['member'];
?>

配列とオブジェクトが混合したものの表示

Sintags:

{people.members-0.name}
{people-latest.created_at}

PHP CODE:

<?php
  echo $people->members[0]->name;
?>
<?php
  echo $people['latest']->created_at;
?>

要素が値を持つ場合(PHPのempty関数にて判断)のみ実行される条件ブロックの生成

Sintags:

{?post-comments}
  {post.comments.details}
{end}

PHP CODE:

<?php
if(!empty($post['comments'])){
  echo $post->comment->detail;
}
?>

コントローラによりセットされた変数のみ表示を試みる

【訳注】実際にはisset()が真になるPHP変数であれば表示する

Sintags:
```
{Post.comments.details?}
```
PHP CODE:
```
<?php
  echo isset($Post->comment->details) ? $Post->comment->details : '';
?>
```

配列やActive Recordコレクションをループする

【訳注】Active Recordについてご存じない方はこの辺りを参照のこと

Sintags:

{loop posts}
    {post.comment?} {post.author?} 
{end}

PHP CODE:

<?php
empty($posts) ? null : $post_loop_counter = 0;
if(!empty($posts)){
  foreach ($posts as $post_loop_key=>$post){
    $post_loop_counter++;
    $post_odd_position = $post_loop_counter%2;
    echo isset($post->comment) ? $post->comment : '';
    echo isset($post->author) ? $post->author : '';
  }
}
?>

{loop *}タグには複数形の"posts"を割り当てる必要があります。そして、個々の要素の詳細を得るためには単数形の"post"を取り出します。
ご覧の通り、生成されたPHPコードは自動的に付け加えられた有用な変数を備えており、その変数はコレクションをイテレートする際に役立ちます。

(以下の * をイテレート処理を行っている配列名の単数形に置き換えて下さい)

*_loop_counter	１ずつカウントされる繰り返し回数を保持(繰り返し処理の度にいつも決まって書くあの退屈な ++ みたいなもの)
*_loop_key	現在の配列キーを保持する
*_odd_position	奇数回数か否かの真偽値を保持する。行の色を適切に切り換えるために役立ちます。

Active Record field のためのデータベースに格納された多言語値を取得

Sintags:
```
{_post.comment}
```
PHP CODE:
```
<?php
  echo empty($post->comment) || !is_array($post->comment)? '' : 
  $text_helper->translate($post->comment);
?>
```
"{"の後に "_"を付け加えるだけで翻訳されたバージョンの"comment"が得られます。英語とスペイン語のコメントがある場合は、データベースに "en_comment" と "es_comment" というカラムが存在する必要があります。

【注意】$post->comment は実際にロケールコードをキーとした配列を保持していますので、locale/ files に付け加えることなく、独自の局所的な値をセットすることができます。

【訳注】locale/ files は akelos/app/locales 以下のファイルを指しているのではないかと思うが定かではない

文字列のための多言語値を得る

Sintags:

<h1>_{Ain't easy to translate text?}</h1>
      _{<p>It's really simple even to add 
      <a href='http://google.co.uk'>Localized links</a>
      </p>}

PHP CODE:

<h1><?php  echo $text_helper->translate('Ain\'t easy to translate text?'); 
?></h1>
<?php  echo $text_helper->translate('<p>It\'s really simple 
    even to add 
      <a href=\'http://google.co.uk\'>Localized links</a>
      </p>'); ?>

この関数を使うことにより、ロケールは自動的に app/locales/CONTROLLER_NAME/ フォルダーに追加されます。

【注意】多言語テキストはフレームワークのデフォルト言語で記述する必要があります。

翻訳されたテキストにおいて {} をエスケープする

Sintags:

 _{ I need to print \{ something_inside_curly_brackets \}.
_\{ Maybe a multilingual text example \} }

PHP CODE:

<?php echo $text_helper->translate('I need to print
 {something_inside_curly_brackets}. 
_{Maybe a multilingual text example} ', array(), 
$controller_name); ?>

ただ、"{" と "}" の前に "\" を加えるだけで、それら("{" , "}")をエスケープすることができます。

【奥付】

SintagsはPHPに取って代わろうとしているわけではありませんが、開発をスピードアップできることを覚えておいて下さい。この構文をを使うの良いことです。viewをより明快な状態に保つことができるのですから。ですから、viewの中に多くのPHP codeが存在し始めた場合は、いくつかの view logic を view helpers に移動することを考慮しましょう。