=========================================================================
Affelio Programming Guide
=========================================================================

	CHANGES
	-------
	Affelio API	1.2				Nov. 21, 2005
	Affelio API	1.1				May  12, 2005
	Affelio API	1.0				May  11, 2005

1.ファイル構成
===================

	affelio/		Affelioディレクトリ
	affelio/apps/		アプリけーションrootディレクトリ

	affelio/apps/app1	各アプリケーションディレクトリ。
	affelio/apps/app2	順次ユーザによって設置される。
	...


　各アプリケーションディレクトリ内のファイル構成

	AF_app.cfg	Affelioアプリケーションとしての設定file。
			必ずこの名前で設置される必要がある。

	以下、各アプリケーション固有のCGIファイル、HTMLファイル、データ
	保存用ディレクトリなどは、各アプリケーションのディレクトリ以下
	にある限り設置方法は自由。

	foo.cgi		Affelioアプリケーションとして動作する
	bar.html	CGIファイル、HTMLファイルなど。

	data/		アプリケーション固有のデータ保存用ディレク
			トリ例。ディレクトリ内のデータファイルは、
			Affelioのユーザ認証によるアクセス制御を用い
			てCGIからのみ読み込まれ、ブラウザに送信され
			ることが想定される。このため直接ブラウザから
			ディレクトリを閲覧できないよう.htaccessを
			設定することが推奨される。

2.AF_app.cfg
===================
	[this_installation]セクション
		**このセクションはAPI1.2においてDeprecatedになりまし
		**た。アプリケーションをAPI1.1のみをサポートする古い
		**バージョンのAffelio上で動作させる場合は、このセク
		**ションは残してください。
		**API1.2においてはこのセクションは無視されます。

	.cfgファイル内のこのセクションには、アプリケーションの、今回
	の設置（インストール）にspecificな情報が用意される。Affelio
	ユーザは、同一のアプリケーションを、違う名前のディレクトリに
	複数設置できる。その場合、Affelioユーザはこのセクションを
	編集することが予想される。

	title=俺の日記		Affelio画面の上部タブに出るタイトル


	---------------------------------------------

	[application]セクション

	applicationセクションには、アプリケーション自体の名前、
	バージョンと言った情報が設定される。通常以下の情報は、
	アプリケーション開発者によって記述され、Affelioユーザは
	通常編集する必要はない。

	app_URI			アプリケーションを示すURI
				　アプリケーションのグローバルな一意性
				　はapp_URIに基づいて区別されます。

	app_name		アプリケーション名

	app_version		バージョン番号

	app_desc		アプリケーションに関する説明

	app_desc		アプリケーションの作者

	guest_index		ゲスト向けデフォルトページのファイル名
				(ゲストタブで表示される)

	owner_index		オーナー向けデフォルトページのファイル名
				(オーナータブで表示される)

	action_types		comma-separated list of action types.
				Each action type is the atomic unit which
				Affelio user can control access from other
				users (via Affelio control panel).	

	action_type_desc	comma-separated list of action type 
				description.
			

3.CGIファイルが行うべき動作
===================

	Affelioアプリケーションとしての各CGIプログラムは、Affelioのユーザ認証
	を使ったアクセス制御を用いて動作し、許可されるコンテンツをブラウザへ
	返信する。

	例えばAffelioアプリケーションとしての「掲示板CGI」は、ユーザからのアク
	セスをAffelioのユーザ認証機構を使って認証し、もし閲覧許可を与えられた
	ユーザからのアクセスであれば、掲示板のHTMLファイルをブラウザに送信す
	る。またもし書き込みを許可されたアクセスであれば、ユーザからの書き込
	みを保存する。以上のような動作が、アプリケーション例として考えられる。

	CGIプログラムの構造に関して、AffelioアプリケーションとしてのCGIプログ
	ラムが通常のCGIプログラムと異なるのは、

	  (1)アクセスユーザの、Affelioユーザとしてのアクセス権の確認

	  (2)Affelioの画面に収まる形でのHTML出力

	の部分である。それぞれ、AffelioAPIとして提供される関数を呼び出すこと
	で行う。

	（既存のCGIプログラムをAffelioアプリケーションとして動作させ
		  るために変更する場合は、上記2点を適切に追加すればよい）


4.プログラミング例
===================

	(apps/sampleapp/index.cgi を参照)


5. Affelio API
===================

   Affelio APIの初期化
   -------------------

   　$ap = new AffelioApp(ConfigDir => Cwd::getcwd(),
                          cgi => $cgi );   

	 IN: ConfigDir         本アプリケーションのサーバ内絶対パス
             cgi               CGIへの参照

         OUT: $ap              AffelioAppへの参照


   Affelioの枠HTMLコードを出力するAPI
   ----------------------------------

   　$str = AffelioApp::get_HTML_header($HTMLtitle);

	 IN: $HTMLtitle        HTMLのタイトル

         OUT: $str             HTML文字列 (ヘッダ部分)


   　$str = AffelioApp::get_HTML_footer();

         OUT: $str             HTML文字列 (フッタ部分)


   現在のアクセス者に関する情報を取得するAPI
   -----------------------------------------
   　$val = AffelioApp::get_visitor_info($info_name);

	 IN: $info_name :      "nickname"   visitor's nickname
	                       "afid"       visitor's Affelio_ID (URL)
		               "type"       visitor's type
                                             "self", "f1", "f2", or "pb"
         OUT: $val:            value


   本ログインセッションへのデータの保存・保存したデータの読込
   ----------------------------------------------------------

     (get)
   　$val = AffelioApp::get_session_param($param_name);

     (set)
   　AffelioApp::set_session_param($param_name, $val);


   Affelioサイトに関する情報を取得するAPI
   --------------------------------------

   　$val = AffelioApp::get_site_info($info_name);
			
	 IN: $info_name :      "web_root"    Affelioのroot URL

         OUT: $val:            value


   このアプリケーションインスタンスに関する情報を取得するAPI
   ---------------------------------------------------------

   　$val = AffelioApp::get_app_info($info_name);
			
	 IN: $info_name :      "install_title"    install title

         OUT: $val:            value



   Affelioサイトのオーナーに関する情報を取得するAPI
   ------------------------------------------------

   　$val = AffelioApp::get_owner_info($info_name);

	 IN: $info_name :      "nickname"   owner's nickname
                               "afid"       owner's Affelio_ID (URL)

         OUT: $val:            value

				
   現在のアクセス者が本アプリ内で許可されるアクセスを調べるAPI
   -----------------------------------------------------------
   
   　$ret = AffelioApp::check_access($action_type);

	 IN: $action_type:     AF_app.cfg内のaction_typesに書き込んだ
                               アクション。"write", "read" など。

                               また、アクション"DF_access"は、基本的な
                               アプリケーションへのアクセス権を意味し、
                               AF_app.cfgに明示しなくてもAffelio側が
                               デフォルトで保持する。

         OUT: $ret:            1 or 0


