公式なドキュメントはRhomobile社のサイトをご覧ください。
また、この文書は2010/8/21(JST)の情報がもとになっています。
この日本語の翻訳について問題・質問などがある場合、コメントを残してください。それ以外については、本ドキュメント内にある問い合わせ先にお願いします。
The following document (a translation of the English original into Japanese) is published with Rhomobile permission.
If you need official documents, please visit Rhomobile site.
In addition, the following document is based on 2010/August/21 (JST) information.
If you have any question, problem about the Japanese translation, please leave your comment. Except for that, refer contacts in the document.
目次
|
CSS フレームワーク (2.0以降)
Rhodes2.0+は改善されたCSSのフレームワークを有しています。これはサポートするプラットフォーム上で強力なWebkitの機能のアドバンテージをもたらします。すべてのプラットフォームにわたって提供するクリーンで、直感的なコードベースを提供します。
メニューのレイアウト
メニューベースのプラットフォーム（現在、RIMとAndroid）については、Rhodesフレームワークは、以下の簡単なAPIを介して、ネイティブ・アプリケーション・メニューの項目を変更する機能を提供します。
@default_menu = {
"Item Label 1" => "/item1path",
"Item Label 2" => "/item2path",
...
} #=> overrides the rhodes default menu
@menu = {
"Item Label 1" => "/item1path",
"Item Label 2" => "/item2path",
...
} #=> overrides the default menu in a specific actionデフォルトメニュー
application.rbのデフォルトのメニューを変更するには：
class AppApplication < Rho::RhoApplication
def initialize
super
@default_menu = {
"Go Home" => :home,
"View Accounts" => "/app/Account",
"Do Refresh" => :refresh,
"Perform Sync" => :sync,
"App Options" => :options,
"View Log" => :log
}
end
end
これは、次の項目のデフォルトのメニューを作成します（トップ-ダウン順）：
- Go Home
- View Accounts
- Do Refresh
- Perform Sync
- Add Options
- View Log
"View Accounts"以外のメニュー項目は、予約されているメニュー項目を呼び出します。"View Accounts"項目は、ハッシュ値で指定されたpathへ移動します。この例では/app/Acountです。
注：AndroidのメニューのカスタマイズはRhodes 2.0で実装されました。
コントローラのアクションメニュー
controller.rbの特定のアクションのメニューを変更するには：
def index
@accounts = Account.find(:all)
@menu = {
"Go Home" => :home,
"Refresh" => :refresh,
"Options" => :options,
:separator => nil,
"Log" => :log,
"New Account" => "/app/Account/new"
}
render
end
注：ユーザーが異なるアクションへ移動したらすぐに、アプリケーションのデフォルトのメニューにリセットされます。
予約メニュー項目
メニューに許される定義済みのアクションはユーザ定義のメニュー/ツールバー/タブバーのアクションを参照してください。
application.rbで何も設定されない場合、以下がデフォルトのRhodesメニューになります：
@default_menu = {
"Home" => :home,
"Refresh" => :refresh,
"Sync" => :sync,
"Options" => :options,
"Log" => :log,
:separator => nil,
"Close" => :close
}ユーザ定義のメニュー/ツールバー/タブバーのアクション
ここではユーザー定義のメニュー、ツールバー、タブバーのアクションに許される値のリストです：
:back #=> do back navigation using web view history or application's back url
:forward #=> do forward navigation
:home #=> navigate to configured start_path
:options #=> navigate to configured options_path
:refresh #=> refresh current page
:sync #=> trigger SyncEngine.dosync
:log #=> load the native logging UI
:separator #=> draw a separator line (if supported)
:close #=> close or put Rhodes to background (depending on platform)
:fullscreen #=> go to full screen mode
アクションは、ユーザー定義のコントローラメソッドのURLも指定できます。URLは'コールバック'を付加することができ、それはWebViewではなくRhodes coreによってロードされることを意味します。これは、バックグラウンドでUIを触ることなく、効果的に指定されたURLをロードする方法です。いくつかの例：
:action => url_for(:action => :do_that) # Calling of this action will be done by UI WebView component so
# result of the do_that method will be rendered in UI
:action => '/app/AnotherController/do_that' # The same as above but for another controller
:action => 'callback:' + url_for(:action => :callback) # Here url of :callback action will be loaded in background
# by the rhodes core. UI will not be touched
:action => 'callback:/app/AnotherController/callback' # The same as above but for another controller
ネイティブバーコントロール
Rhodesは、ネィティブな見た目の'ツールバー'や'タブバー'の表示をサポートします。両者の違いは重要であり、すべてのアプリケーションの開発者に明確にされるべきでものです。
ツールバーは、ユーザーが関連付けられているアクションボタンを追加することができる画面の下にある小さな領域です。Rhodesでは、これらのアクションはURLをロードする必要があります。これらのURLをロードするためのさまざまな方法があります。URLの最初に'callback:'prefixを指定するか(Rhodes coreによってURLのロードがバックグラウンドで実行されます)、prefixなしでURLそのものを使うことができます(URLをロードするために、UI WebViewエレメントを使います-このケースではツールバー・ボタンを押すことは現在のページの再ロードと再描画が発生します)。
タブバーは、各タブに関連付けられたさまざまなUIビューのセットです。タブの選択は関連付けされたビューを表示します。ツールバーにできるようなカスタムアクションを定義することはタブバーにはできません。タブが選択されたときの、唯一のアクションは別のUIのビューに切り替えることです。
ツールバーとタブバーは、1.2.2以降のiPhone上でサポートされ、Androidは1.5からです。
Rhodes1.5からは、実行時にツールバー／タブバーをカスタマイズすることができます。
ツールバーを使用するために、しなければならないことはapplication.rbのツールバー項目を定義することがすべてです：
class AppApplication < Rho::RhoApplication
def initialize
@@toolbar = [
{:action => :back, :icon => '/public/images/back_btn.png'},
{:action => :forward, :icon => '/public/images/forward_btn.png'},
{:action => :separator},
{:action => :home},
{:action => :refresh},
{:action => :options}
]
# Important to call super _after_ you define @@toolbar!
super
end
end
:actionを定義する方法はUser defined menu/toolbar/etc actionsを参照してください。
定義済みのアクションは定義済みのアイコンが表示されますが、アイコンは上記のように:iconを指定することでユーザーにより上書きできます。ユーザー定義のアクションの場合、:iconまたは:lableを指定する必要があります。両方が省略された場合、Rhodesはツールバーにボタンを追加しません。両方が指定された場合、:iconが描画されます:labelは破棄されます。
タブバーの場合：
class AppApplication < Rho::RhoApplication
def initialize
# Tab items are loaded left->right, @tabs[0] is leftmost tab in the tab-bar
@tabs = [
{ :label => "Dashboard", :action => '/app', :icon => "/public/images/tabs/dashboard.png", :reload => true },
{ :label => "Accounts", :action => '/app/Account', :icon => "/public/images/tabs/accounts.png" },
{ :label => "Contacts", :action => '/app/Contact', :icon => "/public/images/tabs/contacts.png" },
{ :label => "Options", :action => '/app/Settings', :icon => "/public/images/tabs/options.png" }
]
# Important to call super _after_ you define @tabs!
super
end
end
各タブバーの項目は上記のサンプルで定義された4つのタブの要素（4つすべてが必要です）を定義します：
:label #=> Visible label to display on the tabbar
:action #=> Path to your rhodes action (i.e. '/app/Account' would load the Account index action)
:icon #=> Relative path to tabbar item icon in your rhodes app (typically located in /public/images/)
:reload => true #=> Optional argument which tells rhodes to reload the tab's :action, defaults to false
舞台裏では、Rho::RhoApplicationは@@toolbarもしくは@tabs配列をその初期化メソッドで検出し、以下の関数でネーティブ・バーを構築します。
NativeBar.create(bar_type, bar_item_array)
次のネイティブバーの種類が許可されています：
RhoApplication::TOOLBAR_TYPE #=> 0
RhoApplication::TABBAR_TYPE #=> 1
RhoApplication::NOBAR_TYPE #=> 2
navbarを完全に無効にするには：
class AppApplication < Rho::RhoApplication
def initialize
@@toolbar = nil
@tab = nil
super
end
end
ネイティブバーランタイムAPI
上記で述べたように、最近のバージョンのRhodesでは、実行時にツールバーやタブバーを作成したり削除したりできます。ツールバーのランタイムのカスタマイズはRhodes1.5、タブバーのカスタマイズは1.4で実装されました。プログラムによるタブの切り替えのサポートも追加されました：
NativeBar.create(Rho::RhoApplication::TABBAR_TYPE, tabs) # Will remove existing toolbar/tabbar (if exists) and create new one
NativeBar.create(Rho::RhoApplication::TABBAR_TYPE, :tabs => tabs) # Supported since rhodes 2.0, means the same as above
NativeBar.remove # Will remove current toolbar/tabbar. Does nothing if there is no active bar
NativeBar.switch_tab(1) # Will switch active tab to second (numeration is zero based i.e. 0 means first tab, 1 - second etc)
ツールバーを作成する例：
NativeBar.create(Rho::RhoApplication::TOOLBAR_TYPE, toolbar)
NativeBar.create(Rho::RhoApplication::TOOLBAR_TYPE, :buttons => toolbar) # Supported since rhodes 2.0, means the same as above
NativeBar.create(Rho::RhoApplication::TOOLBAR_TYPE, :buttons => toolbar, # Supported since rhodes 2.0
:color => {:red => 0, :green => 128, :blue => 128}) # Will create toolbar the same as above but with specified
# background color (support only Android as for now)
NativeBar.createはネイティブタブバーUIエレメントを生成し、その最初のタブをアクテイブにします。もし、他のタブを見たいなら、NativeBar.createの直後に明示的にNativeBar.switch_tabを呼び出します:
NativeBar.create(Rho::RhoApplication::TABBAR_TYPE, tabs)
NativeBar.switch_tab(2) # Switch to 3-rd tab (index is zero-based!)
ツールバーの生成例:
NativeBar.create(Rho::RhoApplication::TOOLBAR_TYPE, toolbar)
NativeBar.create(Rho::RhoApplication::TOOLBAR_TYPE, :buttons => toolbar) # Supported since rhodes 2.0, means the same as above
NativeBar.create(Rho::RhoApplication::TOOLBAR_TYPE, :buttons => toolbar, # Supported since rhodes 2.0
:color => {:red => 0, :green => 128, :blue => 128}) # Will create toolbar the same as above but with specified
# background color (support only Android as for now)
そしてもう一つ：
NativeBar.create(Rho::RhoApplication::TABBAR_TYPE, tabs)
NativeBar.switch_tab(3)
WebView.navigate('app/Settings', 3)
ナビゲーションバー（2.0以降）
2.0から、Rhodesは、iPhone用のネイティブのナビゲーションバーをサポートします。これは、タイトル、'back'ボタンとオプショナルな'right'ボタンからなるネィティブUIエレメントです。
NavBar.create :title => "Navigation bar",
:left => {:action => :back, :label => "Back"},
:right => {:action => url_for(:action => :help), :label => "Help"}
':right'は省略でき、':left'と':right'はUser defined menu/toolbar/etc actionsに説明があります。
日付/時刻の選択
日付/時刻のピッカーAPIは、ユーザーが日付または時刻を選択することができます：
DateTimePicker.choose(callback, title, initial_time, fmt)
DateTimePicker.choose(callback, title, initial_time, fmt, opaque)
"fmt"パラメータは、次の値（他の値は例外がスローされます）持つことができます。
- 0 - 完全な日付と時刻の入力フィールド
- 1 - 日付のみの入力フィールド
- 2 - 時のみの入力フィールド
"opaque"パラメータはオプションの文字列です。それは何も処理されないで（それが"opaque"とうい名前の由来）そのままコールバックに返されます。
いったんユーザーがdate/timeを選択しOKまたはCancelを押すと、指定したコールバックのURLが呼び出されます。コールバックは、POSTメッセージで、メッセージのbodyは'status'、'result'とおそらく'opaque'が含まれています。
- 'status'は'ok'または'cancel'
- 'result'は選択された日付の文字列表現で、Epochからの秒数です。Rubyの時間は、Time::atメソッドを使って作成することができます。
- statusが'cancel'の場合、'result'はありません。
- 'opaque' - 存在する場合、'opaque'は選択されたメソッドへ渡る、そのままの文字列になります。
注：現在Android、iPhoneとBlackberry向けに実装されています。
例
より詳細な情報は、System API Samples applicationの/app/DateTimeフォルダのcontroller.rbとindex.erbビューを参照してください。この例では３つのdate/timeピッカータイプのそれぞれの方法を示しています。
Animated transitions for Webkit platforms
Animated transitionsはiPhoneとAndriodでサポートされます。Rhodesはスクリーン間の移動を提供するために、カスタムバージョンのjQTouchを利用します。アプリケーションでanimated transitionsを有効にするには、レイアウトのヘッダエレメントに以下を含めなければなりません。
<% if System::get_property('platform') == 'APPLE' || System::get_property('platform') == 'ANDROID' %>
<script src="/public/jqtouch/jquery.1.3.2.min.js" type="text/javascript"></script>
<script src="/public/jqtouch/jqtouch.js" type="text/javascript"></script>
<link href="/public/jqtouch/jqtouch.css" type="text/css" rel="stylesheet"/>
<script>$.jQTouch();</script>
<% end %>
また、アプリケーションのrhoconfig.txtにjqtouch_mode=1を追加することを確認してください。このプロパティを設定すると、ボトムツールバーのバックボタンやフォワードボタンを隠すanimationが有効になります。
この行が含まれると、アプリケーションのリンクはスクリーン間のanimated transitionsとして動作します。それぞれのrんくはフルパスでなければなりません。相対パスでは移動は動作しません。url_forやlink_toのヘルパー関数を使っているなら、大丈夫でしょう。
古いアプリケーションへtransitionsを追加する
animated transitionsを追加したい古いアプリケーションがある場合、以下のステップを行ないます。
* 前のセクションで説明された指示を行ないます。
* それぞれのビューテンプレートを確認し、クラスのid属性を全て変更します。例えば：
o <div id="toolbar"> を <div class="toolbar">
o <div id="leftItem" class="regularButton"> を <div class="leftItem regularButton">
* 最新のRhodesからpublic/jqtouchディレクトリをアプリケーションのpublicディレクトリへコピーします。
* 最新のRhodesからpublic/css/*.cssファイルをアプリケーションのpublic/cssディレクトリへコピーします。
o もしくは、idセレクタをclassセレクタへ全て変えることも可能です。cssファイルに独自の変更を行っているならば、この方法を採りたくなるかもしれません。簡単にいえば、#toolbarセレクタはもう.toolbarにすべきだということです。
Transition styles
スクリーン間の移動はデフォルトではスライドです。特定のanimationクラスをリンクに設定することでanimationをoverrideすることができます。有効なanimationクラスは：
* slide (default)
* fade
* dissolve
* flip
* slideup
* swap
* cube
* pop
slide以外のanimationはiPhoneで動作するようにAndoridデバイスでは動作しないでしょう。注意してください。
<div class="toolbar">
<div class="leftItem backButton">
<a class="swap" href="...">Left back button that animates swap transition</a>
</div>
<div class="rightItem regularButton">
<a class="flip" href="...">Right button that animates flip transition</a>
</div>
</div>
<div class="content">
<ul>
<li>
<a class="pop" href="...">
<span class="title">Link that animates pop transition</span>
<span class="disclosure_indicator"></span>
</a>
</li>
<li>
<a class="cube" href="...">
<span class="title">Link that animates cube transition</span>
<span class="disclosure_indicator"></span>
</a>
</li>
</ul>
</div>
Back button
backButtonクラスのリンクは前のanimation transitionの移動を逆に戻ります。リンクの割り当てられたhrefは無視されることに注意して下さい。
<div class="toolbar">
<div class="leftItem backButton">
<a href="...">Cancel</a>
</div>
<div class="rightItem regularButton">
<a href="...">Edit</a>
</div>
</div>
他のページへの移動
target="_webapp"と設定すると、animationは無効になり、リンクに指定されたhrefへ移動します。いかなるanimationクラス(like slide, flip, etc) も無視されることに注意してください。
<div class="content">
<ul>
<li>
<a target="_webapp" href="http://rhomobile.com/">
<span class="title">Rhomobile home page</span>
<span class="disclosure_indicator"></span>
</a>
</li>
</ul>
</div>
Sample application
animated transisionsを使った簡単なアプリケーションの参考として、githubのstore appをチェックアウトしてください。
jQTouchの変更
RhodesフレームワークはjQTouch Version1, beta 2の改変を使っています。以下がjQTouchライブラリの変更の一覧です。
* $.support.WebKitAnimationEvent がAndriod 2.xでtrueに設定されます。デフォルトの実装ではfalseが設定されます。
* Ajaxリクエストのデフォルトのタイムアウトが３０秒に設定されています。
* デフォルトbackSelectorが".back, .cancel, .goback"から".backButton a"に変更されています。
* デフォルトslideSelecotが"body > * > ul li a"から"a"へ変更されています。これはデフォルトでslide transitionですべてのリンクがanimateします。
* 全ての"a"がliveTapを起動し、全ての"[type=submit]"はsubmitParentFormを起動します。
* ドキュメントのロード時、jQTouchのRhodes実装はbodyの子要素をDIVでラップします。
* Android 2.x devicesのslide animationは固定されています。slide transitionsは他のanimated transitionsとは違うハンドリングが行われます。
* この実装は二つのプロパティを含むグローバルRhoオブジェクトを生成します：
o Rho.insertAsyncPage(screenSnippet) - アプリケーションにページを挿入する関数。screenSnippetはページを表すDIVを含むストリングであり、理論的にはpageTitle, toolbarとコンテンツのDIVを含みます。
o Rho.jqt - oublic jQTouchメソッドへの参照で、通常jQTouchのインスタンス化によって得られます。例えば、一つ画面をプログラムで戻るには、Rho.jqt.goBack()を発行します。
* AjaxはTransition-Enabled: true request headerの設定を要求します。これはjQTouchが有効なアプリケーションで作られた要求をコントローラーへ通知します。
* 逆に、AjaxはWait-Page response headerの検査を要求します。これは、コントローラーによって生成された非同期HTTP要求後に返されるページをjQTouchへ通知します。Wait pagesはjQtouchの履歴には追加されません。そのanimationは、Rho.insertAsyncPage()の呼び出し経由で期待したページがユーザインタフェースへ戻るまで、遅延します。
この方法は一般的に、コントローラーでトリガに設定された非同期HTTP callback関数の後に、起動されます。
* フォームのslide animation transitionを<form class="pop">...</form>のようにformにanimation classを設定することで、overrideすることができます。
投稿
0 件のコメント:
コメントを投稿