README.md in sandboxy-1.0.0 vs README.md in sandboxy-1.1.0
- old
+ new
@@ -1,19 +1,21 @@
# Sandboxy - virtual data-oriented environments for Rails
<img src="https://travis-ci.org/slooob/sandboxy.svg?branch=master" /> [](https://badge.fury.io/rb/sandboxy)
-Sandboxy allows you to use two virtual data-oriented environments inside a Rails application with ActiveRecord while being able to switch in between at runtime.
+Sandboxy allows you to use virtual data-oriented environments inside a Rails application while being able to switch in between at runtime. It achieves that by using a combination of Rack Middleware and ActiveRecord.
---
## Table of Contents
* [Installation](#installation)
* [Usage](#usage)
* [Setup](#setup)
+ * [Configuration](#configuration)
* [Sandboxed methods](#sandboxed-methods)
+ * [Sandboxy methods](#sandboxy-methods)
* [Switching environments](#switching-environments)
* [Sandbox & APIs](#sandbox--apis)
* [To Do](#to-do)
* [Contributing](#contributing)
* [Contributors](#contributors)
@@ -45,43 +47,53 @@
Now run the generator:
$ rails g sandboxy
-You can specify that your application should use the sandbox by default by passing `--default true`. Learn more about switching environments [here](#switching-environments).
+You can specify your applications default environment by passing `--default live` or `--default sandbox`. Learn more about switching environments [here](#switching-environments).
+To set that your app should retain it's environment at runtime on new requests pass `--retain_environment true`.
+
+You can always update your [configuration](#configuration) later.
+
To wrap things up, migrate the changes into your database:
$ rails db:migrate
**Note:** Use `rake db:migrate` instead if you run Rails < 5.
-This will create an initializer as well as a migration file and the `Sandbox` model.
+This will create a configuration file under `config/sandboxy.yml` as well as a migration file and the `Sandbox` model.
## Usage
### Setup
-Add Sandboxy to the models where you want to separate live & sandbox reocrds:
+Add Sandboxy to the models where you want to separate live & sandbox records:
```ruby
class Foo < ApplicationRecord
sandboxy
end
```
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 Sandboxy < ApplicationRecord
+class SharedSandbox < ApplicationRecord
sandboxy
end
-class Foo < Sandboxy
+class Foo < SharedSandbox
end
```
+### Configuration
+
+In `config/sandboxy.yml` you define your app's default environment. This can be either set to `live` or `sandbox`. It defaults to `live`.
+
+Now this default gets refreshed before every new request. To retain any environment you [switched in at runtime](#switching-environments), you need to set `retain_environment` to `true`. Defaults to `false`.
+
### Sandboxed methods
By default you can only access records belonging to the current environment (`live` or `sandbox`):
```ruby
@@ -114,14 +126,30 @@
foo.live? # => true
foo.make_sandboxed
foo.sandboxed? # => true
```
-### Switching environments
+### Sandboxy methods
-In `config/initializers/sandboxy.rb` you define your app's default environment by setting the `$sandbox` variable.
+To access your default environment setting:
-You can override that variable anywhere in your application. That makes Sandboxy super flexible.
+```ruby
+Sandboxy.environment # => 'live' / 'sandbox'
+Sandboxy.sandbox? # => true / false
+Sandboxy.live? # => true / false
+```
+
+**Note:** `Sandboxy.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 request:
+
+```ruby
+Sandboxy.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.