モジュールの概要と開発


※上記の広告は60日以上更新のないWIKIに表示されています。更新することで広告が下部へ移動します。

このコンテンツは
http://www.icab.de/blog/2010/02/17/modules-for-icab-mobile/
を日本語訳したものです。曖昧な訳で意味がわからない場合は元の記事を読んでください。
英語の文章と日本語訳を比較したいばあいはこちらのページをご覧ください。


2010.8.2 - autorun機能について追記
2010.8.22 - postRequest関数について追記
2011.1.2 - ローカライズに関しての未翻訳段落を翻訳してくれた方がいたので反映 Thanks!


iCab Mobileのモジュール


バージョン2.1以上のiCab Mobileにはモジュールという機能が備わっています。モジュールによってiCab Mobileは、それらをダウンロードするだけで新たな機能を追加することが可能になります。モジュールはiPhoneの小さなスクリーンでも読みやすくするためにフォントを大きくする、といったシンプルなことにも使えますし、もっと複雑な、たとえばYouTubeからビデオをダウンロードしたりウェブページのURLをTwitterでつぶやく(ログインや短縮URL作成ももちろん含む)、といったこともできます。
iCab Mobile 2.1にはいくつかのモジュールを内蔵していますし、ダウンロード可能なさまざまなモジュールが存在します。

この記事では、あなたがどのようにしてモジュールを書けばいいか、またどのようにしてインストールするかを説明しています。

技術的背景


技術的にはモジュールはブックマークレットと似ていますが、より機能的でより柔軟です。それは、モジュールはJavaScriptで書かれており、JavaScriptで可能なことはすべて可能だという意味でです。ブックマークレットと違うのは、ブックマークレットはjavascriptスキームのURLとして扱われるためにスクリプトをまるごと一行に圧縮しなければなりませんが、モジュールは複数行の見やすいフォーマットでよい点です。モジュールはモジュールのプロパティを定義する特殊なヘッダーセクションを持ちます。プロパティにはiCab Mobileのモジュールパネルに表示されるアイコンや、ユーザがiCab Mobileの設定パネルから変更することができる設定などがあります。


モジュールの構造 (The module structure)


モジュールはJavaScriptのコードが書かれた普通のテキストファイルです。ヘッダーセクションとコードセクションが存在します。サンプルを下に示します:

 //startconfig
 //id=de.icab.crazy
 //icon=iVBORw0KGgoAAAANSUhEUgAAACwAAAAkCAYAAADy19hsAAAWrGlDQ1BJQ0...
 //title=Crazy Layout
 //description=The module sets random colors for the page elements
 //description.de=Das Modul setzt alle Farben der Seite auf Zufallswerte
 //var=confirmation;type=confirmation;default=false;
 //var=language;type=language;
 //endconfig
 
 var hex = "0123456789abcdef";
 
 function iCabMobileGoCrazyForElement(element) {
   if (element.nodeType == 1) {
     if (element.style.display != "none" &&
            element.nodeName.toLowerCase() != 'select') {
       element.style.backgroundColor = "#" +
                    hex.charAt(Math.random()*16) +
                    hex.charAt(Math.random()*16) +
                    hex.charAt(Math.random()*16);
       element.style.color = "#" +
                   hex.charAt(Math.random()*16) +
                   hex.charAt(Math.random()*16) +
                   hex.charAt(Math.random()*16);
       for (var i=0; i<element.childNodes.length; i++) {
         iCabMobileGoCrazyForElement(element.childNodes[i]);
       }
     }
   }
 }
 
 var doAction = (confirmation == false);
 
 if (confirmation) {
   var text = "Go crazy?";
   doAction = confirm(text);
 }
 
 if (doAction) {
   iCabMobileGoCrazyForElement(window.document.body);
 }


ヘッダセクションではモジュールのプロパティを定義します。ヘッダセクションはこの一行から始まります

 //startconfig

終わりはこの一行です

 //endconfig

この二行の間にすべてのプロパティを定義し、それら個々のプロパティ定義は一行ごとに解釈されます。(訳注※ひとつのプロパティごとに一行ということ。)そのため、複数行にわたる内容の定義はできません。また、空行は含んではいけません。どのプロパティも以下のようなフォーマットになります:

 //property=value;additional paramaters
 (additional paramaters = 追加パラメータ)

追加パラメータはオプションであり、いつも必要なわけではありません。

いくつかのプロパティは必須です。もしそれが間違っていたら、iCab Mobileはそのモジュールを無視します。(インストールされません。) その他のプロパティはオプションなのでなくても動作します。ここに現在サポートしているプロパティを挙げます:

