Skip to content

Instantly share code, notes, and snippets.

@eitoball
Created December 30, 2009 15:30
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save eitoball/266129 to your computer and use it in GitHub Desktop.
Save eitoball/266129 to your computer and use it in GitHub Desktop.
この文書はSWFUploadの文書(バージョン2.2.0.1)を訳したものです。元の文書は、http://demo.swfupload.org/Documentation/ より閲覧することができます。この文書は私訳であり、公式文書ではありません。
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
<title>SWFUpload v2 文書</title>
</head>
<style type="text/css">
h1 /* Title */ {
}
h2 /* Chapter Header */ {
background-color: #DCE7F2;
border: solid 1px #CCD7E0;
padding: 10px;
margin-top: 50px;
margin-left: 5px;
}
h3 /* Section Header */ {
background-color: #EDFFEB;
padding: 10px;
margin-left: 15px;
}
h4 {
background-color: #FFFFD1;
padding: 7px;
margin-left: 20px;
}
h5 {
background-color: #F0F0F0;
padding: 4px;
font-weight: normal;
margin-left: 25px;
}
p {
margin-left: 35px;
}
span.function {
font-weight: bold;
}
span.parameter {
font-style: italic;
font-weight: normal;
}
hr {
margin-right: 25px;
}
ul, ol {
list-style-position: outside;
margin: 0;
padding: 0;
margin-left: 50px;
}
li {
padding-left: 15px;
}
code {
display: block;
border: solid 1px #EFEFEF;
background-color: #FAFAFA;
padding: 15px;
margin-left: 25px;
white-space: pre;
overflow-x: scroll;
overflow-y: visible;
}
</style>
<body>
<h1>SWFUpload v2.2.0.1 文書</h1>
<h2>目次</h2>
<ol>
<li><a href="#swfupload">SWFUpload</a></li>
<li><a href="#v2">SWFUploadバージョン2</a></li>
<li><a href="#overview">概要</a></li>
<li><a href="#gettingstarted">はじめに</a></li>
<li><a href="#javascriptobject">SWFUpload JavaScriptオブジェクト</a>
<ol>
<li><a href="#constructor">コンストラクタ</a></li>
<li><a href="#globals">グローバル変数と定数</a>
<ol>
<li><a href="#instances">instances</a></li>
<li><a href="#movieCount">movieCount</a></li>
<li><a href="#queue_error">QUEUE_ERROR</a></li>
<li><a href="#upload_error">UPLOAD_ERROR</a></li>
<li><a href="#file_status">FILE_STATUS</a></li>
<li><a href="#button_action">BUTTON_ACTION</a></li>
<li><a href="#button_cursor">CURSOR</a></li>
<li><a href="#button_window_mode">BUTTON_WINDOW_MODE</a></li>
</ol>
</li>
<li><a href="#properties">プロパティ</a>
<ol>
<li><a href="#customSettings">customSettings</a></li>
<li><a href="#movieName">movieName</a></li>
</ol>
</li>
<li><a href="#methods">メソッド</a>
<ol>
<li><a href="#addSetting">addSetting</a> (非推奨)</li>
<li><a href="#getSetting">getSetting</a> (非推奨)</li>
<li><a href="#retrieveSetting">retrieveSetting</a> (バージョン2.1.0で削除)</li>
<li><a href="#destroy">destroy</a> (バージョン2.1.0で追加)</li>
<li><a href="#displayDebugInfo">displayDebugInfo</a></li>
<li><a href="#selectFile">selectFile</a></li>
<li><a href="#selectFiles">selectFiles</a></li>
<li><a href="#startUpload">startUpload</a></li>
<li><a href="#cancelUpload">cancelUpload</a></li>
<li><a href="#stopUpload">stopUpload</a></li>
<li><a href="#getStats">getStats</a></li>
<li><a href="#setStats">setStats</a></li>
<li><a href="#getFile">getFile</a></li>
<li><a href="#addPostParam">addPostParam</a></li>
<li><a href="#removePostParam">removePostParam</a></li>
<li><a href="#addFileParam">addFileParam</a></li>
<li><a href="#removeFileParam">removeFileParam</a></li>
<li><a href="#setUploadURL">setUploadURL</a></li>
<li><a href="#setPostParams">setPostParams</a></li>
<li><a href="#setFileTypes">setFileTypes</a></li>
<li><a href="#setFileSizeLimit">setFileSizeLimit</a></li>
<li><a href="#setFileUploadLimit">setFileUploadLimit</a></li>
<li><a href="#setFileQueueLimit">setFileQueueLimit</a></li>
<li><a href="#setFilePostName">setFilePostName</a></li>
<li><a href="#setUseQueryString">setUseQueryString</a></li>
<li><a href="#setDebugEnabled">setDebugEnabled</a></li>
<li><a href="#setButtonImageURL">setButtonImageURL (バージョン2.2.0で追加)</a></li>
<li><a href="#setButtonDimensions">setButtonDimensions (バージョン2.2.0で追加)</a></li>
<li><a href="#setButtonText">setButtonText (バージョン2.2.0で追加)</a></li>
<li><a href="#setButtonTextStyle">setButtonTextStyle (バージョン2.2.0で追加)</a></li>
<li><a href="#setButtonTextPadding">setButtonTextPadding (バージョン2.2.0で追加)</a></li>
<li><a href="#setButtonDisabled">setButtonDisabled (バージョン2.2.0で追加)</a></li>
<li><a href="#setButtonAction">setButtonAction (バージョン2.2.0で追加)</a></li>
<li><a href="#setButtonCursor">setButtonCursor (バージョン2.2.0で追加)</a></li>
</ol>
</li>
<li><a href="#events">イベント</a>
<ol>
<li><a href="#flashReady">flashReady</a></li>
<li><a href="#swfUploadLoaded">swfUploadLoaded</a></li>
<li><a href="#fileDialogStart">fileDialogStart</a></li>
<li><a href="#fileQueued">fileQueued</a></li>
<li><a href="#fileQueueError">fileQueueError</a></li>
<li><a href="#fileDialogComplete">fileDialogComplete</a></li>
<li><a href="#uploadStart">uploadStart</a></li>
<li><a href="#uploadProgress">uploadProgress</a></li>
<li><a href="#uploadError">uploadError</a></li>
<li><a href="#uploadSuccess">uploadSuccess</a></li>
<li><a href="#uploadComplete">uploadComplete</a></li>
<li><a href="#debug">debug</a></li>
</ol>
</li>
<li><a href="#utility">SWFUploadユーティリティオブジェクト</a>
<ol>
<li><a href="#settingsobject">Settingsオブジェクト</a></li>
<li><a href="#settingsdescription">設定値の説明</a></li>
<li><a href="#fileobject">Fileオブジェクト</a></li>
<li><a href="#statsobject">Statsオブジェクト</a></li>
</ol>
</li>
</ol>
</li>
<li><a href="#plugins">SWFUploadプラグイン</a></li>
<li><a href="#knownissues">既知の問題</a></li>
</ol>
<h2><a name="swfupload"></a>SWFUpload</h2>
<p>
<a href="http://www.swfupload.org">SWFUpload</a>は、当初は<a href="http://www.vinterwebb.se/">Vinterwebb.se社</a>によって開発されたクライアントサイドで動作するファイルアップロードツールです。&lt;input type="file" /&gt;タグにより提供される基本的なブラウザの機能より豊富なファイルアップロード機能を提供するためにFlashとJavaScriptの組み合わせて使用します。
</p>
<p>SWFUploadが提供する主な機能:</p>
<p>
<ul>
<li>ファイルブラウザダイアログで複数のファイルを選択する機能。</li>
<li>ページを再読込することなしにAJAXを使ったアップロード。</li>
<li>アップロード進行通知イベント。</li>
<li>他のJavaScriptライブラリ(jQuery、Prototypeなど)と相性のよい名前空間を使ったクラス群。</li>
<li>Flash 9とFlash 10のサポート。(Flash 8のサポートはバージョン2.2.0で停止)</li>
</ul>
</p>
<p>
SWFUploadは他のFlashを使ったファイルアップロードツールとは設計思想が異なります。SWFUploadは(可能な限り)ブラウザのユーザーインターフェースから離れて開発者がアップロード処理の制御を提供します。開発者は、サイトの要件やスタイルにアップロードのユーザーインターフェースを合わせるためにXHTML、CSS、そして、JavaScriptを使用することができます。いくつかの簡単なJavaScriptイベントを通してアップロード状況の更新を行います。開発者は、ファイルアップロードの進行に合わせて、ウェブページを更新するためにこれらのイベントを使用します。
</p>
<p>
残念なことにFlashプレーヤー10では、ファイルブラウザダイアログを表示するためにはFlash動画の中に1つのボタンを配置する必要があります。SWFUploadは開発者がJavaScriptによってボタンを配置したりやテキストの重ね合わせたりすることができるようにしています。
</p>
<h2><a name="v2"></a>SWFUploadバージョン2</h2>
<p>
SWFUploadバージョン2では新しく高度な機能、安定性の向上、Flashプレーヤーの不具合に対する対処、いくつかの便利なプラグインを提供しています。新しい機能を以下に示します:
</p>
<p>
<ul>
<li>Flashプレーヤー10のセキュリティーに対する互換性</li>
<li>アップロードとともに追加のPOSTデータ値の送信する機能</li>
<li>ファイル毎でのPOSTデータ値の送信</li>
<li>完全なイベント群</li>
<li>全ての設定を動的に更新可能</li>
<li>サーバーから結果データの取り出し機能</li>
<li>キャンセルすることなしにアップロードを停止する機能</li>
<li>いかなる順序でもファイルをアップロード</li>
<li>複数ファイルを選択できる単一のファイル選択ダイアログ</li>
<li>キューサイズ、アップロードされるファイル数やファイルサイズの制限</li>
<li>0バイトのファイルを正しく処理</li>
<li>アップロード前の妥当性確認イベント</li>
<li>Flashやブラウザの不具合の対処</li>
</ul>
</p>
<h2><a name="overview"></a>概要</h2>
<h3>HTMLアップロード</h3>
<p>
標準のHTMLアップロードファイル入力フィールドでは、ファイルを選択するためにユーザーに入力フィールドとボタンを1つずつ提供します。ファイルはフォームで送信されます。次のページを表示する前にファイルの全てをアップロードしなければなりません。アップロード前にファイルの妥当性確認(例えば、ファイルサイズ制限や有効な拡張子など)をすることができません。アップロード中にはユーザーに対してはフィードバックはほんの少しです。
</p>
<p>
標準のHTMLアップロードの使用パターンは、簡単、単純、そして、ほとんど全てのブラウザでサポートされています。
</p>
<h3>SWFUpload</h3>
<p>
SWFUploadでは、ファイルの選択とアップロードを処理するためにFlashムービーを使用します。Flash製の高度なファイル選択ダイアログウィンドウを起動させるカスタマイズ可能なボタンはFlashムービーで表示しています。ファイル選択ダイアログではユーザーがファイルを1つか複数選択できるのかを設定できます。ユーザーが適切なファイルだけ(例えば、*.jpgや*.gif)を選択できるようにファイルの型を制限することができます。
</p>
<p>
ファイルを選択したら、それぞれ妥当性確認をしてキューに入ります。Flashによってファイルがアップロードされていくにつれて、いくつかのJavaScriptのイベントが発生させます。即時にアップロード状況やエラー文言を提供することができるページのユーザーインターフェースの更新処理を行うために開発者はそれらのイベントを処理します。
</p>
<p>
ウェブページやフォームとは別にアップロードファイルは送信されます。サーバー側でのアップロード処理スクリプトが簡単にするためにそれぞれのファイルは個々にアップロードされます。Flashでアップロードサービスを提供するため、ウェブページを送信したり再読込したりする必要がありません。SWFUploadの利用パターンは、標準のHTMLファームでの利用パターンよりAJAXを使ったアプリケーションの利用パターンに近いです。ウェブページのフォームはファイルのアップロードとは別に処理されます。
</p>
<h2><a name="gettingstarted"></a>はじめに</h2>
<p>SWFUploadはドラッグドロップでファイルをアップロードすることはできません。JavaScriptとDOMの知識が必要になります。SWFUploadができることのいくつかや一般的なタスクを成し遂げる方法を紹介するいくつかのデモがあります。</p>
<p>SWFUploadは次の4項目から構成されています:</p>
<ol>
<li>初期化と設定 (JavaScript)</li>
<li>JavaScriptライブラリ: SWFUpload.js</li>
<li>Flashコントロール: swfupload.swf</li>
<li>イベントハンドラー (JavaScript)</li>
</ol>
<p>SWFUPloadを利用する際、間違った設定、不完全に実装されたイベントハンドラー、Flashやブラウザーの不具合、もしくは、サーバーの設定によって、ほとんどの問題が発生しています。
<h3>初期化と設定</h3>
<p>SWFUploadはウェブページ上で初期化しなければなりません。window.onloadイベントにて一般的に行われます。SWFUloadのコンストラクタはSettingsオブジェクトを受け入れます。Settingsオブジェクトはオブジェクトリテラルとして、直接、コンストラクタに渡すことができます。</p>
<p>アップロードを開始するときやSWFUploadの他の側面を制御するときに必要なので、初期化されたSWFUploadオブジェクトへの参照はどこかに保持しておくべきです。</p>
<p><strong>例:</strong> オブジェクトリテラルでSWFUploadを初期化</p>
<code>var swfu;
window.onload = function () {
swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload.swf",
file_size_limit : "20 MB"
});
};</code>
<p><strong>例:</strong> Settingsオブジェクトの変数でSWFUploadを初期化</p>
<code>var swfu;
window.onload = function () {
var settings_object = {
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload.swf",
file_size_limit : "20 MB"
};
swfu = new SWFUpload(settings_object);
};</code>
<h3>JavaScriptライブラリ</h3>
<p>JavaScriptライブラリファイル(swfupload.js)は、ユーザーがファイルをアップロードするページに含まなければなりません。</p>
<p>SWFUploadオブジェクトが作成されると、開発者によってSWFUploadを制御することができるいくつかの関数が使用できるようになります。</p>
<p><strong>例:</strong> ページへのSWFUpload.jsの組み込み</p>
<code>
&lt;script type="text/javascript" src="http://www.swfupload.org/swfupload.js"&gt;&lt;/script&gt;
</code>
<p><strong>例:</strong> 必要な設定でSWFUploadを初期化</p>
<code>var swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
button_placeholder_id : "spanSWFUploadButton"
});
</code>
<h3>Flashコントロール</h3>
<p>SWFUpload JavaScriptライブラリは動的にFlashコントロール(swfupload.swf)を読み込みます。</p>
<p>Flashコントロールファイルの位置は、初期化の際にSWFUploadのSettingオブジェクトに与えられていなければなりません。</p>
<p>Flashコントロールはファイルブラウズ、妥当性確認、そして、アップロードを処理する小さなFlashムービーです。ウェブページ上にはボタンとして表示され、アップロード状況や他のイベントをブラウザに通知するためにJavaScriptでやりとりを行います。</p>
<h3>イベントハンドラー</h3>
<p>開発者はSWFUploadのイベントを処理するJavaScriptの関数をいくつかを作成しなければなりません。異なる重要なイベントが発生する度にこれらの関数は呼び出されます</p>
<p>SWFUploadのイベントを処理することによって、開発者は、アップロード進行状況、エラー文言、そして、アップロード完了に関するフィードバックを提供することができます。開発者は、SWFUpload.prototypeに定義されている関数をオーバライドするべきではありません。代わりにいくつか関数を作成してSettingsオブジェクトを通してそれら関数の参照を渡して下さい。</p>
<p><strong>例:</strong> SWFUploadイベントハンドラーと初期化</p>
<code>// uploadStartイベントハンドラ。この関数変数はSettingsオブジェクトのupload_start_eventに割り当てられます。
var myCustomUploadStartEventHandler = function (file) {
var continue_with_upload;
if (file.name === "the sky is blue") {
continue_with_upload = true;
} else {
continue_with_upload = false;
}
return continue_with_upload;
};
// The uploadSuccessイベントハンドラ。この関数変数はSettingsオブジェクトのupload_success_handlerに割り当てられます。
var myCustomUploadSuccessEventHandler = function (file, server_data, receivedResponse) {
alert("The file " + file.name + " has been delivered to the server. The server responded with " + server_data);
};
// SWFUploadオブジェクトを作成
var swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload.swf",
file_size_limit : "200 MB",
upload_start_handler : myCustomUploadStartEventHandler,
upload_success_handler : myCustomUploadSuccessEventHandler
});</code>
<h2><a name="javascriptobject"></a>SWFUpload JavaScriptオブジェクト</h2>
<h3><a name="constructor"></a>コンストラクタ</h3>
<p><span class="function">SWFUpload(<span class="parameter">Settingsオブジェクト</span>)</span></p>
<p><b>返値:</b> SWFUploadのインスタンス</p>
<code>var swfupload_instance = new SWFUpload(settings_object);</code>
<h3><a name="globals"></a>グローバル変数と定数</h3>
<p>
いくつかのグローバル変数と定数はSWFUploadオブジェクトに関連しています。これらは、SWFUploadを使った高度なアプリケーションやエラー処理に便利です。これらは読み取り専用と見なされています。
</p>
<h4><a name="instances"></a>SWFUpload.instances</h4>
<p>SWFUpload.instancesはページに読み込まれたSWFUploadインスタンスそれぞれの参照を含んでいるオブジェクトです。Flashプレーヤーは、正しいイベントハンドラーを呼び出すためにこのオブジェクトに頼っています。SWFUpload.instancesはmovieNameプロパティによってインデックス化されています。</p>
<h4><a name="movieCount"></a>SWFUpload.movieCount</h4>
<p>SWFUpload.movieCountは、作成されたSWFUploadのインスタンスの数を保持してそれぞれのFlashムービーに固有のmovieNameを与えることができるようにするグローバル変数です。</p>
<h4><a name="queue_error"></a>SWFUpload.QUEUE_ERROR</h4>
<p>SWFUpload.QUEUE_ERRORは、Queue Errorコード定数を保持する単純なオブジェクトです。通常、fileQueueErrorイベントでどのエラーコードが送られたかを判断するために使用します。</p>
<ul style="padding-left: 15px;">
<li>QUEUE_LIMIT_EXCEEDED - ユーザーが設定されたファイル数よりも多くファイルをキューに格納しようとしていることを示します。ファイルが更新されてキューから削除されたらユーザーは再び追加のファイルをキューに格納することができます。</li>
<li>FILE_EXCEEDS_SIZE_LIMIT - 選択されたファイルがfile_size_limitで設定されたサイズより大きいことを示します。</li>
<li>ZERO_BYTE_FILE - 選択されたファイルが空であることを示します。Flashプレーヤーは空のファイルを処理することができません。そのファイルを拒否します。Windowsのショートカットファイルがこのエラーを引き起こす場合があります。</li>
<li>INVALID_FILETYPE - 選択されたファイルの拡張子がfile_typesの設定での有効な拡張子でないことを示します。ユーザーは、ファイル名を手動で入力することによってfile_typesによる制限を回避することができます。</li>
</ul>
<h4><a name="upload_error"></a>SWFUpload.UPLOAD_ERROR</h4>
<p>SWFUpload.UPLOAD_ERRORは、Upload Errorコード定数を保持する単純なオブジェクトです。通常、uploadErrorイベントでどのエラーコードが送られたかを判断するために使用します。</p>
<ul style="padding-left: 15px;">
<li>HTTP_ERROR - ファイルをアップロードしたが、サーバーがHTTP200ステータスコードを返さなかったことを示します。</li>
<li>MISSING_UPLOAD_URL - upload_urlが設定されていないことを示します。</li>
<li>IO_ERROR - ファイルを読み込むか送信している時に何かエラーが発生したことを示します。サーバーが突然、接続を切断する時にもっともよく発生します。</li>
<li>SECURITY_ERROR - ファイルアップロードがセキュリティ制限を違反していることを示します。このエラーは希です。</li>
<li>UPLOAD_LIMIT_EXCEEDED - ユーザーがfile_upload_limitで設定されたファイル数以上のファイルをアップロード使用としていることを示します。</li>
<li>UPLOAD_FAILED - ファイルアップロードを開始しようとしてエラーが発生したことを示します。このエラーは希です。</li>
<li>SPECIFIED_FILE_ID_NOT_FOUND - ファイルIDがstartUploadに渡されたが、そのファイルIDが見つけることができなかったことを示します。</li>
<li>FILE_VALIDATION_FAILED - uploadStartイベントが偽値を返したことを示します。</li>
<li>FILE_CANCELLED - cancelUploadが呼び出されたことを示します。</li>
<li>UPLOAD_STOPPED - stopUploadが呼び出されたことを示します。</li>
</ul>
<h4><a name="file_status"></a>SWFUpload.FILE_STATUS</h4>
<p>SWFUpload.FILE_STATUSは、File Statusコード定数を保持する単純なオブジェクトです。Fileオブジェクトのファイルの状態にかんするプロパティを確認する為に使用することができます。</p>
<ul style="padding-left: 15px;">
<li>QUEUED - このファイルがキューの中で待機していることを示します。</li>
<li>IN_PROGRESS - このファイルが現在アップロード中であることを示します。</li>
<li>ERROR - このファイルにキュー内もしくはアップロード中にエラーが発生していることを示します。</li>
<li>COMPLETE - このファイルがサーバーに無事に送信されたことを示します。</li>
<li>CANCELLED - このファイルがcancelUploadの呼び出しによってアップロードが中止されたことを示します。</li>
</ul>
<h4><a name="button_action"></a>SWFUpload.BUTTON_ACTION</h4>
<p>SWFUpload.BUTTON_ACTIONはボタンのアクションについてのコードを保持する単純なオブジェクトです。Flash製のファイルダイアログ上のボタンの振る舞いを設定するbutton_actionに使用します。</p>
<ul style="padding-left: 15px;">
<li>SELECT_FILE - Flash製のボタンがクリックされたときファイルダイアログでは1つのファイルだけを選択することができます。</li>
<li>SELECT_FILES - Flash製のボタンがクリックされたときファイルダイアログでは複数のファイルだけを選択することができます。</li>
<li>START_UPLOAD - Flash製のボタンがクリックされている間、最初にキューに格納されたファイルをアップロードします。</li>
</ul>
<h4><a name="button_cursor"></a>SWFUpload.CURSOR</h4>
<p>SWFUpload.CURSORは、ボタンのカーソルについてのコードを保持する単純なオブジェクトです。Flash製のボタン上にある時のマウスカーソルの形状を設定するbutton_cursorに使用します。</p>
<ul style="padding-left: 15px;">
<li>ARROW - 矢印ポインタとしてカーソルを表示します。</p>
<li>HAND - 指もしくは手ポインタとしてカーソルを表示します。</p>
</ul>
<h4><a name="button_window_mode"></a>SWFUpload.WINDOW_MODE</h4>
<p>SWFUpload.WINDOW_MODEは、ボタンのムービーのwmodeパラメータの定数を保持する単純なオブジェクトです。Flashムービーがどのように表示されるかをブラウザに伝えるために使用します。</p>
<p>WINDOW_MODE/WMODEの設定においてブラウザによっては問題が発生する場合があります。問題については<a href="#knownissues">既知の問題</a>を読んで下さい。</p>
<ul style="padding-left: 15px;">
<li>WINDOWは、デフォルトのモードです。Flashムービーはページ上の他の全ての要素の上に描画されます。</li>
<li>OPAQUEでは、 他の要素がボタンの上に覆い被さるようにFlashムービーをページに描画します。</li>
<li>TRANSPARENTでは、ボタンの下のHTML要素が見えるようにボタンの背景が透過されて描画されます。</li>
</ul>
<h3><a name="properties"></a>プロパティ</h3>
<p>
次に示すプロパティの一覧は説明のように使用するようにして下さい。他のプロパティを使ったり読み込み専用のプロパティへ書き込んだ場合にはSWFUploadが正しく動作しないことがあります。
</p>
<h4><a name="customSettings"></a>customSettings (read/write)</h4>
<p>
customSettingsプロパティは、SWFUploadのインスタンスに関連するデータを格納することができる空のJavaScriptのオブジェクトです。customSettingsオブジェクトはcustom_settings設定を利用して初期化することができます。
</p>
<p><strong>例:</strong></p>
<code>// いくつかのカスタム設定でSWFUploadを初期化
var swfu = new SWFUpload({
custom_settings : {
custom_setting_1 : "custom_setting_value_1",
custom_setting_2 : "custom_setting_value_2",
custom_setting_n : "custom_setting_value_n",
}
});
swfu.customSettings.custom_setting_1 = "custom_setting_value_1"; // Change an existing custom setting
swfu.customSettings.myNewCustomSetting = "new custom setting value"; // Add a new custom setting
// Overwrite the customSettings with a completely new object
swfu.customSettings = {
custom_setting_A : "custom_setting_value_A",
custom_setting_B : "custom_setting_value_B"
};
</code>
<p>そして、customSettingsオブジェクトはイベントハンドラー内で簡単にアクセスすることができます:</p>
<code>
function uploadSuccess(file, serverData, receivedResponse) {
if (this.customSettings.custom_setting_A === true) {
alert("Checked the custom setting!");
}
}
</code>
<h4><a name="movieName"></a>movieName</h4>
<p>SWFUploadインスタンスの固有のムービー名が格納されています。この値はFlashへ渡されて、FlashからJavaScriptへのやりとりを手助けするために使用されます。SWFUpload.instancesの配列内のインスタンスをインデックス化するためにも使用されます。movieNameの値を変更するべきではありません。</p>
<h3><a name="methods"></a>メソッド</h3>
<p>次に示すメソッドはSWFUploadを操作するために使用されます。DOM要素のクリックイベントハンドラーに対応しているメソッドもあれば、SWFUploadイベントハンドラー内で使用されるメソッドもあります。</p>
<h4><a name="addSetting"></a>object addSetting(<span class="parameter">setting_name</span>, <span class="parameter">value</span>, <span class="parameter">default_value</span>)</h4>
<p><strong>非推奨</strong> addSetting関数は設定値の設定します。値が定義されていない場合はdefault_valueが使用されます。初期化時にSWFUploadがこの関数を使用します。設定値を更新するためにaddSettingを使ってもFlashコントロール内の設定値は変更されません。</p>
<p>addSettingは設定内に格納された値を返します。</p>
<h4><a name="getSetting"></a>object getSetting(<span class="parameter">setting_name</span>)</h4>
<p><strong>非推奨</strong> getSetting関数は設定値を取得します。指定した設定が存在しない場合は空の文字列を返します。</p>
<h4><a name="retrieveSetting"></a>object retrieveSetting(<span class="parameter">setting_value</span>, <span class="parameter">default_value</span>)</h4>
<p><strong>バージョン2.1.0で削除</strong> retrieveSetting関数は内部の設定オブジェクトを変更しないという点以外ではaddSetting関数と似ています。retrieveSettingはsetting_valueを返します。設定値が定義されていない場合はdefault_valueを返します。</p>
<p>これはユーティリティ関数です。</p>
<h4><a name="destroy"></a>bool destroy()</h4>
<p><strong>バージョン2.1.0で追加</strong></p>
<p>SWFUploadのDOM要素を削除してSWFUpload内部の参照を破棄します。ページからSWFUploadのインスタンスを削除するために使用します。IEでのメモリリークを防ぐことも行います。</p>
<p>要素が無事に削除された場合にはtrueを返します。SWFUploadのインスタンスを不安定な状態にしてエラーが発生した場合にはfalseを返します。</p>
<h4><a name="displayDebugInfo"></a>void displayDebugInfo()</h4>
<p>displayDebugInfoはdebugイベントを利用してSWFUploadの設定を出力します。この関数はdebug設定が’true’の時、初期化の後に自動的に呼び出されます。</p>
<h4><a name="selectFile"></a>void selectFile()</h4>
<p><strong>非推奨。Flashプレーヤー10非互換</strong></p>
<p>selectFileはFlashコントロールにファイル選択ダイアログウィンドウを表示させます。単一のファイルをダイアログウィンドウから選択することができます。</p>
<p>selectFileを呼ぶことで一連のファイル関連のイベントが発生します。</p>
<h4><a name="selectFiles"></a>void selectFiles()</h4>
<p><strong>非推奨。Flashプレーヤー10非互換</strong></p>
<p>selectFilesはFlashコントロールにファイル選択ダイアログウィンドウを表示させます。複数のファイルをダイアログウィンドウから選択することができます。</p>
<p>selectFilesを呼ぶことで一連のファイル関連のイベントが発生します。</p>
<h4><a name="startUpload"></a>void startUpload(<span class="parameter">file_id</span>)</h4>
<p>startUploadはfile_idパラメータで指定したファイルのアップロード処理を開始します。もし、file_idパラメータが省略された場合やundefinedの場合は、キューの中の最初のファイルがアップロードされます。</p>
<p>startUploadを呼ぶことで一連のアップロード関連のイベントが発生します。</p>
<h4><a name="cancelUpload"></a>void cancelUpload(<span class="parameter">file_id</span>, <span class="parameter">trigger_error_event</span>)</h4>
<p>cancelUploadはfile_idで指定したファイルをキャンセルします。そのファイルはキューから取り除かれます。</p>
<p>file_idパラメータが省略された場合やundefinedの場合はキューの中の最初のファイルがキャンセルされます。</p>
<p>trigger_error_eventは任意のパラメータです。falseを指定すれば、uploadErrorイベントは発生しません。</p>
<h4><a name="stopUpload"></a>void stopUpload()</h4>
<p>stopUploadはアップロード中のファイルを停止して再びキューに入れます。</p>
<p>アップロード中のファイルを停止した後にはuploadErrorイベントが発生します。ファイルがアップロードされていない時には、何も起こらず、イベントは発生しません。</p>
<h4><a name="getStats"></a>object getStats()</h4>
<p>Statsオブジェクトを取り出します。</p>
<h4><a name="setStats"></a>void setStats(<span class="parameter">stats_object</span>)</h4>
<p>Statsオブジェクトは変更することができます。アップロードが完了した後に成功したアップロード数や失敗したアップロード数を変更したい場合に便利です。</p>
<h4><a name="getFile"></a>object getFile(<span class="parameter">file_id</span>|<span class="parameter">index</span>)</h4>
<p>getFileはキューからFileオブジェクトを取り出すために使用します。(Fileオブジェクトのidプロパティ)file_idや(Fileオブジェクトのindexプロパティ)ファイルインデックスを渡すことによってFileオブジェクトを取り出します。</p>
<p>file_idを指定して取得するFileオブジェクトはキューに格納されているファイルのみです。ファイルが満kらないばあいはnullが返ります。</p>
<p>indexを指定して取得するFileオブジェクトはあらゆるキュー(キューエラーを発生させていても)に格納されています。もしindexが範囲外の場合にはnullが返ります。</p>
<h4><a name="addPostParam"></a>void addPostParam(<span class="parameter">name</span>, <span class="parameter">value</span>)</h4>
<p>addPostParamはファイルがアップロードされる時の全てのPOSTで送信される名前と値のペアを追加します。</p>
<p>名前と値のペアはpost_params設定にも追加されます。</p>
<h4><a name="removePostParam"></a>void removePostParam(<span class="parameter">name</span>)</h4>
<p>removePostParamはファイルがアップロードされる時の全てのPOSTで送信される値と名前のペアを削除します。</p>
<p>名前と値のペアはpost_params設定からも削除されます。</p>
<h4><a name="addFileParam"></a>bool addFileParam(<span class="parameter">file_id</span>, <span class="parameter">name</span>, <span class="parameter">value</span>)</h4>
<p>addFileParamはfile_idで指定されたファイルでのPOSTで送信される名前と値のペアを追加します。</p>
<p>名前と値のペアは追加したファイルと共に送信されますだけです。全てのアップロードで名前と値のペアはpost_param設定を使用します。</p>
<h4><a name="removeFileParam"></a>bool removeFileParam(<span class="parameter">file_id</span>, <span class="parameter">name</span>)</h4>
<p>removeFileParamはアップロードファイルからaddFileParamを使って追加された名前と値のペアを削除します。</p>
<p>名前と値のペアがない場合は、’false’を返します。</p>
<h4><a name="setUploadURL"></a>void setUploadURL(<span class="parameter">url</span>)</h4>
<p>動的にupload_url設定を変更します。</p>
<h4><a name="setPostParams"></a>void setPostParams(<span class="parameter">param_object</span>)</h4>
<p>動的にpost_param設定を変更します。以前の値は上書きされます。param_objectは単純なJavaScriptオブジェクトである必要があります。全ての名前と値は文字列である必要があります。</p>
<h4><a name="setFileTypes"></a>void setFileTypes(<span class="parameter">types</span>, <span class="parameter">description</span>)</h4>
<p>動的にfile_typesとfile_types_description設定を変更します。両方のパラメータは必須となります。</p>
<h4><a name="setFileSizeLimit"></a>void setFileSizeLimit(<span class="parameter">file_size_limit</span>)</h4>
<p>動的にfile_size_limit設定を変更します。この変更はキューにある全てのファイルに適用されます。file_size_limitパラメータは単位を受け入れます。有効な単位は、B、KB、MB、そして、GBです。デフォルトの単位はKBです。</p>
<p>例: 2147483648 B, 2097152, 2097152KB, 2048 MB, 2 GB</p>
<h4><a name="setFileUploadLimit"></a>void setFileUploadLimit(<span class="parameter">file_upload_limit</span>)</h4>
<p>動的にfile_upload_limit設定を変更します。0は特別な値で制限なしを意味します。</p>
<h4><a name="setFileQueueLimit"></a>void setFileQueueLimit(<span class="parameter">file_queue_limit</span>)</h4>
<p>動的にfile_queue_limit設定を変更します。0は特別な値で制限なしを意味します。</p>
<h4><a name="setFilePostName"></a>void setFilePostName(<span class="parameter">file_post_name</span>)</h4>
<p>動的にfile_post_name設定を変更します。LinuxのFlashプレーヤーはこの設定を無視します。</p>
<h4><a name="setUseQueryString"></a>void setUseQueryString(<span class="parameter">use_query_string</span>)</h4>
<p>動的にuse_query_string設定を変更します。trueの時はSWFUploadにPOSTデータとしてではなくクエリー文字列としてPOSTパラメータを送ることを強制します。use_query_stringはtrueかfalseのいずれかである必要があります。</p>
<h4><a name="setDebugEnabled"></a>void setDebugEnabled(<span class="parameter">debug_enabled</span>)</h4>
<p>動的にdebug出力を可能に不可能にします。debug_enabledパラメータはtrueかfalseのいずれかである必要があります。</p>
<h4><a name="setButtonImageURL"></a>void setButtonImageURL(<span class="parameter">url</span>)</h4>
<p>動的にFlashボタンで使用される画像を変更します。画像のURLはswfupload.swfファイルから相対的か、絶対パス(例えば、/で始まる)、または、完全修飾URL(例えば、http://www.swfupload.org/buttonImage.png)のいずれかでなければなりません。Flashでサポートされる全ての画像形式をロードすることができます。もっとも有名は形式は、jpg、gif、そして、pngです。</p>
<p>ボタン画像はボタンスプライト(もしくは、いくつかの画像を重なりあわせた単一の画像ファイル)であることを見込まれます。画像は必要な部分を表示するだけのために画像を上かしたかに移動することで全てのボタンの状態を描画するために使用されます。ボタンの状態としては、通常の時、マウスが上に来た時、クリックされた時、無効時になります。サンプルのボタン画像を参照して下さい。</p>
<h4><a name="setButtonDimensions"></a>void setButtonDimensions(<span class="parameter">width</span>, <span class="parameter">height</span>)</h4>
<p>動的にFlashボタンの幅と高さを変更します。値は数値である必要があり、単位は含まれてはなりません。ボタン状態のスプライト画像を正しく表示するために高さの値はボタン画像の高さの4分の1までになります。</p>
<h4><a name="setButtonText"></a>void setButtonText(<span class="parameter">text</span>)</h4>
<p>Flashボタン上に描画するテキストを指定します。長すぎてボタンの大きさからはみ出すようなテキストは切り取られます。</p>
<p>テキストはFlashプレーヤーのHTMLサポート(<a target=”_blank” href=”http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/text/TextField.html#htmlText”>Adobe文書</a>)でスタイル付けすることができます。</p>
<h4><a name="setButtonTextStyle"></a>void setButtonTextStyle(<span class="parameter">css_style_text</span>)</h4>
<p>Flashボタン上のテキストをスタイル付けするために使用するCSSスタイルを指定します。CSSはFlashプレーヤー文書(<a target="_blank" href="http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/text/StyleSheet.html">Adobe文書</a>)に記載されている内容に従う必要があります。</p>
<p>ここで定義されたスタイルクラスはbutton_text設定のHTMLによって参照されます。</p>
<h4><a name="setButtonTextPadding"></a>void setButtonTextPadding(<span class="parameter">left</span>, <span class="parameter">top</span>)</h4>
<p>Flashボタン上のテキストの上と左のパディングを指定します。値は負の値も受け付けます。</p>
<h4><a name="setButtonDisabled"></a>void setButtonDisabled(<span class="parameter">isDisabled</span>)</h4>
<p>’true’の場合はFlashボタンの状態は無効になり全てのクリックを無視します。</p>
<h4><a name="setButtonAction"></a>void setButtonAction(<span class="parameter">buttonAction</span>)</h4>
<p>Flashボタンがクリックされた時の実行するアクションを指定します。有効なアクションの値はBUTTON_ACTION定数からの値です。</p>
<h4><a name="setButtonCursor"></a>void setButtonCursor(<span class="parameter">buttonCursor</span>)</h4>
<p>Flashボタンの上にあるときのマウスカーソルを指定します。有効な値はCURSOR定数からの値です。</p>
<h3><a name="events"></a>イベント</h3>
<p>SWFUploadはその動作中に様々なイベントを発生させます。これらのイベントはUIを更新したり、振る舞いを変更したり、エラーを報告したりするために開発者が処理することができます。</p>
<p>全てのSWFUploadでのイベントはSWFUploadのインスタンスのコンテキストで呼び出されます。’this’オブジェクトが、イベントを発生させたSWFUploadのインスタンスを参照しているという意味になります。</P
<p>SWFUploadのイベントは、オブジェクト初期渦中にイベントハンドラー関数をSettingsオブジェクトに与えることでのみ設定される必要があります。SWFUpload.prototypeオブジェクトに属する内部関数をオーバーライドするべきではありません。</p>
<p>ファイルアップロード中にイベントでは以下の順序で呼び出されます(アップロードイベントチェーン):</p>
<ul>
<li>uploadStart</li>
<li>uploadProgress (ファイルがアップロードされるにつれて何回も呼び出されます)</li>
<li>uploadError (何らかのエラーが発生した時やファイルがキャンセルや中止の時に呼び出されます)</li>
<li>uploadSuccess (無事にアップロードが終了した時、サーバーから返ってきたデータが入手可能である時)</li>
<li>uploadComplete (アップロードが完了してSWFUploadが次のファイルの開始する準備ができている時)</li>
</ul>
<h4><a name="flashReady"></a><span class="function">flashReady()</span></h4>
<p>flashReadyはオーバーライドすべきではない内部イベントです。Flashムービーのロードが完了してコマンドを受け入れる準備ができたことをSWFUploadに通知するためにFlashコントロールによって呼び出されます。</p>
<h4><a name="swfUploadLoaded"></a><span class="function">swfUploadLoaded()</span></h4>
<p>swfUploadLoadedイベントはflashReadyによって発生します。設定可能です。swfUploadLoadedはSWFUploadメソッドを呼び出すことが可能であることを知らせるために呼び出されます。</p>
<h4><a name="fileDialogStart"></a><span class="function">fileDialogStart(<span class="parameter"></span>)</span></h4>
<p>fileDialogStartはselectFilesが呼び出されるためのるselectFileの後に発生します。このイベントはファイル選択ダイアログが表示される直前に発生します。しかしながら、イベントはダイアログウィンドウが閉じられるまで実行されないかもしれません。</p>
<h4><a name="fileQueued"></a><span class="function">fileQueued(<span class="parameter">file object</span>)</span></h4>
<p>fileQueuedイベントはファイル選択ダイアログウィンドウが閉じられた後、キューに入ったファイル毎に発生します。</p>
<h4><a name="fileQueueError"></a><span class="function">fileQueueError(<span class="parameter">file object</span>, <span class="parameter">error code</span>, <span class="parameter">message</span>)</span></h4>
<p>fileQueueErrorイベントはファイル選択ダイアログウィンドウが閉じられた後、キューに入らなかったファイル毎に発生します。ファイルサイズが制限を超えている、ファイルが空である、ファイルやキューの制限がこえているなどのいくつかの理由でファイルはキューに入らないことがあります。</p>
<p>キューエラーの理由はエラーコードパラメータによって明記されています。</p>
<h4><a name="fileDialogComplete"></a><span class="function">fileDialogComplete(<span class="parameter">number of files selected</span>, <span class="parameter">number of files queued</span>, <span class="parameter">total number of files in the queued</span>)</span></h4>
<p>fileDialogCompleteイベントはファイル選択ダイアログウィンドウが閉じられてキュー内にある全てのファイルが処理された後に発生します。’number of files queued’引数は、(キュー内のファイルの数とは対照的に)ダイアログでの選択からキューに入ったファイルの数を示します。</p>
<p>ファイルアップロードを自動的に開始したい場合には、このイベントは、’this.startUpload()’を呼び出す格好の場所です。</p>
<h4><a name="uploadStart"></a><span class="function">uploadStart(<span class="parameter">file object</span>)</span></h4>
<p>uploadStartはファイルがアップロードされる直前に呼び出されます。このイベントは、最終検証、POSTパラメータの追加、あるいは、他のファイルがアップロードされる前にすることを行うための機会を提供します。</p>
<p>アップロードはuploadStartから’false’を返すことでキャンセルすることができます。’true’を返したり、値を返さない場合には、アップロードは実施されます。’false’を返すとuploadErrorイベントが発生します。</p>
<h4><a name="uploadProgress"></a><span class="function">uploadProgress(<span class="parameter">file object</span>, <span class="parameter">bytes complete</span>, <span class="parameter">total bytes</span>)</span></h4>
<p>uploadProgressイベントはFlashコントロールによって定期的に発生します。このイベントはページ上のUIの更新を提供するのに便利です。</p>
<p><strong>注意:</strong> LinuxのFlashプレーヤーは、ファイルのアップロードされたら、1回のuploadProgressイベントを発生されます。これは、回避策がないLinuxのFlashプレーヤーのバグです。</p>
<h4><a name="uploadError"></a><span class="function">uploadError(<span class="parameter">file object</span>, <span class="parameter">error code</span>, <span class="parameter">message</span>)</span></h4>
<p>uploadErrorイベントはアップロードが中止された場合や無事に成功しなかった場合にいつでも発生します。エラーコードパラメータは発生したエラーの型を示します。エラーコードはSWFUpload.UPLOAD_ERRORに定数として定めています。</p>
<p>停止、中止、または、uploadStartから’false’を返す事で、uploadErrorの発生の原因となります。キューの中で待っているファイルがアップロード中止となった場合はこのイベントは発生しません。</p>
<h4><a name="uploadSuccess"></a><span class="function">uploadSuccess(<span class="parameter">file object</span>, <span class="parameter">server data</span>, <span class="parameter">received response</span>)</span></h4>
<p>全てのアップロードファイルの転送が完了してサーバーがHTTP200ステータスを返した時にuploadSuccessが発生します。サーバーによって出力されたデータはserver dataパラメータにて利用できます。</p>
<p>Flashプレーヤーの不具合のために、サーバーのレスポンスが認識されない場合があり、Flashによって、uploadSuccessイベントが発生しない場合があります。この場合、assume_success_timeout設定により、uploadSuccessイベントを発生されるのに十分な時間が経過したかをチェックします。この時、received responseパラメータはfalseになります。</p>
<p>http_success設定は、HTTP200以外のHTTPステータスコードでuploadSuccessが発生するようにできます。この場合、Flashプレーヤーはサーバーからのデータは利用することはできません。</p>
<p>この時点ではアップロードは、まだ、完了していません。uploadSuccessから他のアップロードは開始しません</p>
<h4><a name="uploadComplete"></a><span class="function">uploadComplete(<span class="parameter">file object</span>)</span></h4>
<p>uploadCompleteは、(uploadErrorかuploadSuccessが発生した後の)アップロードサイクルの最後にいつも発生します。この時点でアップロードは完了しており他のアップロードが開始します。</p>
<p>もし次のアップロードを自動的に開始したいのであれば、ここがthis.uploadStart()を呼び出す絶好の場所です。もしキューの中の全てのアップロード待ちのファイルを中止するコードがある場合には、uploadCompleteイベントの中でuploadStartを呼び出す際には注意して下さい。</p>
<h4><a name="debug"></a><span class="function">debug(<span class="parameter">message</span>)</span></h4>
<p>debug設定が’true’の時にdebugイベントはSWFUploadライブラリとFlashコントロールによって呼び出されます。もし、debugイベントがオーバーライドされていない場合、SWFUploadはデバッグメッセージをSWFUploadコンソール(ページボディの最後に動的に追加されるテキストボックス)に書き出します。</p>
<h3><a name="utility"></a>SWFUploadユーティリティオブジェクト</h3>
<h4><a name="settingsobject"></a>Settingsオブジェクト</h4>
<p>SettingsオブジェクトはSWFUploadインスタンスに設定を提供するJavaScriptオブジェクトです。<strong>それぞれの設定は一度だけ現れる必要があります。</strong>多くの設定は任意であり、省略すると適切なデフォルトの値が設定されます。必須と任意の設定値については設定の説明を参照して下さい。</p>
<p><strong>設定例:</strong></p>
<code>{
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload.swf",
file_post_name : "Filedata",
post_params : {
"post_param_name_1" : "post_param_value_1",
"post_param_name_2" : "post_param_value_2",
"post_param_name_n" : "post_param_value_n"
},
use_query_string : false,
requeue_on_error : false,
http_success : [201, 202],
assume_success_timeout : 0,
file_types : "*.jpg;*.gif",
file_types_description: "Web Image Files",
file_size_limit : "1024",
file_upload_limit : 10,
file_queue_limit : 2,
debug : false,
prevent_swf_caching : false,
preserve_relative_urls : false,
button_placeholder_id : "element_id",
button_image_url : "http://www.swfupload.org/button_sprite.png",
button_width : 61,
button_height : 22,
button_text : "&lt;b&gt;Click&lt;/b&gt; &lt;span class="redText"&gt;here&lt;/span&gt;",
button_text_style : ".redText { color: #FF0000; }",
button_text_left_padding : 3,
button_text_top_padding : 2,
button_action : SWFUpload.BUTTON_ACTION.SELECT_FILES,
button_disabled : false,
button_cursor : SWFUpload.CURSOR.HAND,
button_window_mode : SWFUpload.WINDOW_MODE.TRANSPARENT,
swfupload_loaded_handler : swfupload_loaded_function,
file_dialog_start_handler : file_dialog_start_function,
file_queued_handler : file_queued_function,
file_queue_error_handler : file_queue_error_function,
file_dialog_complete_handler : file_dialog_complete_function,
upload_start_handler : upload_start_function,
upload_progress_handler : upload_progress_function,
upload_error_handler : upload_error_function,
upload_success_handler : upload_success_function,
upload_complete_handler : upload_complete_function,
debug_handler : debug_function,
custom_settings : {
custom_setting_1 : "custom_setting_value_1",
custom_setting_2 : "custom_setting_value_2",
custom_setting_n : "custom_setting_value_n",
}
}</code>
<h4><a name="settingsdescription"></a>設定値の説明</h4>
<h5>upload_url</h5>
<p>upload_url設定はアップロードファイルの完全、絶対、相対URLを受け入れます。相対URLは文書からの相対である必要があります。upload_urlは互換性のためにFlashコントロールと同じドメイン内にある必要があります。</p>
<p>もし、preserve_relative_urls設定がfalseであれば、SWFUploadは、異なるプラットフォームにFlashプレーヤーによる異なってURLが解釈されることを避けるために相対URLを絶対URLへ変換します。もし、SWFUploadによるURL変換を無効にするなら、相対URLはswfupload.swfファイルから相対である必要があります。</p>
<h5>file_post_name</h5>
<p>file_post_nameは、ファイルをポストするために値の名前を設定することができます。これは、ファイル名とかんけいありません。デフォルト値は'Filedata'です。最大の互換性のためにはデフォルトの値を使うことが推奨されます。</p>
<h5>post_params</h5>
<p>post_params設定はそれぞれのアップロードされるファイルと共にポストされる名前/値のペアを定義します。この設定は単純なJavaScriptオブジェクトを受け入れます。複数のPOSTでの名前/値のペアはサンプルのSettingsオブジェクトで例示されたように定義される必要があります。値は(JavaScriptのtypeof関数で解釈されるような)文字列か数字のいずれかでなければなりません。</p>
<p>注: Flashプレーヤー8は追加のPOSTパラメータの送信をサポートしていません。SWFUploadは自動的に送信します。クエリー文字列の一部としてpost_paramsを送信します。</p>
<h5>use_query_string</h5>
<p>use_query_string設定はtrueかfalseのどちらかです。SWFUploadがこの値はクエリー文字列かPOST値のどちらかとしてpost_paramとファイルパラメータを送信する必要があるかを示します。この設定はSWFUploadバージョン2.1.0で紹介されました。</p>
<h5>preserve_relative_urls</h5>
<p>SWFUploadがFlashプレーヤーによって私用される相対URLを絶対URLに変換するかどうかを示すブーリアン値。trueに設定されれば、SWFUploadはURLを変換しません。デフォルト値はfalseです。</p>
<h5>requeue_on_error</h5>
<p>requeue_on_error設定はtrueかfalseです。この設定がtrueの時、(fileQueueエラーとFILE_CANCELLEDで発生したuploadErrorを除く)uploadErrorがあったファイルを放棄するのではなくキューの先頭に戻します。ファイルは必要であれば再びアップロードすることができます。キューからファイルを削除するにはcancelUploadメソッドを呼び出さなければなりません。</p>
<p>失敗したアップロードに関連するイベントの全ては呼び出されます。そのため、失敗したアップロードファイルを再びキューに入れることはQueueプラグイン(もしくは、キュー全体をアップロードするカスタムコード)と衝突する可能性があります。自動的にキュー内の次のファイルをアップロードするコードは、失敗したアップロードをキャンセルするようにしなければ、何回も失敗したファイルをアップロードします。</p>
<p>この設定はSWFUploadバージョン2.1.0で導入されました。</p>
<h5>http_success</h5>
<p>成功となるHTTPステータスコードを定義する配列。200は常に成功です。また、200のステータスコードだけserverDataを提供します。</p>
<p>200以外のHTTPステータスコードを返して受け入れる場合は、サーバはコンテンツを返す必要はありません。</p>
<h5>assume_success_timeout</h5>
<p>ファイルのアップロードが完了してからFlashがサーバーのレスポンスを認識するのをSWFUploadが待つ秒数。この設定で長時間実行するサーバー再度のスクリプトによってFlashがサーバーからのレスポンスを無視したりMacのFlashプレーヤーのバグでコンテンツのないサーバーのレスポンスを無視するといったFlashプレーヤーの不具合を回避することができます。</p>
<p>Flashは最後のuploadProgressイベントの後、30秒以上かかるサーバーのレスポンスを無視するというテスト結果が出ています</p>
<p>零(0)秒のタイムアウトはこの機能を無効します。これはデフォルトの値です。SWFUploadはFlashプレーヤーがuploadSucessイベントを発生されるまでいつまでも待ちます。</p>
<h5>file_types</h5>
<p>file_types設定はユーザーが選択することのできるファイル拡張子をセミコロンで分けた一覧を受け入れます。全てのファイルタイプを許可するには'*.*'を使います。</p>
<h5>file_types_description</h5>
<p>ファイルブラウザダイアログでユーザーに表示する説明テキストです。</p>
<h5>file_size_limit</h5>
<p>file_size_limit設定はアップロードするファイルの最大のサイズを定義します。この設定は値と単位を受け入れます。有効な単位は、B、KB、MB、そして、GBです。単位が省略された場合のデフォルトはKBです。零(0)の値は無制限を意味します。</p>
<p>注: この設定はユーザーのブラウザにのみ適用されます。ウェブサーバーの設定や制限には影響しません。</p>
<h5>file_upload_limit</h5>
<p>SWFUploadによってアップロードできるファイル数を定義します。この設定はfile_queue_limit設定の上限も設定します。一度、ユーザーがファイル数の上限までアップロード、もしくは、キューに入れたなら、追加のファイルをキューに入れることはできません。零(0)は無制限になります。成功したアップロード(uploadSucessイベントを発生させたアップロード)だけがアップロード制限数に数えられます。setStats関数は成功したアップロードの数を変更するために使用することができます。</p>
<p>注: この値はページをまたいでは保持されません。ページが再読込される時はリセットされます。ファイル容量はウェブサーバーによって管理する必要があります。</P>
<h5>file_queue_limit</h5>
<p>同時にキューに入ることができる未処理のファイル数を定義します。ファイルがアップロード、エラー、キャンセルされるとキューの制限に達するまで新しいファイルがキューに入ります。アップロードの制限(もしくは、残りのアップロード)がキューの制限より小さい場合は、少ない方の数が適用されます。</p>
<h5>flash_url</h5>
<p>Flashコントロールswfファイルへの完全、絶対、もしくは、相対URL。この設定は一旦、SWFUploadがインスタンス化されたら変更することができません。相対URLはページのURLから相対となります。</p>
<h5>flash_width</h5>
<p><strong>(バージョン2.1.0で削除)</strong> Flashを含むHTML要素の幅を定義します。この設定が1px未満の場合には正しく動作しないブラウザがあります。この設定は任意で1pxがデフォルト値です。</p>
<h5>flash_height</h5>
<p><strong>(バージョン2.1.0で削除)</strong> Flashを含むHTML要素の高さを定義します。この設定が1px未満の場合には正しく動作しないブラウザがあります。この設定は任意で1pxがデフォルト値です。</p>
<h5>flash_color</h5>
<p><strong>(バージョン2.2.0で削除)</strong> この設定はFlashを含むHTML要素の背景色を定義します。デフォルト値は、'#FFFFFF'です。</p>
<p>注: この設定は全てのブラウザにおいて、"最小の"1pxのFlash要素の場合では、効果がないかもしれません。</p>
<h5>prevent_swf_caching</h5>
<p><strong>(バージョン2.2.0で追加)</strong> このブーリアン設定はブラウザがSWF動画をキャッシュしないようにランダムな値がFlashのURLに付与されるかどうかを示します。この設定はIEのレンダリングエンジンを使ったブラウザの不具合を回避します。</p>
<p>注: ランダムな数字をURLに付与するアルゴリズムは単純でパラメータがあるURLを正しく扱うことができません。</p>
<h5>debug</h5>
<p>デバッグのイベントハンドラが実行されるかどうかを定義するブーリアン値。</p>
<h5>button_placeholder_id</h5>
<p><strong>(バージョン2.2.0で追加)</strong> この必須の設定は、Flashボタンにより<em>置き換えられる</em>DOM要素のIDを設定します。この設定はbutton_placeholder設定を上書きします。FlashボタンはCSSクラス'swfupload'を使ってスタイル付けをすることができます。</p>
<h5>button_placeholder</h5>
<p><strong>(バージョン2.2.0で追加)</strong> この必須の設定は、Flashボタンによって<em>置き換えられる</em>DOM要素を設定します。この設定は、button_placeholder_idが設定されていないときのみに適用されます。FlashボタンはCSSクラス'swfupload'を使ってスタイル付けをすることができます。</p>
<h5>button_image_url</h5>
<p><strong>(バージョン2.2.0で追加)</strong> Flashボタンに使用される画像ファイルへの完全、絶対、もしくは、相対URL。Flashがサポートしている画像ファイル形式(他のFlashファイルや、gif、jpg、もしくは、png)を使用することができます。</p>
<p>このURLは、preserve_relative_urls設定によって影響されます。そして、upload_url設定と同じルールに従います。</p>
<p>ボタン画像はスプライトとして扱われます。ボタン画像によって描かれる必要がある4つのボタン状態があります。それぞれのボタンの状態画像は次の順序で積み重ねられます: normal、hover、down/click、disabled</p>
<h5>button_width</h5>
<p><strong>(バージョン2.2.0で追加)</strong> Flashボタンの幅を定義する数値。</p>
<h5>button_height</h5>
<p><strong>(バージョン2.2.0で追加)</strong> Flashボタンの高さを定義する数値。この値はボタン画像の高さの4分の1である必要があります。</p>
<h5>button_text</h5>
<p><strong>(バージョン2.2.0で追加)</strong> Flashボタン上に描画されるプレーンかHTMLテキスト。HTMLテキストにCSSクラスを使ってさらなるスタイル付けを行うことができます。詳細については、<a target="_blank" href="http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/text/TextField.html#htmlText">Adobe社のFlash仕様書</a>を読んで下さい。</p>
<h5>button_text_style</h5>
<p><strong>(バージョン2.2.0で追加)</strong> button_textがどのように表示されるかを定義するCSSスタイル文字列。詳細については、<a target="_blank" href="http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/flash/text/StyleSheet.html">Adobe社のFlash仕様書</a>を読んで下さい。</p>
<h5>button_text_top_padding</h5>
<p><strong>(バージョン2.2.0で追加)</strong> Flashボタンの文字を垂直方向に配置するために使用されます。負の値を使用することができます。</p>
<h5>button_text_left_padding</h5>
<p><strong>(バージョン2.2.0で追加)</strong> Flashボタンの文字を水平方向に配置するために使用されます。負の値を使用することができます。</p>
<h5>button_action</h5>
<p><strong>(バージョン2.2.0で追加)</strong> Flashボタンがクリックされた時に実行するアクションを定義します。swfupload.js内のBUTTON_ACTIONオブジェクトに有効なアクションの値が定義されています。</p>
<h5>button_disabled</h5>
<p><strong>(バージョン2.2.0で追加)</strong> Flashボタンを使用不可状態にするかどうかを設定するブーリアン値。使用不可状態の時、ボタンはいかなるアクションも実行しません。</p>
<h5>button_cursor</h5>
<p><strong>(バージョン2.2.0で追加)</strong> マウスカーソルがFlashボタン上にある時の形状を定義するために使用されます。</p>
<h5>button_window_mode</h5>
<p><strong>(バージョン2.2.0で追加)</strong> Flash動画のWMODEプロパティ定義します。有効な値はSWFUpload.WINDOW_MODE定数内に定義されています。</p>
<h5>custom_settings</h5>
<p>custom_settings設定を使うことで開発者はSWFUploadインスタンスに追加情報をSWFUploadの内部値や新しいバージョンのSWFUploadでの変更に心配することなく安全に加えることができます。この設定はJavaScriptオブジェクトを受け入れます。</p>
<p>インスタンス化されたcustom_settingsはSWFUploadのインスタンスの'customSettings'プロパティを通じてアクセスされます。</p>
<code>var swfu = new SWFUpload({
custom_settings : {
"My Setting" : "This is my setting",
myothersetting : "This is my other setting",
integer_setting : 100,
a_dom_setting : document.getElementById("some_element_id")
}
});
var my_setting = swfu.customSettings["My Setting"]);
swfu.customSettings["My Setting"] = "This is my new setting";
swfu.customSetting.myothersetting = "another new value";
swfu.customSetting.integer_setting += 25;
swfu.customSetting["a_dom_setting"].style.visibility = "hidden";</code>
<h5>イベントハンドル</h5>
<p>残りの設定はSWFUploadが動作している間に発生するイベントハンドラを定義します。これらのイベントの処理が必要なときにJavaScript関数を定義します。</p>
<h4><a name="fileobject"></a>Fileオブジェクト</h4>
<p>The file object is passed to several event handlers. It contains information about the file. Some operating systems do not fill in all the values (this
is especially true for the createdate and modificationdate values).</p>
<code>{
id : string, // SWFUpload file id, used for starting or cancelling and upload
index : number, // The index of this file for use in getFile(i)
name : string, // The file name. The path is not included.
size : number, // The file size in bytes
type : string, // The file type as reported by the client operating system
creationdate : Date, // The date the file was created
modificationdate : Date, // The date the file was last modified
filestatus : number, // The file's current status. Use SWFUpload.FILE_STATUS to interpret the value.
}</code>
<h4><a name="statsobject"></a>Stats Object</h4>
<p>The Stats object provides information about the upload queue.</p>
<p>That stats object contains the following properties:</p>
<code>{
in_progress : number // 1 or 0 indicating if a file upload is currently in progress
files_queued : number // The number of files currently in the queue
successful_uploads : number // The number of files that have uploaded successfully (caused uploadSuccess to be fired)
upload_errors : number // The number of files that have had errors (excluding cancelled files)
upload_cancelled : number // The number of files that have been cancelled
queue_errors : number // The number of files that caused fileQueueError to be fired
}</code>
<p>All these values can be updated using setStats() except the <em>in_progress</em> and <em>files_queued</em> values.</p>
<h2><a name="plugins"></a>SWFUpload Plug-ins</h2>
<p>With SWFUpload v2.0 several plugins have been introduced. They are provided to help with common tasks associated with implementing SWFUpload.</p>
<p>Currently most of the documentation for using the plugins is contained in the plugin JavaScript file.</p>
<h3>SWFObject</h3>
<p>
The SWFObject plugin uses the <a href="http://code.google.com/p/swfobject/">SWFObject library</a> to handle the embedding
of the SWFUpload Flash Component into the page.
</p>
<p>
This plugin also provides support for Document Ready loading and Flash Version Detection. Usage details are documented
in the plugin file itself. You should not use the SWFObject's Document Ready loading mixed with another libraries DOMReady. Use
one or the other but not both.
</p>
<p><strong>Flash Player 10: </strong> Because Flash Player 10 requires the SWFUpload swf to act is a button the movie must be visible in order
for it to load. If the button_placeholder_id is set to an element that is hidden (visibility set to hidden or display set to none) SWFUpload will
fail to load.</p>
<h3>Cookies</h3>
<p>In response to the Flash Cookie Bug the Cookies Plugin automatically retrieves your browser's cookies and sends them
with the upload. The are sent as POST or GET variables to the upload url.</p>
<p>Note that this plugin sends the cookies name/values in the POST or GET. On the server side they will not be accessible as cookies. Some frameworks that
automatically check cookies for session or authentication values still will not be able to find the values.</p>
<h3>Queue Handling</h3>
<p>This plugin provides Queue Handling features such as entire queue uploading, entire queue cancelling and automatic starting of uploads after being queued.</p>
<h3>Speed</h3>
<p>This Plugin extends the 'file' object with several properties that describe the current upload. This includes current speed, average speed, elapsed time, remaining time and more.</p>
<h2><a name="knownissues"></a>Known Issues</h2>
<p>The Flash Player and many Browsers have bugs that have a direct impact on the performance of SWFUpload. While we have worked
hard to get around many issues but there are some things that we cannot fix.</p>
<h3>Cancelling in Linux</h3>
<p>Older Flash 9 Players for Linux cause the browser to crash if an upload is cancelled. Newer Flash 9 Players behave better.</p>
<h3>Upload Progress in Linux</h3>
<p>The Flash Player in Linux sends a single uploadProgress event after the file has finished uploading.</p>
<p>In some distributions the entire browser locks up while the upload is in progress.</p>
<h3>Upload Progress in OS X</h3>
<p>There have been some reports that uploadProgress events are not fired in MAC Flash Players. The specifics haven't been pinned down but be aware of the possible issue.</p>
<h3>MIME Type</h3>
<p>The Flash Player uploads all files with a mime type of <em>application/octet-stream</em> regardless of the file's actual mime type.</p>
<h3>Maximum number of selected files</h3>
<p>The Flash Player does not impose a maximum number of selected files. However, it builds a selected files string which does have a maximum length.
The string is built using the file's name and the separator [quote][space][quote]. The total number of files selected is determined by the sum
of the lengths of the file names and a prefixed and postfixed [quote] character (2 characters) and the number of files selected minus one times 3 (for the separator string)</p>
<p>This limitation may vary from system to system. If a use selects too many files they will be receive a Flash Player generated warning message and will
be left at the File Selection Dialog.</p>
<h3>Proxies</h3>
<p>The Flash Player may not properly use proxies. It does not handle authenticating proxies well (if at all) and will some-times crash.</p>
<p>Some anti-virus software uses a proxy to scan uploads and cause SWFUpload to believe the entire file has been uploaded. SWFUpload will fire uploadProgress events very quickly
until it reaches 100% and will then seem to pause until the proxy completes uploading the file to the server.</p>
<h3>Apache mod_security</h3>
<p>Apache's mod_security validates POST to the server. Flash Player has implemented an edge case (there is argument as to whether it is invalid or note)
POST for file uploads and so servers implementing
mod_security will reject the upload. mod_security can be disabled using your .htaccess file</p>
<h3>SSL</h3>
<p>There have been some reports that the Flash Player cannot upload through SSL.
The issue has not been pinned down but uploading over SSL may be unreliable. There especially seems to be an issue with
using self-signed certificates.</p>
<p>Also, SSL tickets from untrusted Certificate Authorities (CA) do not work as Flash does not provide a method for accepting the certificate. It has been noted that, like the cookie bug,
that Flash Player on Windows obtains its trusted CA list from Internet Explorer regardless of the browser in use.</p>
<h3>Authentication</h3>
<p>HTTP Authentication is not well supported by the Flash Player. Later versions of Flash Player behave better. Old version of Flash Player would crash the browser.</p>
<h3>Prematurely terminated connections</h3>
<p>Prematurely ending the response (such as a Response.end() in ASP.Net) can sometimes cause successful uploads to be reported as failed.</p>
<h3>Filedata in Linux</h3>
<p>Changing the Filedata value (file_post_name setting) is ignored in Linux Flash Players.</p>
<h3>Cookie issue</h3>
<p>On Windows the Non-IE Flash Player plugin (FireFox, Opera, Safari, etc) will send the IE cookies regardless of the browser used. This breaks authentication and sessions for many server-side scripting technologies.</p>
<p>Developers should manually pass Session and Authentication cookie information and manually restore Sessions on the Server Side if they wish to use Sessions</p>
<p>The SWFUpload package contains work-around sample code for PHP and ASP.Net</p>
<h3>ExternalInterface bugs</h3>
<p>Flash Player does not properly escape data when communication with the browser/JavaScript. SWFUpload goes to great lengths to work-around this issue. If this
bug is fixed in future Flash Players/Browsers then SWFUpload will send extra escaped data.</p>
<h3>Server Data length bugs</h3>
<p>Very long server data is corrupted on Mac and Linux Flash Players. Server data will be truncated, garbled, and/or repeated. We recommend
keeping data returned from the server short and concise.</p>
<h3>Avant Browser</h3>
<p>For some users the Avant Browser does not work with SWFUpload after the Flash Control has been cached. This has been reproduced by the
SWFUpload developers but the Avant Browser developers did not experience any problems.</p>
<p>When the page is reloaded SWFUpload loads and fires the swfupload_loaded event. However, none of the ExternalInterface callback functions are defined
on the movie element. SWFUpload v2.0.2 has added checks which prevent swfupload_loaded from firing if the callback functions are not detected.</p>
<p><strong>SWFUpload v2.2.0 added the prevent_swf_caching setting that attempts to work around this issue.</strong></p>
<h3>File Dialog &amp; Page Changing</h3>
<p>Leaving or reloading the current page while the File Browser Dialog window is open will cause the browser to crash (all browsers, all OSs). Most commonly this is caused by failing to
cancel a click event on an &lt;a&gt; tag where the onclick event calls the selectFile or selectFiles function.</p>
<h3>Long Running Upload Scripts</h3>
<p>After Flash has uploaded the file to the webserver the upload script is executed. This script handles the file whether that means saving it, creating a thumbnail, scanning for viruses, etc.
If the upload script does not return any data within 30 seconds Flash will disconnect and return an IO Error. You can prevent this by returning characters or data while
the script runs (if possible). For PHP, the script continues to run and complete successfully even though Flash has terminated the connection. Any data returned
by the script after Flash has disconnected is lost.</p>
<h3>WMODE / BUTTON_WINDOW_MODE</h3>
<p>In some browsers the selected WMODE (which is set using the BUTTON_WINDOW_MODE) can prevent the Flash Control from loading
if the control is not on screen. The control will finally load once the user scrolls the page so the control becomes visible.</p>
<p>This behavior can adversely affect the SWFObject plugin. No SWFUpload events will be fire and the button image will not be
loaded until the control becomes visible.</p>
<h3>Memory Leaks</h3>
<p>Some browsers (especially IE) cannot recover memory used by the Flash Player when JavaScript communication via the ExternalInterface classes is used (like in SWFUpload).
Creating many SWFUpload instances and/or reloading the page several times will cause the browser to consume more and more memory until it crashes or otherwise harms the
system.</p>
<p>In v2.2.0 SWFUpload we gave implemented some preventative measures. Some of these measures are pro-active but it is still recommended that you
call the destroy method when the page unloads. If you are using hundreds of SWFUpload instances on a page you should use caution and test
carefully for memory leaks.</p>
<h3>Other Mac Issues</h3>
<ul>
<li>
Users have reported that uploading to subdomains does not work with the Mac Flash Player.
</li>
<li>
Users have reported that pages that redirect (HTTP Status 302) are not handled by the Mac Flash Player. Windows
clients seem to handle this issue.
</li>
<li>
The flash documentation states that on OS early than OS X 10.3 the bytes loaded is always reported as -1. SWFUpload converts
this to 0 but the total bytes will never be sent and 100% won't be reached. The UI should be updated to display 100% complete in
uploadSuccess or uploadComplete events to maintain a consistent UI.
</li>
<li>
Some users have reported issues if there is a space character in the upload_url for the Mac Flash Player. Avoid spaces or try replacing them with + or %20.
</li>
<li>
Users have reported that the Flash Player for Mac adds the PORT to the HTTP_HOST server variable (e.g., http://www.example.com:80). If you are
checking this variable in your server-side script be aware of the possible issue.
</li>
</ul>
</body>
</html>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment