README.md in set_as_primary-0.1.1 vs README.md in set_as_primary-0.1.2
- old
+ new
@@ -1,14 +1,21 @@
# SetAsPrimary
-The simplest way to handle the primary or default flag (:white_check_mark:) to
+The simplest way to handle the primary or default flag to
your Rails models.
-Supports PostgreSQL, MySQL, and SQLite.
+Features:
+* Supports single model (without association), model with (`belongs_to`) association, and even polymorphic associations
+* Force primary
+* Supports PostgreSQL's unique partial index (constraint)
+* Supports PostgreSQL, MySQL, and SQLite
+
+
+
[Demo Rails application](https://cryptic-lake-90495.herokuapp.com/) |
-[Demo Rails application GitHub repository](https://github.com/mechanicles/set_as_primary_rails_app)
+[Source code of Demo Rails application](https://github.com/mechanicles/set_as_primary_rails_app)
[](https://travis-ci.org/mechanicles/set_as_primary)
## Installation
@@ -31,11 +38,11 @@
In your Rails application, you might have models like EmailAddress, PhoneNumber,
Address, etc., which belong to the User/Person model or polymorphic model. There,
you might need to set a primary email address, primary phone number, or default
address for a user, and this gem helps you to do that.
-It also supports single model with no association's context.
+It also supports a single model with no association context.
Examples:
```ruby
class User < ApplicationRecord
@@ -55,46 +62,81 @@
belongs_to :owner, polymorphic: true
set_as_primary :primary, owner_key: :owner
end
-# Single model with no owner/association's context.
+# Single model with no owner/association context.
class Post < ApplicationRecord
include SetAsPrimary
- set_as_primary
+ set_as_primary :primary
end
```
You need to include `SetAsPrimary` module in your model where you want to handle the primary flag.
Then to `set_as_primary` class helper method, pass your primary flag attribute. You might need to pass
- association key `owner_key` if you wan to consider owner's (association's) context.
+ association key `owner_key` if you wan to consider owner (association) context.
-**NOTE:** Default primary flag attribute is `primary`, and you can use another one too like `default` but
-make sure that flag should be present in the table and should be a boolean column type.
+**Note:** Default primary flag attribute is `primary`, and you can use another one too like `default` but
+make sure that flag should be present in the table and should be a boolean data type column.
#### Migration
If your table does not have the primary flag column, then you can add it by running
following command in your rails project:
```ssh
-rails generate set_as_primary your_table_name
+rails generate set_as_primary your_table_name flag_name
```
-If you run above command for `email_addresses` table, then it creates
-migration like this:
+Example:
+If you want to add a `primary` column to your `posts` table, then you can run command like this:
+
+```shell
+rails generate set_as_primary posts primary
+```
+
+Then migration gets created like this:
+
```ruby
+class AddPrimaryColumnToPosts < ActiveRecord::Migration[6.0]
+ def change
+ add_column :posts, :primary, :boolean, default: false, null: false
+ # NOTE: Please uncomment following line if you want only one 'true' (constraint) in the table.
+ # add_index :posts, :primary, unique: true, where: "(posts.primary IS TRUE)"
+ end
+end
+```
+
+If you want to create a primary column to `email_addresses` table, then you can run command like this:
+
+```shell
+rails generate set_as_primary email_addresses primary user
+```
+
+Then it creates migration like this:
+
+```ruby
class AddPrimaryColumnToEmailAddresses < ActiveRecord::Migration[6.0]
def change
add_column :email_addresses, :primary, :boolean, default: false, null: false
+ # NOTE: Please uncomment following line if you want only one 'true' (constraint) in the table.
+ # add_index :email_addresses, %i[user_id, primary], unique: true, where: "(email_addresses.primary IS TRUE)"
end
end
```
-Don't forget to run `rails db:migrate` to create actual column in the table.
+You might have seen extra commented lines there. These lines are there for handling the unique constraint. Currently, these lines get created only for `PostgreSQL` adapter as it supports partial index.
+Please note that here we have passed an extra option `user` in the command that is nothing but the owner/association name. This extra option helps to handle the unique partial index.
+
+**Note:** Partial indexes are only supported for PostgreSQL and SQLite 3.8.0+. But I also found that SQLite gives an error so currently this gem only supports PostgreSQL's unique partial index constraint.
+
+**Even if we don't have constraint (only one 'true' constraint in the table), this gem takes care of it so don't worry about the constraint.**
+
+Once migration file gets created, don't forget to run `rails db:migrate` to create an actual column in the table.
+
#### force_primary
```ruby
class Address < ApplicationRecord
include SetAsPrimary
@@ -111,11 +153,9 @@
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run
`rake test` to run the tests. You can also run `bin/console` for an interactive
prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`.
## Contributing
Bug reports and pull requests are welcome on GitHub at
https://github.com/mechanicles/set_as_primary. This project is intended to be a
\ No newline at end of file