Skip to content

Commit

Permalink
link between rhomsource, rhocontact, and API in documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
David Strom committed Jan 19, 2013
1 parent f40d4ce commit 450434a
Show file tree
Hide file tree
Showing 3 changed files with 52 additions and 156 deletions.
116 changes: 15 additions & 101 deletions doc/device-caps.txt
View file
Expand Up @@ -245,121 +245,35 @@ To allow read/modify personal information and contacts enable the pim capability
capabilities:
- pim

The following methods are available in the RhoContact class:
### PIM Contacts API

Return hash of hashes of contacts stored in the phonebook (index):
:::ruby
Rho::RhoContact.find(:all)

On some platforms an extended Rho::RhoContact.find routine is implemented
:::ruby
Rho::RhoContact.find(:all, params)
Rho::RhoContact.find(:first, params)
Rho::RhoContact.find(:count, params)

Currently the extended functionality is available at Android and iOS

* :all - get all contacts as usual
* :first - find first contact from list
* :count - returns count of contacts

For these selectors an additional params hash may be used. The next keys and values are recognized in additional params:

* :per_page - max count if contacts returned by find
* :offset - offset from begin of contacts' list
These two parameters are used to paginate contacts list. If used with :count exact number of returned contacts can be determined (for example for last page).

:max_results - used with :count. maximum number of contacts to be returned.
Refer to the [PIM Contacts API](/rhodesapi/rhocontact-api) methods to perform the following functionality.

