Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update readme #117

Merged
merged 2 commits into from
Oct 9, 2015
Merged

Update readme #117

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1b33da3
Merge remote-tracking branch 'joost/master'
toydestroyer Oct 9, 2015
135795c
Update README.md
toydestroyer Oct 9, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 85 additions & 49 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,21 @@ Find version information in the [CHANGELOG](CHANGELOG.md).

Add this line to your application's Gemfile:

gem 'phony_rails' # Include phony_rails after mongoid (if you use mongoid, see issue #66 on github).
```ruby
gem 'phony_rails' # Include phony_rails after mongoid (if you use mongoid, see issue #66 on github).
```

And then execute:

$ bundle
```
$ bundle
```

Or install it yourself as:

$ gem install phony_rails
```
$ gem install phony_rails
```

## Usage

Expand All @@ -27,28 +33,31 @@ Or install it yourself as:

For **ActiveRecord**, in your model add:

class SomeModel < ActiveRecord::Base
# Normalizes the attribute itself before validation
phony_normalize :phone_number, :default_country_code => 'US'
```ruby
class SomeModel < ActiveRecord::Base
# Normalizes the attribute itself before validation
phony_normalize :phone_number, default_country_code: 'US'

# Normalizes attribute before validation and saves into other attribute
phony_normalize :phone_number, :as => :phone_number_normalized_version, :default_country_code => 'US'
# Normalizes attribute before validation and saves into other attribute
phony_normalize :phone_number, as: :phone_number_normalized_version, default_country_code: 'US'

# Creates method normalized_fax_number that returns the normalized version of fax_number
phony_normalized_method :fax_number
end
# Creates method normalized_fax_number that returns the normalized version of fax_number
phony_normalized_method :fax_number
end
```

#### Mongoid

For **Mongoid**, in keeping with Mongoid plug-in conventions you must include the `Mongoid::Phony` module:

class SomeModel
include Mongoid::Document
include Mongoid::Phony

# methods are same as ActiveRecord usage
end
```ruby
class SomeModel
include Mongoid::Document
include Mongoid::Phony

# methods are same as ActiveRecord usage
end
```
#### General info

The `:default_country_code` options is used to specify a country_code when normalizing.
Expand All @@ -57,98 +66,125 @@ PhonyRails will also check your model for a country_code method to use when norm

You can also do-it-yourself and call:

# Options:
# :country_code => The country code we should use (forced).
# :default_country_code => Some fallback code (eg. 'NL') that can be used as default (comes from phony_normalize_numbers method).
```ruby
# Options:
# :country_code => The country code we should use (forced).
# :default_country_code => Some fallback code (eg. 'NL') that can be used as default (comes from phony_normalize_numbers method).

PhonyRails.normalize_number('some number', :country_code => 'NL')
PhonyRails.normalize_number('some number', country_code: 'NL')

PhonyRails.normalize_number('+4790909090', :country_code => 'SE') # => '+464790909090' (forced to +46)
PhonyRails.normalize_number('+4790909090', :default_country_code => 'SE') # => '+4790909090' (still +47 so not changed)
PhonyRails.normalize_number('+4790909090', country_code: 'SE') # => '+464790909090' (forced to +46)
PhonyRails.normalize_number('+4790909090', default_country_code: 'SE') # => '+4790909090' (still +47 so not changed)
```

