######################
だぶ天 -- JavaScript用テンプレートエンジン --
dabten.js 1.0.h
(C) Wataru Kanzaki, Wings-Winds, http://www.wi-wi.jp/, 2007-2010
######################

This file is writen in Japanese. (UTF-8)
=================================

だぶ天ホームページ
http://dabten.wi-wi.jp/

=================================
メソッド

################################
Dabten.Load(files, option)

テンプレートファイルをロードします。
XMLHttpRequest、またはActiveXObjectの
Microsoft.XMLHTTP, Msxml2.XMLHTTP, Msxml2.XMLHTTP.2.0, Msxml2.XMLHTTP.3.0
のいずれかが使えるブラウザのみ動作します。

----- arguments -----------
files (Object)
  {ID1: ファイル1, ID2: ファイル2 [, ...] }
    このIDはテンプレートからHTMLやDOMノードツリーを作成するときに参照します。
    Load()関数は何度でも呼び出せますが、IDは共有されます。
    同じIDが指定された場合は上書きされます。

option (Object)
ファイルをロードするために必要なデータです。
主にCGIスクリプト等でテンプレートを生成している場合に使用します。
これらのデータは第一引数のファイルが複数ある場合は、全てに同じデータが送信されますので、
個々に指定する場合は１つずつLoad()を呼び出すか、
ファイル名の後ろにQUERY_STRING形式で送信データをつけて下さい。

  method: (String)
    送信メソッド
  
  postData: (String | Object)
    サーバーに送信するデータ
  
  user: (String)
    Authroizationが必要なページで使用するユーザー名
  
  password: (String)
    Authroizationが必要なページで使用するパスワード
  
  onsuccess: (Function)
    Load()関数が呼び出されたときの第一引数のセットを１つのグループとして、
    全てのファイルを読み終えた後に実行されるコールバック関数です。
    エラーがあった場合でも呼び出されます。
    
---- sample ------------
Dabten.Load(
		{
		 id1: 'template1.txt'
		,id2:'template2.txt'
		,id3:'template3.txt'
		}
		,
		{
		  onsuccess:callback
		}
	);

---- sample ------------
Dabten.Load(
		{
		 id1:'templage.cgi?id=1'
		,id2:'template.cgi?id=2'
		,id3:'template.cgi?id=3'
		}
	);


################################
Dabten.LoadMixed(uri, files, option)

全てのテンプレートファイルを、multipart/form-dataの形式で送信、および受信します。
methodに"GET"が指定されるとapplication/x-www-urlencodedとして送信します。
１回の送受信で全てのファイルの受信が完了しますので、
テンプレート数が多いときに、ネットワークリソースの消費を押さえるのに有効です。

一部のブラウザでmultipart/mixedのデータの受信に不具合があるため、
text/plainからエミュレートする方法もあります。
詳しくはウェブサイトをご覧下さい。
http://dabten.wi-wi.jp/method/multipart.html

----- arguments -----------
uri (String)
  テンプレートファイルを受信するためのCGIスクリプトファイルなどのURI

files (Object)
  {ID1: ファイル名1, ID2: ファイル名2 [, ...] }
    このIDはテンプレートからHTMLやDOMノードツリーを作成するときに参照します。
    Load()関数は何度でも呼び出せますが、IDは共有されます。
    同じIDが指定された場合は上書きされます。

option (Object)
ファイルをロードするために必要なデータです。
主にCGIスクリプト等でテンプレートを生成している場合に使用します。
これらのデータは第一引数のファイルが複数ある場合は、全てに同じデータが送信されますので、
個々に指定する場合は１つずつLoad()を呼び出すか、
ファイル名の後ろにQUERY_STRING形式で送信データをつけて下さい。

################################
Dabten.GetHTML('templateID', data)
Dabten.InsertHTML('elementID', 'templateID', data)

HTMLを作成します。
戻り値はStringです。
Load()で指定されていないIDが指定された場合、
またはLoad()に失敗したファイルのIDが指定された場合は空文字列が返されます。

