rest_framework 0.9.2 → 0.9.3

data/docs/_guide/2_controller_mixins.md

@@ -1,293 +0,0 @@
----
-layout: default
-title: Controller Mixins
-position: 2
-slug: controller-mixins
----
-# Controller Mixins
-
-This is the core of the REST Framework. Generally speaking, projects already have an existing
-controller inheritance hierarchy, so we want developers to be able to maintain that project
-structure while leveraging the power of the REST Framework. Also, different controllers which
-inherit from the same parent often need different REST Framework mixins. For these reasons, REST
-Framework provides the controller functionality as modules that you mix into your controllers.
-
-## Response Rendering
-
-Before we go into the various controller mixins, one of the core capabilities of the REST Framework
-is to provide system-consumable responses along side a browsable API for developers. While you can
-use Rails' builtin rendering tools, such as `render`, the REST Framework provides a rendering helper
-called `api_response`. This helper allows you to return a browsable API response for the `html`
-format which shows you what the JSON/XML response would look like, along with faster and lighter
-responses for `json` and `xml` formats.
-
-Here is an example:
-
-```ruby
-class ApiController < ApplicationController
-  include RESTFramework::BaseControllerMixin
-  self.extra_actions = {test: :get}
-
-  def test
-    api_response({message: "Test successful!"})
-  end
-end
-```
-
-## `BaseControllerMixin`
-
-To transform a controller into the simplest possible RESTful controller, you can include
-`BaseControllerMixin`, which provides a simple `root` action so it can be used at the API root.
-
-```ruby
-class ApiController < ApplicationController
-  include RESTFramework::BaseControllerMixin
-end
-```
-
-### Controller Attributes
-
-You can customize the behavior of `BaseControllerMixin` by setting or mutating various class
-attributes.
-
-#### `singleton_controller`
-
-This property primarily controls the routes that are generated for a RESTful controller. If you use
-`api_resource`/`api_resources` to define whether the generates routes are for a collection or for
-a single member, then you do not need to use this property. However, if you are autogenerating those
-routers, then `singleton_controller` will tell REST Framework whether to provide collection routes
-(when `singleton_controller` is falsy) or member routes (when `singleton_controller` is truthy). To
-read more about singular vs plural routing, see Rails' documentation here:
-https://guides.rubyonrails.org/routing.html#singular-resources.
-
-#### `extra_actions`
-
-This property defines extra actions on the controller to be routed. It is a hash of
-`endpoint -> method(s)` (where `method(s)` can be a method symbol or an array of method symbols).
-
-```ruby
-class ApiController < ApplicationController
-  include RESTFramework::BaseControllerMixin
-  self.extra_actions = {test: :get}
-
-  def test
-    api_response({message: "Test successful!"})
-  end
-end
-```
-
-Or with multiple methods:
-
-```ruby
-class ApiController < ApplicationController
-  include RESTFramework::BaseControllerMixin
-  self.extra_actions = {test: [:get, :post]}
-
-  def test
-    api_response({message: "Test successful!"})
-  end
-end
-```
-
-If your action conflicts with a builtin method, then you can also override the path:
-
-```ruby
-class ApiController < ApplicationController
-  include RESTFramework::BaseControllerMixin
-
-  # This will route `test_action` to `/test`, in case there is already a `test` method that cannot
-  # be overridden.
-  self.extra_actions = {test_action: {path: :test, methods: :get}}
-
-  def test_action
-    api_response({message: "Test successful!"})
-  end
-end
-```
-
-## `ModelControllerMixin`
-
-`ModelControllerMixin` assists with providing the standard model CRUD (create, read, update,
-destroy) for your controller. This is the most commonly used mixin since it provides default
-behavior for models which matches Rails' default routing.
-
-```ruby
-class Api::MoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-end
-```
-
-By default, all columns and associations are included in `self.fields`, which can be helpful when
-developing an administrative API. For user-facing APIs, however, `self.fields` should always be
-explicitly defined.
-
-### Controller Attributes
-
-You can customize the behavior of `ModelControllerMixin` by setting or mutating various class
-attributes.
-
-#### `model`
-
-The `model` property allows you to define the model if it is not obvious from the controller name.
-
-```ruby
-class Api::CoolMoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-
-  self.model = Movie
-end
-```
-
-#### `recordset`
-
-The `recordset` property allows you to define the set of records this API should be limited to. If
-you need to change the recordset based on properties of the request, then you can override the
-`get_recordset()` method.
-
-```ruby
-class Api::CoolMoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-
-  self.recordset = Movie.where(cool: true).order({id: :asc})
-end
-```
-
-#### `extra_member_actions`
-
-The `extra_member_actions` property allows you to define additional actions on individual records.
-
-```ruby
-class Api::MoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-
-  self.extra_member_actions = {disable: :post}
-
-  def disable
-    @record = self.get_record  # REST Framework will rescue ActiveRecord::RecordNotFound
-
-    # REST Framework will rescue ActiveRecord::RecordInvalid or ActiveRecord::RecordNotSaved
-    @record.update!(enabled: false)
-
-    return api_response(@record)
-  end
-end
-```
-
-#### `fields`
-
-The `fields` property defines the default fields for serialization and for parameters allowed from
-the body or query string.
-
-```ruby
-class Api::MoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-
-  self.fields = [:id, :name]
-end
-```
-
-#### `action_fields`
-
-The `action_fields` property is similar to `fields`, but allows you to define different fields for
-different actions. A good example is to serialize expensive computed properties only in the `show`
-action, but not in the `list` action (where many records are serialized).
-
-```ruby
-class Api::MoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-
-  self.fields = [:id, :name]
-  self.action_fields = {
-    show: [:id, :name, :some_expensive_computed_property],
-  }
-end
-```
-
-#### `native_serializer_config`
-
-These properties define the serializer configuration if you are using the native `ActiveModel`
-serializer. You can also specify serializers for singular/plural
-
-```ruby
-class Api::MoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-
-  self.native_serializer_config = {
-    only: [:id, :name],
-    methods: [:active, :some_expensive_computed_property],
-    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
-  }
-
-  # Or you could configure a default and a plural serializer:
-  self.native_serializer_plural_config = {
-    only: [:id, :name],
-    methods: [:active],
-    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
-  }
-  self.native_serializer_config = {
-    only: [:id, :name],
-    methods: [:active, :some_expensive_computed_property],
-    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
-  }
-
-  # Or you could configure a default and a singular serializer:
-  self.native_serializer_config = {
-    only: [:id, :name],
-    methods: [:active],
-    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
-  }
-  self.native_serializer_singular_config = {
-    only: [:id, :name],
-    methods: [:active, :some_expensive_computed_property],
-    include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
-  }
-end
-```
-
-#### `allowed_parameters` / `allowed_action_parameters`
-
-These properties define the permitted parameters to be used in the request body for create/update
-actions. If you need different allowed parameters, then you can also override the
-`get_create_params` or `get_update_params` methods.
-
-```ruby
-class Api::MoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-
-  self.allowed_parameters = [:name]
-end
-```
-
-#### `create_from_recordset` (default: `true`)
-
-The `create_from_recordset` attribute (`true` by default) is a boolean to control the behavior in
-the `create` action. If it is disabled, records will not be created from the filtered recordset, but
-rather will be created directly from the model interface.
-
-For example, if this is your controller:
-
-```ruby
-class Api::CoolMoviesController < ApiController
-  include RESTFramework::ModelControllerMixin
-
-  def get_recordset
-    return Movie.where(cool: true)
-  end
-end
-```
-
-Then if you hit the `create` action with the payload `{name: "Superman"}`, it will also set `cool`
-to `true` on the new record, because that property is inherited from the recordset.
-
-## `ReadOnlyModelControllerMixin`
-
-`ReadOnlyModelControllerMixin` only enables list/show actions. In this example, since we're naming
-this controller in a way that doesn't make the model obvious, we can set that explicitly:
-
-```ruby
-class Api::ReadOnlyMoviesController < ApiController
-  include RESTFramework::ReadOnlyModelControllerMixin
-
-  self.model = Movie
-end
-```

