Bshe利用マニュアル

Bshe_View（テンプレートエンジンマニュアル）

プログラマー向けマニュアル:独自のクラスで拡張

独自のリソースクラスの作成

概要

Bshe_Viewでは、Viewクラスに値や配列をセットして、テンプレートへ値や属性を反映するほかに、キー属性に対して、独自のリソースクラスを定義することができます。
簡単なWebページの開発では利用することは少ないと思いますが、同じ機能を複数のWebページに展開する場合や、キャッシュを複雑にコントロールしたい場合にこの機能は有用だと思います。

ただ、この実装がいろいろと考えていたら難解になってしまいました。
この部分は、今のままの実装のほかに、別の方法も取れるような機能拡張を現在検討中ですが、
現在の実装ではほとんどのことができるようになっていると思います。

リソースクラス判別の仕組み

Bshe_Viewでは、HTML上のキー属性から、実際にそのタグに対して処理を実施するリソースクラスやメソッドを判別し処理を実行します。
キー属性のルールから「処理クラス名」「処理メソッド名」が抽出されますが、
この「処理クラス名」「処理メソッド名」は実際のクラス名ではなく、その一部になります。

まず、リソースクラス判別については、以下の4つの項目が設定可能です

• assignClassPath:　独自リソースクラスのパス（配列により複数設定可能）
• assignClassPrefix: 独自リソースクラスの頭文字
• builtinAssignClassPrefix: ビルトインリソースクラスの頭文字（通常は指定不要）

取り出されたクラス名は以下の順序で判別され、処理する実際のクラスを決定します。

1. 独自定義のリソースクラスを検索
   1. 独自設定したassignClassPathから、処理クラス名.php（処理クラス名は自動で頭を大文字、その他を小文字に変換しております）というファイルがあるかを確認
   2. ファイルがある場合は、そのファイルをrequire_onceし、処理対象クラスが読み込まれたかをチェックします。
2. ビルトインクラスの検索
   1. 独自定義のクラスが見つからなかった場合、あらかじめ決められたビルトインのリソースクラスを検索します。
   2. この際、もし設定していれば[builtinAssignClassPrefix]_処理クラス名というクラスを、設定されていない場合は、デフォルトのクラスを検索します。

具体的に例を示します。

• 以下のように設定が行われている場合
  • assignClassPath:　'/resource'
  • assignClassPrefix: 'MyClass_'
• キー属性が「bshe::myclass:mymethod」だった場合

この場合、クラスとメソッドは次のように決められます。

1. 独自定義のリソースクラスを検索
   1. '/resource'から、「Myclass.php」というファイルがあるかを確認
   2. ファイルがある場合は、そのファイルをrequire_onceし、「MyClass_Myclass」クラスが読み込まれたかをチェックします。
   3. 正しく読み込まれれば、このキー属性に対しては、「MyClass_Myclass」クラスの「assignValuesMymethod」または「noChacheAssignValuesMymethod」のいずれかのメソッドが実行されます。（「assignValuesMymethod」「noChacheAssignValuesMymethod」は、キャッシュ対象と非対象を示すメソッドです、実装の詳細は独自のリソースクラスの作成を参照してください。）
       

キャッシュ対象メソッドとキャッシュ対象外メソッド

上で、記載しましたが、キー属性から判別された、メソッド名は実際のクラスのメソッド名ではなく、その一部になります。
取り出されたメソッド名の頭に「assignValues」か「noChacheAssignValues」のいずれかをつけることで、Bshe_Viewから呼び出されるメソッドとなります。
また、これらのメソッドは「static public」で実装しなくてはなりません。

ここで、「assignValues」と「noChacheAssignValues」の違いは、読んだままですが

• assignValues
  • キャッシュされる対象処理
• noChacheAssignValues
  • キャッシュされない対象処理
    となります。

ここでのキャッシュとは、コンパイルキャッシュとキャッシュで説明されている2つのキャッシュのうち、
後者の通常のキャッシュの方になります。

つまり、前項の例で説明すると、「bshe::myclass:method」というキー属性に対する処理を、
MyClass_MyclassクラスのassignValuesMymethodというメソッドに実装した場合、この実装内で処理されたものは、キャッシュ設定が有効な場合キャッシュされます。
逆にnoChacheAssignValuesMymethodというメソッドに実装した場合は、キャッシュ設定を有効にしてもキャッシュされず都度実行されるようになります。