InsertHTMLでは、生成したHTMLを第一引数のエレメントに挿入します。
戻り値は成功時true、失敗時falseです。

----- arguments -----------
ID (String)
  Load()の第一引数のIDに対応。

data (オブジェクト)
  {id1: value1, id2: value2 [...]}
  テンプレートの{tpl:id}に適用するデータ
  
---- sample ------------
document.getElementById('docid').innerHTML=Dabten.GetHTML('id', {name:'Joe',age:33});


========================
１つのテンプレートで完結しない場合は、１回ずつinnerHTMLに代入するのではなく、
先に必要なテンプレートを全て読み込んでから、まとめてinnerHTMLに入れてください。

Dabten.Load(
		{
		 head: 'head.tpl'
		 foot: 'foot.tpl'
		 cont: 'cont.tpl'
		}
	);

head.tpl
------------------------
<div>
<h1>Topic</h1>
</div>
<table>             <- 開始タグで終わる
------------------------

foot.tpl
------------------------
</table>            <- 終了タグから始まる
<div>
<p>End of Table</p>
</div>
------------------------

cont.tpl
------------------------
<tbody>{tpl::contain}</tbody>
------------------------

document.getElementById('docid').innerHTML=
                        Dabten.GetHTML('head', {})
                      + Dabten.GetHTML('cont', {contain:'<tr><td>contants</td></tr>'})
                      + Dabten.GetHTML('foot', {});

この形式のテンプレートはGetDOMで取得すると開始タグで終わるエレメントは閉じられます。
終了タグで始まるタグは無視されます。

========================
InternetExplorerにおいて、テーブルコンテンツのtbodyやtrだけを挿入する場合など、
innerHTMLを使用できない場合はDabten.GetDOM()を使用してください。

template
------------------------
<tr><td>１行１列</td><td>１行２列</td>
<tr><td>２行１列</td><td>２行２列</td>
------------------------

HTML
------------------------
<table id="tableid">
<tbody></tbody>
</table>
------------------------

// ERROR
tbody=document.getElementById('tableid').getElementsByTagName('tbody')[0];
tbody.innerHTML=Dabten.GetHTML(table, data)

// SUCCESS
domarray = Dabten.GetHTML(table, data)
tbody = document.getElementById('tableid').getElementsByTagName('tbody')[0];
for(var i=0;i<domarray.length;i++){
    tbody.appendChild(domarray[i]);
}

========================
タグの閉じ忘れがある場合、Operaで表示に不具合が出ることがあります。
これはOpera内部での問題と思われます。

<table>
<tr><td>１行１列<td>１行２列
<tr><td>２行１列<td>２行２列
</table>


################################
Dabten.GetDOM('teplateID', data, namespace)

DOMエレメントを作成します。
戻り値はリスト(配列)となります。
存在しないテンプレートIDが指定された場合は、サイズ０のリストを返します。

----- arguments -----------
ID (String)
  Load()の第一引数のテンプレートIDに対応。

data (オブジェクト)
  {id1: value1, id2: value2 [...]}
  テンプレートの{tpl:id}に適用するデータ
  
namespace
  XHTMLで作成している場合に true、または、htmlタグのxmlns属性を指定してください。
  DOMエレメント作成時にnamespace付きで作成するようになります。
  MIME-Typeがapplication/xmlなど、*/xmlである必要があり、text/htmlではnamespaceは無視します。
  この形式は一部のブラウザで対応していません。そのようなブラウザではnamespaceなしとして作成します。

---- sample ------------

------------------------
<h1>{tpl:title}</h1>
<p>{tpl:summary}</p>
------------------------
domarray=Dabten.GetDOM(tplId, {title:'学生簿', summary:'２年１組男子生徒一覧'}, true);
docobj=document.getElementById('doc');
for(var id=0;i<domarray.length;i++){
	docobj.appendChild(domarray[i]);
}

