README.md in sandboxy-2.0.0 vs README.md in sandboxy-3.0.0
- old
+ new
@@ -10,11 +10,10 @@
* [Installation](#installation)
* [Usage](#usage)
* [Setup](#setup)
* [`sandboxy` methods](#sandboxy-methods)
- * [Sandboxy class methods](#sandboxy-class-methods)
* [Switching environments](#switching-environments)
* [Sandbox & APIs](#sandbox--apis)
* [Configuration](#configuration)
* [Testing](#testing)
* [Test Coverage](#test-coverage)
@@ -26,11 +25,11 @@
---
## Installation
-Sandboxy works with Rails 5.0 onwards. You can add it to your `Gemfile` with:
+Sandboxy works with Rails 5 onwards. You can add it to your `Gemfile` with:
```ruby
gem 'sandboxy'
```
@@ -58,11 +57,11 @@
## Usage
### Setup
-Add Sandboxy to the models where you want to separate live & sandbox records:
+Add Sandboxy to the models where you want to separate records depending on their environments:
```ruby
class Foo < ApplicationRecord
sandboxy
end
@@ -70,98 +69,89 @@
In most use cases you would want to add `sandboxy` to a lot of ActiveRecord models if not all. To simplify that you could create a new class and let all your models inherit from it:
```ruby
class SharedSandbox < ApplicationRecord
+ self.abstract_class = true
sandboxy
end
class Foo < SharedSandbox
end
```
### `sandboxy` methods
-By default you can only access records belonging to the current environment (`live` or `sandbox`):
+By default you can only access records belonging to the current environment (defined by `Sandboxy.environment`):
```ruby
-$sandbox = true
+Sandboxy.environment = 'test'
+Foo.all # => returns all test foo's
+Sandboxy.environment = 'sandbox'
Foo.all # => returns all sandbox foo's
```
-Now to access the records belonging to a certain group regardless of your current environment, you can use:
+Now to access the records belonging to a certain environment regardless of your current environment, you can use:
```ruby
-Foo.live # => returns all live foo's
-Foo.sandboxed # => returns all sandbox foo's
+Foo.live_environment # => returns all live foo's
+Foo.sandbox_environment # => returns all sandbox foo's
Foo.desandbox # => returns all foo's
```
Let's check to which environment this `Foo` belongs:
```ruby
foo = Foo.create!
-foo.live? # => false
-foo.sandboxed? # => true
+foo.live_environment? # => false
+foo.sandbox_environment? # => true
```
You should keep in mind that when you create a new record, it will automatically belong to your app's current environment.
Don't worry, you can move records between environments:
```ruby
-foo.make_live
-foo.live? # => true
-foo.make_sandboxed
-foo.sandboxed? # => true
+foo.move_environment_live
+foo.live_environment? # => true
+foo.move_environment_sandbox
+foo.sandbox_environment? # => true
```
-### `Sandboxy` class methods
+### Switching environments
-To access your default environment setting:
+At runtime you can always switch environments anywhere in your application by setting `Sandboxy.environment`. You can set it to any string you like. That makes Sandboxy super flexible.
```ruby
-Sandboxy.configuration.environment # => 'live' / 'sandbox'
-Sandboxy.configuration.sandbox? # => true / false
-Sandboxy.configuration.live? # => true / false
+Sandboxy.environment = 'live'
+Sandboxy.live_environment? # => true
+Sandboxy.sandbox_environment? # => true
```
-**Note:** `Sandboxy.configuration.environment` does *NOT* return the apps current environment. For that use the [`$sandbox` variable](#switching-environments) instead.
-
-You can also access whether your app retains your environment throughout requests:
-
-```ruby
-Sandboxy.configuration.retain_environment # => true / false
-```
-
-### Switching environments
-
-At runtime you can always switch environments by using the `$sandbox` variable anywhere in your application. Set it to `true` to enable the `sandbox` environment. Set it to `false` to enable the `live` environment. That makes Sandboxy super flexible.
-
#### Sandbox & APIs
It's flexibility allows Sandboxy to work really well with APIs.
Typically an API provides two sets of authentication credentials for a consumer - one for live access and one for sandbox/testing.
-Whenever you authenticate your API's consumer, just make sure to set the `$sandbox` variable accordingly to the credential the consumer used. From thereon, Sandboxy will make sure that your consumer only reads & updates data from the environment he is in.
+Whenever you authenticate your API's consumer, just make sure to set `Sandboxy.environment` accordingly to the credential the consumer used. From thereon, Sandboxy will make sure that your consumer only reads & updates data from the environment he is in.
---
## Configuration
You can configure Sandboxy by passing a block to `configure`. This can be done in `config/initializers/sandboxy.rb`:
```ruby
Sandboxy.configure do |config|
- config.environment = 'sandbox'
+ config.default = 'sandbox'
end
```
-**`environment`** Set your environment default: Must be either `live` or `sandbox`. This is the environment that your app boots with. By default it gets refreshed with every new request to your server. Defaults to `'live'`.
+**`default`** Set your environment default. This is the environment that your app boots with. By default it gets refreshed with every new request to your server. Takes a string. Defaults to `'live'`.
-**`retain_environment`** Specify whether to retain your current app environment on new requests. If set to `true`, your app will only load your environment default when starting. Every additional switch of your environment at runtime will then not be automatically resolved to your environment default on a new request. Takes a boolean. Defaults to `false`.
+**`retain`** Retain your current app environment on new requests. If set to `false`, your app will return to your default environment on every new request. Takes a boolean. Defaults to `false`.
---
## Testing
@@ -179,10 +169,10 @@
### Test Coverage
Test coverage can be calculated using SimpleCov. Make sure you have the [simplecov gem](https://github.com/colszowka/simplecov) installed.
-1. Uncomment SimpleCov in the Gemfile
+1. Add SimpleCov to the Gemfile
2. Uncomment the relevant section in `test/test_helper.rb`
3. Run tests
`$ rake test`