id (必須)
このプロパティはモジュールを識別するためのものです。モジュールをアップデートや再インストールするときにこの"id"の値が、新しいものに置き換える必要のある古いモジュールを見つけるときに使用されます。ですからモジュールをアップデートするときに、この"id"の値を変更してはいけません。そのほかなら何を変えても構いません、モジュールの名前でさえ。このidというプロパティは、この世に存在する他のすべてのモジュールとかぶらないユニークなものである必要があります。良いidを見つけるベストな手段として、ドメイン名をひっくり返しモジュール名を足して使うという手があります。もしあなたが"www.your-domain.com"というドメインをあなたのウェブページに使っているならば、あなたはidに"com.your-domain.moduleName"を使うべきでしょう。あなた作ったすべてのモジュールは、ひっくり返したドメイン名を接頭辞に、モジュール名を接尾語に持つということになります。もしあなたがドメインを持っていないならば、あなたは接頭辞にあなたの名前や都市の名前にいくつかのランダムな数字(不幸にも同じidを持ってしまわないために)を足して使うといいでしょう。idはiCab Mobileのユーザの目に触れることはありません。モジュールの識別のためだけに使用されます。

Example: 例:
 //id=de.icab.crazy
もしドメインを持ってないならば、例としてはこんな感じです:
 //id=de.darmstadt.clauss.alexander.crazy
 //id=ja.saitama.taro.yamada.crazy

title (必須)
titleでモジュールの名前を定義します。iCab Mobileのモジュール設定で表示されるものです。タイトルプロパティはユーザがアプリ内設定でモジュールを有効化/無効化するときやモジュールの設定をするときのために必要です。

Example: 例:
 //title=Crazy Colors

あなたはローカライズされたタイトルを定義することができます。iPhone OS がサポートする言語の言語コード(たとえば英語なら"en", ドイツ語なら"de", イタリア語なら"it")を"title"という語の後につけるだけです
(訳注※日本語はjaです。日本語を使用する場合は文字コードに注意する必要があります)
like this: こんな風に:
 //title.de=Verrückte Farben
 //title.ja=狂った色

この方法で、簡単にモジュールを多言語にローカライズできます。言語コードのついていない「title」というキーは言語コードが現在の[デバイス]の言語に適合する定義済みの言語コードが無かったときに使われる既定の言語として使用されます。
一般には既定の言語は英語であるべきです。もし既定の言語が定義されていないときは、一番最初に定義されている言語が既定の言語として使われますが、既定の言語(言語コードの無いtitleキー)として英語を使うことが大いに推薦されます。

ですので、もしモジュールが英語とドイツ語をサポートするのであれば、titleは次のように定義されます:

 //title=Crazy Colors
 //title.de=Verrückte Farben


description (オプション)
descriptionはiCab Mobileのモジュール設定パネルで表示されます。descriptionはモジュールが何をするものなのかの説明がよいでしょう。titleプロパティと同様の手段を用いて次のようにローカライズが可能です:

 //description=The module sets random colors for the page elements
 //description.de=Das Modul setzt alle Farben der Seite auf Zufallswerte


icon (オプションだが強く推奨)
iconはユーザがモジュールのアイコンをタップすることによってそのモジュールを動作させることができるモジュールパネルを開いたときに表示されます。iconはPNGかJPGフォーマットの画像ファイルです。画像ファイルはBase64でエンコードされている必要があり、このBase64でエンコードされたデータをiconプロパティに指定します。通常、Base64データは64種類の文字からなる複数行で成りますが、モジュールに組み込むにあたり、改行を削除し一行にする必要があります。モジュールのアイコンは41*32が推奨されます。あなたのアイコンを作るにあたって空のアイコンイメージを用意したので使ってください:
http://www.icab.de/img/empty.png (iCabが用意した空のボタン画像)

 //icon=iVBORw0KGgoAAAANSUhEUgAAACwAAAAkCAYAAADy19hsAAAWrGlDQ1BJQ0...


var
"var"プロパティはiCab Mobileによって初期化されるJavaScriptの変数を定義します。これらの変数はユーザがモジュールの設定として変更することができ、またそれだけでなく、システム言語のようなシステムプロパティを得ることもできます。

変数は次のような形式をとります:

 //var=NameOfVar;type=typeOfVar;default=defaultValue;title=labelForSettings;