========================
------------------------
{tpl::repeat=students}
<tr>
<td>{tpl:sid}</td>
<td>{tpl:name}</th>
</tr>
{tpl::endrepeat}
------------------------
data={students:[
                 {sid:1, name:'Joe'}
                ,{age:2, name:'Peat'}
               ]};

domarray=Dabten.GetDOM(tplId, data);
table=document.getElementsByTagName('table')[0];
tbody=table.getElementsByTagName('tbody')[0]
for(var i=0;i<domarray.length;i++){
    tbody.appendChild(domarray[i]);
}


========================
戻り値は通常の配列ですので１つめだけを挿入することが決まっている場合は
関数の後ろに [0] を付けることができます。

------------------------
<div>
<h1>{tpl:title}</h1>
<p>{tpl:summary}</p>
</div>
------------------------
document.getElementById('doc').appendChild(
            Dabten.GetDOM(tplId, {title:'学生簿', summary:'２年１組男子生徒一覧'})[0]
                                          );


========================
Safariでは配列に対してfor(var i in domarray)を使うと取得できないことがあります。
for(var i=0;i<domarray.length;i++)など、
lengthを調べる形式でループさせることをお薦めします。

========================
インラインフレームなど、DOMを使用できない場合はDabten.GetHTML()を使用してください。


################################
Dabten.InsertDOM('elementID', 'templateID', data, add, namespace)

生成したDOMエレメントをelementIDで指定したエレメントに挿入します。
addが指定されていると、古いデータを消去せずに追加します。

----- arguments -----------
elementID (String | Object)
  HTMLドキュメントのエレメントID。

templateID (String)
  Load()の第一引数のテンプレートIDに対応。

data (Object)
  {id1: value1, id2: value2 [...]}
  テンプレートの{tpl:id}に適用するデータ

add (Boolean)  
  true : 古いデータを削除せずに追加します
  false : 古いデータを削除し、新しいデータを挿入します。（デフォルト）
  
namespace
  XHTMLで作成している場合に true、または、htmlタグのxmlns属性を指定してください。
  DOMエレメント作成時にnamespace付きで作成するようになります。
  XHTML1.0、XHTML1.1では xmlns属性は "http://www.w3.org/1999/xhtml" と決まっています。
  MIME-Typeがapplication/xmlなど、*/xmlである必要があります。
  text/htmlではnamespaceは無視します。
  この形式は一部のブラウザで表示出来ません。



################################
Dabten.Set('templateid', 'string')
Dabten.Load()の代わりにIDと文字列を指定し、登録します。


################################
Dabten.Document('templateid', 'elementID')
Dabten.Load()の代わりにドキュメント内のHTML/XHTML/XMLを読み込み、登録します。


################################
Dabten.GetFromURI(type, id, uri, option)

CGIスクリプトなどのデータを受信し、テンプレートに適用します。
CGIスクリプトから取得するデータは、XML、またはプレーンテキスト(Object()に変換可能なもの)です。

----- arguments -----------
type (String)
  'html', 'dom', 'xml'のいずれか
  戻り値のタイプをHTML、HTML-DOMエレメント、XML-DOMエレメントのいずれかにします。
  
id (String)
  テンプレートID
  Load()の第一引数のIDに対応。

uri (URI)
  データ受信のためのCGIスクリプトのURI
  
option (オブジェクト)
  method
    送信メソッド、"GET"または"POST"
  postdata
    CGIアプリケーションに送信データ
  namespace
    typeが'xml'または'dom'の時に有効。
    XHTMLで作成している場合に true、または、htmlタグのxmlns属性を指定してください。
    DOMエレメント作成時にnamespace付きで作成するようになります。
    XHTML1.0、XHTML1.1では xmlns属性は "http://www.w3.org/1999/xhtml" と決まっています。

---- sample ------------
Dabten.tpl
------------------------
<h1>{tpl:title}</h1>
<p>{tpl:summary}</p>
------------------------
domarray=Dabten.GetURI('dom', tplId, 'data.cgi');
docobj=document.getElementById('doc');
for(var id=0;i<domarray.length;i++){
	docobj.appendChild(domarray[i]);
}

