基本的な使用方法

空のexposeデコレータは、そのメソッドをウェブ上で利用可能にすることを意味しますが、コンテンツのフォーマットやヘッダの設定をあなたがすべて制御することになります。

@expose()

より一般的なのはテンプレートへの関連づけを指定することです:

@expose("projectname.templates.baz")

このようにした場合、コントローラメソッドから辞書を返すことが期待されます。この辞書の値はテンプレートで利用可能になります。たいていのテンプレートはキーと値のペアをローカル変数としてexposeします。言い換えれば、 {'a':2} を返せば、テンプレート内ではすべての ${a} が2に置き換わるということになります。

Tip: 値がコントローラメソッドの名前空間にすでにあるならば、 return locals() とすることができます。

上記で ("projectname.templates.baz") としたテンプレートはレンダリングするためにデフォルトのテンプレートエンジンとしてKidを使うでしょう。あるメソッドに対してのみ別のテンプレートエンジンを利用したい場合は、テンプレート指定の前にその名前とコロンを置くだけです:

@expose("cheetah:foo.templates.plaintext")

いくつかのテンプレートエンジンではテンプレートファイルを指定する必要さえないかもしれません。例えばJSONの出力はそのように動きます。このような時は、テンプレートエンジンそのものを書くだけです:

@expose("json")

同じメソッドを異なるテンプレートで

コントローラメソッドが辞書を返すだけであるとき、この辞書を異なるテンプレートエンジンへ渡して、異なる結果を返すようにしたいと考えるかもしれません。これは正しい考えです:

@expose("projectname.templates.baz")
@expose("json", as_format="json", accept_format="text/javascript")
def yourmethod(self):
    return dict(a_value="something")

この場合、デフォルトのテンプレート言語を変更しない限り projectname/templates/baz.kid はKidへ渡されます。一方で yourmethod が "tg_format=json" と共に呼び出されたり、あるいは "Accept: text/javascript" ヘッダが存在した場合には、JSONフォーマットのデータが返されるでしょう。

JSONはAjax操作をするのに一般的かつ便利なフォーマットなので、JSON出力を得るための簡単な方法があります:

@expose("foo.templates.baz", allow_json=True)
def yourmethod(self):
     return dict(a_value="something")

このサンプルは先ほどのサンプルと同等です。 allow_json=True パラメータを追加することは、先ほどのサンプルの２つめの@exposeデコレータと同じなのです。

もちろんこれはJSON出力に限ったことではありません。HTML出力でKidを使っているときに、cheetahフォーマットテキストを返したいときには以下のようにします:

@expose("cheetah:projectname.templates.plaintext",
         as_format="plain", accept_format="text/plain"
         content_type="text/plain")

このメソッドが "tg_format=plain" パラメータと共に呼ばれたとき（``as_format``がこれに該当します）や、 "Accept: text/plain" ヘッダが存在したとき（``accept_format``がこれに該当します）には、Cheetahテンプレートが使われ、そのページのプレーンテキストがレンダリングされるでしょう。 content_type を省略すると、このドキュメントは text/html として扱われます。ほとんどのクライアントはMIMEタイプをミスしたテキストをうまく処理できますが、PDFやPNGなどのテキストでない出力を返す場合は正しいMIMEタイプをセットするのがよいでしょう。

Kidのようないくつかのテンプレートエンジンはいくつかのフォーマットでテンプレートをレンダリングすることができます。 format パラメータはそのエンジンがどのフォーマットで出力するかを制御します。Kidではこのオプションは "html" （デフォルト）、 "xml" 、 "xhtml" を採ることができます。