beforeAssignとafterAssignメソッド

上記のほかに、各リソースクラスへ「beforeAssign」「afterAssign」メソッドを定義することができます。
これらのメソッドは、「assignValues」や「noChacheAssignValues」が呼ばれる前に「beforeAssign」がよばれ、後で「afterAssign」が呼ばれるようになっています。
各デフォルトのリソースクラスでは処理後にキー属性がHTMLに残らないように削除する後処理がここに実装されています。

メソッドの継承と引数と返値

リソースクラスはすべてBshe_View_Resource_Html_Abstractクラスを継承して実装する必要があります。
これは、次の項以降で説明する、いくつかのHTMLへのデータ登録関数を利用するためと、
キー属性を処理後に削除するafterAssignメソッドが実装されているためです。

また、assignValues、noChacheAssignValuesのいずれのメソッドも同じ引数、返値で作成する必要があります。
それぞれ、以下のとおりです。

• 引数
  • 引数は1つの配列で渡されます。配列の中身は以下のとおりです。

    array(
      'templateClass' => Bshe_Viewのテンプレートクラス（DOMクラスを内包している）本体
      'element' => 処理対象element（タグ）のtemplateClass上での一意名ID
      'params' => キー属性をパースした配列
      'presetValues' => プログラム上でBshe_Viewへセットした値の配列
    )

  • ここでparamsに保存される配列は以下の構造です。

    array(
      'originalId' => キー属性の文字列,
      'className' => 処理を実施するクラス名（通常は自身の名称が入っています）,
      'methodName' => 処理を実施するメソッド名（assignValues/noChacheAssignValuesを含まないメソッド名）,
      'helperName' => ヘルパーが指定されている場合そのクラス名,
      'helperParams' => キー属性からヘルパーの引数がパースできた場合その配列,
      'arrayMethodParams' => キー属性からメソッドの引数がパースできた場合その値の配列,
      'seq' => 同じキー属性文字列が複数ある場合、現在処理を行っているものの番号（0から順次カウントアップ）
    )

  • プログラム上でBshe_Viewへセットした値の配列は投入したキーで配列化されていますが、同じキーに対して、複数の処理を登録できるため、投入した内容が配列として保存されています。（通常は独自のリソースクラスで利用するための変数に複数の値をセットすることはないかもしれません）
  • たとえば、以下のようにプログラム上投入していた場合

    $view->a = 10;
    $view->a = 20;

  • 以下のような配列でデータが保持されます。

    array(
      0 => 10,
      1 => 20
    )

• 返値
  • 上記の引数を元にtemplateClassへさまざまな処理を実装し、最後にtemplateClassを返値として終了させます。
    
     

各タグへのアサイン処理の書き方

HTMLタグへの属性や値のセットは、そのタグによっても処理挙動が異なるようなケースも多いため、リソースクラスから呼び出せるいくつかの機能があらかじめ用意されています。
これらはいずれもリソースクラス内から以下のような形式で呼び出すことができます。

$templateClass = self::assign($templateClass, $arrayData);

• ここで、$templateClassは引数と返値に利用するテンプレートクラスです。
• $arrayDataは処理により異なる指示配列です。
• assignメソッドは、対象のタグにあわせて、それぞれのタグに適した、タグクラスから処理メソッドを呼び出す機能を提供します。（通常プログラマーがこれを意識する必要はありません）

指示できる機能は以下のとおりです。

• 値の属性(innerHTML含む）へのセット

  array(
    'method' => 'a', // 値のセットであることを表す文字
    'element' => 対象のテンプレート上での一意名ID（リソースメソッドの引数から取得）
    'params' => 
      array(
        0 => 対象の属性（innerHTMLの場合は'innerHTML'）
        1 => セットする値
        2 => Helperクラス名（省略可能：省略時はなにもせずそのまま出力）
        3 => Helper引数配列（省略可能）
      )
  )

• 属性の削除

  array(
    'method' => 'd', // 属性削除を表す文字
    'element' => 対象のテンプレート上での一意名ID（リソースメソッドの引数から取得）
    'params' => 削除する属性名
  )

• タグの削除

  array(
    'method' => 'r', // タグ削除を表す文字
    'element' => 対象のテンプレート上での一意名ID（リソースメソッドの引数から取得）
  )