################################
Dabten.InsertFromURI(elementID, type, templateID, uri, option)

CGIスクリプトなどのデータを受信し、テンプレートに適用、HTMLドキュメントに挿入します。
CGIスクリプトから取得するデータは、XML、またはプレーンテキスト(Object()に変換可能なもの)です。

----- arguments -----------
elementID (String | Object)
  HTMLドキュメントのエレメントID。

type (String)
  'html', 'dom'のいずれか
  戻り値のタイプをHTML、HTML-DOMエレメントのいずれかにします。
  
id (String)
  テンプレートID
  Load()の第一引数のIDに対応。

uri (URI)
  データ受信のためのCGIスクリプトのURI
  
option (オブジェクト)
  method
    送信メソッド、"GET"または"POST"
  postData
    CGIアプリケーションに送信データ
  onSuccess
    データ受信後、呼び出す関数

---- sample ------------
------------------------
<h1>{tpl:title}</h1>
<p>{tpl:summary}</p>
------------------------
Dabten.InsertFromURI('element', 'dom', templateId, 'data.cgi', {onSuccess:callback});


################################
Dabten.InsertJSONP(elementId, templateID, uri, cbkey, post, callback)

JSONPを使用してデータを受信します。
JSONPデータはサーバーによって形式が異なるため、
通常は受信するデータを受けるための関数（callback）を用意して下さい。

callback({key1:value1, key2:value2}) の形式で受け取れるサーバーでは、
callbackが指定されていない場合、
[{key: key1, value: value1}, {key:key2, value:value2}]
の配列に変換し、InsertDOMを実行します。

----- arguments -----------
elementID (String | Object)
  HTMLドキュメントのエレメントID。

templateID (String)
  Load()の第一引数のテンプレートIDに対応。

uri (String)
  JSONP送信プログラムのURI

cbkey (String)
  JSONP送信者が指定したcallback関数の呼び出し名
  ほとんどのサーバーで "callback" のようです。

post (Object)
  {id1: value1, id2: value2 [...]}
  サーバーに送信するデータ

callback (Function)
  データ受信後（<script>タグ挿入、読み込み完了後）に呼び出す関数

################################
Dabten.Net.Load(url, callback, option)

いわゆるAjaxライブラリ。
戻り値はObject()。
Object.clientがXMLHttpRequest/ActiveXObject本体。

----- arguments -----------
url (%URI)
  データ送信先URI
  
callback (Function)
  受信完了後に呼び出すコールバック関数

option (オブジェクト)
  method (String デフォルト:"GET")
    送信メソッド、"GET"または"POST"
  postdata (any)
    CGIアプリケーションに送信するデータ
    フォームエレメント、またはフォームエレメントの配列を渡すと、その各フィールドの値を送信します。
  enctype (String デフォルト:"applecation/x-www-form-urlencoded")
    送信データ種別
  encoded (boolean デフォルト:true)
    送信データがURIエンコードされているか
    falseが指定されるとencodeURIComponentを使用してエンコードします。
    encodeURIComponentはSafari1.0とMacIEで使えませんが、XMLHttpRequestを使えないブラウザなので放置
  onFileNotFound (Function)
    受信完了後、ファイルが存在しない場合に呼び出すコールバック関数
  onError (Function)
    受信完了後、エラーがあった場合に呼び出すコールバック関数
  user (String)
    ユーザー名
  password  (String)
    パスワード
  async (boolean デフォルト:true)
    非同期指定



---- sample ------------
var o=new Dabten.Net.Load('sample.cgi', callback,
          {
             postData:'postData'
            ,onFileNotFound:callbackError
            ,onError:callbackError
            ,async:true
            ,method:'GET'
          });


function callback(obj){
    alert(obj.client.responseText);
}
function callbackError(obj){
    alert('something error occured');
}

################################
CopyRight

=================================
dabten.js 1.0.h
(C) Wataru Kanzaki, Wings-Winds, http://www.wi-wi.jp/, 2007-2010
=================================