compony 0.7.0 → 0.7.1

data/doc/guide/pre_built_components/form.md

@@ -0,0 +1,117 @@
+- [Back to the guide](/README.md#guide)
+- [List of pre-built components](/doc/guide/pre_built_components.md)
+
+# Pre-built components: Form
+
+This component holds a form and should only be instantiated by the `form_comp` call of a component that inherits from [`WithForm`](./with_form.md).
+
+`Compony::Components::Form` is an abstract base class for any components presenting a regular form. This class comes with a lot of tooling for rendering forms and inputs, as well as validating parameters. When the component is rendered, the Gem SimpleForm is used to create the actual form: [https://github.com/heartcombo/simple_form](https://github.com/heartcombo/simple_form).
+
+Parameters are structured like typical Rails forms. For instance, if you have a form for a `User` model and the attribute is `first_name`, the parameter looks like `user[first_name]=Tom`. In this case, we will call `user` the `schema_wrapper_key`. Parameters are validated using Schemacop: [https://github.com/sitrox/schemacop](https://github.com/sitrox/schemacop).
+
+The following DSL calls are provided by the Form component:
+
+- Required: `form_fields` takes a block that renders the inputs of your form. More on that below.
+- Optional: `skip_autofocus` will prevent the first input to be auto-focussed when the user visits the form.
+- Typically required: `schema_fields` takes the names of fields as a whitelist for strong parameters. Together with model fields, this will completely auto-generate a Schemacop schema suitable for validating this form. If your argument list gets too long, you can use multiple calls to `schema_field` instead to declare your fields one by one on separate lines.
+- Optional: `schema_line` takes a single Schemacop line. Use this for custom whitelisting of an argument, e.g. if you have an input that does not have a corresponding model field.
+- Optional: `schema` allows you to instead fully define your own custom Schemacop V3 schema manually. Note that this disables all of the above schema calls.
+- Optional: `disable!` causes generated inputs to be disabled. Alternatively, `disabled: true` can be passed to the initializer to achieve the same result.
+
+The `form_fields` block acts much like a content block and you will use Dyny there. Two additional methods are made available exclusively inside the block:
+
+- `field` (not to be confused with the model mixin's static method) takes the name of a model field and auto-generates a suitable SimpleForm input as defined in the field's type.
+- `f` gives you direct access to the `simple_form` instance. You can use it to write e.g. `f.input(...)`.
+
+Here is a simple example for a form for a sample user:
+
+```ruby
+class Components::Users::Form < Compony::Components::Form
+  setup do
+    form_fields do
+      concat field(:first_name)
+      concat field(:last_name)
+      concat field(:age)
+      concat field(:comment)
+      concat field(:role)
+    end
+    schema_fields :first_name, :last_name, :age, :comment, :role
+  end
+end
+```
+
+Note that the inputs and schema are two completely different concepts that are not auto-inferred from each other. You must make sure that they always correspond. If you forget to mention a field in `schema_fields`, posting the form will fail. Luckily, Schemacop's excellent error messaging will explain which parameter is prohibited.
+
+Both calls respect Cancancan's `permitted_attributes` directive. This means that you can safely declare `field` and `schema_field` in a form that is shared among users with different kinds of permissions. If the current user is not allowed to access a field, the input will be omitted automatically. Further, the parameter validation will exclude that field, effectively disallowing that user from submitting that parameter.
+
+## Handling password fields
+
+When using Rails' `has_secure_password` method, which typically generates the attributes accessors `:password` and `password_confirmation`, do not declare these two as fields in your User model.
+
+There are two main reasons for this:
+
+- `password` and `password_confirmation` should never show up in lists and show pages, and as these kinds of components tend to iterate over all fields, it's best to have anything that should not show up there declared as a field in the first place.
+- Rails' `authenticate_by` does not work when `password` is declared as a model attribute.
+
+Instead of making these accessors Compony fields, ignore them in the User model and use the following methods in your Form:
+
+```ruby
+class Components::Users::Form < Compony::Components::Form
+  setup do
+    form_fields do
+      # ...
+      concat pw_field(:password)
+      concat pw_field(:password_confirmation)
+    end
+
+    # ...
+    schema_pw_field :password
+    schema_pw_field :password_confirmation
+  end
+end
+```
+
+In contrast to the regular `field` and `schema_field` calls, their `pw_...` pendants do not check for per-field authorization. Instead, they check whether the current user can `:set_password` on the form's object. Therefore, your ability may look something like:
+
+```ruby
+class Ability
+  # ...
+  can :manage, User # This allows full access to all users
+  cannot :manage, User, [:user_role] # This prohibits access to user_role, thus removing the input and making the parameter invalid if passed anyway
+  cannot :set_password, User # This prohibits setting and changing passwords of any user
+```
+
+## Dealing with multilingual fields
+
+When using Gems such as `mobility`, Compony provides support for multilingual fields. For instance, assuming that a model has the attribute `label` translated in English and German, making `label` a virtual attribute reading either `label_en` and `label_de`, depending on the user's language, Compony automatically generates a multilingual field if the following is used:
+
+In the model:
+
+```ruby
+class Foo < ApplicationRecord
+  # No need to write:
+  field :label, :string, virtual: true
+  I18n.available_locales.each do |locale|
+    field :"label_#{locale}", :string
+  end
+
+  # Instead, write this, which is equivalent:
+  field :label, :string, multilang: true
+end
+```
+
+In the same mindset, you can simplify your form as follows to generate one input per language:
+
+```ruby
+class Components::Foos::Form < Compony::Components::Form
+  setup do
+    form_fields do
+      # Since `field` only generates an input, you must loop over them and render them as you wish, e.g. with "concat":
+      field(:label, multilang: true).each { |inp| concat inp }
+    end
+
+    # Don't forget to mark `schema_field` as multilingual as well, which will accept label_en and label_de:
+    schema_field :label, multilang: true
+  end
+end
+```

data/doc/guide/pre_built_components/index.md

@@ -0,0 +1,6 @@
+- [Back to the guide](/README.md#guide)
+- [List of pre-built components](/doc/guide/pre_built_components.md)
+
+# Pre-built components: Index
+
+This stanalone component is resourceful, holds a collection of records and corresponds to Rail's `index` controller action. It is a wrapper for the [`List` component](./list.md).

data/doc/guide/pre_built_components/list.md

@@ -0,0 +1,14 @@
+- [Back to the guide](/README.md#guide)
+- [List of pre-built components](/doc/guide/pre_built_components.md)
+
+# Pre-built components: List
+
+This resourceful component displays a table / list of records. It is meant to be nested within another component, typically [`Index`](./index.md) of the same family or [`Show`](./show.md) of another family. Compony's implementation of this component features:
+
+- Inferrence of rows from model fields as well as custom rows
+- Row actions for each displayed record
+- Pagination
+- Sorting: if the Ransack gem is installed and at least one sorting column has been specified, the component can automatically generate a select input for sorting as well as sorting links.
+- Filtering / Searching: if the Ransack gem is installed and at least one filter has been specified, the component can automatically generate a filter / search form that works with Ransack.
+
+This component serves as a base block for building powerful management interfaces. Consult the component's class to learn about the various methods you can use in `setup` in order to customize the behavior. You will likely want to implement your own custom base component based on this component and overwrite the `content` blocks that you would like to customize.

data/doc/guide/pre_built_components/new.md

@@ -0,0 +1,27 @@
+- [Back to the guide](/README.md#guide)
+- [List of pre-built components](/doc/guide/pre_built_components.md)
+
+# Pre-built components: New
+
+This component is the Compony equivalent to a typical Rails controller's `new` and `create` actions.
+
+`Compony::Components::New` is a resourceful standalone component based on [`WithForm`](./with_form.md) that listens to two verbs:
+
+- GET will cause the New component to create a fresh instance of its `data_class` and render the form.
+- POST (equivalent to a `create` action in a controller) will attempt to save the resource. If that fails, the form is rendered again with a HTTP 422 code ("unprocessable entity"). If the creation succeeds, a flash is shown and the user is redirected:
+  - if present: the data's Show component
+  - otherwise, if the resource is owned by another resource class: the owner's Show component
+  - otherwise, the data's Index component
+
+Authorization checks for `create` even in GET. The reason is that it makes no sense to present an empty form to a user who cannot create a new record. This also causes any `compony_link` and `compony_button` to New components to be hidden to users lacking the permission.
+
+This component follows the [resourceful lifecycle](/doc/guide/resourceful.md#complete-resourceful-lifecycle). `load_data` is set to create a new record and `store_data` attempts to create it. Parameters are validated in `assign_attributes` using a Schemacop schema that is generated from the form. The schema corresponds to Rail's typical strong parameter structure for forms. For example, a user's New component would look for a parameter `user` holding a hash of attributes (e.g. `user[first_name]=Tom`).
+
+In case you overwrite `store_data`, make sure to set `@create_succeeded` to true if storing was successful (and to set it to false otherwise).
+
+The following DSL calls are implemented to allow for convenient overrides of default logic:
+
+- The block `on_create_failed_respond` is run if `@create_succeeded` is not true. By default, it logs all error messages with level `warn` and renders the component again through HTTP 422, causing Turbo to correctly display the page. Error messages are displayed by the form inputs.
+- The block `on_created` is evaluated between successful record creation and responding. By default, it is not implemented and doing so is optional. This would be a suitable location for hooks that update state after a resource was created (like an `after_create` hook, but only executed if a record was created by this component). Do not redirect or render here, use the next blocks instead.
+- The block given in `on_created_respond` is evaluated after successful creation and by default shows a flash, then redirects. Overwrite this block if you need to completely customize all logic that happens after creation. If this block is overwritten, `on_created_redirect_path` will not be called.
+- `on_created_redirect_path` is evaluated as the second step of `on_created_respond` and redirects to the resource's Show, its owner's Show, or its own Index component as described above. Overwrite this block in order to redirect ot another component instead, while keeping the default flash provided by `on_created_respond`.

data/doc/guide/pre_built_components/show.md

@@ -0,0 +1,8 @@
+- [Back to the guide](/README.md#guide)
+- [List of pre-built components](/doc/guide/pre_built_components.md)
+
+# Pre-built components: Show
+
+This resourceful component corresponds to a typical Rails controller's `show` action and presents `@data` which is typically a model instance.
+
+To use it, create a component of the style `Components::Users::Show` and inherit from `Compony::Components::Show`. By default, this will display all permitted fields along with their labels. Consult the component's class to learn about the methods you can use in `setup` in order to customize the behavior.

data/doc/guide/pre_built_components/with_form.md

@@ -0,0 +1,18 @@
+- [Back to the guide](/README.md#guide)
+- [List of pre-built components](/doc/guide/pre_built_components.md)
+
+# Pre-built components: WithForm
+
+`Compony::Components::WithForm` is an abstract base class for components that render a form. Those components can further be resourceful, but don't have to be. If a component inherits from WithForm, it is always twinned with another component that will provide the form.
+
+WithForm adds the following DSL methods:
+
+- `form_comp_class` sets the class that will be instantiated by `form_comp`
+- `form_comp` returns an instance of the Form component twinned with this component. If `form_comp_class` was never set, it will default to loading the component named `Form` in the same family as this component.
+- `submit_verb` takes a symbol containing a verb, e.g. `:patch`. It defines this component's standalone verb that should be called when the twinned Form component is submitted.
+- `submit_path` defaults to this component's standalone path. You can override this to submit the form to another component, should you need it.
+
+The following other pre-built components implement `WithForm`:
+
+- [`New`](new.md)
+- [`Edit`](edit.md)

data/doc/guide/pre_built_components.md

@@ -0,0 +1,19 @@
+[Back to the guide](/README.md#guide)
+
+# Pre-built components shipped with Compony
+
+Compony comes with a few pre-built components that cover the most common cases that can be speed up development. They are meant to be inherited from and the easiest way to do this is by using the [provided Rails generators](./generators.md) `rails g component ...`.
+
+The pre-built components can be found in the module `Compony::Components`. As you can see, there is no Show and no Index component. The reason is that these will depend a lot on your application's UI framework (e.g. Bootstrap) and thus the benefits a UI-agnostic base component can provide are minimal. Additionally, these components are very easy to implement, as is illustrated in the example at the beginning of this documentation.
+
+In the following, the pre-built components currently shipped with Compony are presented:
+
+- [Button](./pre_built_components/button.md): This component class gets instanciated whenever using `Compony.button` or `compony_button`.
+- [Show](./pre_built_components/show.md): Compony's equivalent to Rail's `show` controller action
+- [Index](./pre_built_components/index.md): Compony's equivalent to Rail's `index` controller action
+- [List](./pre_built_components/list.md): Compony's equivalent to Rail's `_list` partial
+- [Destroy](./pre_built_components/destroy.md): Compony's equivalent to Rail's `destroy` controller action
+- [WithForm](./pre_built_components/with_form.md): A base class for components containing and submitting forms
+- [Form](./pre_built_components/form.md): Compony's equivalent to Rail's `_form` partial
+- [New](./pre_built_components/new.md): Compony's equivalent to Rail's `new` and `create` controller action
+- [Edit](./pre_built_components/new.md): Compony's equivalent to Rail's `edit` and `update` controller action

data/doc/guide/resourceful.md

@@ -0,0 +1,101 @@
+[Back to the guide](/README.md#guide)
+
+# Resourceful components
+
+So far, we have mainly seen how to present static content, without considering how loading and storing data is handled. Whenever a component is about data, be it a collection (e.g. index, list) or a single instance (e.g. new, show, edit, destroy, form), that component typically becomes resourceful. In order to implement a resourceful component, include the mixin `Compony::ComponentMixins::Resourceful`.
+
+Resourceful components use an instance variable `@data` and provide a reader `data` for it. As a convention, always store the data the component "is about" in this variable.
+
+Further, the class of which `data` should be can be specified and retrieved by using `data_class`. By default, `data_class` is inferred from the component's family name, i.e. `Components::User::Show` will automatically return `User` as `data_class`.
+
+The mixin adds extra hooks that can be used to store logic that can be executed in the request context when the component is rendered standalone. The formulation of that sentence is important, as the decision which of these blocks are executed depends on the verb DSL. But before elaborating on that, let's first look at all the available hooks provided by the Resourceful mixin:
+
+- `load_data`: Important. Specify a block that assigns something to `@data` here. The block will be run before authorization - thus, you can check `@data` for authorizing (e.g. `can?(:read, @data)`).
+- `after_load_data`: Optional. If a block is specified, it is run immediately after `load_data`. This is useful if you inherit from a component that loads data but you need to alter something, e.g. refining a collection.
+- `assign_attributes`: Important for components that alter data, e.g. New, Edit. Specify a block that assigns attributes to your model from `load_data`. The model is now dirty, which is important: **do not save your model here**, as authorization has not yet been performed. Also, **do not forget to validate params before assigning them to attributes**.
+- `after_assign_attributes`: Optional. If a block is specified, it is run immediately after `assign_attributes`. Its usage is similar to that of `after_load_data`.
+- (At this point, your `authorize` block is executed, throwing a `CanCan::AccessDenied` exception causing HTTP 403 not authorized if the block returns false.)
+- `store_data`: Important for components that alter data, e.g. New, Edit. This is where you save your model stored in `@data` to the database.
+
+Another important aspect of the Resourceful mixin is that it also **extends the Verb DSL** available in the component. The added calls are:
+
+- `load_data`
+- `assign_attributes`
+- `store_data`
+
+Unlike the calls above, which are global for the entire component, the ones in the Verb DSL are on a per-verb basis, same as the `authorize` call. If the same hook is both given as a global hook and in the Verb DSL, the Verb DSL hook overwrites the global one. The rule of thumb on where to place logic is:
+
+- If multiple verbs use the same logic for a hook, place it in the global hook. For example, let us consider an Edit component: if GET is called on it, the model is loaded and parameters are assigned to it in order to fill the form's inputs. If PATCH is called, the exact same thing is done before attempting to save the model. In this case, you would implement both `load_data` and `assign_attributes` as global hooks.
+- If a hook is specific to a single verb, place it in the verb config.
+
+Let's build an example of a simplified Destroy component. In practice, you'd instead inherit from `Compony::Components::Destroy`. However, for the sake of demonstration, we will implement it from scratch:
+
+```ruby
+class Components::Users::Destroy < Compony::Component
+  # Make the component resourceful
+  include Compony::ComponentMixins::Resourceful
+
+  setup do
+    # Let the path be of the form users/42/destroy
+    standalone path: 'users/:id/destroy' do
+      verb :get do
+        # In the case of a GET request, ask for confirmation, not deleting anything.
+        # Nevertheless, we should authorize :destroy, not :read.
+        # Reason: this way, buttons pointing to this component will not be shown
+        # to users which lack the permission to destroy @data.
+        authorize { can?(:destroy, @data) }
+      end
+
+      verb :delete do
+        # In the case of a DELETE request, the record will be destroyed.
+        authorize { can?(:destroy, @data) }
+        store_data { @data.destroy! }
+        # We overwrite the respond block because we want to redirect, not render
+        respond do
+          flash.notice = "#{@data.label} was deleted."
+          redirect_to Compony.path(:index, :users)
+        end
+      end
+    end
+
+    # Resourceful components have a default `load_data` block that loads the model.
+    # Therefore, the default behavior is already set to:
+    # load_data { @data = User.find(params[:id]) }
+
+    label(:short) { |_| 'Delete' }
+    label(:long) { |data| "Delete #{data.label}" }
+    content do
+      h1 "Are you sure to delete #{@data.label}?"
+      div compony_button(:destroy, @data, label: 'Yes, delete', method: :delete)
+    end
+  end
+end
+```
+
+## Complete resourceful lifecycle
+
+This graph documents a typical resourceful lifecycle according to which Compony's [pre-built components](./pre_built_components.md) are implemented.
+
+- `load_data` creates or fetches the resource from the database.
+- `after_load_data` can refine the resource, e.g. add scopes to a relation.
+- `assign_attributes` takes the HTTP parameters, validates them and assigns them to the resource.
+- `after_assign_attributes` can refine the assigned resource, e.g. provide defaults for blank attributes.
+- `authorize` is called.
+- `store_data` creates/updates/destroys the resource.
+- `respond` typically shows a flash and redirects to another component.
+
+![Graph of the complete resourceful lifecycle](/doc/resourceful_lifecycle.png)
+
+## Nesting resourceful components
+
+As mentioned earlier, hooks such as those provided by Resourceful typically run only when a component is accessed standalone. This means that in a nested setting, only the component running those hooks is the root component.
+
+When nesting resourceful components, it is therefore best to load all necessary data in the root component. Make sure to include any relations used by sub-components in order to avoid "n+1" queries in the database.
+
+`resourceful_sub_comp` is the resourceful sibling of `sub_comp` and both are used the same way. Under the hood, the resourceful call passes two extra parameters to the sub component: `data` and `data_class`.
+
+The rule of thumb thus becomes:
+
+- When a resourceful component instantiates a resourceful sub-component, use `resourceful_sub_comp` in the parent component.
+- When a resourceful component instantiates a non-resourceful sub-component, use `sub_comp`.
+- The situation where a non-resourceful component instantiates a resourceful component should not occur. Instead, make your parent component resourceful, even if it doesn't use the data itself. By housing a resourceful sub-comp, the parent component's nature inherently becomes resourceful and you should use the Resourceful mixin.

data/doc/guide/root_actions.md

@@ -0,0 +1,67 @@
+[Back to the guide](/README.md#guide)
+
+# Compony root actions
+
+The word "actions" is heavily overused, so here is a disambiguation:
+
+- Rails controller actions: a method that is implemented in a Rails controller
+- CanCanCan actions: the first method to CanCanCan's `can?` method
+- Compony root actions: buttons that point to other components
+
+At this point, Compony actions are a loose concept, which will likely be refined in the future. Currently, Compony actions are defined as buttons, rendered by the application layout, that point to other components. They provide context-sensitive buttons to your application.
+
+## Defining and manipulating root actions
+
+In addition to regular buttons that are rendered as part of the content blocks, components can expose root actions with the `actions` call. Root actions will only be rendered if the component they are defined in is currently the root component.
+
+To have a component expose a root action, call the method `action` in a `setup` block and return a Compony button:
+
+```ruby
+setup do
+  action :edit do
+    Compony.button(:edit, @data)
+  end
+
+  action :destroy do
+    Compony.button(:destroy, @data)
+  end
+end
+```
+
+The name of the action ("edit" and "destroy" in the example above) allows you to refer to that action in a component inheriting from this one:
+
+```ruby
+# Assuming that this component inherits from the example above
+setup do
+  skip_action :destroy
+
+  action :overview, before: :edit do
+    Compony.button(:index, :users, label: 'Overview')
+  end
+end
+```
+
+In this example, two actions will be shown: overview and edit.
+
+An action button can be disabled through the [feasibility framework](./feasibility.md). However, it can also instead be hidden completely by returning nil from within the action block:
+
+```ruby
+action :edit do
+  next if @data.locked?
+  Compony.button(:edit, @data)
+end
+```
+
+The action in this example will be skipped entirely if `locked?` returns true.
+
+## Displaying root actions
+
+Root actions are not shown by default in Compony because layouting is up to you. In order to display the root component's actions, add the following view helper call to your layout:
+
+```erb
+<%# layouts/application.html.erb %>
+...
+<%= compony_actions %>
+```
+
+If there is currently no root component, or if the root component defines no actions, this does nothing. However, if there are root actions available, the Compony buttons returned by the root component will be rendered.

data/doc/guide/standalone.md

@@ -0,0 +1,136 @@
+[Back to the guide](/README.md#guide)
+
+# Standalone (routing to components)
+
+As stated earlier, Compony can generate routes to your components. This is achieved by using the standalone DSL inside the setup block. The first step is calling the method `standalone` with a path. Inside this block, you will then specify which HTTP verbs (e.g. GET, PATCH etc.) the component should listen to. As soon as both are specified, Compony will generate an appropriate route.
+
+Assume that you want to create a simple component `statics/welcome.rb` that displays a static welcome page. The component should be exposed under the route `'/welcome'` and respond to the GET method. Here is the complete code for making this happen:
+
+```ruby
+# app/components/statics/welcome.rb
+class Components::Statics::Welcome < Compony::Component
+  setup do
+    label(:all) { 'Welcome' }
+
+    standalone path: 'welcome' do
+      verb :get do
+        authorize { true }
+      end
+    end
+
+    content do
+      h1 'Welcome to my dummy site!'
+    end
+  end
+end
+```
+
+This is the minimal required code for standalone. For security, every verb config must provide an `authorize` block that specifies who has access to this standalone verb. The block is given the request context and is expected to return either true (access ok) or false (causing the request to fail with `Cancan::AccessDenied`).
+
+Typically, you would use this block to check authorization using the CanCanCan gem, such as `authorize { can?(:read, :welcome) }`. However, since we skip authentication in this simple example, we pass `true` to allow all access.
+
+The standalone DSL has more features than those presented in the minimal example above. Excluding [resourceful](./resourceful.md) features, the full list is:
+
+- `standalone` can be called multiple times, for components that need to expose multiple paths, as described below. Inside each `standalone` call, you can call:
+  - `skip_authentication!` which disables authentication, in case you provided some. You need to implement `authorize` regardless.
+  - `skip_forgery_protection!` which disables CSRF protection for the controller action generated for this standalone configuration.
+  - `layout` which takes the file name of a Rails layout and defaults to `layouts/application`. Use this to have your Rails application look differently depending on the component.
+  - `verb` which takes an HTTP verb as a symbol, one of: `%i[get head post put delete connect options trace patch]`. `verb` can be called up to once per verb. Inside each `verb` call, you can call (in the non-resourceful case):
+    - `authorize` is mandatory and explained above.
+    - `respond` can be used to implement special behavior that in plain Rails would be placed in a controller action. The default, which calls `before_render` and the `content` blocks, is usually the right choice, so you will rarely implement `respond` on your own. See below how `respond` can be used to handle different formats or redirecting clients. **Caution:** `authorize` is evaluated in the default implementation of `respond`, so when you override that block, you must perform authorization yourself!
+
+## Exposing multiple paths in the same component (calling standalone multiple times)
+
+If your component loads data dynamically from a JavaScript front-end (e.g. implemented via Stimulus), you will find yourself in the situation where you need an extra route for a functionality that inherently belongs to the same component. Example use cases would be search fields that load data as the user types, maps that load tiles, dynamic photo galleries etc.
+
+In this case, you can call `standalone` a second time and provide a name for your extra route:
+
+```ruby
+setup do
+  # Regular route for rendering the content
+  standalone path: 'map/viewer' do
+    verb :get do
+      authorize { true }
+    end
+  end
+
+  # Extra route for loading tiles via AJAX
+  standalone :tiles, path: 'map/viewer/tiles' do
+    verb :get do
+      respond do # Again: overriding `respond` skips authorization! This is why we don't need to provide an `authorize` block here.
+        controller.render(json: MapTiler.load(params, current_ability)) # current_ability is provided by CanCanCan and made available by Compony.
+      end
+    end
+  end
+
+  # More code for labelling, content etc.
+end
+```
+
+Please note that the idea here is to package things that belong together, not to provide different kinds of content in a single component. For displaying different pages, use multiple components and have each expose a single route.
+
+## Naming of exposed routes
+
+The routes to standalone components are named and you can point to them using Rails' `..._path` and `..._url` helpers. The naming scheme is: `[standalone]_[component]_[family]_comp`. Examples:
+
+- Default standalone: `Components::Users::Index` exports `index_users_comp` and thus `index_users_comp_path` can be used.
+- Named standalone: If `standalone :foo, path: ...` is used within `Components::Users::Index`, the exported name is `foo_index_users_comp`.
+
+## Handling formats
+
+Compony is capable of responding to formats like Rails does. This is useful to deliver PDFs, CSV files etc. to a user from within Compony. This can be achieved by specifying the `respond` block:
+
+```ruby
+setup do
+  standalone path: 'generate/report' do
+    verb :get do
+      # Respond with a file when generate/report.pdf is GETed:
+      respond :pdf do
+        file, filename = PdfGenerator.generate(params, current_ability)
+        send_data(file, filename:, type: 'application/pdf')
+      end
+      # If someone visits generate/report, issue a 404:
+      respond do
+        fail ActionController::RoutingError, 'Unsupported format - please make sure your URL ends with `.pdf`.'
+      end
+    end
+  end
+end
+```
+
+## Redirect in `respond` or in `before_render`?
+
+Rails controller redirects can be issued both in a verb DSL's `respond` block and in `before_render`. The rule of thumb that tells you which way to go is:
+
+- If you want to redirect depending on the HTTP verb, use `respond`.
+- If you want to redirect depending on params, state, time etc.  **independently of the HTTP verb**, use `before_render`, as this is more convenient than writing a standalone -> verb -> respond tree.
+
+## Path constraints
+
+When calling `standalone`, you may specify the keyword `constraints` that will be passed to the route. For example:
+
+```ruby
+# In your component
+standelone path: '/:lang', constraints: { lang: /([a-z]{2})?/i }
+
+# This will automatically lead to a route of this form:
+get ':lang', constraints: { lang: /([a-z]{2})?/i }
+```
+
+## Passing scopes
+
+When calling `standalone`, you may specify the keyword `scope` to wrap the component's Rails route into a route scope. Additionally, you may specify a hash `scope_args`, which will be passed as keyword arguments to the `scope` call in the route:
+
+```ruby
+# In your component
+standalone path: '/welcome', scope: '(:lang)', scope_args: { lang: /([a-z]{2})?/i } do
+  verb :get do
+    # ....
+  end
+end
+
+# This will automatically lead to a route of this form:
+scope '(:lang)', lang: /([a-z]{2})?/i do
+  get 'welcome', to: 'compony#your_component'
+end
+```

data/doc/guide/virtual_models.md

@@ -0,0 +1,29 @@
+[Back to the guide](/README.md#guide)
+
+# Unleashing virtual models through Compony's `ActiveType` integration
+
+Compony explicitely supports using virtual models using the `active_type` gem for its resourceful components. However, when doing so, your model should inherit from `Compony::VirtualModel` rather than from `ActiveType::Object`.
+
+Combining Compony with virtual models enables programming patterns that are extremely powerful for use cases such as non-persistent wizards, filter forms, stateless launch forms for generators and much more.
+
+For instance, let us consider an application that that generates configurable reports. In this example, the user workflow is to click on a "Generate report" button, fill in a configuration form (what kind of report the generator should produce, what timespan should be considered, which criteria to filter and group by etc.), and, by submitting the form, queueing a job that will perform the report in the background. To realize this, a simple approach would be the following:
+
+- Add the `active_type` gem to your `Gemfile` and run `bundle install`.
+- Implement `Components::Reports::Request` which inherits from `Compony::Components::New`.
+- In the top section of the component class, define a class `VirtualModel < Compony::VirtualModel` (within the namespace of `Components::Reports::Request`). Use `active_type`'s `attribute` method to add virtual columns for any kind of information your generator will need. Call Compony's `field` method as you would with a normal Rails model and implement any suitable Rails validations. You may even use Rails associations such as `belongs_to` to a real (database-backed) Rails model by implementing an attribute with the following three lines:
+    - `attribute :user_id, :bigint` (provided by `active_type`)
+    - `belongs_to :user` (provided by Rails)
+    - `field :user, :association` (provided by Compony)
+- Implement `Components::Reports::RequestForm < Compony::Components::Form` and implement your configuration form there.
+- In your `Components::Reports::Request`:
+    - Call `standalone path: '/reports/request'` to avoid path conflicts with other components in the `Components::Reports` namespace inheriting from `New`.
+    - Call `data_class VirtualModel` to tell the component to use the class you just created within the component's namespace.
+    - Call `form_comp_class Components::Reports::RequestForm` to inform the component to use the custom named form.
+    - Call something like `label(:all) { ... }` to set a label for your component.
+    - Implement `on_created_respond` to create the report job and redirect to a suitable location.
+
+Why this works: As your `Components::Reports::Request` inherits from Compony's `New` component, Compony will believe that the user is about to create a new resource, providing the Compony equivalents for the Rails controller actions `new` and `create`. When the user submits the form, Compony will run validations, re-render the form with error messages if they fail, or otherwise call `@data.save` which does nothing since the model is only virtual. This is why you take back control by overriding the `on_created_respond` block, which is called only if all validations have passed.
+
+Note: it is even possible to combine this pattern with Rails' `accepts_nested_attributes_for` and `simple_form`'s `f.simple_fields_for` call, where the nested object is a real database-backed model. Even though the component's resource is purely virtual, Rails will create or update the nested model when Compony calls `save` on the parent resource. This allows for very fast implementation of business logic creating multiple objects from a single form post by wrapping the resources in a virtual model.
+
+If you intend to use this technique in combination with `ActiveStorage`, you must also override the `store_data` block to just validate the model instead of saving it, as the hook creating the attachment is bound to fail (the virtual model does not exist in the database and thus cannot be referenced from `ActiveStorage::Attachment`). For the same reason, you cannot call `blob.download`, but must find the file's tempfile in the request parameters in order to process the file attached by the user.