data/docs/assets/css/rest_framework.css

@@ -1,159 +0,0 @@
-/********************************
- * START OF LIB/DOCS COMMON CSS *
- ********************************/
-
- :root {
-  --rrf-red: #900;
-  --rrf-red-hover: #5f0c0c;
-  --rrf-light-red: #db2525;
-  --rrf-light-red-hover: #b80404;
-}
-#rrfAccentBar {
-  background-color: var(--rrf-red);
-  height: .3em;
-}
-header nav { background-color: black; }
-
-/* Header adjustments. */
-h1 { font-size: 2rem; }
-h2 { font-size: 1.7rem; }
-h3 { font-size: 1.5rem; }
-h4 { font-size: 1.3rem; }
-h5 { font-size: 1.1rem; }
-h6 { font-size: 1rem; }
-h1, h2, h3, h4, h5, h6 {
-  color: var(--rrf-red);
-}
-html[data-bs-theme="dark"] h1,
-html[data-bs-theme="dark"] h2,
-html[data-bs-theme="dark"] h3,
-html[data-bs-theme="dark"] h4,
-html[data-bs-theme="dark"] h5,
-html[data-bs-theme="dark"] h6 {
-  color: var(--rrf-light-red);
-}
-
-/* Improve code and code blocks. */
-pre code {
-  display: block;
-  overflow-x: auto;
-}
-code, .trix-content pre {
-  padding: .5em !important;
-  background-color: #eee !important;
-  border: 1px solid #aaa;
-  border-radius: 3px;
-}
-p code {
-  padding: .1em .3em !important;
-}
-html[data-bs-theme="dark"] code, html[data-bs-theme="dark"] .trix-content pre {
-  background-color: #2b2b2b !important;
-}
-
-/* Anchors */
-a:not(.nav-link) {
-  text-decoration: none;
-  color: var(--rrf-red);
-}
-a:hover:not(.nav-link) {
-  text-decoration: underline;
-  color: var(--rrf-red-hover);
-}
-html[data-bs-theme="dark"] a:not(.nav-link) { color: var(--rrf-light-red); }
-html[data-bs-theme="dark"] a:hover:not(.nav-link) { color: var(--rrf-light-red-hover); }
-
-/******************************
- * END OF LIB/DOCS COMMON CSS *
- ******************************/
-
-/* Header adjustments. */
-h1, h2, h3, h4, h5, h6 {
-  width: 100%;
-  font-weight: normal;
-  margin-top: 1.8rem;
-  margin-bottom: 1.2rem;
-}
-h1 a:not(:hover),
-h2 a:not(:hover),
-h3 a:not(:hover),
-h4 a:not(:hover),
-h5 a:not(:hover),
-h6 a:not(:hover) {
-  color: #ddd;
-}
-html[data-bs-theme="dark"] h1 a:not(:hover),
-html[data-bs-theme="dark"] h2 a:not(:hover),
-html[data-bs-theme="dark"] h3 a:not(:hover),
-html[data-bs-theme="dark"] h4 a:not(:hover),
-html[data-bs-theme="dark"] h5 a:not(:hover),
-html[data-bs-theme="dark"] h6 a:not(:hover) {
-  color: #444;
-}
-h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover {
-  text-decoration: none !important;
-}
-
-/* Navbar */
-.navbar .navbar-toggler {
-  margin: .2em 0;
-  padding: .2em .3em;
-  border: none;
-}
-.navbar .navbar-toggler .navbar-toggler-icon {
-  height: 1.1em;
-  width: 1.1em;
-}
-.navbar .navbar-nav .nav-item .nav-link {
-  padding: .45em .6em;
-}
-.navbar .navbar-nav .nav-item .nav-link:hover {
-  background-color: #262a2f;
-}
-.navbar .dropdown-menu a.dropdown-item {
-  font-size: .9em;
-  padding: .2em .8em;
-}
-
-/* Headers table. */
-.headers-table {
-  padding: .5em 1em;
-  background-color: #eee;
-  border: 1px solid #aaa;
-  border-radius: .3em;
-  font-size: .9em;
-}
-html[data-bs-theme="dark"] .headers-table {
-  background-color: #2b2b2b;
-}
-.headers-table:empty { display: none; }
-.headers-table ul {
-  list-style-type: none;
-  margin: 0;
-  padding-left: 0;
-  padding-right: .6em;
-}
-.headers-table ul li { margin: .3em 0; }
-.headers-table ul ul { padding-left: .8em; padding-right: 0; }
-.headers-table > ul > li {
-  font-weight: bold;
-}
-
-/* Style the github and mode component. */
-#rrfGithubAndModeWrapper {
-  height: 2.4em;
-}
-#rrfGithubComponent {
-  display: inline-block;
-  position: relative;
-  top: .6em;
-}
-#rrfModeComponent .dropdown-toggle {
-  float: right;
-}
-#rrfModeComponent .dropdown-menu {
-  position: absolute;
-  right: 0;
-  left: auto;
-  top: 100%;
-}