iCab Mobileはこれら変数プロパティをJavaScriptから利用するために変数宣言と初期化をするJavaScriptコードを生成し、モジュールのJavaScriptコードに追加します。そのため、それらはJavaScriptの変数であるため、特別な利用方法などいらず普通の変数として扱うことができます。

"var"プロパティの値は変数の名前となります。
"title"プロパティはユーザがモジュール設定にて変更可能であるときに必要で、これによってユーザは変数の値を変更することができます。"title"プロパティの値は設定パネルのラベルにて使用されます。言語コードを付加すればローカライズされた表示をすることも可能です。
"default"プロパティで変数の規定値を定義することができます。

"type"プロパティは変数の型で、次のうちのひとつをとることができます:

bool or boolean
trueかfalseの値をとる真偽値型です。モジュール設定でスイッチコントロールによってユーザによる状態変更が可能です。この型にはモジュール設定でラベルとして表示するための"title"プロパティが必要です。
int or integer
数値型です。モジュール設定では数字しか入力できないテキストフィールドによってユーザによる数値の変更が可能です。この型にはモジュール設定でラベルとして表示するための"title"プロパティが必要です。
string or text
文字列型です。モジュール設定ではテキストフィールドによってユーザによる文字列の変更が可能です。この型にはモジュール設定でラベルとして表示するための"title"プロパティが必要です。
pass or password
パスワード文字列型です。セキュリティのために入力した文字列が隠される点を除いて、文字列型と一緒です。この型にはモジュール設定でラベルとして表示するための"title"プロパティが必要です。
lang or language
システムの既定の言語の言語コードが代入される文字列型です。"title"プロパティは不要です。"en", "de", "it", "ja"といった値をとります。

confirm or confirmation
確認ダイアログ設定が代入される真偽型です。モジュール設定でできる確認ダイアログを有効にするか無効にするかの設定がどうなっているかを提供します。もし有効にされているなら、iCab Mobileはモジュールが作動するときに毎回本当に実行するかどうかを訪ねます。この変更オプションはiCab Mobileによって提供され自動的にローカライズされるので、この変数には"title"プロパティはいりません。

autorun
この変数は真偽値を持ちます。もしページロード完了時にモジュールが自動的に起動されるように推奨される場合、モジュール設定にあるユーザが設定することができるスイッチが提供されます。この変数には"title"プロパティは必要ありません。勝手にローカライズされます。もし"autorun"変数が定義されていない場合、モジュールは手動によってのみ起動できます。あなたはあなたのモジュールにおける"autorun"機能のデフォルトの設定をオン、オフのどちらにも設定することが出来ます。しかし、ユーザはいつでも"autorun"機能を停止することができます。モジュールが実行されたとき、 autorun型の変数は自動実行されたとき(つまりページロード完了時にiCab Mobileがモジュールを起動させたとき)は"true"、もしくはユーザによって手動起動されたときは"false"の値をとります。なのでモジュールは自動実行と手動実行のときで別々の振る舞いをすることができます。[この機能はiCab Mobile 3.3から利用可能になります。バージョン3.2では利用不能です]

select
The variable of this type can be used to select one item from an array of items. This variable type uses the title property in the same way as the other types to define the label in the module settings.
ようするに列挙型です。ラジオボタンの方が近いかもしれません。"title"プロパティを設定すればモジュール設定で反映されます。

この変数では後述する二つのプロパティが定義されている必要があります。"values"プロパティはユーザが選んだ項目がとる値の配列で、"valuetitles"プロパティはユーザが選ぶ項目名の配列です。"valuetitles"プロパティもまた、"title"プロパティと同じように言語コードをつければローカライズすることができます。"values"と"valuetitles"プロパティは項目を区切るために"|"で区切る必要があります。
例:

 //var=s;type=select;valuetitles=One|Two|Three;values=1|2|3;title=Number;default=2
 //var=j;type=select;valuetitles=壱|弐|参;values=1|2|3;title=数値;default=2

この設定の場合、ユーザは"One" "Two" "Three"のうちからひとつを選ぶことができます。もしユーザが"One"を選んだなら変数の値は 1 になり、もし"Two"を選んだなら 2 になる、とっった具合です。"default"によって変数は 2 に、最初から"Two"を選んだ状態になります。このラジオ選択自体に"title"でラベルをつけることができます。