The next parameters are available at Android only.
* [find](/rhodesapi/rhocontact-api#find) - Returns the contacts in the device phone book.
* [create!](/rhodesapi/rhocontact-api#create) - Create a new contact in the phonebook.
* [destroy](/rhodesapi/rhocontact-api#destroy) - Delete this contact from the phonebook.
* [update_attributes](/rhodesapi/rhocontact-api#updateattributes) - Find a contact in the phonebook and update its properties.

* :select - list of contact properties have to be selected from phonebook (Use it to enhance query performance)
* :conditions - hash of conditions to query contacts. Look for more details below.
The [Contact Properties](/rhodesapi/rhocontact-api#contact-properties) lists the contact properties that are supported for all platforms, and additional contact properties supported on Android and iOS.

**NOTE: It is allowed to pass additional params hash at all platforms. Platforms that has no extended functionality will just skip these**
Example of returning a hash of hashes of all the contacts stored in the phonebook (index):

Return hash of all properties of the contact identified by the provided id (show):
:::ruby
Rho::RhoContact.find(@params['id'])
Rho::RhoContact.find(:all)

Create new contact in the phonebook, set properties of the contact passed as parameter hash, and save created phonebook record (create). Return the new contact as a hash.
:::ruby
created_contact = Rho::RhoContact.create!(@params['contact'])
Example for Android and iOS of finding the number of contacts in the phonebook:

Find contact record in the phonebook, update record properties from the hash passed as parameter, and save updated record. Contact id passed in the hash (update):
:::ruby
Rho::RhoContact.update_attributes(@params['contact'])

Remove contact identified by the provided id from the phonebook. (delete)
:::ruby
Rho::RhoContact.destroy(@params['id'])

On all devices, properties currently supported are: "id","first_name","last_name","mobile_number","home_number","business_number","email_address","company_name"

### iPhone
Rho::RhoContact.find(:first)

On iPhone, additional contact properties are supported.

General:
"prefix", "first_name", "middle_name", "last_name", "suffix", "nickname",
"birthday", "anniversary", "created", "updated",
"company_name", "job_title", "assistant_name", "assistant_number",
"spouse_name", "person_note"

**NOTE: "birthday", "anniversary", "created", "updated" properties expect a date formatted as YYYY-MM-DD**

Addresses:
"street_address_1", "city_1", "state_1", "zip_1", "country_1"
"street_address_2", "city_2", "state_2", "zip_2", "country_2"
"street_address_3", "city_3", "state_3", "zip_3", "country_3"

**NOTE: Address 1 is mapped to "work," 2 is to "home," 3 is to "other."**

Email addresses:
"email_address", "home_email_address", "other_email_address"
**NOTE: "email_address" is mapped to "work" **

Phone numbers:
"business_number", "home_number", "mobile_number", "main_number", "pager_number", "home_fax", "work_fax"

Home pages:
"home_page"

### Android

**NOTE: In most cases the result of RhoContact::find query may return more contact properties then defined in :select**

On Android the next contact properties are supported (every of them may be used in :select list):

General:
"id", "display_name", "first_name", "last_name"
The "display_name" is always filled by Android even if "first_name" and "last_name" are both empty. In this case email or phone number may be used.

Phone numbers:
"mobile_number", "home_number", "business_number"

E-mails:
"email_address"

Company:
"company_name"
**NOTE: It is allowed to pass additional params hash at all platforms. Platforms that has no extended functionality will just skip these**

#### Conditions
Example of returning a hash of all properties of the contact identified by the provided id (show):

:conditions parameter is a hash of conditions. Keys of the hash are contact property selectors (condition to be applied to) and values are conditions itself.
The next property selectors are defined:
- :phone
- :email
A property selector has no one-to-one relation to a single contact property like mobile_phone or email_address. Selectors are mapped to whole property group like all phones or all emails (support for several emails may be implemented in future).
Condition like
:::ruby
{:phone => 'not_nil'}
will select all contacts which has at least one phone.
The following conditions are currently supported:
- 'not_nil'
- 'is_nil'
Rho::RhoContact.find(@params['id'])

**NOTE: It may be useful to sort received contacts (especially if paginated). Contacts is ordered by 'display_name' column and then split for pages. Unfortunately the order inside page is lost while passing the list to ruby**
Example of finding with conditions:

:::ruby
@count = Rho::RhoContact.find(:count, :conditions => {:phone => 'not_nil'})
Expand Down
73 changes: 21 additions & 52 deletions doc/rhom.txt
View file
Expand Up @@ -287,7 +287,7 @@ If you want to remove all local data when upgrading to new application version:
This scenario will work for Property Bag and Fixed Schema models.

## Rhom API
Below is the full list of links to the [Rhom API methods] available to Rhom models.
Below is the full list of links to the [Rhom API methods](/rhodesapi/rhom-api) available to Rhom models.

* [client_id](/rhodesapi/rhom-api#clientid) - Returns the current sync client id.
* [clear_notification](/rhodesapi/rhom-api#clearnotification) - Clear notification for the object.
Expand All @@ -304,6 +304,7 @@ Below is the full list of links to the [Rhom API methods] available to Rhom mode
* [sync](/rhodesapi/rhom-api#sync) - Start the sync process for a Rhodes model.
* [can_modify](/rhodesapi/rhom-api#canmodify) - Returns true if the Rhodes model object is not currently being synced (if it is being synced, you should disable editing of the object).
* [changed?](/rhodesapi/rhom-api#changed) - Returns true if a Rhodes model object has local database changes that need to be synchronized, false otherwise.
* [have_local_changes?](/rhodesapi/rhom-api#havelocalchanges) - Returns true if any of the Rhodes model objects have local database changes that need to be synchronized, false otherwise.
* [save](/rhodesapi/rhom-api#save) - Saves the current Rhodes model object to the database.
* [set_notification](/rhodesapi/rhom-api#setnotification) - Set a notification to be called when the sync is complete for this model.
* [update_attributes](/rhodesapi/rhom-api#updateattributes) - Updates the current Rho model object attributes and saves it to the database.
Expand Down Expand Up @@ -353,7 +354,7 @@ Find Rhom objects.<a id="rhom-find-example" />
#### Order Examples
The `:order` argument for `find` accepts several forms.

* `:order` by one attribute:
`:order` by one attribute.

:::ruby
@accts = Account.find(
Expand All @@ -362,21 +363,21 @@ The `:order` argument for `find` accepts several forms.
:orderdir => 'DESC'
)

* `:order` by one attribute with a block:
`:order` by one attribute with a block.

:::ruby
@accts = Account.find(:all, :order => 'name') do |x,y|
y <=> x
end

* `:order` with a block:
`:order` with a block.

:::ruby
@accts = Account.find(:all) do |item1,item2|
item2.name <=> item1.name
end

* `:order` by multiple attributes:
`:order` by multiple attributes.

:::ruby
@accts = Account.find(
Expand Down Expand Up @@ -583,64 +584,32 @@ To access a RhomSource, load it by name:
:::ruby
@source = RhomSource.find('source_name')

Here are the available statistics:

`source_id` returns the id of a source.

:::ruby
@source.source_id
#=> 1

`name` gets the name of the source.
Then you can get statistics and information about the source, such as the name.

:::ruby
@source.name
#=> "Product"

`last_updated` returns the last time the source was successfully synchronized (in `Time.at` format).

:::ruby
@source.last_updated.to_s
#=> "Wed Jan 19 18:35:05 -0800 2011"
Here are the available statistics, from the [rhomsource API](/rhodesapi/rhomsource-api).

* [find](/rhodesapi/rhomsource-api#find) - Returns a RhomSource object.
* [source-id](/rhodesapi/rhomsource-api#sourceid) - Returns the id number of a source.
* [name](/rhodesapi/rhomsource-api#name) - Returns the name of the source.
* [last_updated](/rhodesapi/rhomsource-api#lastupdated) - returns the last time the source was successfully synchronized (in `Time.at` format).
* [last_inserted_size](/rhodesapi/rhomsource-api#lastinsertedsize) - returns the number of records inserted on last sync.
* [last_deleted_size](/rhodesapi/rhomsource-api#lastdeletedsize) - returns the number of records deleted on the last sync.
* [last_sync_duration](/rhodesapi/rhomsource-api#lastsyncduration) - returns the duration in milliseconds of the last sync for this source.
* [last_sync_success](/rhodesapi/rhomsource-api#lastsyncsuccess) - returns 1 if last sync was successful, 0 if it failed.
* [distinct_objects](/rhodesapi/rhomsource-api#distinctobjects) - returns the number of records for this source.

For example, to show the formatted time for the `Product` model:
This example shows the formatted time for the `Product` model.

:::ruby
RhomSource.find(
Product.get_source_name
).last_updated.strftime("%m/%d/%Y, %I:%M%p")
#=> "01/19/2011, 06:40PM"

`last_inserted_size` returns the number of records inserted on last sync.

:::ruby
@source.last_inserted_size
#=> 3

`last_deleted_size` returns the number of records deleted on last sync.

:::ruby
@source.last_deleted_size
#=> 1

`last_sync_duration` returns the duration in milliseconds of the last sync for this source.

:::ruby
@source.last_sync_duration
#=> 7

`last_sync_success` returns 1 if last sync was successful, 0 if it failed.

:::ruby
@source.last_sync_success
#=> 1

`distinct_objects` returns the number of records for this source.

:::ruby
@source.distinct_objects
#=> 837

## Resetting the Database
Rhodes provides the following functions for recovering the database from a bad or corrupt state, or if the RhoConnect server returns errors.

Expand Down Expand Up @@ -898,9 +867,9 @@ If your application requires that the local database is encrypted on the filesys
db.rollback
end

*NOTE: If ::Rho::RHO.get_src_db('Model') return nil, it means that you never call this models methods before(models are loaded by demand). To fix it call 'require_source': *
*NOTE: If ::Rho::RHO.get_src_db('Model') returns nil, it means that you never called this model's methods before (models are loaded by demand). To fix it, call 'require_source'.

:::ruby
require_source 'Model'

*NOTE see more tips here: [How can I create a lot of objects in controller action](/faq#how-can-i-create-a-lot-of-objects-in-controller-action)
*NOTE: see more tips here: [How can I create a lot of objects in controller action](/faq#how-can-i-create-a-lot-of-objects-in-controller-action).
19 changes: 16 additions & 3 deletions doc/ui.txt
View file
Expand Up @@ -560,9 +560,12 @@ To disable the toolbar entirely:

### Native Toolbar runtime API

As mentioned above, with recent versions of Rhodes you can create/remove toolbars/tabbars in runtime.
As mentioned above, with recent versions of Rhodes you can create/remove toolbars/tabbars in runtime, using the [Native Toolbar API](/rhodesapi/nativetoolbar-api).

Toolbar elements :
* [create](/rhodesapi/nativetoolbar-api#create) - creates a toolbar.
* [remove](/rhodesapi/nativetoolbar-api#remove) - removes a toolbar.

Toolbar elements:

* :background_color=>system_color - define custom background color

Expand Down Expand Up @@ -682,12 +685,22 @@ To disable the tabbar entirely:
end
end

### Native Tabbar runtime API
### NativeTabbar runtime API

You need to require rhotabbar in your controller to use the native tabbar.
:::ruby
require 'rho/rhotabbar'

You can create/remove toolbars/tabbars in runtime, using the [Native Tabbar API](/rhodesapi/nativetabbar-api).

* [create](/rhodesapi/nativetabbar-api#create) - removes the current tabbar and replaces it with this one.
* [create_vertical](/rhodesapi/nativetabbar-api#createvertical) - creates a vertical tabbar on the iPad, a regular tabbar on other platforms.
* [get_current_tab](/rhodesapi/nativetabbar-api#getcurrenttab) - returns the current tab index.
* [remove](/rhodesapi/nativetabbar-api#remove) - removes the current tabbar.
* [set_tab_badge](/rhodesapi/nativetabbar-api#settabbadge) - set the iPhone badge to tab (only for iOS devices).
* [switch_tab](/rhodesapi/nativetabbar-api#switchtab) - switch active tab to second.
* [Tab Elements](/rhodesapi/nativetabbar-api#tab-elements) - Several of the NativeTabbar methods use a tabs parameter, which is a list of name/value pairs.

Removes existing tabbar (if it exists) and create a new one.
:::ruby
Rho::NativeTabbar.create(tabs)
Expand Down

0 comments on commit 450434a

Please sign in to comment.