The country_code should always be a ISO 3166-1 alpha-2 (http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

### Validation

In your model use the Phony.plausible method to validate an attribute:

validates :phone_number, :phony_plausible => true

```ruby
validates :phone_number, phony_plausible: true
```
or the helper method:

validates_plausible_phone :phone_number
```ruby
validates_plausible_phone :phone_number
```

this method use other validators under the hood to provide:
* presence validation using `ActiveModel::Validations::PresenceValidator`
* format validation using `ActiveModel::Validations::FormatValidator`

so we can use:

validates_plausible_phone :phone_number, :presence => true
validates_plausible_phone :phone_number, :with => /^\+\d+/
validates_plausible_phone :phone_number, :without => /^\+\d+/
validates_plausible_phone :phone_number, :presence => true, :with => /^\+\d+/
```ruby
validates_plausible_phone :phone_number, presence: true
validates_plausible_phone :phone_number, with: /^\+\d+/
validates_plausible_phone :phone_number, without: /^\+\d+/
validates_plausible_phone :phone_number, presence: true, with: /^\+\d+/
```

the i18n key is `:improbable_phone`. Languages supported by default: de, en, fr, it, ja, kh and tr.
the i18n key is `:improbable_phone`. Languages supported by default: de, en, fr, it, ja, kh, tr, ua and ru.

You can also validate if a number has the correct country number:

validates_plausible_phone :phone_number, :country_number => '61'
```ruby
validates_plausible_phone :phone_number, country_number: '61'
```

or correct country code:

validates_plausible_phone :phone_number, :country_code => 'AU'
```ruby
validates_plausible_phone :phone_number, country_code: 'AU'
```

You can validate against the normalized input as opposed to the raw input:

phony_normalize :phone_number, as: :phone_number_normalized, :default_country_code => 'US'
validates_plausible_phone :phone_number, :normalized_country_code => 'US'
```ruby
phony_normalize :phone_number, as: :phone_number_normalized, default_country_code: 'US'
validates_plausible_phone :phone_number, normalized_country_code: 'US'
```

#### Allowing records country codes to not match phone number country codes

You may have a record specifying one country (via a `country_code` attribute) but using a phone number from another country. For example, your record may be from Japan but have a phone number from the Philippines. By default, `phony_rails` will consider your record's `country_code` as part of the validation. If that country doesn't match the country code in the phone number, validation will fail.

Additionally, `phony_normalize` will always add the records country code as the country number (eg. the user enters '+81xxx' for Japan and the records `country_code` is 'DE' then `phony_normalize` will change the number to '+4981'). You can turn this off by adding `:enforce_record_country => false` to the validation options. The country_code will then only be added if no country code is specified.
Additionally, `phony_normalize` will always add the records country code as the country number (eg. the user enters '+81xxx' for Japan and the records `country_code` is 'DE' then `phony_normalize` will change the number to '+4981'). You can turn this off by adding `enforce_record_country: false` to the validation options. The country_code will then only be added if no country code is specified.

If you want to allow records from one country to have phone numbers from a different one, there are a couple of options you can use: `ignore_record_country_number` and `ignore_record_country_code`. Use them like so:

validates :phone_number, :phony_plausible => { :ignore_record_country_code => true, :ignore_record_country_number => true }
```ruby
validates :phone_number, phony_plausible: { ignore_record_country_code: true, ignore_record_country_number: true }
```

Obviously, you don't have to use both, and you may not need or want to set either.

### Display / Views

In your views use:

<%= "311012341234".phony_formatted(:format => :international, :spaces => '-') %>
<%= "+31-10-12341234".phony_formatted(:format => :international, :spaces => '-') %>
<%= "+31(0)1012341234".phony_formatted(:format => :international, :spaces => '-') %>
```erb
<%= "311012341234".phony_formatted(format: :international, spaces: '-') %>
<%= "+31-10-12341234".phony_formatted(format: :international, spaces: '-') %>
<%= "+31(0)1012341234".phony_formatted(format: :international, spaces: '-') %>
```

To first normalize the String to a certain country use:

<%= "010-12341234".phony_formatted(:normalize => :NL, :format => :international, :spaces => '-') %>
```erb
<%= "010-12341234".phony_formatted(normalize: :NL, format: :international, spaces: '-') %>
```

To return nil when a number is not valid:

"123".phony_formatted(:strict => true) # => nil
```ruby
"123".phony_formatted(strict: true) # => nil
```

You can also use the bang method (phony_formatted!):

number = "010-12341234"
number.phony_formatted!(:normalize => :NL, :format => :international)
number # => "+31 10 123 41234"
```ruby
number = "010-12341234"
number.phony_formatted!(normalize: :NL, format: :international)
number # => "+31 10 123 41234"
```

You can also easily normalize a phone number String:

"+31 (0)30 1234 123".phony_normalized # => '31301234123'
"(0)30 1234 123".phony_normalized # => '301234123'
"(0)30 1234 123".phony_normalized(country_code: 'NL') # => '301234123'
```ruby
"+31 (0)30 1234 123".phony_normalized # => '31301234123'
"(0)30 1234 123".phony_normalized # => '301234123'
"(0)30 1234 123".phony_normalized(country_code: 'NL') # => '301234123'
```

### Find by normalized number

Say you want to find a record by a phone number. Best is to normalize user input and compare to an attribute stored in the db.

Home.find_by_normalized_phone_number(PhonyRails.normalize_number(params[:phone_number]))
```ruby
Home.find_by_normalized_phone_number(PhonyRails.normalize_number(params[:phone_number]))
```

## Contributing

Expand Down