ユーザがモジュールを動作させるとき、iCab Mobileはヘッダーセクションを読み込み、ヘッダーセクションのすべての変数定義のためにJavaScriptコードを作り出します。それらの変数の値はモジュール設定によって決定されます。技術的には、iCab Mobileはそれらの変数宣言をモジュールのJavaScriptコードセクションの前に追加するので、それによってモジュールがそれらの変数にアクセスできるようになります、それらの変数やJavaScriptコードセクションはブロックに組み込まれて実行されるため、現在表示しているウェブページのスコープを汚すことはありません。

それはつまり、以下のモジュールを例に考えると:

   //startconfig
   //id=de.icab.module
   //icon=iVBORw0KGgoAAAANSUhEUgAAACwAAAAkCAYAAADy19hsAAAWrGlDQ1BJQ0...
   //title=Some Module
   //var=confirmation;type=confirmation;default=false;
   //var=language;type=language;
   //var=text;type=string;title=Text;
   //endconfig
   
   function DoSomething() {
     // ここにモジュールの実際のコードを書きます
   }
   
   if (confirmation) {
     doAction = confirm("本当にこのモジュールを実行しますか?");
   } else {
     doAction = true;
   }
   
   if (doAction) {
     DoSomething();
   }

実際に実行されるコードはこのようになります:

   {
     var confirmation = true;
     var language = "en";
     var text = "User Input";
     
     function DoSomething() {
       // ここにモジュールの実際のコードを書きます
     }
     
     if (confirmation) {
       doAction = confirm("本当にこのモジュールを実行しますか?");
     } else {
       doAction = true;
     }
     
     if (doAction) {
       DoSomething();
     }
   }


JavaScriptの特別関数 (Special JavaScript functions)


モジュールはiCab Mobileによって定義された特殊な関数を呼ぶことができます。

次のような関数が利用可能です:

startDownload(url,file)
この関数はダウンロードを開始します。引数はURLと保存されるファイル名です。

postRequest(url,content,”callBackFunction”) new!!
この関数はHTTPのPOSTコマンド(”content”をサーバにポスト)でデータを取得し、HTTPステータスとデータを引数にコールバック関数を呼びます。(コールバック関数に関しては下のgetRequest()関数の説明をご覧ください)

getRequest(url,”callBackFunction”)
この関数は指定されたURLからHTTPのGETコマンドを使ってデータを取得し、HTTPステータスとデータを引数にコールバック関数を呼びます。(二番目の引数はモジュール内で実装されたコールバック関数の関数名の文字列です)

   function callBackFunction(status, data) {
     // "status"はHTTPステータスコードの数値です
     // "data"は取得したデータ(文字列)です
   }


モジュールのインストール (Installing the modules)


モジュールのインストールは、ウェブサイトからモジュールをダウンロードするだけです。ですからあなたがすべきことはモジュールへのリンクが含まれるウェブページを用意するだけです。モジュールへのURLは、通常の"http"スキームの代わりに "icabmobule"スキームか"javascriptmodule"スキームを使ってください。

たとえば、もしあなたのモジュールに次のURLでアクセスできるとしたら
http://your.webspace.com/modules/TheModule.icabmodule
あなたがウェブページに盛り込むべきHTMLのリンクは次のようになります:

 <a href="icabmodule://your.webspace.com/modules/TheModule.icabmodule">Download TheModule</a>

あるいは、次のようにします:

 <a href="javascriptmodule://your.webspace.com/modules/TheModule.icabmodule">Download TheModule</a>


もし、誰もがアクセスできるウェブページにこれらのリンクを組み込んでいるのであれば、ほかのiCab Mobileユーザも同じようにあなたのモジュールをインストールすることができます。
ですからあなたは簡単にあなたのモジュールをほかのユーザーとシェアすることができます。

我々はモジュールのために二種類のURLスキームを用意しました。ほかのiPhoneデベロッパー(とくにiPhoneのウェブブラウザ開発者)がこのモジュール機能に興味をもってくれた場合、すべてのモジュールが互換性を持っているならすばらしいでしょう。

この場合において、"javascriptmodule"スキームはモジュール機能をサポートするすべてのアプリに使われます。もう一方は、特化したモジュール(つまり、"icabmodule"スキームはiCab Mobileしか受け付けません)に使われます。

あなたはモジュールを私(訳注※iCab Mobileの作者)に送ることができ、そうすれば私はそれらのモジュールをiCab Mobileに元から入っている"Download"モジュールを通してアクセス可能なモジュールダウンロードページに取り入れます。この方法ならすべてのiCab Mobileユーザがモジュールを即座に発見することができるでしょう。


today: -
total: -

ツールボックス

下から選んでください:

新しいページを作成する
ヘルプ / FAQ もご覧ください。