` itself.
### Limitations
- **No cell-level options yet.** A future `cell_options` API will let you customize individual `` elements via the field DSL. For now, `row_options` only affects the row container.
- **No grid or kanban analog.** `self.grid_view` is the future home for grid-card options; kanban gets its own when the time comes.
- **Turbo Stream re-renders.** When a row is broadcast-updated via Turbo Stream, the `view:` local resolves based on the original render context. Verify in your specs if you depend on `view` branching.
---
# Grid view
Some resources are best displayed in a grid view. We can do that with Avo using a `cover_url`, a `title`, and a `body`.
What should be used as the title of the card.
```ruby
self.grid_view = {
card: -> do
{
title: record.title
}
end
}
```
What should be used as the body of the card. You can use this field to display a description of the record.
```ruby
self.grid_view = {
card: -> do
{
body: record.truncated_body
}
end
}
```
What should be used as the cover URL of the card.
```ruby
self.grid_view = {
card: -> do
{
cover_url: record.image.attached? ? main_app.url_for(record.image.variant(resize_to_fill: [300, 300])) : nil
}
end
}
```
If `nil` is given, a default placeholder image will be used.
Optionally you may add a badge to give more context to the card or make it stand out.
See [below](#grid-item-badge) a list of options you can configure for the badge.
The visible text displayed on the badge. This is the primary content that users will see on your grid items.
```ruby
self.grid_view = {
card: -> do
{
badge: { label: "New" }
}
end
}
```
Sets the badge color. Accepts a static value or a proc for dynamic coloring based on the record.
#### Available colors
**Base colors:** `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`
**Semantic colors:** `neutral`, `success`, `danger`, `warning`, `info`
```ruby
self.grid_view = {
card: -> do
{
badge: {
label: "New",
color: "green"
}
}
end
}
```
Controls the badge appearance style.
#### Available styles
- `subtle` - Light background with colored text (default)
- `solid` - Solid colored background with white text
```ruby
self.grid_view = {
card: -> do
{
badge: {
label: "New",
color: "green",
style: "solid"
}
}
end
}
```
The tooltip text that appears when users hover over the badge. Useful for providing additional context or detailed information.
```ruby
self.grid_view = {
card: -> do
{
badge: {
label: "New",
title: "New product available"
}
}
end
}
```
Adds an icon to the badge.
```ruby
self.grid_view = {
card: -> do
{
badge: {
label: "New",
color: "green",
icon: "tabler/outline/trending-up"
}
}
end
}
```
---
# Map view
Some resources that contain geospatial data can benefit from being displayed on a map. For
resources to be displayed to the map view they require a `coordinates` field, but that's customizable.
## Enable map view
To enable map view for a resource, you need to add the `map_view` class attribute to a resource. That will add the view switcher to the
The options you pass here are forwarded to the [`mapkick` gem](https://github.com/ankane/mapkick).
This block is being applied to all the records present in the current query to fetch the coordinates of off the record.
You may use this block to fetch the coordinates from other places (API calls, cache queries, etc.) rather than the database.
This block has to return a hash compatible with the [`PointMap` items](https://github.com/ankane/mapkick#point-map). Has to have `latitude` and `longitude` and optionally `tooltip`, `label`, or `color`.
This is the configuration for the adjacent table. You can set the visibility to `true` or `false`, and set the position of the table `:top`, `:right`, `:bottom`, or `:left`.
Available since version
## Make it the default view
To make the map view the default way of viewing a resource on
Overriding this method, you can tell Avo what path to follow after a record was created with success.
```ruby
def after_create_path
"/avo/resources/users"
end
```
Override this method to create a custom response when a record was created with success.
```ruby
def create_success_action
respond_to do |format|
format.html { redirect_to after_create_path, notice: create_success_message}
end
end
```
Override this method to create a custom response when a record failed to be created.
```ruby
def create_fail_action
respond_to do |format|
flash.now[:error] = create_fail_message
format.html { render :new, status: :unprocessable_entity }
end
end
```
Override this method to change the message the user receives when a record was created with success.
```ruby
def create_success_message
"#{@resource.name} #{t("avo.was_successfully_created")}."
end
```
Override this method to change the message the user receives when a record failed to be created.
```ruby
def create_fail_message
t "avo.you_missed_something_check_form"
end
```
## Update methods
For the `update` method, you can modify the `after_update_path`, the messages, and the actions both on success or failure.
Overriding this method, you can tell Avo what path to follow after a record was updated with success.
```ruby
def after_update_path
"/avo/resources/users"
end
```
Override this method to create a custom response when a record was updated with success.
```ruby
def update_success_action
respond_to do |format|
format.html { redirect_to after_update_path, notice: update_success_message }
end
end
```
Override this method to create a custom response when a record failed to be updated.
```ruby
def update_fail_action
respond_to do |format|
flash.now[:error] = update_fail_message
format.html { render :edit, status: :unprocessable_entity }
end
end
```
Override this method to change the message the user receives when a record was updated with success.
```ruby
def update_success_message
"#{@resource.name} #{t("avo.was_successfully_updated")}."
end
```
Override this method to change the message the user receives when a record failed to be updated.
```ruby
def update_fail_message
t "avo.you_missed_something_check_form"
end
```
## Destroy methods
For the `destroy` method, you can modify the `after_destroy_path`, the messages, and the actions both on success or failure.
Overriding this method, you can tell Avo what path to follow after a record was destroyed with success.
```ruby
def after_update_path
"/avo/resources/users"
end
```
Override this method to create a custom response when a record was destroyed with success.
```ruby
def destroy_success_action
respond_to do |format|
format.html { redirect_to after_destroy_path, notice: destroy_success_message }
end
end
```
Override this method to create a custom response when a record failed to be destroyed.
```ruby
def destroy_fail_action
respond_to do |format|
format.html { redirect_back fallback_location: params[:referrer] || resources_path(resource: @resource, turbo_frame: params[:turbo_frame], view_type: params[:view_type]), error: destroy_fail_message }
end
end
```
Override this method to change the message the user receives when a record was destroyed with success.
```ruby
def destroy_success_message
t("avo.resource_destroyed", attachment_class: @attachment_class)
end
```
Override this method to change the message the user receives when a record failed to be destroyed.
```ruby
def destroy_fail_message
@errors.present? ? @errors.join(". ") : t("avo.failed")
end
```
---
# Breadcrumbs
Avo has a pretty advanced breadcrumbs system.
It will use the resource avatar or initials to display the breadcrumb and context.
!Breadcrumbs
It has minimal configuration options but you will have the oportunity to interact with it in a few places like the `avo.rb` config file or in the controller actions when you want to add breadcrumbs to a custom tool.
## API
## `add_breadcrumb`
This method is used to add a breadcrumb to the stack.
It takes the following arguments:
### Options
Sets the title of the breadcrumb.
```ruby
add_breadcrumb title: "Home"
add_breadcrumb title: "Details"
```
| Option | Value |
| --------------- | ------- |
| Required | `true` |
| Default value | `nil` |
| Possible values | Strings |
This sets the link of the breadcrumb.
```ruby
add_breadcrumb title: "Posts", path: avo.posts_path
add_breadcrumb title: "Custom tool", path: avo.custom_tool_path
```
:::warning
You're most probably linking to an internal Avo page, so you need to prefix the path using the `avo` dot as per Rails' engine rules. See Rails engines and path helpers for a full guide.
:::
| Option | Value |
| --------------- | ------- |
| Required | `false` |
| Default value | `nil` |
| Possible values | Strings |
Sets the icon of the breadcrumb.
```ruby
add_breadcrumb title: "Home", icon: "heroicons/outline/home"
add_breadcrumb title: "Details", icon: "heroicons/outline/information-circle"
```
| Option | Value |
| --------------- | ---------------------------------------------- |
| Required | `false` |
| Default value | `nil` |
| Possible values | Icon strings (e.g. `"heroicons/outline/home"`) |
Sets the initials displayed in the breadcrumb avatar when no icon is present. Useful for resource records where you want to show abbreviated identifiers (e.g. "JD" for a user named John Doe).
```ruby
add_breadcrumb title: "John Doe", initials: "JD", path: user_path(@user)
add_breadcrumb title: "Post #123", initials: "P123", path: post_path(@post)
```
| Option | Value |
| --------------- | ------- |
| Required | `false` |
| Default value | `nil` |
| Possible values | Strings |
It returns the breadcrumb object.
```ruby
add_breadcrumb title: "Home", path: root_path
```
## Breadcrumbs for custom pages
You can add breadcrumbs to custom pages in the controller action.
```ruby{3}
class Avo::ToolsController < Avo::ApplicationController
def custom_tool
add_breadcrumb title: "Custom tool", path: avo.custom_tool_path
end
end
```
---
# Fields
Fields are the backbone of a `Resource`.
Through fields you tell Avo what to fetch from the database and how to display it on the
Format the field value using a block.
:::info
Notice that this block will have effect on **all** views.
:::
Formatting affects copyable value, when using `format_using` with `copyable`, the formatted value is what gets copied to the clipboard, not the original database value. For example, using `format_using: -> { value.truncate(20) }` will copy the truncated text (including the `...`). If you need to display a truncated value while copying the full value, consider using CSS truncation via the `html` option instead of `format_using`.
```ruby
field :is_writer, as: :text, format_using: -> {
if view.form?
value
else
value.present? ? 'π' : 'π'
end
}
```
This example snippet will make the `:is_writer` field generate `π` or `π` emojis instead of `1` or `0` values on display views and the values `1` or `0` on form views.
Avo provides helper methods to format fields based on the current view.
- `format_index_using` - Format the field value **only** for the **index** view
- `format_show_using` - Format the field value **only** for the **show** view
- `format_edit_using` - Format the field value **only** for the **edit** view
- `format_new_using` - Format the field value **only** for the **new** view
- `format_form_using` - Format the field value **only** for the **forms** view (**new** and **edit**)
- `format_display_using` - Format the field value **only** for the **display** view (**index** and **show**)
This methods are available for all fields.
Example on how to format a field in the index and show views:
```ruby
field :is_writer, format_display_using: -> { value.present? ? 'π' : 'π' }
```
## Formatting with Rails helpers
You can also format using Rails helpers like `number_to_currency` (note that `view_context` is used to access the helper):
```ruby
field :price, as: :number, format_using: -> { view_context.number_to_currency(value) }
```
## Parse value before update
When it's necessary to parse information before storing it in the database, the `update_using` option proves to be useful. Inside the block you can access the raw `value` from the form, and the returned value will be saved in the database.
```ruby
field :metadata,
as: :code,
update_using: -> do
ActiveSupport::JSON.decode(value)
end
```
## Sortable fields
One of the most common operations with database records is sorting the records by one of your fields. For that, Avo makes it easy using the `sortable` option.
Add it to any field to make that column sortable in the
Sometimes you will need some extra text to explain better what the field is used for. You can achieve that by using the `help` method.
The value can be either text or HTML and is displayed only on the here .'
```
The `label_help` option allows you to add a help text below the label of a field on every view.
```ruby
# using the text value
field :custom_css, as: :code, theme: 'dracula', language: 'css', label_help: "This enables you to edit the user's custom styles."
# using HTML value
field :password, as: :password, label_help: 'You may verify the password strength here .'
```
## Nullable
When a user uses the **Save** button, Avo stores the value for each field in the database. However, there are cases where you may prefer to explicitly instruct Avo to store a `NULL` value in the database row when the field is empty. You do that by using the `nullable` option, which converts `nil` and empty values to `NULL`.
You may also define which values should be interpreted as `NULL` using the `null_values` method.
```ruby
# using default options
field :updated_status, as: :status, failed_when: [:closed, :rejected, :failed], loading_when: [:loading, :running, :waiting], nullable: true
# using custom null values
field :body, as: :textarea, nullable: true, null_values: ['0', '', 'null', 'nil', nil]
```
## Link to record
Sometimes, on the
The field's `components` option allows you to customize the view components used for rendering the field in all, `index`, `show` and `edit` views. This provides you with a high degree of flexibility.
### Ejecting the field components
To start customizing the field components, you can eject one or multiple field components using the `avo:eject` command. Ejecting a field component generates the necessary files for customization. Here's how you can use the `avo:eject` command:
#### Ejecting All Components for a Field
`$ rails g avo:eject --field-components FIELD_TYPE --scope admin`
Replace `FIELD_TYPE` with the desired field type. For instance, to eject components for a Text field, use:
`$ rails g avo:eject --field-components text --scope admin`
This command will generate the files for all the index, edit and show components of the Text field, for each field type the amount of components may vary.
For more advanced usage check the eject documentation.
:::warning Scope
If you don't pass a `--scope` when ejecting a field view component, the ejected component will override the default components all over the project.
Check eject documentation for more details.
:::
### Customizing field components using `components` option
Here's some examples of how to use the `components` option in a field definition:
::: code-group
```ruby [Hash]
field :description,
as: :text,
components: {
index_component: Avo::Fields::Admin::TextField::IndexComponent,
show_component: Avo::Fields::Admin::TextField::ShowComponent,
edit_component: "Avo::Fields::Admin::TextField::EditComponent"
}
```
```ruby [Block]
field :description,
as: :text,
components: -> do
{
show_component: Avo::Fields::Admin::TextField::ShowComponent,
edit_component: "Avo::Fields::Admin::TextField::EditComponent"
}
end
```
:::
The components block it's executed using `Avo::ExecutionContent` and gives access to a bunch of variables as: `resource`, `record`, `view`, `params` and more.
`_component` is the key used to render the field's ``'s component, replace `` with one of the views in order to customize a component per each view.
:::warning Initializer
It's important to keep the initializer on your custom components as the original field view component initializer.
:::
### Attach HTML attributes
Using the `html` option you can attach `style`, `classes`, and `data` attributes. The `style` attribute adds the `style` tag to your element, `classes` adds the `class` tag, and the `data` attribute the `data` tag to the element you choose.
You may find more detailed information about the HTML attributes here.
Allows to specify the target attribute on the model for each field. By default the target attribute is the field's id.
Usage example:
```ruby
field :status, as: :select, options: [:one, :two, :three], only_on: :forms
field :secondary_field_for_status,
as: :badge,
for_attribute: :status,
options: {info: :one, :success: :two, warning: :three},
except_on: :forms,
help: "Secondary field for status using the for_attribute option"
```
This handy option enables you to send arbitrary information to the field. It's especially useful when you're building your own custom fields or you are using [custom components](#components) for the built-in fields.
Usage example:
```ruby{4,9-11}
# meta as a hash
field :status,
as: :custom_status,
meta: {foo: :bar}
# meta as a block
field :status,
as: :badge,
meta: -> do
record.statuses.map(&:id)
end
```
Within your field template you can now access the `@field.meta` attribute.
```erb{2}
<%= field_wrapper **field_wrapper_args do %>
<% if @field.meta[:foo] %>
<%= @resource.record.foo_value %>
<% else %>
<%= @field.value %>
<% end %>
<% end %>
```
---
# Field Discovery
`discover_columns` and `discover_associations` automatically detect and configure fields for your Avo resources based on your model's database structure.
```rb{6-7}
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
# ...
def fields
discover_columns
discover_associations
end
end
```
VIDEO
## Options
Specify which fields should be discovered, excluding all others.
```rb{6-7}
# app/avo/resources/post.rb
class Avo::Resources::Post < Avo::BaseResource
# ...
def fields
discover_columns only: [:title, :body, :published_at]
discover_associations only: [:author, :comments]
end
end
```
##### Default value
`nil`
#### Possible values
Array of symbols representing column or association names
Specify which fields should be excluded from discovery.
```rb{6-7}
# app/avo/resources/post.rb
class Avo::Resources::Post < Avo::BaseResource
# ...
def fields
discover_columns except: [:metadata, :internal_notes]
discover_associations except: [:audit_logs]
end
end
```
##### Default value
`nil`
#### Possible values
Array of symbols representing column or association names
Override how specific column names are mapped to field types globally.
```rb{5-8}
# config/initializers/avo.rb
Avo.configure do |config|
# ...
config.column_names_mapping = {
published_at: { field: :date_time, timezone: 'UTC' },
role: { field: :select, enum: -> { User.roles } }
}
end
```
##### Default value
`{}`
#### Possible values
Hash mapping column names to field configurations
Override how database column types are mapped to field types globally.
```rb{5-8}
# config/initializers/avo.rb
Avo.configure do |config|
# ...
config.column_types_mapping = {
jsonb: { field: :code, language: 'json' },
decimal: { field: :number, decimals: 2 }
}
end
```
##### Default value
`{}`
#### Possible values
Hash mapping database column types to field configurations
## Examples
### Basic Discovery
```rb{6-7}
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
# ...
def fields
discover_columns
discover_associations
end
end
```
### Custom Field Options
This will add the provided options to every discovered field or association. This is particularly useful when having duplicative configurations across many fields.
```rb{6-7}
# app/avo/resources/post.rb
class Avo::Resources::Post < Avo::BaseResource
# ...
def fields
discover_columns help: "Automatically discovered fields"
discover_associations searchable: false
end
end
```
### Combining Manual and Discovered Fields
```rb{6,8-9,11}
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
# ...
def fields
field :custom_field, as: :text
discover_columns except: [:custom_field]
discover_associations
field :another_custom_field, as: :boolean
end
end
```
## Automatic Type Mapping
Field discovery maps database column types to Avo field types automatically.
e.g.
- `string` β `:text`
- `integer` β `:number`
- `float` β `:number`
- `datetime` β `:datetime`
- `boolean` β `:boolean`
- `json/jsonb` β `:code`
The full, up-to-date list can be found [here](https://github.com/avo-hq/avo/blob/main/lib/avo/mappings.rb)
## Association Discovery
The following associations are automatically configured:
- `belongs_to` β `:belongs_to`
- `has_one` β `:has_one`
- `has_many` β `:has_many`
- `has_one_attached` β `:file`
- `has_many_attached` β `:files`
- `has_rich_text` β `:trix`
- `acts-as-taggable-on :tags` β `:tags`
The full, up-to-date list can be found [here](https://github.com/avo-hq/avo/blob/main/lib/avo/mappings.rb)
---
# Resource Header
The resource header is a key component that, by default, is displayed at the top of your resource pages. It provides a consistent area showing the resource's title, description, profile photo, discreet information and controls.
The `header` DSL allows you to control where the header appears within your resource's field layout. By default, if you don't explicitly declare a `header`, Avo automatically generates one and places it at the top of the page.
```ruby
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
self.title = :name
self.description = "Users of the application"
def fields
header # Explicitly place the header
card do
field :id, as: :id
field :email, as: :text
end
end
end
```
## Automatic Header Generation
If you don't explicitly define a `header` in your `fields` method, Avo will automatically create one and insert it as the first item on the page. This ensures that every resource page has a consistent header with the title, description, and controls.
```ruby
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
self.title = :name
def fields
# No explicit header - Avo will automatically add one at the top
card do
field :id, as: :id
field :email, as: :text
end
end
end
```
## Positioning the Header
One of the key benefits of the `header` DSL is the ability to position it anywhere within your fields layout. This is particularly useful when you want to display some content before the main header.
```ruby
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
self.title = :name
def fields
# Display a card before the header
card do
field :status, as: :badge
end
header # Header appears after the card
card do
field :id, as: :id
field :email, as: :text
end
end
end
```
---
# Resource panels
---
# Resource Sidebar
By default, all declared fields are going to be stacked vertically in the main area. But there are some fields with information that needs to be displayed in a smaller area, like boolean, date, and badge fields.
Those fields don't need all that horizontal space and can probably be displayed in a different space.
That's we created the **resource sidebar**.
## Adding fields to the sidebar
Using the `sidebar` block on a resource you may declare fields the same way you would do on the root level. Notice that the sidebar should be declared inside a panel. Each resource can have several panels or main panels and each panel can have it's own sidebars.
```ruby
class Avo::Resources::User < Avo::BaseResource
def fields
main_panel do
field :id, as: :id, link_to_record: true
field :first_name, as: :text, placeholder: "John"
field :last_name, as: :text, placeholder: "Doe"
# We can also add custom resource tools
tool UserTimeline
sidebar do
field :email, as: :gravatar, link_to_record: true, only_on: :show
field :active, as: :boolean, name: "Is active", only_on: :show
end
end
end
end
```
The `panel_wrapper` it's helpful when you want to render a custom tool inside a sidebar and you don't want to apply the `white_panel_classes` to it
```ruby
sidebar panel_wrapper: false do
tool Avo::ResourceTools::SidebarTool
end
```
---
# Tabs
Once your Avo resources reach a certain level of complexity, you might feel the need to better organize the fields, associations, and resource tools into groups. You can already use the `heading` to separate the fields inside a panel, but maybe you'd like to do more.
Tabs are a new layer of abstraction over panels. They enable you to group panels and tools together under a single pavilion and toggle between them.
```ruby
class Avo::Resources::User < Avo::BaseResource
def fields
field :id, as: :id, link_to_record: true
field :email, as: :text, name: "User Email", required: true
tabs do
tab title: "User information", description: "Some information about this user" do
panel do
field :first_name, as: :text, required: true, placeholder: "John"
field :last_name, as: :text, required: true, placeholder: "Doe"
field :active, as: :boolean, name: "Is active", show_on: :show
end
end
field :teams, as: :has_and_belongs_to_many
field :people, as: :has_many
field :spouses, as: :has_many
field :projects, as: :has_and_belongs_to_many
end
end
end
```
The `visible` option allows you to control the visibility of either a group of tabs or an individual tab. It can be a `boolean` or a lambda.
#### Example
```ruby
tabs visible: -> { resource.record.enabled? } do
tab title: "General Information" do
panel do
field :name, as: :text
field :email, as: :text
end
end
tab title: "Admin Information", visible: -> { current_user.is_admin? } do
panel do
field :role, as: :text
field :permissions, as: :text
end
end
end
```
In this example:
- The entire group of tabs is only visible if the record is enabled (`resource.record.enabled?`).
- Within this group, the "General Information" tab is always visible when the tabs are shown.
- The "Admin Information" tab is only visible for admin records (`resource.record.admin?`).
The `title` option enables you to specify a label for the entire group of tabs. This title serves as an overarching descriptor for the collection, providing context regarding the purpose or content of the tabs.
You can define the title of a tabs group by passing it as an argument to the `tabs` block. The value should be a string that succinctly encapsulates the theme or purpose of the tabs.
```ruby
tabs title: "Tabs group title" do
# ...
end
```
The `description` option allows you to provide an auxiliary explanation or detailed note for the entire group of tabs. This can be used to elaborate on the purpose of the tabs or provide additional guidance.
You can define a description for a tabs group by passing it as an argument to the `tabs` block. The value should be a string that offers further clarity about the content or functionality of the tabs.
```ruby
tabs description: "Tabs group description" do
# ...
end
```
The `lazy_load` option enables deferred loading of tab content, improving performance by fetching data only when the tab is clicked. By default, `lazy_load` is set to `false`, ensuring that all tabs load immediately. However, in form views, this option is automatically disabled to prevent data loss during form submission.
```ruby{2}
tabs do
tab title: "Address", lazy_load: true do
# ...
end
end
```
---
# Array
The `Array` field in allows you to display and manage structured array data. This field supports flexibility in fetching and rendering data, making it suitable for various use cases.
:::tip Important
To use the `Array` field, you must create a resource specifically for it. Refer to the Array Resource documentation for detailed instructions.
For example, to use `field :attendees, as: :array`, you can generate an array resource by running the following command:
```bash
rails generate avo:resource Attendee --array
```
This step ensures the proper setup of your array field within the Avo framework.
:::
### Example 1: Array field with a block
You can define array data directly within a block. This is useful for static or pre-configured data:
```ruby{3-8}
class Avo::Resources::Course < Avo::BaseResource
def fields
field :attendees, as: :array do
[
{ id: 1, name: "John Doe", role: "Software Developer", organization: "TechCorp" },
{ id: 2, name: "Jane Smith", role: "Data Scientist", organization: "DataPros" }
]
end
end
end
```
:::warning Authorization
The `array` field internally inherits many behaviors from `has_many`, including authorization. If you are using authorization and the array field is not rendering, it is most likely not authorized.
To explicitly authorize it, define the following method in the resource's policy:
```ruby{3}
# app/policies/course_policy.rb
class CoursePolicy < ApplicationPolicy
def view_attendees? = true
end
```
For more details, refer to the view_{association}? documentation.
:::
### Example 2: Array field fetching data from the model's method
If no block is defined, Avo will attempt to fetch data by calling the corresponding method on the model:
```ruby
class Course < ApplicationRecord
def attendees
User.all.first(6) # Example fetching first 6 users
end
end
```
Here, the `attendees` field will use the `attendees` method from the `Course` model to render its data dynamically.
### Example 3: Fallback to the `records` method
If neither the block nor the model's method exists, Avo will fall back to the `records` method defined in the resource used to render the array field. This is useful for providing a default dataset.
When neither a block nor a model's method is defined, Avo will fall back to the `records` method in the resource used to render the field. This is a handy fallback for providing default datasets:
```ruby
class Avo::Resources::Attendee < Avo::Resources::ArrayResource
def records
[
{ id: 1, name: "Default Attendee", role: "Guest", organization: "DefaultOrg" }
]
end
end
```
## Summary of Data Fetching Hierarchy
When using `has_many` with `array: true`, Avo will fetch data in the following order:
1. Use data returned by the **block** provided in the field.
2. Fetch data from the **associated model method** (e.g., `Course#attendees`).
3. Fall back to the **`records` method** defined in the resource.
This hierarchy provides maximum flexibility and ensures seamless integration with both dynamic and predefined datasets.
---
# Avatar
The `Avatar` field is a field that displays a user's avatar or initials.
Maps field values to badge colors. Keys are color names (semantic or base colors), and values can be a single value (string/symbol) or an array of values that should display with that color.
#### Available colors
**Base colors:** `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`
**Semantic colors:** `neutral`, `success`, `danger`, `warning`, `info`
:::info Default behavior
If a value doesn't match any of the configured options, it will default to `neutral`.
:::
```ruby
# Map values to colors
field :status, as: :badge,
options: {
success: ["Done", :completed], # Arrays with mixed types
danger: "Cancelled", # Single string
warning: :pending, # Single symbol
violet: "Idea" # Base color
}
```
Controls the badge appearance style.
#### Available styles
- `subtle` - Light background with colored text (default)
- `solid` - Solid colored background with white text
:::info Default behavior
If an invalid style is provided, it will default to `subtle`.
:::
```ruby
field :status, as: :badge,
options: { success: :done },
style: "solid"
# Or dynamically
field :status, as: :badge,
options: { success: :done },
style: -> { record.completed? ? "solid" : "subtle" }
```
Adds an icon to the badge.
```ruby
field :status, as: :badge,
options: { success: :done },
icon: "heroicons/outline/check-circle"
# Or dynamically
field :status, as: :badge,
options: { success: :done },
icon: -> {
record.approved? ? "heroicons/outline/check-circle" : "heroicons/outline/x-circle"
}
```
## Examples
### Using semantic colors
```ruby
field :status, as: :badge,
options: {
success: ["active", "completed"],
info: ["pending", "review"],
danger: ["failed", "cancelled"],
neutral: ["unknown"]
}
```
### Using base colors
```ruby
field :priority, as: :badge,
options: {
green: :low,
amber: :medium,
orange: :high,
red: :urgent
}
```
### Using Badge with a Select field for editing
Since Badge is display-only, pair it with a Select field to allow editing:
```ruby
field :stage,
as: :select,
hide_on: [:show, :index],
options: {
'Discovery': :discovery,
'Idea': :idea,
'Done': :done,
'On hold': 'on hold',
'Cancelled': :cancelled,
'Drafting': :drafting
},
placeholder: 'Choose the stage.'
field :stage,
as: :badge,
options: {
info: ["Discovery", "Idea"],
success: :Done,
warning: "On hold",
danger: "Cancelled",
neutral: :Drafting
},
style: -> { ["Done", "Cancelled"].include?(record.stage) ? "solid" : "subtle" },
icon: -> {
{
"Discovery" => "tabler/outline/zoom",
"Idea" => "tabler/outline/bulb",
"Drafting" => "tabler/outline/file-text",
"Done" => "tabler/outline/circle-check",
"On hold" => "tabler/outline/player-pause",
"Cancelled" => "tabler/outline/xbox-x"
}[record.stage]
}
```
---
# Boolean
The `Boolean` field renders a `input[type="checkbox"]` on **Form** views and a nice green `check` icon/red `X` icon on the **Show** and **Index** views.
What should count as true. You can use `1`, `yes`, or a different value.
#### Default value
`[true, "true", "1"]`
What should count as false. You can use `0`, `no`, or a different value.
#### Default value
`[false, "false", "0"]`
When `true`, `nil` values render as a gray minus-circle icon on **Show** and **Index** views instead of the default dash. This keeps the `nil` value intact while making it more visible.
Render the field as a toggle on the form views.
#### Default value
`false`
---
# Boolean Group
The `options` attribute should be a `Hash` where the keys match the DB keys and the values are the visible labels.
#### Default value
Empty `Hash`.
```ruby
{}
```
#### Computed options
You may need to compute the options dynamically for your `BooleanGroup` field. You can use a lambda for this, which provides access to the `record`, `resource`, `view`, and `field` properties where you can pull data off.
```ruby{5-9}
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
field :features,
as: :boolean_group,
options: -> do
record.features.each_with_object({}) do |feature, hash|
hash[feature.id] = feature.name.humanize
end
end
end
```
The output value must be a hash as described above.
## Updates
Before version
Customize the color theme.
#### Default value
`material-darker`
#### Possible values
`material-darker`, `eclipse`, or `dracula`
Preview the themes here: [codemirror-themes](https://codemirror.net/demo/theme.html).
Customize the syntax highlighting using the language method.
#### Default value
`javascript`
#### Possible values
`css`, `dockerfile`, `htmlmixed`, `javascript`, `markdown`, `nginx`, `php`, `ruby`, `sass`, `shell`, `sql`, `vue` or `xml`.
Customize the height of the editor.
#### Default value
`auto`
#### Possible values
`auto`, or any value in pixels (eg `height: 250px`).
Customize the tab_size of the editor.
#### Default value
`2`
#### Possible values
Any integer value.
Customize the type of indentation.
#### Default value
`false`
#### Possible values
`true` or `false`
Customize whether the editor should apply line wrapping.
#### Default value
`true`
#### Possible values
`true` or `false`
---
# Country
`Country` field generates a [Select](#select) field on **Edit** view that includes all [ISO 3166-1](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) countries. The value stored in the database will be the country code, and the value displayed in Avo will be the name of the country.
:::warning
You must manually require the `countries` gem in your `Gemfile`.
```ruby
# All sorts of useful information about every country packaged as convenient little country objects.
gem "countries"
```
:::
```ruby
field :country, as: :country, display_code: true
```
## Options
You can easily choose to display the `code` of the country on **Index** and **Show** views by declaring `display_code` to `true`.
### Default value
`false`
### Possible values
`true`, `false`
---
# Date
The `Date` field may be used to display date values.
```ruby
field :birthday,
as: :date,
first_day_of_week: 1,
picker_format: "F J Y",
format: "yyyy-LL-dd",
placeholder: "Feb 24th 1955"
```
## Options
Format the date shown to the user on the `Index` and `Show` views.
#### Default
`{{ $frontmatter.default_format }}`
#### Possible values
Use [`luxon`](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) formatting tokens.
Format the date shown to the user on the `Edit` and `New` views.
#### Default
`{{ $frontmatter.default_picker_format }}`
#### Possible values
Use [`flatpickr`](https://flatpickr.js.org/formatting) formatting tokens.
Passes the options here to [flatpickr](https://flatpickr.js.org/).
#### Default
`{}`
#### Possible values
Use [`flatpickr`](https://flatpickr.js.org/options) options.
By default, flatpickr is [disabled on mobile](https://flatpickr.js.org/mobile-support/) because the mobile date pickers tend to give a better experience, but you can override that using `disable_mobile: true` (misleading to set it to `true`, I know. We're just forwarding the option). So that will override that behavior and display flatpickr on mobile devices too.
Set which should be the first date of the week in the picker calendar. Flatpickr [documentation](https://flatpickr.js.org/localization/) on that. 1 is Monday, and 7 is Sunday.
#### Default value
`1`
#### Possible values
`1`, `2`, `3`, `4`, `5`, `6`, and `7`
---
# DateTime
Format the date shown to the user on the `Index` and `Show` views.
#### Default
`{{ $frontmatter.default_format }}`
#### Possible values
Use [`luxon`](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) formatting tokens.
Format the date shown to the user on the `Edit` and `New` views.
#### Default
`{{ $frontmatter.default_picker_format }}`
#### Possible values
Use [`flatpickr`](https://flatpickr.js.org/formatting) formatting tokens.
Passes the options here to [flatpickr](https://flatpickr.js.org/).
#### Default
`{}`
#### Possible values
Use [`flatpickr`](https://flatpickr.js.org/options) options.
By default, flatpickr is [disabled on mobile](https://flatpickr.js.org/mobile-support/) because the mobile date pickers tend to give a better experience, but you can override that using `disable_mobile: true` (misleading to set it to `true`, I know. We're just forwarding the option). So that will override that behavior and display flatpickr on mobile devices too.
Set which should be the first date of the week in the picker calendar. Flatpickr [documentation](https://flatpickr.js.org/localization/) on that. 1 is Monday, and 7 is Sunday.
#### Default value
`1`
#### Possible values
`1`, `2`, `3`, `4`, `5`, `6`, and `7`
Displays time picker in 24-hour mode or AM/PM selection.
If `true`, the time will be relative to the configured `timezone`. If the timezone is not configured, the browser's timezone will be used.
If `false`, the time will be displayed as absolute in UTC and not change based on the browser's or configured timezone.
Select in which timezone the values should be cast.
:::warning
This option is only taken into account if the `relative` option is `true`.
:::
#### Default
If nothing is selected, the browser's timezone will be used.
#### Possible values
[TZInfo identifiers](https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html).
```ruby-vue{1,3}
field :start, as: :{{ $frontmatter.field_type }}, relative: true, timezone: "EET"
# Or
field :start, as: :{{ $frontmatter.field_type }}, relative: true, timezone: -> { record.timezone }
```
---
# EasyMDE
:::info
Before Avo 3.17 this field was called `markdown`. It was renamed to `easy_mde` so we can add our own implementation with `markdown`.
:::
By default, the content of the `easy_mde` field is not visible on the `Show` view, instead, it's hidden under a `Show Content` link that, when clicked, displays the content. You can set `easy_mde` to always display the content by setting `always_show` to `true`.
#### Default
`false`
#### Possible values
`true`, `false`
Sets the value of the editor
#### Default
`auto`
#### Possible values
`auto` or any number in pixels.
Toggles the editor's spell checker option.
```ruby
field :description, as: :easy_mde, spell_checker: true
```
#### Default
`false`
#### Possible values
`true`, `false`
---
# External image
You may have a field in the database that has the URL to an image, and you want to display that in Avo. That is where the `ExternalImage` field comes in to help.
It will take that value, insert it into an `image_tag`, and display it on the `Index` and `Show` views.
```ruby
field :logo, as: :external_image
```
## Options
All options can be static values or procs that are executed within Avo's execution context. When using procs, you have access to all the defaults that `Avo::ExecutionContext` provides plus:
- `record`
- `resource`
- `view`
- `field`
#### Default value
`40`
#### Possible values
Use any number to size the image, or a proc that returns a number.
#### Example with proc
```ruby
field :logo, as: :external_image, width: -> { view.index? ? 30 : 120 }
```
#### Default value
`40`
#### Possible values
Use any number to size the image, or a proc that returns a number.
#### Example with proc
```ruby
field :logo, as: :external_image, height: -> { view.index? ? 30 : 120 }
```
#### Default value
`0`
#### Possible values
Use any number to set the radius value, or a proc that returns a number.
#### Example with proc
```ruby
field :logo, as: :external_image, radius: -> { view.index? ? 4 : 8 }
```
Wraps the content into an anchor that links to the resource.
## Conditional sizing based on view
You can use procs to set different image dimensions and styling based on the current view:
```ruby
field :logo, as: :external_image,
width: -> { view.index? ? 40 : 150 },
height: -> { view.index? ? 40 : 150 },
radius: -> { view.index? ? 4 : 12 }
```
This example will display smaller, slightly rounded images on the index view (40x40px with 4px radius) and larger, more rounded images on the show view (150x150px with 12px radius).
## Use computed values
Another common scenario is to use a value from your database and create a new URL using a computed value.
```ruby
field :logo, as: :external_image do
"//logo.clearbit.com/#{URI.parse(record.url).host}?size=180"
rescue
nil
end
```
## Use in the Grid `cover` position
Another common place you could use it is in the grid `:cover` position.
```ruby
cover :logo, as: :external_image, link_to_record: true do
"//logo.clearbit.com/#{URI.parse(record.url).host}?size=180"
rescue
nil
end
```
---
# File
:::warning
You must manually require `activestorage` and `image_processing` gems in your `Gemfile`.
```ruby
# Active Storage makes it simple to upload and reference files
gem "activestorage"
# High-level image processing wrapper for libvips and ImageMagick/GraphicsMagick
gem "image_processing"
```
:::
The `File` field is the fastest way to implement file uploads in a Ruby on Rails app using [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html).
Avo will use your application's Active Storage settings with any supported [disk services](https://edgeguides.rubyonrails.org/active_storage_overview.html#disk-service).
```ruby
field :avatar, as: :file, is_image: true
```
## Authorization
:::info
Please ensure you have the `upload_{FIELD_ID}?`, `delete_{FIELD_ID}?`, and `download_{FIELD_ID}?` methods set on your model's **Pundit** policy. Otherwise, the input and download/delete buttons will be hidden.
:::
**Related:**
- Attachment pundit policies
## Variants
When using the `file` field to display an image, you can opt to show a processed variant of that image. This can be achieved using the `format_using` option.
### Example:
```ruby{3-5}
field :photo,
as: :file,
format_using: -> {
value.variant(resize_to_limit: [150, 150]).processed.image
}
```
## Options
Instructs the input to accept only a particular file type for that input using the `accept` option.
```ruby
field :cover_video, as: :file, accept: "image/*"
```
#### Default
`nil`
#### Possible values
`image/*`, `audio/*`, `doc/*`, or any other types from [the spec](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept).
Option that specify if the file should have the caption present or not.
```ruby
field :cover_video, as: :file, display_filename: false
```
#### Default
`true`
#### Possible values
`true`, `false`
Wraps the content into an anchor that links to the resource.
---
# Files
:::warning
You must manually require `activestorage` and `image_processing` gems in your `Gemfile`.
```ruby
# Active Storage makes it simple to upload and reference files
gem "activestorage"
# High-level image processing wrapper for libvips and ImageMagick/GraphicsMagick
gem "image_processing"
```
:::
The `Files` field is similar to `File` and enables you to upload multiple files at once using the same easy-to-use [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) implementation.
```ruby
field :documents, as: :files
```
## Options
Instructs the input to accept only a particular file type for that input using the `accept` option.
```ruby
field :cover_video, as: :file, accept: "image/*"
```
#### Default
`nil`
#### Possible values
`image/*`, `audio/*`, `doc/*`, or any other types from [the spec](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept).
Option that specify if the file should have the caption present or not.
```ruby
field :cover_video, as: :file, display_filename: false
```
#### Default
`true`
#### Possible values
`true`, `false`
## Authorization
:::info
Please ensure you have the `upload_{FIELD_ID}?`, `delete_{FIELD_ID}?`, and `download_{FIELD_ID}?` methods set on your model's **Pundit** policy. Otherwise, the input and download/delete buttons will be hidden.
:::
**Related:**
- Attachment pundit policies
Option to hide the view type switcher component.
#### Default
`false`
#### Possible values
`true`, `false`
---
# Gravatar
The `Gravatar` field turns an email field from the database into an avatar image if it's found in the [Gravatar](https://en.gravatar.com/site/implement/images/) database.
```ruby
field :email,
as: :gravatar,
rounded: false,
size: 60,
default_url: 'some image url'
```
## Options
Choose whether the rendered avatar should be rounded or not on the `Index` view.
On `Show`, the image is always a `square,` and the size is `responsive`.
#### Default
`true`
#### Possible values
`true`, `false`
Set the size of the avatar.
#### Default
`32`
#### Possible values
Any number in pixels. Remember that the size will influence the `Index` table row height.
Set the default image if the email address was not found in Gravatar's database.
#### Default
`32`
#### Possible values
Any number in pixels. Remember that the size will influence the `Index` table row height.
Wraps the content into an anchor that links to the resource.
## Using computed values
You may also pass in a computed value.
```ruby
field :email, as: :gravatar do
"#{record.google_username}@gmail.com"
end
```
---
# Heading
:::code-group
```ruby [Field id]
field :user_information, as: :heading
```
```ruby [Label]
field :some_id, as: :heading, label: "user information"
```
```ruby [Computed]
field :some_id, as: :heading do
"user information"
end
```
:::
The `as_html` option will render it as HTML.
```ruby
field :dev_heading, as: :heading, as_html: true do
'DEV
'
end
```
#### Default
`false`
#### Possible values
`true`, `false`
The content of `label` is the content displayed on the heading space.
```ruby
field :some_id, as: :heading, label: "user information"
```
---
# Hidden
There are scenarios where in order to be able to submit a form, an input should be present but inaccessible to the user. An example of this might be where you want to set a field by default without the option to change, or see it. `Hidden` will render a `
Wraps the content into an anchor that links to the resource.
---
# KeyValue
Customize the label for the key header.
#### Default
`I18n.translate("avo.key_value_field.key")`
#### Possible values
Any string value.
Customize the label for the value header.
#### Default
`I18n.translate("avo.key_value_field.value")`
#### Possible values
Any string value.
Customize the label for the add row button tooltip.
#### Default
`I18n.translate("avo.key_value_field.add_row")`
#### Possible values
Any string value.
Customize the label for the delete row button tooltip.
#### Default
`I18n.translate("avo.key_value_field.delete_row")`
#### Possible values
Any string value.
Toggle on/off the ability to disable editing keys, editing values, adding rows, and deleting rows for that field.
#### Default
`false`
#### Possible values
`true`, `false`
Toggle on/off the ability to edit the keys for that field. Turning this off will allow the user to customize only the value fields.
#### Default
`false`
#### Possible values
`true`, `false`
Toggle on/off the ability to edit the values for that field. Turning this off will allow the user to customize only the key fields.
#### Default
`false`
#### Possible values
`true`, `false`
Toggle on/off the ability to add new rows.
#### Default
`false`
#### Possible values
`true`, `false`
Toggle on/off the ability to delete rows from that field. Turning this on will prevent the user from deleting existing rows.
#### Default
`false`
#### Possible values
`true`, `false`
## Customizing the labels
You can easily customize the labels displayed in the UI by mentioning custom values in `key_label`, `value_label`, `action_text`, and `delete_text` properties when defining the field.
```ruby
field :meta, # The database field ID
as: :key_value, # The field type.
key_label: "Meta key", # Custom value for key header. Defaults to 'Key'.
value_label: "Meta value", # Custom value for value header. Defaults to 'Value'.
action_text: "New item", # Custom value for button to add a row. Defaults to 'Add'.
delete_text: "Remove item" # Custom value for button to delete a row. Defaults to 'Delete'.
```
## Enforce restrictions
You can enforce some restrictions by removing the ability to edit the field's key or value by setting `disable_editing_keys` or `disable_editing_values` to `true` respectively. If `disable_editing_keys` is set to `true`, be aware that this option will also disable adding rows as well. You can separately remove the ability to add a new row by setting `disable_adding_rows` to `true`. Deletion of rows can be enforced by setting `disable_deleting_rows` to `true`.
```ruby
field :meta, # The database field ID
as: :key_value, # The field type.
disable_editing_keys: false, # Option to disable the ability to edit keys. Implies disabling to add rows. Defaults to false.
disable_editing_values: false, # Option to disable the ability to edit values. Defaults to false.
disable_adding_rows: false, # Option to disable the ability to add rows. Defaults to false.
disable_deleting_rows: false # Option to disable the ability to delete rows. Defaults to false.
```
Setting `disabled: true` enforces all restrictions by disabling editing keys, editing values, adding rows, and deleting rows collectively.
```ruby
field :meta, # The database field ID
as: :key_value, # The field type.
disabled: true, # Option to disable editing keys, editing values, adding rows, and deleting rows. Defaults to false.
```
`KeyValue` is hidden on the `Index` view.
---
# Location
The `Location` field is used to display a point on a map.
```ruby
field :coordinates, as: :location
```
It's customary to have the coordinates in two distinct database columns, one named `latitude` and another `longitude`.
You can instruct Avo to use those two with the `stored_as` option
#### Default value
`nil`
#### Possible values
`nil`, or `[:latitude, :longitude]`.
```ruby
field :coordinates, as: :location, stored_as: [:latitude, :longitude]
```
By using this notation, Avo will grab the `latitude` and `longitude` from those particular columns to compose the map.
This will also render the
---
# Markdown
VIDEO
## Supported features
- [x] ActiveStorage file attachments
- [x] Media Library integration
- [x] Preview panel
- [x] [Ready-to-use renderer](https://github.com/avo-hq/marksmith#built-in-preview-renderer)
- [x] Text formatting
- [x] Lists
- [x] Links
- [x] Images
- [x] Tables
- [x] Code blocks
- [x] Headings
## Customize the renderer
There are two places where we parse the markdown into the HTML you see.
1. In the controller
2. In the
Controls the visibility of the **"Attach from gallery"** option in the markdown editor.
##### Default value
`true`
#### Possible values
- `true`
- `false`
#### Code example
```ruby
field :body, as: :markdown, media_library: false
```
Controls the visibility of the **"Upload files"** option in the markdown editor.
##### Default value
`true`
#### Possible values
- `true`
- `false`
#### Code example
```ruby
field :body, as: :markdown, file_uploads: false
```
Sends additional parameters to the **preview renderer** of the markdown field.
Useful for injecting context-specific data during preview rendering.
##### Default value
`{}`
#### Possible values
- Any `Hash` of key-value pairs.
#### Code example
```ruby
field :body, as: :markdown, extra_preview_params: { foo: :bar }
```
---
# Money
The `Money` field is used to display a monetary value.
```ruby
field :price, as: :money, currencies: %w[EUR USD RON PEN]
```
## Money Field Example
You can explore the implementation of the money field in [avodemo](https://main.avodemo.com/avo/resources/products/new) and it's corresponding code on GitHub [here](https://github.com/avo-hq/main.avodemo.com/blob/main/app/avo/resources/product.rb)
### Example on new
The `currencies` option controls which currencies will be visible on the dropdown.
```ruby
field :price, as: :money, currencies: %w[EUR USD RON PEN]
```
#### Default
By default it's going to be an empty array.
`[]`
#### Possible values
Add an array of currencies by the ISO code.
`%w[EUR USD RON PEN]`
---
# Number
The `number` field renders a `input[type="number"]` element.
```ruby
field :age, as: :number
```
## Options
Set the `min` attribute.
#### Default
`nil`
#### Possible values
Any number.
Set the `max` attribute.
#### Default
`nil`
#### Possible values
Any number.
Set the `step` attribute.
#### Default
`nil`
#### Possible values
Any number.
## Examples
```ruby
field :age, as: :number, min: 0, max: 120, step: 5
```
---
# Password
The `Password` field renders a `input[type="password"]` element for that field. By default, it's visible only on the `Edit` and `New` views.
```ruby
field :password, as: :password
```
#### Revealable
Sets the maximum value of the progress bar.
#### Default
`100`
#### Possible values
Any number.
Sets the step in which the user can move the slider on the `Edit` and `New` views.
#### Default
`1`
#### Possible values
Any number.
Choose if the value is displayed on the `Edit` and `New` views above the slider.
#### Default
`true`
#### Possible values
`true`, `false`
Set a string value to be displayed after the value above the progress bar.
#### Default
`nil`
#### Possible values
`%` or any other string.
## Examples
```ruby
field :progress,
as: :progress_bar,
max: 150,
step: 10,
display_value: true,
value_suffix: "%"
```
The `options` attribute accepts either a `Hash` or a proc, allowing the incorporation of custom logic. Within this block, you gain access to all attributes of `Avo::ExecutionContext` along with the `record`, `resource`, `view` and `field`.
This attribute represents the options that should be displayed in the radio buttons.
#### Default value
Empty `Hash`.
```ruby
{}
```
#### Possible values
Any `Hash`. The keys represent the value that will be persisted and the values are the visible labels. Example:
```ruby
options: {
admin: "Administrator",
manager: "Manager",
writer: "Writer"
}
```
Or a `Proc`:
```ruby
options: -> do
record.roles.each_with_object({}) do |role, hash|
hash[role.id] = role.name.humanize
end
end
```
---
# Record link
Sometimes you just need to link to a field. That's it!
This is what this field does. You give it a record and it will link to it.
That record can come off an association a method or any kind of property on the record instance.
:::info Add this field to the `Gemfile`
```ruby
# Gemfile
gem "avo-record_link_field"
```
:::
:::warning
That record you're pointing to should have a resource configured.
:::
```ruby{14,19}
class Comment < ApplicationRecord
# Your model must return an instance of a record
has_one :post
# or
belongs_to :post
# or
def post
# trivially find a post
Post.find 42
end
end
# Calling the method like so will give us an instance of a Post
Comment.first.post => #
class Avo::Resources::Comment < Avo::BaseResource
def fields
# This will run `record.post` and try to display whatever is returned.
field :post, as: :record_link
end
end
```
In case you want to set the target to `_blank`.
#### Default value
`nil`
#### Possible values
`:self`, `:blank`
#### Example
```ruby
field :post, as: :record_link, target: :blank
```
Because you only give it an instance of a record, Avo will try to guess which resource it should use to display the title of the record and how to compute it's link.
With more advanced configurations (when you have multiple resources for the same model) that resource might not be the one that you wish for.
Using the `use_resource` configuration value you can tell Avo which resource it should use.
#### Default value
`nil`
#### Possible values
`big_post`, `AdminUser`, `Avo::Resources::TinyPhoto`
#### Example
```ruby
field :post, as: :record_link, use_resource: "big_post"
field :admin, as: :record_link, use_resource: "AdminUser"
field :thumbnail, as: :record_link, use_resource: "Avo::Resources::TinyPhoto"
```
In other places where Avo generates a link to a record like in the `belongs_to` field, Avo adds `via` params to the URL so it knows how to generate the back button link.
That URL can also be passed on to other team mates and everyone can have the same navigation experience.
In the `record_link` field Avo adds these params automatically, but that might not be what you want. You can remove those `via` params by setting the `add_via_params` option to `false`.
#### Default value
`true`
#### Possible values
`true`, `false`
#### Example
```ruby
# This will generate a link similar to this
# https://example.com/avo/resources/projects/40?via_record_id=40&via_resource_class=Avo%3A%3AResources%3A%3AProject
field :post, as: :record_link, add_via_params: true
# This will generate a link similar to this
# https://example.com/avo/resources/projects/40
field :post, as: :record_link, add_via_params: false
```
## Using computed values
Of course you can take full control of this field and use your computed values too.
In order to do that, open a block and run some ruby query to return an instance of a record.
#### Example
```ruby
field :post, as: :record_link do
# This will generate a link similar to this
# https://example.com/avo/resources/posts/42
Post.find 42
end
# or
field :creator, as: :record_link, add_via_params: false do
user_id = SomeService.new(comment: record).fetch_user_id # returns 31
# This will generate a link similar to this
# https://example.com/avo/resources/users/31
User.find user_id
end
# or
field :creator, as: :record_link, use_resource: "AdminUser", add_via_params: false do
user_id = SomeService.new(comment: record).fetch_user_id # returns 31
# This will generate a link similar to this
# https://example.com/avo/resources/admin_users/31
User.find user_id
end
```
---
# Rhino
By default, the content of the field is not visible on the `Show` view; instead, it's hidden under a `Show Content` link that, when clicked, displays the content. You can set it to display the content by setting `always_show` to `true`.
---
# Select
The `Select` field renders a `select` field.
```ruby
field :type, as: :select, options: { 'Large container': :large, 'Medium container': :medium, 'Tiny container': :tiny }, display_value: true, placeholder: 'Choose the type of the container.'
```
A `Hash` representing the options that should be displayed in the select. The keys represent the labels, and the values represent the value stored in the database.
The options get cast as `ActiveSupport::HashWithIndifferentAccess` objects if they are a `Hash`.
#### Default
`nil`
#### Possible values
- `{ 'Large container': :large, 'Medium container': :medium, 'Tiny container': :tiny }` or any other `Hash`.
- A lambda function that returns a `Hash` (computed options)
### Computed options
You may want to compute the values on the fly for your `Select` field. You can use a lambda for that where you have access to the `record`, `resource`, `view`, and `field` properties where you can pull data off.
```ruby{5-7}
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
field :type,
as: :select,
options: -> do
record.get_types_from_the_database.map { |type| [type.name, type.id] }
end,
placeholder: 'Choose the type of the container.'
end
```
The output value must be a supported [`options_for_select`](https://apidock.com/rails/ActionView/Helpers/FormOptionsHelper/options_for_select) value.
Set the select options as an Active Record [enum](https://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html). You may use `options` or `enum`, not both.
```ruby{3,10}
# app/models/project.rb
class Project < ApplicationRecord
enum type: { 'Large container': 'large', 'Medium container': 'medium', 'Tiny container': 'small' }
end
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
field :type,
as: :select,
enum: ::Project.types,
display_value: true,
placeholder: 'Choose the type of the container.'
end
```
#### Default
`nil`
#### Possible values
`Post::statuses` or any other `enum` stored on a model.
You may want to display the values from the database and not the labels of the options. You may configure this behaviour by setting `display_value` to `true`. Note that this setting has no effect if an array of options is provided.
```ruby{5}
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
field :type,
as: :select,
display_value: true
end
```
#### Default
`false`
#### Possible values
`true`, `false`
The `Select` field also has the `include_blank` option. That can have three values.
If it's set to `false` (default), it will not show any blank option but only the options you configured.
If it's set to `true` and you have a `placeholder` value assigned, it will use that placeholder string as the first option.
If it's a string `include_blank: "No country"`, the `No country` string will appear as the first option in the `` and will set the value empty or `nil` depending on your settings.
```ruby{5}
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
field :type,
as: :select,
include_blank: 'No type'
end
```
#### Default
`nil`
#### Possible values
`nil`, `true`, `false`, or a string to be used as the first option.
---
# Stars
The `stars` field renders a star rating display on
Sets the maximum number of stars to display.
#### Default
`5`
#### Possible values
Any positive integer.
## Examples
```ruby
field :rating, as: :stars
```
```ruby
field :rating, as: :stars, max: 10
```
The field stores a numeric value (e.g., `0` to `5` for a 5-star rating). On edit forms, users can click on stars to set the rating. Filled stars represent the current value, while unfilled stars show the remaining capacity up to the maximum.
---
# Status
Displays the status of a record in three ways; `loading`, `failed`, `success`, or `neutral`.
You may select the `loading`, `failed`, and `success` state values, and everything else will fall back to `neutral`.
```ruby
field :progress,
as: :status,
failed_when: [:closed, :rejected, :failed],
loading_when: [:loading, :running, :waiting, "in progress"],
success_when: [:done],
```
Set the values for when the status is `failed`.
#### Default value
`[]`
#### Possible values
`[:closed, :rejected, :failed]` or an array with strings or symbols that indicate the `failed` state.
Set the values for when the status is `loading`.
#### Default value
`[]`
#### Possible values
`[:loading, :running, :waiting, "in progress"]` or an array with strings or symbols that indicate the `loading` state.
Set the values for when the status is `success`.
#### Default value
`[]`
#### Possible values
`[:done, :success, :deployed, "ok"]` or an array with strings or symbols that indicate the `success` state.
Set the values for when the status is `neutral`.
#### Default value
`[]`
#### Possible values
`[:holding, "waiting"]` or an array with strings or symbols that indicate a `neutral` state.
---
# Tags field
Adding a list of things to a record is something we need to do pretty frequently; that's why having the `tags` field is helpful.
```ruby
field :skills, as: :tags
```
:::warning
**This warning no longer applies**
The `disallowed` param works similarly to `suggestions`. Use it to prevent the user from adding specific values.
```ruby{3}
field :skills,
as: :tags,
disallowed: ["not", "that"]
```
Set whether the field should accept other values outside the suggested ones. If set to `true` the user won't be able to add anything else than what you posted in the `suggestions` option.
```ruby{4}
field :skills,
as: :tags,
suggestions: %w(one two three),
enforce_suggestions: true
```
Set of suggestions that can be displayed at once. The excessive items will be hidden and the user will have to narrow down the query to see them.
```ruby{4}
field :skills,
as: :tags,
suggestions: %w(one two three),
suggestions_max_items: 2
```
Set whether the `suggestions` dropdown should close after the user makes a selection.
```ruby{4}
field :items,
as: :tags,
suggestions: -> { Post.tags_suggestions },
close_on_select: true
```
Set the field the `acts_as_taggable_on` is set.
#### Default
`nil`
#### Possible values
Any string or symbol you have configured on your corresponding model.
Set the characters that will cut off the content into tags when the user inputs the tags.
```ruby{3}
field :skills,
as: :tags,
delimiters: [",", " "]
```
By default, the tags field produces an array of items (ex: categories for posts), but in some scenarios you might want it to produce a single value (ex: dynamically search for users and select just one). Use `mode: :select` to make the field produce a single value as opposed to an array of values.
```ruby{3}
field :skills,
as: :tags,
mode: :select
```
#### Default
`nil`
#### Possible values
Valid values are `nil` for array values and `select` for a single value.
There might be cases where you want to dynamically fetch the values from an API. The `fetch_values_from` option enables you to pass a URL from where the field should suggest values.
This options works wonderful when used in Actions.
```ruby{3}
field :skills,
as: :tags,
fetch_values_from: "/avo/resources/skills/skills_for_user"
```
When the user searches for a record, the field will perform a request to the server to fetch the records that match that query.
:::warning
Deprecated since
:::info
Since
## PostgreSQL array fields
You can use the tags field with the PostgreSQL array field.
```ruby{11}
# app/avo/resources/course.rb
class Avo::Resources::Course < Avo::BaseResource
def fields
field :skills, as: :tags
end
end
# db/migrate/add_skills_to_courses.rb
class AddSkillsToCourses < ActiveRecord::Migration[6.0]
def change
add_column :courses, :skills, :text, array: true, default: []
end
end
```
## Acts as taggable on
One popular gem used for tagging is [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on). The tags field integrates very well with it.
You need to add `gem 'acts-as-taggable-on', '~> 9.0'` in your `Gemfile`, add it to your model `acts_as_taggable_on :tags`, and use `acts_as_taggable_on` on the field.
```ruby{6}
# app/avo/resources/post.rb
class Avo::Resources::Post < Avo::BaseResource
def fields
field :tags,
as: :tags,
acts_as_taggable_on: :tags,
close_on_select: false,
placeholder: 'add some tags',
suggestions: -> { Post.tags_suggestions },
enforce_suggestions: true,
help: 'The only allowed values here are `one`, `two`, and `three`'
end
end
# app/models/post.rb
class Post < ApplicationRecord
acts_as_taggable_on :tags
end
```
That will let Avo know which attribute should be used to fill with the user's tags.
:::info Related
You can set up the tags as a resource using this guide.
:::
## Array fields
We haven't tested all the scenarios, but the tags field should play nicely with any array fields provided by Rails.
```ruby{10-12,14-16}
# app/avo/resources/post.rb
class Avo::Resources::Post < Avo::BaseResource
def fields
field :items, as: :tags
end
end
# app/models/post.rb
class Post < ApplicationRecord
def items=(items)
puts ["items->", items].inspect
end
def items
%w(1 2 3 4)
end
end
```
---
# Text
The `Text` field renders a regular `
Displays the value as HTML on the `Index` and `Show` views. Useful when you need to link to another record.
```ruby
field :title, as: :text, as_html: true do
'Avo '
end
```
#### Default
`false`
#### Possible values
`true`, `false`
Render the value with a protocol prefix on the `Index` and `Show` views. So, for example, you can make a text field a `mailto` link very quickly.
```ruby{3}
field :email,
as: :text,
protocol: :mailto
```
Wraps the content into an anchor that links to the resource.
## Customization
You may customize the `Text` field with as many options as you need.
```ruby
field :title, # The database field ID
as: :text, # The field type
name: 'Post title', # The label you want displayed
required: true, # Display it as required
readonly: true, # Display it disabled
as_html: true # Should the output be parsed as html
placeholder: 'My shiny new post', # Update the placeholder text
format_using: -> { value.truncate 3 } # Format the output
```
---
# Textarea
The `textarea` field renders a `` element.
:::tip
By default, the `textarea` field don't have a component for the Index view. For this reason, on the Index view the field is not even visible.
Follow the Generating a custom component for a field guide to add a component to the index view for this field.
:::
```ruby
field :body, as: :textarea
```
## Options
Set the number of rows visible in the `Edit` and `New` views.
```ruby
field :body, as: :textarea, rows: 5
```
#### Default
`5`
#### Possible values
Any integer.
---
# Time
Format the date shown to the user on the `Index` and `Show` views.
#### Default
`{{ $frontmatter.default_format }}`
#### Possible values
Use [`luxon`](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) formatting tokens.
Format the date shown to the user on the `Edit` and `New` views.
#### Default
`{{ $frontmatter.default_picker_format }}`
#### Possible values
Use [`flatpickr`](https://flatpickr.js.org/formatting) formatting tokens.
Passes the options here to [flatpickr](https://flatpickr.js.org/).
#### Default
`{}`
#### Possible values
Use [`flatpickr`](https://flatpickr.js.org/options) options.
By default, flatpickr is [disabled on mobile](https://flatpickr.js.org/mobile-support/) because the mobile date pickers tend to give a better experience, but you can override that using `disable_mobile: true` (misleading to set it to `true`, I know. We're just forwarding the option). So that will override that behavior and display flatpickr on mobile devices too.
Displays time picker in 24-hour mode or AM/PM selection.
If `true`, the time will be relative to the configured `timezone`. If the timezone is not configured, the browser's timezone will be used.
If `false`, the time will be displayed as absolute in UTC and not change based on the browser's or configured timezone.
Select in which timezone the values should be cast.
:::warning
This option is only taken into account if the `relative` option is `true`.
:::
#### Default
If nothing is selected, the browser's timezone will be used.
#### Possible values
[TZInfo identifiers](https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html).
```ruby-vue{1,3}
field :start, as: :{{ $frontmatter.field_type }}, relative: true, timezone: "EET"
# Or
field :start, as: :{{ $frontmatter.field_type }}, relative: true, timezone: -> { record.timezone }
```
---
# Tip Tap
The `TipTap` field is deprecated in favor of the Rhino field.
The Rhino field is a fork of the TipTap editor with some additional features and improvements.
The Rhino field is fully integrated with Avo and provides a seamless experience for managing rich text content using the [ActiveStorage](https://guides.rubyonrails.org/active_storage_overview.html) integration and the Media Library.
---
# Trix
```ruby
field :body, as: :trix
```
The `Trix` field renders a [WYSIWYG Editor](https://trix-editor.org/) and can be associated with a `string` or `text` column in the database. The value stored in the database will be the editor's resulting `HTML` content.
It supports [ActiveStorage](https://guides.rubyonrails.org/active_storage_overview.html) file attachments, [ActionText](https://guides.rubyonrails.org/action_text_overview.html), and seamlessly integrates with the Media Library.
By default, the content of the field is not visible on the `Show` view; instead, it's hidden under a `Show Content` link that, when clicked, displays the content. You can set it to display the content by setting `always_show` to `true`.
Hides the attachments button from the Trix toolbar.
#### Default
`false`
#### Possible values
`true`, `false`
Hides the attachment's name from the upload output in the field value.
#### Default
`false`
#### Possible values
`true`, `false`
Hides the attachment size from the upload output in the field value.
#### Default
`false`
#### Possible values
`true`, `false`
Hides the attachment URL from the upload output in the field value.
#### Default
`false`
#### Possible values
`true`, `false`
Enables file attachments.
#### Default
`nil`
#### Possible values
`nil`, or a symbol representing the `has_many_attachments` key on the model.
## File attachments
:::warning
You must manually require `activestorage` and `image_processing` gems in your `Gemfile`.
```ruby
# Active Storage makes it simple to upload and reference files
gem "activestorage"
# High-level image processing wrapper for libvips and ImageMagick/GraphicsMagick
gem "image_processing"
```
:::
Trix supports drag-and-drop file attachments. To enable **Active Storage** integration, you must add the `attachment_key` option to your Trix field.
```ruby
field :body, as: :trix, attachment_key: :trix_attachments
```
That `attachment_key` has to have the same name as the model.
```ruby{2}
class Post < ApplicationRecord
has_many_attached :trix_attachments
end
```
Now, when you upload a file in the Trix field, Avo will create an Active Record attachment.
## Disable attachments
You may want to use Trix only as a text editor and disable the attachments feature. Adding the `attachments_disabled` option will hide the attachments button (paperclip icon).
```ruby
field :body, as: :trix, attachments_disabled: true
```
## Remove attachment attributes
By default, Trix will add some meta-data in the editor (filename, filesize, and URL) when adding an attachment. You might not need those to be present in the document. You can hide them using `hide_attachment_filename`, `hide_attachment_filesize`, and `hide_attachment_url`.
## Active Storage
Trix integrates seamlessly with Active Storage. When you use it with a plain database column on a record table (not with Action Text) you have to set the `attachment_key` option (documented above).
## Action Text
Trix integrates seamlessly with Action Text. It will automatically work with Action Text as well and it won't require you to add an `attachment_key`.
## Demo app
We prepared a [demo](https://trix.avodemo.com/) to showcase Trix's abilities to work with Action Text and Active Storage.
## Javascript Alert Messages
Turns the attach field/modal from a `select` input to a searchable experience
```ruby{5}
class Avo::Resources::CourseLink < Avo::BaseResource
def fields
field :links,
as: :has_many,
searchable: true
end
end
```
:::warning
Avo uses the **resource search feature** behind the scenes, so **make sure the target resource has the `search_query` option configured**.
:::
```ruby{3-7}
# app/avo/resources/course_link.rb
class Avo::Resources::CourseLink < Avo::BaseResource
self.search = {
query: -> {
query.ransack(id_eq: q, link_cont: q, m: "or").result(distinct: false)
}
}
end
```
#### Default
`false`
#### Possible values
`true`, `false`
Keeps the field enabled when visiting from the parent record.
#### Default
`false`
#### Possible values
`true`, `false`
Scope out the records the user sees on the Attach modal.
#### Default
`nil`
#### Possible values
```ruby{3}
field :user,
as: :belongs_to,
attach_scope: -> { query.non_admins }
```
Pass in a block where you attach scopes to the `query` object and `parent` object, which is the actual record where you want to assign the association. The block is executed in the `ExecutionContext`.
:::warning
The `attach_scope` will not filter the records in the listing from `has_many` or `has_and_belongs_to_many` associations.
Use [`scope`](#scope) or a Pundit policy `Scope` for that.
:::
```ruby-vue{3}
field :members,
as: :{{ $frontmatter.field_type }},
attach_scope: -> { query.where.not(team_id: parent.id) }
```
In this example, in the `attach_scope`, we ensure that when attaching members to a team, only those who are not already members will appear in the list of options.
Sets the field as polymorphic with the key set on the model.
#### Default
`nil`
#### Possible values
A symbol, used on the `belongs_to` association with `polymorphic: true`.
:::warning
You must use this option with the `types` option.
:::
#### Example
```ruby
field :commentable, as: :belongs_to, polymorphic_as: :commentable, types: [::Post, ::Project]
```
Sets the types the field can morph to.
#### Default
`[]`
#### Possible values
`[Post, Project, Team]`. Any array of model names.
:::warning
You must use this option with the `polymorphic_as` option.
:::
#### Example
```ruby
field :commentable, as: :belongs_to, polymorphic_as: :commentable, types: [::Post, ::Project]
```
Sets the help text for the polymorphic type dropdown. Useful when you need to specify to the user why and what they need to choose as polymorphic.
#### Default
`nil`
#### Possible values
Any string.
Sets a different resource to be used when displaying (or redirecting to) the association table.
#### Default
`nil`. When nothing is selected, Avo infers the resource type from the reflected association.
#### Possible values
`Avo::Resources::Post`, `Avo::Resources::PhotoComment`, or any Avo resource class.
The value can be the actual class or a string representation of that class.
```ruby
# the class
Avo::Resources::Post
# the string representation of the class
"Avo::Resources::Post"
```
Controls the creation link visibility on forms.
#### Default
`true`
#### Possible values
`true`, `false`
:::warning Since version
## Overview
On the `Index` and `Show` views, Avo will generate a link to the associated record containing the `self.title` value of the target resource.
Turns the attach field/modal from a `select` input to a searchable experience
```ruby{5}
class Avo::Resources::CourseLink < Avo::BaseResource
def fields
field :links,
as: :has_many,
searchable: true
end
end
```
:::warning
Avo uses the **resource search feature** behind the scenes, so **make sure the target resource has the `search_query` option configured**.
:::
```ruby{3-7}
# app/avo/resources/course_link.rb
class Avo::Resources::CourseLink < Avo::BaseResource
self.search = {
query: -> {
query.ransack(id_eq: q, link_cont: q, m: "or").result(distinct: false)
}
}
end
```
#### Default
`false`
#### Possible values
`true`, `false`
Scope out the records the user sees on the Attach modal.
#### Default
`nil`
#### Possible values
```ruby{3}
field :user,
as: :belongs_to,
attach_scope: -> { query.non_admins }
```
Pass in a block where you attach scopes to the `query` object and `parent` object, which is the actual record where you want to assign the association. The block is executed in the `ExecutionContext`.
:::warning
The `attach_scope` will not filter the records in the listing from `has_many` or `has_and_belongs_to_many` associations.
Use [`scope`](#scope) or a Pundit policy `Scope` for that.
:::
```ruby-vue{3}
field :members,
as: :{{ $frontmatter.field_type }},
attach_scope: -> { query.where.not(team_id: parent.id) }
```
In this example, in the `attach_scope`, we ensure that when attaching members to a team, only those who are not already members will appear in the list of options.
## Show on edit screens
By default, the `{{ $frontmatter.field_type }}` field is only visible in the show view. To make it available in the edit view as well, include the `show_on: :edit` option. This ensures that the `{{ $frontmatter.field_type }}` show view component is also rendered within the edit view.
## Nested in Forms
You can use ["Show on edit screens"](#show-on-edit-screens) to make the `{{ $frontmatter.field_type }}` field available in the edit view. However, this will render it using the show view component.
To enable nested creation for the `{{ $frontmatter.field_type }}` field, allowing it to be created and / or edited alongside its parent record within the same form, use the `nested` option which is a hash with configurable option.
:::info The `avo-nested` gem
Nested association forms are provided by the **`avo-nested`** gem. Add it to your `Gemfile` using the same private gem source as your other Avo paid gems:
```ruby
gem "avo-nested", source: "https://packager.dev/avo-hq/"
```
Run `bundle install`. If you have not set up packager.dev access yet, see Gem server authentication.
:::
Keep in mind that this will display the fieldβs resource as it appears in the edit view.
Enables this field as a nested form in the specified views.
##### Default value
`{}`
#### Possible values
A hash with the following options:
- `on:` Views in which to enable nesting. Accepted values:
- `:new` - Enables nesting in the new view.
- `:edit` - Enables nesting in the edit view.
- `:forms` - Enables nesting in the new and edit views.
- `limit:` *(Only for `has_many` and `has_and_belongs_to_many` fields)* Hides the "Add" button when the specified limit is reached.
:::tip
Setting `nested: true` is a shortcut for `nested: { on: :forms }`.
:::
#### Example
```ruby-vue{4,5,7,8,10,11,13-14,16-19}
# app/avo/resources/book.rb
class Avo::Resources::Book < Avo::BaseResource
def fields
# Shortcut for full nesting
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: true
# Explicit nesting on new only
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: { on: :new }
# Explicit nesting on edit only
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: { on: :edit }
# Explicit nesting on both new and edit
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: { on: :forms }
# Limit nested creation (for has_many or has_and_belongs_to_many only)
field :authors,
as: :{{ $frontmatter.field_type }},
nested: { on: [:new, :edit], limit: 2 }
end
end
```
---
# Has Many
By default, the `HasMany` field is visible only on the `Show` view. You will see a new panel with the model's associated records below the regular fields panel.
```ruby
field :projects, as: :has_many
```
## Options
Turns the attach field/modal from a `select` input to a searchable experience
```ruby{5}
class Avo::Resources::CourseLink < Avo::BaseResource
def fields
field :links,
as: :has_many,
searchable: true
end
end
```
:::warning
Avo uses the **resource search feature** behind the scenes, so **make sure the target resource has the `search_query` option configured**.
:::
```ruby{3-7}
# app/avo/resources/course_link.rb
class Avo::Resources::CourseLink < Avo::BaseResource
self.search = {
query: -> {
query.ransack(id_eq: q, link_cont: q, m: "or").result(distinct: false)
}
}
end
```
#### Default
`false`
#### Possible values
`true`, `false`
Scope out the records the user sees on the Attach modal.
#### Default
`nil`
#### Possible values
```ruby{3}
field :user,
as: :belongs_to,
attach_scope: -> { query.non_admins }
```
Pass in a block where you attach scopes to the `query` object and `parent` object, which is the actual record where you want to assign the association. The block is executed in the `ExecutionContext`.
:::warning
The `attach_scope` will not filter the records in the listing from `has_many` or `has_and_belongs_to_many` associations.
Use [`scope`](#scope) or a Pundit policy `Scope` for that.
:::
```ruby-vue{3}
field :members,
as: :{{ $frontmatter.field_type }},
attach_scope: -> { query.where.not(team_id: parent.id) }
```
In this example, in the `attach_scope`, we ensure that when attaching members to a team, only those who are not already members will appear in the list of options.
Scope out the records displayed in the table.
#### Default
`nil`
#### Possible values
```ruby{3}
field :user,
as: :belongs_to,
scope: -> { query.approved }
```
Pass in a block where you attach scopes to the `query` object. The block gets executed in the `ExecutionContext`.
With version 2.5.0, you'll also have access to the `parent` record so that you can use that to scope your associated models even better.
Starting with version 3.12, access to `resource` and `parent_resource` was additionally provided.
Changes the text displayed as association name.
#### Default
Plural association name.
#### Possible values
Any string or any zero arity lambda function.
Within lambda, you have access to all attributes of `Avo::ExecutionContext`.
Changes the text displayed under the association name.
Sets a different resource to be used when displaying (or redirecting to) the association table.
#### Default
`nil`. When nothing is selected, Avo infers the resource type from the reflected association.
#### Possible values
`Avo::Resources::Post`, `Avo::Resources::PhotoComment`, or any Avo resource class.
The value can be the actual class or a string representation of that class.
```ruby
# the class
Avo::Resources::Post
# the string representation of the class
"Avo::Resources::Post"
```
Hides the pagination details when only there's only one page for that association.
#### Default
`false`
#### Possible values
`true`, `false`
Hides the search input displayed on the association table.
#### Default
`false`. When nothing is selected and the `search_query` of association's resource is configured, Avo displays the search input.
#### Possible values
`true`, `false`.
Hides the filters button displayed on the association table.
#### Default
`false`. The filters button is displayed by default and only hidden when `hide_filter_button` is set to `true`
#### Possible values
`true`, `false`.
Sets which resource should be used in an STI scenario.
See more on this in the STI section.
#### Default
`false`. When it's `false` it will use the same resource.
#### Possible values
`true`, `false`.
## Search query scope
You can add use this option to make the association title clickable. That link will open a new page with the same view.
This feature doesn't go deeper than this. It just helps you see the association table easier in a separate page.
## Has Many Through
The `HasMany` association also supports the `:through` option.
```ruby{3}
field :members,
as: :has_many,
through: :memberships
```
## Show on edit screens
By default, the `{{ $frontmatter.field_type }}` field is only visible in the show view. To make it available in the edit view as well, include the `show_on: :edit` option. This ensures that the `{{ $frontmatter.field_type }}` show view component is also rendered within the edit view.
## Nested in Forms
You can use ["Show on edit screens"](#show-on-edit-screens) to make the `{{ $frontmatter.field_type }}` field available in the edit view. However, this will render it using the show view component.
To enable nested creation for the `{{ $frontmatter.field_type }}` field, allowing it to be created and / or edited alongside its parent record within the same form, use the `nested` option which is a hash with configurable option.
:::info The `avo-nested` gem
Nested association forms are provided by the **`avo-nested`** gem. Add it to your `Gemfile` using the same private gem source as your other Avo paid gems:
```ruby
gem "avo-nested", source: "https://packager.dev/avo-hq/"
```
Run `bundle install`. If you have not set up packager.dev access yet, see Gem server authentication.
:::
Keep in mind that this will display the fieldβs resource as it appears in the edit view.
Enables this field as a nested form in the specified views.
##### Default value
`{}`
#### Possible values
A hash with the following options:
- `on:` Views in which to enable nesting. Accepted values:
- `:new` - Enables nesting in the new view.
- `:edit` - Enables nesting in the edit view.
- `:forms` - Enables nesting in the new and edit views.
- `limit:` *(Only for `has_many` and `has_and_belongs_to_many` fields)* Hides the "Add" button when the specified limit is reached.
:::tip
Setting `nested: true` is a shortcut for `nested: { on: :forms }`.
:::
#### Example
```ruby-vue{4,5,7,8,10,11,13-14,16-19}
# app/avo/resources/book.rb
class Avo::Resources::Book < Avo::BaseResource
def fields
# Shortcut for full nesting
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: true
# Explicit nesting on new only
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: { on: :new }
# Explicit nesting on edit only
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: { on: :edit }
# Explicit nesting on both new and edit
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: { on: :forms }
# Limit nested creation (for has_many or has_and_belongs_to_many only)
field :authors,
as: :{{ $frontmatter.field_type }},
nested: { on: [:new, :edit], limit: 2 }
end
end
```
## Add scopes to associations
---
# Has And Belongs To Many
The `HasAndBelongsToMany` association works similarly to `HasMany`.
```ruby
field :users, as: :has_and_belongs_to_many
```
## Options
Turns the attach field/modal from a `select` input to a searchable experience
```ruby{5}
class Avo::Resources::CourseLink < Avo::BaseResource
def fields
field :links,
as: :has_many,
searchable: true
end
end
```
:::warning
Avo uses the **resource search feature** behind the scenes, so **make sure the target resource has the `search_query` option configured**.
:::
```ruby{3-7}
# app/avo/resources/course_link.rb
class Avo::Resources::CourseLink < Avo::BaseResource
self.search = {
query: -> {
query.ransack(id_eq: q, link_cont: q, m: "or").result(distinct: false)
}
}
end
```
#### Default
`false`
#### Possible values
`true`, `false`
Scope out the records the user sees on the Attach modal.
#### Default
`nil`
#### Possible values
```ruby{3}
field :user,
as: :belongs_to,
attach_scope: -> { query.non_admins }
```
Pass in a block where you attach scopes to the `query` object and `parent` object, which is the actual record where you want to assign the association. The block is executed in the `ExecutionContext`.
:::warning
The `attach_scope` will not filter the records in the listing from `has_many` or `has_and_belongs_to_many` associations.
Use [`scope`](#scope) or a Pundit policy `Scope` for that.
:::
```ruby-vue{3}
field :members,
as: :{{ $frontmatter.field_type }},
attach_scope: -> { query.where.not(team_id: parent.id) }
```
In this example, in the `attach_scope`, we ensure that when attaching members to a team, only those who are not already members will appear in the list of options.
Scope out the records displayed in the table.
#### Default
`nil`
#### Possible values
```ruby{3}
field :user,
as: :belongs_to,
scope: -> { query.approved }
```
Pass in a block where you attach scopes to the `query` object. The block gets executed in the `ExecutionContext`.
With version 2.5.0, you'll also have access to the `parent` record so that you can use that to scope your associated models even better.
Starting with version 3.12, access to `resource` and `parent_resource` was additionally provided.
Changes the text displayed as association name.
#### Default
Plural association name.
#### Possible values
Any string or any zero arity lambda function.
Within lambda, you have access to all attributes of `Avo::ExecutionContext`.
Changes the text displayed under the association name.
Sets a different resource to be used when displaying (or redirecting to) the association table.
#### Default
`nil`. When nothing is selected, Avo infers the resource type from the reflected association.
#### Possible values
`Avo::Resources::Post`, `Avo::Resources::PhotoComment`, or any Avo resource class.
The value can be the actual class or a string representation of that class.
```ruby
# the class
Avo::Resources::Post
# the string representation of the class
"Avo::Resources::Post"
```
Hides the pagination details when only there's only one page for that association.
#### Default
`false`
#### Possible values
`true`, `false`
Hides the search input displayed on the association table.
#### Default
`false`. When nothing is selected and the `search_query` of association's resource is configured, Avo displays the search input.
#### Possible values
`true`, `false`.
Hides the filters button displayed on the association table.
#### Default
`false`. The filters button is displayed by default and only hidden when `hide_filter_button` is set to `true`
#### Possible values
`true`, `false`.
## Search query scope
You can use ["Show on edit screens"](#show-on-edit-screens) to make the `{{ $frontmatter.field_type }}` field available in the edit view. However, this will render it using the show view component.
To enable nested creation for the `{{ $frontmatter.field_type }}` field, allowing it to be created and / or edited alongside its parent record within the same form, use the `nested` option which is a hash with configurable option.
:::info The `avo-nested` gem
Nested association forms are provided by the **`avo-nested`** gem. Add it to your `Gemfile` using the same private gem source as your other Avo paid gems:
```ruby
gem "avo-nested", source: "https://packager.dev/avo-hq/"
```
Run `bundle install`. If you have not set up packager.dev access yet, see Gem server authentication.
:::
Keep in mind that this will display the fieldβs resource as it appears in the edit view.
Enables this field as a nested form in the specified views.
##### Default value
`{}`
#### Possible values
A hash with the following options:
- `on:` Views in which to enable nesting. Accepted values:
- `:new` - Enables nesting in the new view.
- `:edit` - Enables nesting in the edit view.
- `:forms` - Enables nesting in the new and edit views.
- `limit:` *(Only for `has_many` and `has_and_belongs_to_many` fields)* Hides the "Add" button when the specified limit is reached.
:::tip
Setting `nested: true` is a shortcut for `nested: { on: :forms }`.
:::
#### Example
```ruby-vue{4,5,7,8,10,11,13-14,16-19}
# app/avo/resources/book.rb
class Avo::Resources::Book < Avo::BaseResource
def fields
# Shortcut for full nesting
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: true
# Explicit nesting on new only
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: { on: :new }
# Explicit nesting on edit only
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: { on: :edit }
# Explicit nesting on both new and edit
field :{{ $frontmatter.field_type === 'has_one' ? 'author' : 'authors' }}, as: :{{ $frontmatter.field_type }}, nested: { on: :forms }
# Limit nested creation (for has_many or has_and_belongs_to_many only)
field :authors,
as: :{{ $frontmatter.field_type }},
nested: { on: [:new, :edit], limit: 2 }
end
end
```
### Searchable `has_and_belongs_to_many`
Similar to `belongs_to`, the `has_many` associations support the `searchable` option.
## Add scopes to associations
---
# Actions Overview
The `arguments` option allows you to pass custom data to your action. These arguments are accessible throughout the entire action class including the `handle` and `fields` methods.
```ruby{5-7,11-15}
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
def actions
action Avo::Actions::ToggleInactive,
arguments: {
special_message: true
}
# Or as a proc to make it dynamic
action Avo::Actions::ToggleInactive,
arguments: -> do
{
special_message: resource.view.index? && current_user.is_admin?
}
end
end
end
```
Now, the arguments can be accessed all over the action class like inside `handle` and `fields` methods.
```ruby{4-8}
# app/avo/actions/toggle_inactive.rb
class Avo::Actions::ToggleInactive < Avo::BaseAction
def handle(**args)
if arguments[:special_message]
succeed "I love π₯"
else
succeed "Success response βοΈ"
end
end
end
```
---
## `divider`
You can also add a label to the divider for better organization:
```ruby{5}
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
def actions
action Avo::Actions::ActivateUser
divider label: "Communication"
action Avo::Actions::SendWelcomeEmail
end
end
```
---
# Execution flow
When a user triggers an action in Avo, the following flow occurs:
1. Record selection phase:
- This phase can be bypassed by setting `self.standalone = true`
- For bulk actions on the index page, Avo collects all the records selected by the user
- For actions on the show page or row controls, Avo uses that record as the target of the action
2. The action is initiated by the user through the index page (bulk actions), show page (single record actions), or resource controls (custom action buttons)
3. Form display phase (optional):
- This phase can be bypassed by setting `self.confirmation = false`
- By default, a modal is displayed where the user can confirm or cancel the action
- If the action has defined fields, they will be shown in the modal for the user to fill out
- The user can then choose to run the action or cancel it
- If the user cancels, the execution stops here
4. Action execution:
- The `handle` method processes selected records, form values, current user, and resource details
- Your custom business logic is executed within the `handle` method
- User feedback is configured ([`succeed`](#succeed), [`warn`](#warn), [`inform`](#inform), [`error`](#error), or [`silent`](#silent))
- Response type is configured ([`redirect_to`](#redirect_to), [`reload`](#reload), [`keep_modal_open`](#keep_modal_open), and [more](#response-types))
## Fields
An action can define fields, which will be shown to the user in the action's modal. Fields on an action work the same way as on resources. Whenever an action runs on a single record, those fields are tied to that record. Otherwise, they're just form inputs that are passed to the action's `handle` method.
Check out the Fields page for more information.
## The `handle` method
The `handle` method is where you define what happens when your action is executed. This is the core of your action's business logic and receives the following arguments:
- `query` Contains the selected record(s). Single records are automatically wrapped in an array for consistency
- `fields` Contains the values submitted through the action's form fields
- `current_user` The currently authenticated user
- `resource` The Avo resource instance that triggered the action
```ruby{10-23}
# app/avo/actions/toggle_inactive.rb
class Avo::Actions::ToggleInactive < Avo::BaseAction
self.name = "Toggle Inactive"
def fields
field :notify_user, as: :boolean
field :message, as: :textarea
end
def handle(query:, fields:, current_user:, resource:, **args)
query.each do |record|
# Toggle the inactive status
record.update!(inactive: !record.inactive)
# Send notification if requested
if fields[:notify_user]
# Assuming there's a notify method
record.notify(fields[:message])
end
end
succeed "Successfully toggled status for #{query.count}"
end
end
```
## Feedback notifications
After an action runs, you can respond to the user with different types of notifications or no feedback at all. The default feedback is an `Action ran successfully` message of type `inform`.
All feedback notification methods (`succeed`, `warn`, `inform`, `error`) support an optional `timeout` parameter to control how long the notification remains visible:
```ruby
# Display notification for 5 seconds
succeed 'Task completed successfully', timeout: 5000
# Keep notification open indefinitely, until the user dismisses it
warn 'Important warning - requires attention', timeout: :forever
# Use default timeout (falls back to global configuration)
inform 'Action completed'
```
:::info
Set the `timeout` to `:forever` to keep the notification open indefinitely until the user dismisses it.
The default timeout is set to `config.alert_dismiss_time` in the Avo configuration.
:::
Displays a **green** success alert to indicate successful completion.
Displays an **orange** warning alert for cautionary messages.
Displays a **blue** info alert for general information.
Displays a **red** error alert to indicate failure or errors.
You may want to run an action and show no notification when it's done. That is useful for redirect scenarios. You can use the `silent` response for that.
```ruby{5}
# app/avo/actions/toggle_inactive.rb
class Avo::Actions::ToggleInactive < Avo::BaseAction
def handle(**args)
redirect_to "/admin/some-tool"
silent
end
end
```
:::info
You can show multiple notifications at once by calling multiple feedback methods (`succeed`, `warn`, `inform`, `error`) in your action's `handle` method. Each notification will be displayed in sequence.
:::
```ruby{4-7}
# app/avo/actions/toggle_inactive.rb
class Avo::Actions::ToggleInactive < Avo::BaseAction
def handle(**args)
succeed "Success response βοΈ"
warn "Warning response βοΈ"
inform "Info response βοΈ"
error "Error response βοΈ"
end
end
```
The `reload` response triggers a full-page reload. This is the default behavior if no other response type is specified.
```ruby{9}
def handle(query:, **args)
query.each do |project|
project.update active: false
end
succeed 'Done!'
reload # This is optional since reload is the default behavior
end
```
`redirect_to` will execute a redirect to a new path of your app. It accept `allow_other_host`, `status` and any other arguments.
Example:
`redirect_to path, allow_other_host: true, status: 303`
```ruby{9}
def handle(query:, **args)
query.each do |project|
project.update active: false
end
succeed 'Done!'
redirect_to avo.resources_users_path
end
```
`download` will start a file download to your specified `path` and `filename`.
:::warning
**Ignore this warning if you are using Avo 3.2.2 or later.**
You need to set `self.may_download_file` to true for the download response to work like below.
:::
:::code-group
```ruby{3-4,17} [app/avo/actions/download_file.rb]
class Avo::Actions::DownloadFile < Avo::BaseAction
self.name = "Download file"
# Only required for versions before 3.2.2
self.may_download_file = true
def handle(query:, **args)
filename = "projects.csv"
report_data = []
query.each do |project|
report_data << project.generate_report_data
end
succeed 'Done!'
if report_data.present? and filename.present?
download report_data, filename
end
end
end
```
```ruby{8} [app/avo/resources/project.rb]
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
def fields
# fields here
end
def actions
action Avo::Actions::DownloadFile
end
end
```
:::
There might be situations where you want to run an action and if it fails, respond back to the user with some feedback but still keep it open with the inputs filled in.
`keep_modal_open` will tell Avo to keep the modal open.
```ruby
class Avo::Actions::KeepModalOpenAction < Avo::BaseAction
self.name = "Keep Modal Open"
self.standalone = true
def fields
field :name, as: :text
field :birthday, as: :date
end
def handle(fields:, **args)
User.create fields
succeed "All good βοΈ"
rescue => error
error "Something happened: #{error.message}"
keep_modal_open
end
end
```
`do_nothing` is an alias for `close_modal`.
```ruby{7}
class Avo::Actions::CloseModal < Avo::BaseAction
self.name = "Close modal"
def handle(**args)
# do_something_here
succeed "Modal closed!!"
do_nothing
end
end
```
:::warning
This option **only** works on **Index** pages, **NOT** on **associations**.
:::
This option leverages Turbo Stream to refresh specific table rows and grid view cards in response to an action. For individual records, you can use the `reload_record` alias method.
```ruby{8}
def handle(query:, fields:, **args)
query.each do |record|
record.update! active: !record.active
record.notify fields[:message] if fields[:notify_user]
end
reload_records(query)
end
```
The `reload_records` and `reload_record` methods are aliases, and they accept either an array of records or a single record.
:::code-group
```ruby[Array]{1}
reload_records([record_1, record_2])
```
```ruby[Single]{1}
reload_record(record)
```
:::
---
# Customization
Actions can be customized in several ways to enhance the user experience. You can modify the action's display name, confirmation message, button labels, and confirmation behavior between other things.
There are 2 types of customization, visual and behavioral.
## Visual customization
Visual customization is the process of modifying the action's appearance. This includes changing the action's name, message and button labels.
All visual customization options can be set as a string or a block.
The blocks are executed using `Avo::ExecutionContext`. Within these blocks, you gain access to:
- All attributes of `Avo::ExecutionContext`
- `resource` - The current resource instance
- `record` - The current record
- `view` - The current view
- `arguments` - Any passed arguments
- `query` - The current query parameters
The `name` option is used to change the action's display name.
```ruby{3,5-8}
# app/avo/actions/release_fish.rb
class Avo::Actions::ReleaseFish < Avo::BaseAction
self.name = "Release fish"
# Or as a block
self.name = -> {
record.present? ? "Release #{record.name}?" : "Release fish"
}
end
```
The `description` option adds a short description displayed below the action's name in the modal header. This helps users understand what the action does before confirming.
```ruby{3,5-8}
# app/avo/actions/release_fish.rb
class Avo::Actions::ReleaseFish < Avo::BaseAction
self.description = "Release the fish back into the ocean"
# Or as a block
self.description = -> {
record.present? ? "Release #{record.name} back into the ocean" : "Release fish back into the ocean"
}
end
```
The `message` option is used to change the action's confirmation message.
```ruby{3,5-12}
# app/avo/actions/release_fish.rb
class Avo::Actions::ReleaseFish < Avo::BaseAction
self.message = "Are you sure you want to release the fish?"
# Or as a block
self.message = -> {
if resource.record.present?
"Are you sure you want to release the #{resource.record.name}?"
else
"Are you sure you want to release the fish?"
end
}
end
```
The `confirm_button_label` option is used to change the action's confirmation button label.
```ruby{3,5-12}
# app/avo/actions/release_fish.rb
class Avo::Actions::ReleaseFish < Avo::BaseAction
self.confirm_button_label = "Release fish"
# Or as a block
self.confirm_button_label = -> {
if resource.record.present?
"Release #{resource.record.name}"
else
"Release fish"
end
}
end
```
The `cancel_button_label` option is used to change the action's cancel button label.
```ruby{3,5-12}
# app/avo/actions/release_fish.rb
class Avo::Actions::ReleaseFish < Avo::BaseAction
self.cancel_button_label = "Cancel release"
# Or as a block
self.cancel_button_label = -> {
if resource.record.present?
"Cancel release on #{resource.record.name}"
else
"Cancel release"
end
}
end
```
## Behavioral customization
Behavioral customization is the process of modifying the action's behavior. This includes changing the action's confirmation behavior and authorization.
By default, actions display a confirmation modal before execution. You can bypass this modal by setting `self.confirmation = false`, which will execute the action immediately upon triggering.
```ruby{3}
# app/avo/actions/release_fish.rb
class Avo::Actions::ReleaseFish < Avo::BaseAction
self.confirmation = false
end
```
This is particularly useful for actions that:
- Are safe to execute without confirmation
- Need to provide immediate feedback
- Are part of a multi-step workflow where confirmation is handled elsewhere
Standalone actions allow you to execute operations that aren't tied to specific model records. These are useful for global operations like:
- Generating system-wide reports
- Running maintenance tasks
- Triggering background jobs
You can create a standalone action in two ways:
1. Using the generator with the `--standalone` flag:
```bash
bin/rails generate avo:action global_action --standalone
```
2. Adding `self.standalone = true` to an existing action:
```ruby{4}
# app/avo/actions/global_report.rb
class Avo::Actions::GlobalReport < Avo::BaseAction
self.name = "Generate Global Report"
self.standalone = true
end
```
Standalone actions will be active in the Actions dropdown even when no records are selected. They can be used alongside regular record-based actions in the same resource.
:::tip
Standalone actions work well with the [`fields`](#fields) feature to collect additional input needed for the operation.
:::
You may want to hide specific actions on some views, like a standalone action on the `Show` and `Edit` views, and show it only on the `Index` view. You can do that using the `self.visible` attribute.
```ruby{5,8}
# app/avo/actions/global_report.rb
class Avo::Actions::GlobalReport < Avo::BaseAction
self.name = "Generate Global Report"
self.standalone = true
self.visible = true
# Or as a block
self.visible = -> { view.index? }
end
```
The `visible` attribute accepts a boolean or a block.
The block will be executed within the `Avo::ExecutionContext` environment, giving you access to important contextual attributes like:
- `view` - The current view type (index, show, edit)
- `resource` - The current resource instance
- `parent_resource` - The parent resource (if applicable).
- You can access the `parent_record` by `parent_resource.record`
- Plus all other `Avo::ExecutionContext` default attributes
The `authorize` attribute is used to restrict access to actions based on custom logic.
If an action is unauthorized, it will be hidden. If a bad actor attempts to proceed with the action, the controller will re-evaluate the authorization and block unauthorized requests.
```ruby{2,4-7}
class Avo::Actions::GlobalReport < Avo::BaseAction
self.authorize = false
# Or as a block
self.authorize = -> {
current_user.is_admin?
}
end
```
The `authorize` attribute accepts a boolean or a proc.
The block will be executed within the `Avo::ExecutionContext` environment, giving you access to important contextual attributes like:
- `action` - The current action instance
- `resource` - The current resource instance
- `view` - The current view type (index, show, edit)
- All other `Avo::ExecutionContext` attributes
The `turbo` attribute is used to control the Turbo behavior of actions.
There are times when you don't want to perform the actions with Turbo. In such cases, turbo should be set to false.
```ruby{3}
# app/avo/actions/toggle_inactive.rb
class Avo::Actions::ToggleInactive < Avo::BaseAction
self.turbo = false
end
```
The `turbo` attribute accepts a boolean.
---
# WIP
this section is under construction
## Helpers
### `link_arguments`
The `link_arguments` method is used to generate the arguments for an action link.
You may want to dynamically generate an action link. For that you need the action class and a resource instance (with or without record hydrated). Call the action's class method `link_arguments` with the resource instance as argument and it will return the `[path, data]` that are necessary to create a proper link to a resource.
Let's see an example use case:
```ruby{4-,16} [Current Version]
# app/avo/resources/city.rb
class Avo::Resources::City < Avo::BaseResource
field :name, as: :text, name: "Name (click to edit)", only_on: :index do
path, data = Avo::Actions::City::Update.link_arguments(
resource: resource,
arguments: {
cities: Array[resource.record.id],
render_name: true
}
)
link_to resource.record.name, path, data: data
end
end
```
`self.name` is what is going to be displayed to the user in the filters panel.
```ruby
self.name = "User names filter"
```
The value of `self.button_label` is the label displayed on the button that applies the filter.
```ruby
self.button_label = "Filter by user names"
```
You may want to show/hide the filter in some scenarios. You can do that using the `self.visible` attribute.
Inside the visible block you can acces the following variables and you should return a boolean (`true`/`false`).
```ruby
self.visible = -> do
# You have access to:
# block
# context
# current_user
# params
# parent_model
# parent_resource
# resource
# view
# view_context
true
end
```
There might be times when you will want to show a message to the user when you're not returning any options.
More on this in the [Empty message guide](#empty-message-text).
Some filters allow you to pass options to the user. For example on the [select filter](#select_filter) you can set the options in the dropdown, and on the [boolean filter](#boolean_filter) you may set the checkbox values.
Each filter type has their own `options` configuration explained below.
In the `options` method you have access to the `request`, `params`, `context`, `view_context`, and `current_user` objects.
The `apply` method is what is going to be run when Avo fetches the records on the
You may set default values for the `options` you set. For example you may set which option to be selected for the [select filter](#select_filter) and which checkboxes to be set for the [boolean filter](#boolean_filter).
In the `default` method you have access to the `request`, `params`, `context`, `view_context`, and `current_user` objects.
This is a hook in which you can change the value of the filter based on what other filters have for values.
More on this in the [React to filters guide](#react-to-filters)
## Register filters
In order to use a filter you must register it on a `Resource` using the `filter` method inside the `filters` method.
```ruby{9}
class Avo::Resources::Post < Avo::BaseResource
self.title = :name
def fields
field :id, as: :id
end
def filters
filter Avo::Filters::Published
end
end
```
## Filter types
Avo has several types of filters available [Boolean filter](#Boolean%20Filter), [Select filter](#Select%20Filter), [Multiple select filter](#Multiple%20select%20filter), [Text filter](#Text%20Filter) and since version
The boolean filter is a filter where the user can filter the records using one or more checkboxes.
To generate one run:
```bash
bin/rails generate avo:filter featured
```
or
```bash
bin/rails generate avo:filter featured --type boolean
```
Here's a sample filter
```ruby
class Avo::Filters::Featured < Avo::Filters::BooleanFilter
self.name = 'Featured filter'
# `values` comes as a hash with stringified keys
# Eg:
# {
# 'is_featured': true
# }
def apply(request, query, values)
return query if values['is_featured'] && values['is_unfeatured']
if values['is_featured']
query = query.where(is_featured: true)
elsif values['is_unfeatured']
query = query.where(is_featured: false)
end
query
end
def options
{
is_featured: "Featured",
is_unfeatured: "Unfeatured"
}
end
# Optional method to set the default state.
# def default
# {
# is_featured: true
# }
# end
end
```
Each filter file comes with a `name`, `apply`, and `options` methods.
The `name` method lets you set the name of the filter.
The `apply` method is responsible for filtering out the records by giving you access to modify the `query` object. The `apply` method also gives you access to the current `request` object and the passed `values`. The `values` object is a `Hash` containing all the configured `options` with the option name as the key and `true`/`false` as the value.
```ruby
# Example values payload
{
'is_featured': true,
'is_unfeatured': false,
}
```
The `options` method defines the available values of your filter. They should return a `Hash` with the option id as a key and option label as value.
### Default value
You can set a default value to the filter, so it has a predetermined state on load. To do that, return the state you desire from the `default` method.
```ruby{23-27}
class Avo::Filters::Featured < Avo::Filters::BooleanFilter
self.name = 'Featured status'
def apply(request, query, values)
return query if values['is_featured'] && values['is_unfeatured']
if values['is_featured']
query = query.where(is_featured: true)
elsif values['is_unfeatured']
query = query.where(is_featured: false)
end
query
end
def options
{
is_featured: "Featured",
is_unfeatured: "Unfeatured"
}
end
def default
{
is_featured: true
}
end
end
```
Select filters are similar to Boolean ones but they give the user a dropdown with which to filter the values.
```bash
rails generate avo:filter published --type select
```
The most significant difference from the **Boolean filter** is in the `apply` method. You only get back one `value` attribute, which represents which entry from the `options` method is selected.
A finished, select filter might look like this.
```ruby
class Avo::Filters::Published < Avo::Filters::SelectFilter
self.name = 'Published status'
# `value` comes as a string
# Eg: 'published'
def apply(request, query, value)
case value
when 'published'
query.where.not(published_at: nil)
when 'unpublished'
query.where(published_at: nil)
else
query
end
end
def options
{
published: "Published",
unpublished: "Unpublished"
}
end
# Optional method to set the default state.
# def default
# :published
# end
end
```
### Default value
The select filter supports setting a default too. That should be a string or symbol with the select item. It will be stringified by Avo automatically.
```ruby{22-24}
class Avo::Filters::Published < Avo::Filters::SelectFilter
self.name = 'Published status'
def apply(request, query, value)
case value
when 'published'
query.where.not(published_at: nil)
when 'unpublished'
query.where(published_at: nil)
else
query
end
end
def options
{
'published': 'Published',
'unpublished': 'Unpublished',
}
end
def default
:published
end
end
```
You may also use a multiple select filter.
```bash
rails generate avo:filter post_status --type multiple_select
```
```ruby
class Avo::Filters::PostStatus < Avo::Filters::MultipleSelectFilter
self.name = "Status"
# `value` comes as an array of strings
# Ex: ['admins', 'non_admins']
def apply(request, query, value)
if value.include? 'admins'
query = query.admins
end
if value.include? 'non_admins'
query = query.non_admins
end
query
end
def options
{
admins: "Admins",
non_admins: "Non admins",
}
end
# Optional method to set the default state.
# def default
# ['admins', 'non_admins']
# end
end
```
You can add complex text filters to Avo using the Text filter
```bash
rails generate avo:filter name --type text
```
```ruby
class Avo::Filters::Name < Avo::Filters::TextFilter
self.name = "Name filter"
self.button_label = "Filter by name"
# `value` comes as text
# Eg: 'avo'
def apply(request, query, value)
query.where('LOWER(name) LIKE ?', "%#{value}%")
end
# def default
# 'avo'
# end
end
```
## Dynamic filter options
Decodes the `filters` param. This Rails helper can be used anywhere in a view or off the `view_context`.
#### Usage
```ruby
# in a view
decode_filter_params params[:filters] # {"NameFilter"=>"Apple"}
# Or somewhere in an Avo configuration file
class Avo::Actions::DummyAction < Avo::BaseAction
self.name = "Dummy action"
def handle(**args)
filters = view_context.decode_filter_params(params[:filters])
do_something_important_with_the_filters filters
end
end
```
Encodes a `filters` object into a serialized state that Avo understands. This Rails helper can be used anywhere in a view or off the `view_context`.
#### Usage
```ruby
# in a view
filters = {"NameFilter"=>"Apple"}
encode_filter_params filters # eyJOYW1lRmlsdGVyIjoiQXBwbGUifQ==
# Or somewhere in an Avo configuration file
class Avo::Actions::DummyAction < Avo::BaseAction
self.name = "Dummy action"
def handle(**args)
do_something_important
redirect_to avo.resources_users_path(filters: view_context.decode_filter_params({"NameFilter"=>"Apple"}))
end
end
```
### Standalone helpers
Decodes the `filters` param. This standalone method can be used anywhere.
#### Usage
```ruby
class Avo::Actions::DummyAction < Avo::BaseAction
self.name = "Dummy action"
def handle(**args)
filters = Avo::Filters::BaseFilter.decode_filters(params[:filters])
do_something_important_with_the_filters filters
end
end
```
Encodes a `filters` object into a serialized state that Avo understands. This standalone method can be used anywhere.
#### Usage
```ruby
class Avo::Actions::DummyAction < Avo::BaseAction
self.name = "Dummy action"
def handle(**args)
do_something_important
redirect_to avo.resources_users_path(encoded_filters: Avo::Filters::BaseFilter.encode_filters({"Avo::Filters::NameFilter"=>"Apple"}))
end
end
```
---
# Dynamic filters
The Dynamic filters make it so easy to add multiple, composable, and dynamic filters to the
### Conditions
- Is true
- Is false
- Is null
- Is not null
```ruby
{
is_true: "Is true",
is_false: "Is false",
is_null: "Is null",
is_not_null: "Is not null",
}.invert
```
Test it on [avodemo](https://main.avodemo.com/avo/resources/users?filters[is_admin?][is_true][]=), check the [source code](https://github.com/avo-hq/main.avodemo.com/blob/main/app/avo/resources/user.rb#L38)
### Conditions
- Is
- Is not
- Is on or before
- Is on or after
- Is within
- Is null
- Is not null
```ruby
{
is: "Is",
is_not: "Is not",
lte: "Is on or before",
gte: "Is on or after",
is_within: "Is within",
is_null: "Is null",
is_not_null: "Is not null",
}.invert
```
Test it on [avodemo](https://main.avodemo.com/avo/resources/teams?filters[created_at][lte][]=2024-07-02%2012%3A00), check the [source code](https://github.com/avo-hq/main.avodemo.com/blob/main/app/avo/resources/team.rb#L50)
Same as **Date** (same conditions and visuals), but the picker also enables time selection.
```ruby
dynamic_filter :created_at, type: :date_time
```
Same as **Date** (same conditions and visuals), but the picker is time-only (no calendar).
```ruby
dynamic_filter :published_at, type: :time
```
### Conditions
- `=` (equals)
- `!=` (is different)
- `>` (greater than)
- `>=` (greater than or equal to)
- `<` (lower than)
- `<=` (lower than or equal to)
- Is within
Test it on [avodemo](https://main.avodemo.com/avo/resources/teams?filters[id][gte][]=2), check the [source code](https://github.com/avo-hq/main.avodemo.com/blob/main/app/avo/resources/team.rb#L27)
### Conditions
- Is
- Is not
- Is null
- Is not null
```ruby
{
is: "Is",
is_not: "Is not",
is_null: "Is null",
is_not_null: "Is not null",
}.invert
```
Test it on [avodemo](https://main.avodemo.com/avo/resources/courses?filters[country][is][]=USA), check the [source code](https://github.com/avo-hq/main.avodemo.com/blob/main/app/avo/resources/course.rb#L55)
### Conditions
- Contains
- Does not contain
- Is
- Is not
- Starts with
- Ends with
- Is null
- Is not null
- Is present
- Is blank
```ruby
{
contains: "Contains",
does_not_contain: "Does not contain",
is: "Is",
is_not: "Is not",
starts_with: "Starts with",
ends_with: "Ends with",
is_null: "Is null",
is_not_null: "Is not null",
is_present: "Is present",
is_blank: "Is blank",
}.invert
```
Test it on [avodemo](https://main.avodemo.com/avo/resources/users?filters[first_name][contains][]=Avo), check the [source code](https://github.com/avo-hq/main.avodemo.com/blob/main/app/avo/resources/user.rb#L33)
### Conditions
- Are
- Contain
- Overlap
- Contained in ([`active_record_extended`](https://github.com/GeorgeKaraszi/ActiveRecordExtended) gem required)
```ruby
{
array_is: "Are",
array_contains: "Contain",
array_overlap: "Overlap",
array_contained_in: "Contained in" # (active_record_extended gem required)
}.invert
```
:::warning
Contained in will not work when using the `acts-as-taggable-on` gem.
:::
Test it on [avodemo](https://main.avodemo.com/avo/resources/courses?filters[skills][array_contains][]=), check the [source code](https://github.com/avo-hq/main.avodemo.com/blob/main/app/avo/resources/course.rb#L46)
:::info
The source code uses custom dynamic filters DSL available
## Options
You can have a few customization options available that you can add in your `avo.rb` initializer file.
```ruby
Avo.configure do |config|
# Other Avo configurations
end
if defined?(Avo::DynamicFilters)
Avo::DynamicFilters.configure do |config|
config.button_label = "Advanced filters"
config.always_expanded = true
end
end
```
This will change the label on the expand label.
You may opt-in to have them always expanded and have the button hidden.
## Field to filter matching
On versions **lower** than
Customize filter's label
##### Default value
Field's / filter's ID humanized.
#### Possible values
Any string
Customize filter's icon. Check icons documentation
##### Default value
Boolean filter - `heroicons/outline/check-circle`
Customize filter's type
##### Default value
Computed from field using [`field_to_filter` method](#field-to-filter-matching).
#### Possible values
- [`:boolean`](#boolean)
:::info
Customize filter's conditions
##### Default value
Check default conditions for each filter type above on this page.
#### Possible values
- A hash with the desired key-values to customize available conditions
- An empty hash `{}` to hide conditions dropdown and use the first default condition
##### Usage examples
###### Custom conditions
```ruby {6-9,15-18}
# Using field's filterable option
field :first_name,
as: :text,
filterable: {
# ...
conditions: {
case_sensitive: "Case sensitive",
not_case_sensitive: "Not case sensitive"
}.invert
# ...
}
# Using dynamic_filter method
dynamic_filter :first_name,
conditions: {
case_sensitive: "Case sensitive",
not_case_sensitive: "Not case sensitive"
}.invert
```
###### Hide conditions dropdown
When set to an empty hash (`{}`), this option hides the conditions dropdown and automatically applies the first default condition for each filter type. This is particularly useful when you want to simplify the filter interface by removing the conditions selection, especially for filters where only one condition makes sense.
```ruby{3}
dynamic_filter :last_name,
type: :select,
conditions: {},
options: User.pluck(:last_name).compact
```
```ruby{4}
field :department,
as: :select,
filterable: {
conditions: {},
type: :select,
options: ["Engineering", "Marketing", "Sales", "Support"]
}
```
:::info
When `conditions: {}` is used, the filter will automatically use the first condition from the default conditions list for that filter type. For example, a select filter will use "Is" condition, and a text filter will use "Contains" condition.
:::
Customize filter's query attributes
##### Default value
Field's / filter's id
#### Possible values
Any model DB column(s). Use an array of symbols for multiple columns or a single symbol for a single column. If your model has DB columns like `first_name` and `last_name`, you can combine both on a single filter:
```ruby {6,13}
# Using field's filterable option
field :name,
as: :text,
filterable: {
# ...
query_attributes: [:first_name, :last_name]
# ...
}
# Using dynamic_filter method
dynamic_filter :name,
type: :text,
query_attributes: [:first_name, :last_name]
```
You can also add query attributes for a `belongs_to` association. For example, with a model that belongs to `User`:
```ruby {7,13}
# Using field's filterable option
field :user,
as: :belongs_to,
filterable: {
label: "User (email & first_name)",
icon: "heroicons/solid/users",
query_attributes: [:user_email, :user_first_name]
}
# Using dynamic_filter method
dynamic_filter label: "User (email & first_name)",
icon: "heroicons/solid/users",
query_attributes: [:user_email, :user_first_name]
```
This is possible due to a Ransack feature. To use it, you need to add the association name before the attribute.
Suggestions work on filters that provide text input, enhancing the user experience by offering relevant options. This functionality is especially useful in scenarios where users might need guidance or where the filter values are numerous or complex.
##### Default value
`nil`
:::info
Controls whether the "Apply" button should be rendered in the filter interface.
##### Default value
`true`
#### Possible values
Boolean value (`true` or `false`).
When set to `false`, the apply button will be hidden from the filter interface. This is particularly useful when combined with `apply_on_select: true` to create an immediate filtering experience.
##### Usage examples
```ruby{3}
dynamic_filter :status,
type: :select,
render_apply_button: false
```
```ruby{4-5}
field :status,
as: :select,
filterable: {
render_apply_button: false,
apply_on_select: true,
options: ["active", "inactive", "pending"]
}
```
Controls whether the filter should be applied immediately when the selected value changes, without requiring the user to click the "Apply" button.
##### Default value
`false`
#### Possible values
Boolean value (`true` or `false`).
When set to `true`, the filter will automatically apply as soon as the user selects or changes a value. This creates a more responsive user experience, especially when combined with `render_apply_button: false`.
##### Usage examples
```ruby{3-4}
dynamic_filter :category,
type: :select,
apply_on_select: true,
render_apply_button: false
```
```ruby{4-5}
field :priority,
as: :select,
filterable: {
apply_on_select: true,
render_apply_button: false,
options: ["high", "medium", "low"]
}
```
Allows you to customize how filter values are displayed in the filter interface by providing humanized, user-friendly representations of the internal filter values.
##### Default value
`value` - The filter will display the raw filter values.
#### Possible values
A lambda/proc that returns a string representing the humanized value. Within the function, you have access to the `value` and `filter` object which contains the current filter's condition, as well as all attributes of `Avo::ExecutionContext`. Additionally `parent_record` (when the filter is applied to an association) is available.
##### Usage examples
```ruby{4-11}
field :is_capital,
as: :boolean,
filterable: {
humanized_value: -> {
case filter.condition
when "is_true"
"yes"
when "is_false"
"no"
end
}
}
```
```ruby{4-8}
dynamic_filter label: "Tags with fetch_values_from",
type: :tags,
fetch_values_from: -> { "/avo-filters/resources/cities/tags" },
humanized_value: -> {
City.controller_suggestions.select do |suggestion|
suggestion[:value].to_s.in?(value.split(","))
end.map { _1[:label] }.join(", ")
}
```
## Guides & Tutorials
Learn how to effectively filter records based on their associations in Avo. This video tutorial demonstrates how to set up and use dynamic filters to query records through the attributes of their associations, enabling powerful and flexible data filtering capabilities.
#### `belongs_to` example
```ruby{5-11,16-18}
# app/avo/resources/post.rb
class Avo::Resources::Post < Avo::BaseResource
# Using field's filterable option
def fields
field :user,
as: :belongs_to,
filterable: {
label: "User (email & first_name)",
icon: "heroicons/solid/users",
query_attributes: [:user_email, :user_first_name]
}
end
# OR using dynamic_filter method
def filters
dynamic_filter label: "User (email & first_name)",
icon: "heroicons/solid/users",
query_attributes: [:user_email, :user_first_name]
end
end
```
### `has_many` example
```ruby{19-22}
class Avo::Resources::Author < Avo::BaseResource
self.record_selector = false
def fields
field :preview, as: :preview
field :book_list, only_on: :preview do
tag.div do
tag.ul do
safe_join(
record.books.map do |book|
tag.li("#{book.title} (#{book.genre})")
end
)
end
end
end
field :name, filterable: true
# Filter the books by title and genre
field :books, as: :has_many, filterable: {
query_attributes: [:books_title, :books_genre]
}
end
end
```
When you have multiple fields that require similar filtering logic, you can create reusable filter helpers to avoid code duplication. This is particularly useful when working with JSON columns, complex queries, or any scenario where multiple fields share the same filtering pattern.
This guide demonstrates four different approaches to create composable filters, each with its own benefits and use cases.
### The Problem: Repetitive Filter Code
Before diving into the solutions, let's look at a common problem where filter logic is repeated across multiple fields:
```ruby
class Avo::Resources::Feedback < Avo::BaseResource
def fields
field :company_size, filterable: {
type: :select,
options: -> { Feedback.pluck(Arel.sql("answers->>'company_size'")).uniq },
query: -> { query.where(Arel.sql("answers->>'company_size' = '#{filter_param.value}'")) }
}
field :company_industry, filterable: {
type: :select,
options: -> { Feedback.pluck(Arel.sql("answers->>'company_industry'")).uniq },
query: -> { query.where(Arel.sql("answers->>'company_industry' = '#{filter_param.value}'")) }
}
field :title, filterable: {
type: :select,
options: -> { Feedback.pluck(Arel.sql("answers->>'title'")).uniq },
query: -> { query.where(Arel.sql("answers->>'title' = '#{filter_param.value}'")) }
}
field :description, filterable: {
type: :select,
options: -> { Feedback.pluck(Arel.sql("answers->>'description'")).uniq },
query: -> { query.where(Arel.sql("answers->>'description' = '#{filter_param.value}'")) }
}
end
end
```
As you can see, the same filtering logic is repeated for each field, which violates the DRY (Don't Repeat Yourself) principle and makes the code harder to maintain.
### Method 1: Helper Method with Field Configuration
This approach extracts the common filtering logic into a helper method that returns the filterable configuration hash. It's the most straightforward refactoring and maintains the existing field-based approach.
```ruby
class Avo::Resources::Feedback < Avo::BaseResource
def filterable_helper(field_name)
{
type: :select,
options: -> { Feedback.pluck(Arel.sql("answers->>'#{field_name}'")).uniq },
query: -> { query.where(Arel.sql("answers->>'#{field_name}' = '#{filter_param.value}'")) }
}
end
def fields
field :company_size, filterable: filterable_helper(:company_size)
field :company_industry, filterable: filterable_helper(:company_industry)
field :title, filterable: filterable_helper(:title)
field :description, filterable: filterable_helper(:description)
end
end
```
**Benefits:**
- Simple refactoring that maintains the existing field structure
- Easy to understand and implement
- Minimal changes to existing code
**Best for:** Quick refactoring of existing resources with repetitive filter logic.
:::warning
When you're using this approach within a `with_options` block, you need allow the extra args that are passed to the helper method.
```ruby
def filterable_helper(field_name, **args)
# ...
end
```
:::
### Method 2: Separate Fields and Filters with Helper
This approach separates the field definitions from the filter definitions using the `dynamic_filter` method. The helper method now directly creates the dynamic filter instead of returning a configuration hash.
```ruby
class Avo::Resources::Feedback < Avo::BaseResource
def fields
field :company_size
field :company_industry
field :title
field :description
end
def filterable_helper(field_name)
dynamic_filter field_name,
type: :select,
options: -> { Feedback.pluck(Arel.sql("answers->>'#{field_name}'")).uniq },
query: -> { query.where(Arel.sql("answers->>'#{field_name}' = '#{filter_param.value}'")) }
end
def filters
filterable_helper(:company_size)
filterable_helper(:company_industry)
filterable_helper(:title)
filterable_helper(:description)
end
end
```
**Benefits:**
- Clear separation between field definitions and filter logic
- Uses the more flexible `dynamic_filter` method
- Filters can be defined independently of fields
**Best for:**
- Resources where you want to maintain clean separation between display fields and filtering logic.
- Dynamic filters that are common across multiple resources.
### Method 3: Programmatic Filter Generation
This approach uses Ruby's array iteration to programmatically generate multiple filters with the same logic. It's the most concise and reduces the code to its essential elements.
```ruby
class Avo::Resources::Feedback < Avo::BaseResource
def fields
field :company_size
field :company_industry
field :title
field :description
end
def filters
[:company_size, :company_industry, :title, :description].map do |field_name|
dynamic_filter field_name,
type: :select,
options: -> { Feedback.pluck(Arel.sql("answers->>'#{field_name}'")).uniq },
query: -> { query.where(Arel.sql("answers->>'#{field_name}' = '#{filter_param.value}'")) }
end
end
end
```
**Benefits:**
- Most concise code
- Easy to add or remove filterable fields by modifying the array
- Clearly shows which fields share the same filtering logic
**Best for:** Resources with many fields that share identical filtering logic, especially when the list of filterable fields might change frequently.
### Method 4: Custom DSL with Method Override
This approach creates a custom DSL by overriding the `field` method to intercept a special symbol (`:by_answer`). This provides the cleanest syntax at the field level while hiding the complexity in the method override.
```ruby
class Avo::Resources::Feedback < Avo::BaseResource
def fields
field :company_size, filterable: :by_answer
field :company_industry, filterable: :by_answer
field :title, filterable: :by_answer
field :description, filterable: :by_answer
end
def field(field_name, **args, &block)
if args[:filterable] == :by_answer
args[:filterable] = {
type: :select,
options: -> { Feedback.pluck(Arel.sql("answers->>'#{field_name}'")).uniq },
query: -> { query.where(Arel.sql("answers->>'#{field_name}' = '#{filter_param.value}'")) }
}
end
super(field_name, **args, &block)
end
end
```
**Benefits:**
- Creates a clean, semantic DSL
- Hides complexity while maintaining readable field definitions
- Easy to extend with additional filter types
- Most maintainable for resources with many similar filterable fields
**Best for:** Resources where you want to create a custom, reusable filtering pattern that feels natural and integrated with Avo's field DSL.
### Choosing the Right Approach
- **Method 1** for quick refactoring of existing code
- **Method 2** when you want clear separation between fields and filters
- **Method 3** when you have many fields with identical filtering logic
- **Method 4** when you want to create a clean, reusable DSL for your team
All approaches achieve the same goal of eliminating code duplication while providing different levels of abstraction and maintainability.
---
# Customization options
## Change the app name
On the main navbar next to the logo, Avo generates a link to the homepage of your app. The label for the link is usually computed from your Rails app name. You can customize that however, you want using `config.app_name = 'Avocadelicious'`.
The `app_name` option is also callable using a block. This is useful if you want to reference a `I18n.t` method or something more dynamic.
```ruby
Avo.configure do |config|
config.app_name = -> { I18n.t "app_name" }
end
```
## Timezone and Currency
Your data-rich app might have a few fields where you reference `date`, `datetime`, and `currency` fields. You may customize the global timezone and currency with `config.timezone = 'UTC'` and `config.currency = 'USD'` config options.
## Resource Index view
There are a few customization options to change how resources are displayed in the **Index** view.
### Resources per page
You may customize how many resources you can view per page with `config.per_page = 24`.
In the CRUD interface Avo adds the
`default_url_options` is a Rails [controller method](https://apidock.com/rails/ActionController/Base/default_url_options) that will append params automatically to the paths you generate through path helpers.
In order to implement some features like route-level Multitenancy we exposed an API to add to Avo's `default_url_options` method.
::: code-group
```ruby [config/initializers/avo.rb]{2}
Avo.configure do |config|
config.default_url_options = [:account_id]
end
```
```ruby [app/config/routes.rb]{3}
Rails.application.routes.draw do
# Use to test out route-based multitenancy
scope "/account/:account_id" do
mount_avo
end
end
```
:::
Now, when you visit `https://example.org/account/adrian/avo`, the `account_id` param is `adrian` and it will be appended to all path helpers.
You may want to configure how turbo behave on Avo.
You can configure it using `config.turbo` option on `avo.rb` initializer
Supported options with default values:
```ruby
config.turbo = -> do
{
instant_click: true
}
end
```
You can configure the default pagination settings key by key.
```ruby
config.pagination = {
type: :countless
}
# Or
config.pagination = -> do
{
type: :countless,
}
end
```
This will make all your application's tables countless keeping the size key / value as the default one.
Verify all possible options here.
This setting allows your users to click on a record to navigate to its
## Associations lookup list limit
### Persistent UI State Configuration
Specifies the duration (in milliseconds) for which alerts remain visible before automatically dismissing.
A lower value results in quicker dismissal, while a higher value keeps the alert on screen for longer.
### Default value
`5000`
### Example
```ruby
# config/initializers/avo.rb
Avo.configure do |config|
config.alert_dismiss_time = 8000
end
```
Defines the default sorting option for the fields on the index view.
### Default value
`:desc`
### Possible values
- `:asc`
- `:desc`
### Example
```ruby{3}
# config/initializers/avo.rb
Avo.configure do |config|
config.first_sorting_option = :asc
end
```
Defines which status items to exclude from the status page (`/avo_private/status`). This is useful for hiding sensitive information like license keys from the status page.
### Default value
`[]`
### Possible values
An array of strings or a callable that returns an array of strings representing the status items to exclude.
### Example
```ruby
# config/initializers/avo.rb
Avo.configure do |config|
config.exclude_from_status = ["license_key"]
# OR using a callable
config.exclude_from_status = -> do
["license_key"]
end
end
```
### Common use case
The most common use case is to exclude the `license_key` from being displayed on the status page for security reasons.
Controls whether Avo sends usage metadata to Avo HQ, such as fields count, resources count, and other relevant metrics. This helps the Avo team understand how the framework is being used.
:::info
This option only takes effect on the community tier. Any other paid tier always sends metadata.
:::
### Default value
`true`
### Example
```ruby
# config/initializers/avo.rb
Avo.configure do |config|
config.send_metadata = false
end
```
---
# Eject
If you want to change one of Avo's built-in views, you can eject it, update it and use it in your admin panel.
:::warning
Once ejected, the views will not receive updates on new Avo releases. You must maintain them yourself.
:::
Utilize the `--partial` option when you intend to extract certain partial
## Prepared templates
We prepared a few templates to make it easier for you.
`bin/rails generate avo:eject --partial :head` will eject the `_head.html.erb` partial.
```
βΆ bin/rails generate avo:eject --partial :head
Running via Spring preloader in process 20947
create app/views/avo/partials/_head.html.erb
```
A list of prepared templates:
- `:head` β‘οΈ `app/views/avo/partials/_head.html.erb`
- `:header` β‘οΈ `app/views/avo/partials/_header.html.erb`
- `:scripts` β‘οΈ `app/views/avo/partials/_scripts.html.erb`
- `:sidebar_extra` β‘οΈ `app/views/avo/partials/_sidebar_extra.html.erb`
### Logo
In the `app/views/avo/partials` directory, you will find the `_logo.html.erb` partial, which you may customize however you want. It will be displayed in place of Avo's logo.
### Header
The `_header.html.erb` partial enables you to customize the name and link of your app.
### Scripts
The `_scripts.html.erb` partial enables you to insert scripts in the footer of your admin.
## Eject any template
You can eject any partial from Avo using the partial path.
```
βΆ bin/rails generate avo:eject --partial app/views/layouts/avo/application.html.erb
create app/views/layouts/avo/application.html.erb
```
You can eject any view component from Avo using the `--component` option.
```bash
$ bin/rails generate avo:eject --component Avo::Index::TableRowComponent
```
or
```bash
$ bin/rails generate avo:eject --component avo/index/table_row_component
```
Have the same output:
```bash
create app/components/avo/index/table_row_component.rb
create app/components/avo/index/table_row_component.html.erb
```
With `--field-components` option is easy to eject, one or multiple field components. Notice that without using the `--scope`, the ejected components will override the original components for that field everywhere on the project.
Check the `--scope` and the `components` field options for more details on how to override the components only on specific parts of the project.
```bash
$ rails g avo:eject --field-components text
create app/components/avo/fields/text_field
create app/components/avo/fields/text_field/edit_component.html.erb
create app/components/avo/fields/text_field/edit_component.rb
create app/components/avo/fields/text_field/index_component.html.erb
create app/components/avo/fields/text_field/index_component.rb
create app/components/avo/fields/text_field/show_component.html.erb
create app/components/avo/fields/text_field/show_component.rb
```
Let's say you want to override only the edit component of the `TextField`, that can be achieved with this simple command.
```bash
$ rails g avo:eject --field-components text --view edit
create app/components/avo/fields/text_field/edit_component.rb
create app/components/avo/fields/text_field/edit_component.html.erb
```
While utilizing the `--field-components` option, you can selectively extract a specific view using the `--view` parameter, as demonstrated in the example above. If this option is omitted, all components of the field will be ejected.
When you opt to eject a view component that exists under `Avo::Views` or a field component under `Avo::Fields` namespace, for example the `Avo::Views::ResourceIndexComponent` or `Avo::Fields::TextField::ShowComponent` you can employ the `--scope` option to specify the namespace that should be adopted by the ejected component, extending from `Avo::Views` / `Avo::Fields`.
```bash
$ rails g avo:eject --component Avo::Views::ResourceIndexComponent --scope admins
create app/components/avo/views/admins/resource_index_component.rb
create app/components/avo/views/admins/resource_index_component.html.erb
$ rails g avo:eject --field-components text --view show --scope admins
create app/components/avo/fields/admins/text_field/show_component.rb
create app/components/avo/fields/admins/text_field/show_component.html.erb
```
The ejected file have the same code that original `Avo::Views::ResourceIndexComponent` or `Avo::Fields::TextField::ShowComponent` but you can notice that the class name and the directory has changed
```ruby
class Avo::Views::Admins::ResourceIndexComponent < Avo::ResourceComponent
class Avo::Fields::Admins::TextField::ShowComponent < Avo::Fields::ShowComponent
```
:::info Scopes transformation
`--scope users_admins` -> `Avo::Views::UsersAdmins::ResourceIndexComponent`
You can eject any Avo controller using the `--controller` option. Once ejected, you'll be responsible for maintaining the ejected controller.
```bash
$ rails g avo:eject --controller application_controller
```
The most common use case is ejecting the `application_controller`. The ejected application controller serves as an extendable layer that inherits from `Avo::BaseApplicationController`, where the core logic resides. All your Avo controllers for a specific resource inherit from this extendable layer, allowing you to customize behavior that applies to all resources' controllers.
This approach provides a clean way to add custom functionality or override default behaviors without directly modifying Avo's base controllers.
---
# Custom view types
Avo ships with three built-in view types for the resource index: **table**, **grid**, and **map**. You can restrict which ones are available per-resource, or create entirely new view types through plugins.
## Restricting available view types
By default, Avo displays all the configured view types on the view switcher. For example, if you have `map_view` and `grid_view` configured, both of them, along with the `table_view`, will be available on the view switcher.
However, there might be cases where you only want to make a specific view type available without removing the configurations for other view types. This can be achieved using the `view_types` class attribute on the resource. Note that when only one view type is available, the view switcher will not be displayed.
```ruby{3}
class Avo::Resources::City < Avo::BaseResource
# ...
self.view_types = :table
#...
end
```
If you want to make multiple view types available, you can use an array. The icons on the view switcher will follow the order in which they are declared in the configuration.
```ruby{3}
class Avo::Resources::City < Avo::BaseResource
# ...
self.view_types = [:table, :grid]
#...
end
```
You can also dynamically restrict the view types based on user roles, params, or other business logic. To do this, assign a block to the `view_types` attribute. Within the block, you'll have access to `resource`, `record`, `params`, `current_user`, and other default accessors provided by `ExecutionContext`.
```ruby{3-9}
class Avo::Resources::City < Avo::BaseResource
# ...
self.view_types = -> do
if current_user.is_admin?
[:table, :grid]
else
:table
end
end
#...
end
```
## Creating a custom view type through a plugin
You can register entirely new view types from a Rails Engine (Avo plugin). The view type will appear in the view switcher alongside the built-in ones and can be set as the default for any resource.
The process has three parts: **create the component**, **register the view type**, and **configure a resource to use it**.
### 1. Create the view type component
Every view type is a ViewComponent that inherits from `Avo::ViewTypes::BaseViewTypeComponent`. The base class provides these props automatically:
| Prop | Description |
| ----------------- | ------------------------------------------------------------- |
| `resources` | Array of Avo resource wrappers (call `.record` for the model) |
| `resource` | The Avo resource class |
| `pagy` | Pagination object |
| `query` | The current query |
| `turbo_frame` | The Turbo Frame ID |
| `index_params` | Current index parameters |
| `reflection` | Association reflection (if nested) |
| `parent_record` | Parent record (if nested) |
| `parent_resource` | Parent resource (if nested) |
| `actions` | Available actions |
Create your component class inside your engine's namespace:
```ruby
# app/components/my_plugin/view_types/timeline_view_type_component.rb
class MyPlugin::ViewTypes::TimelineViewTypeComponent < Avo::ViewTypes::BaseViewTypeComponent # [!code focus]
def grouped_resources
@resources.group_by { |r| r.record.created_at.to_date }
end
def empty?
@resources.blank?
end
end
```
Then create the template. You have full control over the HTML β render items however you like and include the paginator at the bottom:
```erb
<%# app/components/my_plugin/view_types/timeline_view_type_component.html.erb %>
<% if empty? %>
No records found.
<% else %>
<% grouped_resources.each do |date, resources| %>
<%= date.strftime("%B %d, %Y") %>
<% resources.each do |resource| %>
<%= resource.record.title %>
<% end %>
<% end %>
<% end %>
`link_to` is the menu item that the user will probably interact with the most. It will generate a link on your menu. You can specify the `name`, `path` , and `target`.
```ruby
link_to "Google", path: "https://google.com", target: :_blank
```
When you add the `target: :_blank` option, a tiny external link icon will be displayed.
#### `link_to` options
#### `path`
This is the path of the item.
It may be ommited to make the API look like Rail's
```ruby
config.main_menu = -> {
# These two are equivalent
link_to "Home", path: main_app.root_path
link_to "Home", main_app.root_path
}
```
##### `data`
You may add arbitraty `data` attributes to your link.
You can make a link execute a `put`, `post`, or `delete` request similar to how you use the `data-turbo-method` attribute.
```ruby
config.main_menu = -> {
link_to "Sign out!", main_app.destroy_user_session_path, data: { turbo_method: :delete }
}
```
The `render` method will render renderable objects like partials or View Components.
You can even pass `locals` to partials.
The partials follow the same pattern as the regular `render` method.
```ruby
render "avo/sidebar/items/custom_tool"
render "avo/sidebar/items/custom_tool", locals: { something: :here }
render Super::Dooper::Component.new(something: :here)
```
To make it a bit easier, you can use `resource` to quickly generate a link to one of your resources. For example, you can pass a short symbol name `:user` or the full name `Avo::Resources::User`.
```ruby
resource :posts
resource "Avo::Resources::Comments"
```
You can also change the label for the `resource` items to something else.
```ruby
resource :posts, label: "News posts"
```
Additionally, you can pass the `params` option to the `resource` items to add query params to the link.
```ruby
resource :posts, params: { status: "published" }
resource :users, params: -> do
decoded_filter = {"Avo::Filters::IsAdmin"=>["non_admins"]}
{ encoded_filters: Avo::Filters::BaseFilter.encode_filters(decoded_filter)}
end
```
### Subitems
You can add sub-links beneath a resource by passing a block. These appear as child items under the resource link in the sidebar and are useful for linking to filtered views, specific records, or nested paths.
```ruby
resource :projects, path: "/admin/resources/projects" do
link "First project", active: :inclusive, path: "/admin/resources/projects/1"
link "Second project", active: :inclusive, path: "/admin/resources/projects/2"
end
```
The `active` option controls when the sub-link is highlighted as active:
- `:inclusive` β the link is active when the current path starts with the given `path` (useful for nested routes)
- `:exclusive` β the link is active only on an exact path match (default)
`subitems` is an optional wrapper you can use inside a `resource` block to make the sub-links more explicit and readable. It is functionally equivalent to writing links directly in the block. Note that `subitems` and the `link` items within it do not support the `icon` option.
```ruby
# These two are equivalent
resource :projects do
link "New project", path: "/admin/resources/projects/new"
link "All projects", path: "/admin/resources/projects"
end
resource :projects do
subitems do
link "New project", path: "/admin/resources/projects/new"
link "All projects", path: "/admin/resources/projects"
end
end
```
Similar to `resource`, this is a helper to make it easier to reference a dashboard. You pass in the `id` or the `name` of the dashboard.
```ruby
dashboard :dashy
dashboard "Sales"
```
You can also change the label for the `dashboard` items to something else.
```ruby
dashboard :dashy, label: "Dashy Dashboard"
```
Sections are the **top-level containers** in the sidebar. They are rendered with a prominent header that includes an `icon` and a `name`. Sections are intended to group related `group`s and items at the highest level of the menu.
```ruby
section "Resources", icon: "heroicons/outline/academic-cap" do
group "Academia", collapsable: true do
resource :course
resource :course_link
end
group "Blog", collapsable: true, collapsed: true do
resource :posts
resource :comments
end
end
```
You can also place items directly inside a section without a group:
```ruby
section "Tools", icon: "heroicons/outline/finger-print" do
all_tools
end
```
Groups are **sub-categories** nested inside sections. They render as a collapsable label and are used to cluster related items within a section. Groups support `collapsable` and `collapsed` options. Note that groups do not support the `icon` option.
```ruby
section "Resources", icon: "heroicons/outline/academic-cap" do
group "Blog", collapsable: true, collapsed: true do
resource :posts
resource :categories
resource :comments
end
end
```
Groups can also be placed at the top level without a parent section, but the recommended structure is to nest them inside sections.
Renders all resources, except those explicitly excluded.
#### Arguments:
- `except`: *(Array, optional)* β A list of resource names to be excluded.
#### Example:
```ruby
section "App", icon: "heroicons/outline/beaker" do
group "Resources" do
all_resources except: [:users, :orders]
end
end
```
In the example above, all resources will be rendered except `Avo::Resources::Users` and `Avo::Resources::Orders`.
Renders all dashboards, except those explicitly excluded.
#### Arguments:
- `except`: *(Array, optional)* β A list of dashboard names to be excluded.
#### Example:
```ruby
section "App", icon: "heroicons/outline/beaker" do
group "Dashboards" do
all_dashboards except: [:sales, :analytics]
end
end
```
In this example, all dashboards will be rendered except `Avo::Resources::Sales` and `Avo::Resources::Analytics`.
Renders all tools.
```ruby
section "App", icon: "heroicons/outline/beaker" do
group "All tools" do
all_tools
end
end
```
### `all_` helpers
```ruby
section "App", icon: "heroicons/outline/beaker" do
group "Dashboards" do
all_dashboards
end
group "Resources" do
all_resources
end
group "All tools" do
all_tools
end
end
```
:::warning
The `all_resources` helper is taking into account your authorization rules, so make sure you have `def index?` enabled in your resource policy.
:::
` badge next to the label and registers the key binding so users can jump straight to that item from anywhere in the admin panel.
```ruby
Avo.configure do |config|
config.main_menu = -> {
section "Content", icon: "tabler/outline/files" do
resource :post, hotkey: "g p"
resource :category, hotkey: "g c"
link "Analytics", path: "/avo/analytics", hotkey: "g a"
end
}
end
```
The hotkey string follows [@github/hotkey](https://github.com/github/hotkey) syntax. Use space-separated keys for sequences (e.g. `"g p"` means press g then p ).
For `resource` items you can also set the hotkey on the resource class itself, which acts as a fallback when no `hotkey:` is passed to the menu item:
```ruby
class Avo::Resources::Post < Avo::BaseResource
self.hotkey = "g p"
end
```
Keyboard shortcuts β full reference for built-in shortcuts and patterns
## Collapsable sections and groups
Both `section` and `group` support the `collapsable` option. When enabled, an arrow icon is added to indicate the item can be collapsed. The collapsed/expanded state is stored in the browser's Local Storage and remembered across page loads.
```ruby
section "Resources", icon: "heroicons/outline/academic-cap", collapsable: true do
group "Blog", collapsable: true do
resource :posts
resource :comments
end
end
```
Cmd + K keyboard shortcut (Ctrl + K on Windows). The search includes enhanced keyboard navigation:
- Ctrl + K or Cmd + K - Open global search
- Up and Down arrow keys - Navigate through search results
- Enter - Visit the selected record
- Esc - Close the search modal
The global search shows a limited number of quick results in the dropdown, with an option to view all matching results on a dedicated page without limits.
## Global configuration
Use the `global_search` configuration to enable/disable the feature and control related options.
```ruby{3-6}
# config/initializers/avo.rb
Avo.configure do |config|
config.global_search = {
enabled: true,
navigation_section: true,
}
end
```
Set `enabled: false` to hide the global search.
All configuration options can be set using a lambda. Within this block, you gain access to all attributes of `Avo::ExecutionContext`.
```ruby{3-6}
# config/initializers/avo.rb
Avo.configure do |config|
config.global_search = {
enabled: -> { current_user.is_admin? },
navigation_section: -> { current_user.is_admin? },
}
end
```
The `item` configuration is used to configure the item displayed in the search results. It is a hash with the following options:
| Option | Description | Default | Possible Values |
|--------|-------------|---------|-----------------|
| `title` | The title of the search result | Resource title | Any string |
| `description` | The description of the search result | `nil` | Any string |
| `image_url` | The URL of the image to display in the search result | `nil` | Any valid URL |
| `image_format` | The format of the image to display in the search result | `:square` | `:square`, `:rounded`, `:circle` |
| `path` | The path to redirect to when clicking the search result | Record's show page | Any valid path |
### Example with all configurations
```ruby{5-13}
# app/avo/resources/post.rb
class Avo::Resources::Post < Avo::BaseResource
self.search = {
query: -> { query.ransack(name_cont: q, body_cont: q, m: "or").result(distinct: false) },
item: -> do
{
title: "[#{record.id}] #{record.name}",
description: record.truncated_body,
image_url: main_app.url_for(record.cover_photo),
image_format: :rounded,
path: avo.resources_post_path(record, custom: "search")
}
end
}
end
```
You might have a resource that you'd like to be able to perform a search on when on its `Index` page but not have it present in the global search. You can hide it using `hide_on_global: true`.
```ruby{9}
class Avo::Resources::TeamMembership < Avo::BaseResource
self.search = {
query: -> { query.ransack(id_eq: q, m: "or").result(distinct: false) },
item: -> do
{
description: record.level,
}
end,
hide_on_global: true
}
end
```
By default, Avo displays 8 search results for each resource in the global search. You can change the number of results displayed by configuring the `search_results_count` option:
```ruby{3}
# config/initializers/avo.rb
Avo.configure do |config|
config.search_results_count = 16
end
```
You can also change the number of results displayed on individual resources:
```ruby{4}
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
self.search = {
results_count: 5
query: -> {
# ...
},
}
end
```
You can also assign a lambda to dynamically set the value. Inside that block you have access to all attributes of the `Avo::ExecutionContext`.
```ruby{3}
class Avo::Resources::User < Avo::BaseResource
self.search = {
results_count: -> { user.admin? ? 30 : 10 }
}
end
```
If you configure `results_count` by specifying it in the resource file then that number takes precedence over the global [`search_results_count`](#search_results_count) for that resource.
By default, Avo displays the search results count for each resource in the global search. Example: "Users (8 of 21)". You can avoid counting the number of results by configuring the `display_count` option
This is useful if you have a custom search provider that doesn't return the number of results or if you want to avoid counting the number of results on large datasets.
```ruby{4}
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
self.search = {
display_count: false
query: -> {
# ...
},
}
end
```
You can also assign a lambda to dynamically set the value. Inside that block you have access to all attributes of the `Avo::ExecutionContext`.
```ruby{4}
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
self.search = {
display_count: -> { user.admin? }
}
end
```
## Scope out global or resource searches
You may want to perform different searches on the `global` search from the `resource` search. You may use the `params[:global]` flag to figure that out.
```ruby{5-11}
# app/avo/resources/order.rb
class Avo::Resources::Order < Avo::BaseResource
self.search = {
query: -> {
if params[:global]
# Perform global search
query.ransack(id_eq: q, m: "or").result(distinct: false)
else
# Perform resource search
query.ransack(id_eq: q, details_cont: q, m: "or").result(distinct: false)
end
}
}
end
```
## Custom search provider
You can use custom search providers like Elasticsearch.
In such cases, or when you want to have full control over the search results, the `query` block should return an array of hashes. Each hash should follow the structure below:
```ruby
{
_id: 1,
_label: "The label",
_url: "The URL",
_description: "Some description about the record", # only with Avo Pro and above
_avatar: "URL to an image that represents the record", # only with Avo Pro and above
_avatar_type: :rounded # or :circle or :square; only with Avo Pro and above
}
```
Example:
```ruby{2-10}
class Avo::Resources::Project < Avo::BaseResource
self.search = {
query: -> do
[
{ _id: 1, _label: "Record One", _url: "https://example.com/1" },
{ _id: 2, _label: "Record Two", _url: "https://example.com/2" },
{ _id: 3, _label: "Record Three", _url: "https://example.com/3" }
]
end
}
end
```
:::warning
Results count will not be available with custom search providers.
:::
---
# Localization (i18n)
Avo leverages Rails' powerful `I18n` translations module.
:::warning Multi-language URL Support
If you're serving Avo using multiple languages and you're using the locale in your routes (`/en/resources/users`, `/de/resources/users`), check out this guide.
:::
When you run `bin/rails avo:install`, Rails will not generate for you the `avo.en.yml` translation file. This file is already loaded will automatically be injected into the I18n translations module.
## Localizing resources
Let's say you want to localize a resource. All you need to do is add a `self.translation_key` class attribute in the `Resource` file. That will tell Avo to use that translation key to localize this resource. That will change the labels of that resource everywhere in Avo.
```ruby{4}
# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
self.title = :name
self.translation_key = 'avo.resource_translations.user'
end
```
```yaml{6-10}
# avo.es.yml
es:
avo:
dashboard: 'Dashboard'
# ... other translation keys
resource_translations:
user:
zero: 'usuarios'
one: 'usuario'
other: 'usuarios'
```
## Localizing fields
Similarly, you can even localize fields. All you need to do is add a `translation_key:` option on the field declaration.
```ruby{8}
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
self.title = :name
def fields
field :id, as: :id
# ... other fields
field :files, as: :files, translation_key: 'avo.field_translations.file'
end
end
```
```yaml{6-10}
# avo.es.yml
es:
avo:
dashboard: 'Dashboard'
# ... other translation keys
field_translations:
file:
zero: 'archivos'
one: 'archivo'
other: 'archivos'
```
## Localizing buttons label
<%= render Avo::PanelComponent.new title: 'Dashboard', display_breadcrumbs: true do |c| %>
<% c.with_tools do %>
This is the panels tools section.
<% end %>
<% c.with_body do %>
What a nice new tool π
<%= custom_helper %>
<% end %>
<% end %>
There may be times when you want to duplicate an existing field and start from there.
To achieve this behavior, use the `--field_template` argument and pass the original field as a value.
Now, all components will have the exact same code (except the name) as the original field.
```bash
$ bin/rails generate avo:field super_text --field_template text
create app/components/avo/fields/super_text_field
create app/components/avo/fields/super_text_field/edit_component.html.erb
create app/components/avo/fields/super_text_field/edit_component.rb
create app/components/avo/fields/super_text_field/index_component.html.erb
create app/components/avo/fields/super_text_field/index_component.rb
create app/components/avo/fields/super_text_field/show_component.html.erb
create app/components/avo/fields/super_text_field/show_component.rb
create app/avo/fields/super_text_field.rb
```
We can verify that all components have the text field code. From here there are endless possibilities to extend the original field features.
```ruby
# app/avo/fields/super_text_field.rb
module Avo
module Fields
class SuperTextField < BaseField
attr_reader :link_to_record
attr_reader :as_html
attr_reader :protocol
def initialize(id, **args, &block)
super(id, **args, &block)
add_boolean_prop args, :link_to_record
add_boolean_prop args, :as_html
add_string_prop args, :protocol
end
end
end
end
# lib/avo/fields/text_field.rb
module Avo
module Fields
class TextField < BaseField
attr_reader :link_to_record
attr_reader :as_html
attr_reader :protocol
def initialize(id, **args, &block)
super(id, **args, &block)
add_boolean_prop args, :link_to_record
add_boolean_prop args, :as_html
add_string_prop args, :protocol
end
end
end
end
```
## Field options
This file is where you may add field-specific options.
```ruby{3-6,11-14}
# app/avo/fields/progress_bar_field.rb
class Avo::Fields::ProgressBarField < Avo::Fields::BaseField
attr_reader :max
attr_reader :step
attr_reader :display_value
attr_reader :value_suffix
def initialize(name, **args, &block)
super(name, **args, &block)
@max = 100
@step = 1
@display_value = false
@value_suffix = nil
end
end
```
The field-specific options can come from the field declaration as well.
```ruby{11-14,24}
# app/avo/fields/progress_bar_field.rb
class Avo::Fields::ProgressBarField < Avo::Fields::BaseField
attr_reader :max
attr_reader :step
attr_reader :display_value
attr_reader :value_suffix
def initialize(name, **args, &block)
super(name, **args, &block)
@max = args[:max] || 100
@step = args[:step] || 1
@display_value = args[:display_value] || false
@value_suffix = args[:value_suffix] || nil
end
end
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
self.title = :name
def fields
field :id, as: :id, link_to_record: true
field :progress, as: :progress_bar, step: 10, display_value: true, value_suffix: "%"
end
end
```
## Field Visibility
If you need to hide the field in some view, you can use the visibility helpers.
```ruby{16}
# app/avo/fields/progress_bar_field.rb
class Avo::Fields::ProgressBarField < Avo::Fields::BaseField
attr_reader :max
attr_reader :step
attr_reader :display_value
attr_reader :value_suffix
def initialize(name, **args, &block)
super(name, **args, &block)
@max = args[:max] || 100
@step = args[:step] || 1
@display_value = args[:display_value] || false
@value_suffix = args[:value_suffix] || nil
hide_on :forms
end
end
```
## Customize the views
No let's do something about those views. Let's add a progress bar to the `Index` and `Show` views.
```erb{1,15}
# app/components/avo/fields/progress_bar_field/show_component.html.erb
<%= show_field_wrapper field: @field, index: @index do %>
<% if @field.display_value %>
<%= @field.value %><%= @field.value_suffix if @field.value_suffix.present? %>
<% end %>
<%= @field.value %><%= @field.value_suffix if @field.value_suffix.present? %>
<% end %>
<%= @field.value %> <%= @field.value_suffix if @field.value_suffix.present? %>
<% end %>
<%= @form.range_field @field.id,
class: 'w-full',
placeholder: @field.placeholder,
disabled: @field.readonly,
min: 0,
# add the field-specific options
max: @field.max,
step: @field.step,
%>
<% end %>
```
<% unless @field.always_show %>
<%= link_to t('avo.show_content'), 'javascript:void(0);', class: 'font-bold inline-block', data: { action: 'click->hidden-input#showContent' } %>
<% end %>
class="hidden" <% end %> data-hidden-input-target="content">
<%= @field.value %>
This adds a class to the `th` element of the table header.
We added it when we needed to force a certain column to be a certain size, but you can use it for any purpose.
It defaults to `nil`
```ruby
def table_header_class
"w-32"
end
```
---
# Custom errors
Actions such as create, update, attach, etc... will not be completed if the record contains any errors. This ensures that only valid data is processed and saved, maintaining the integrity of your application. Custom validations can be added to your models to enforce specific rules and provide meaningful error messages to users.
## Adding Custom Errors
To add custom errors, you can define a validation method in your model. If the validation fails it adds an error to the record. These errors will prevent the action from completing and will be displayed as notifications to the user.
## In a Simple Record
Consider a simple `User` model where you want to enforce a custom validation rule, such as ensuring that the user's age is over a certain value.
```ruby
# app/models/user.rb
class User < ApplicationRecord
validate :age_must_be_over_18
private
def age_must_be_over_18
# Add a custom error to the record if age is less than 18.
if age < 18
errors.add(:age, "must be over 18.")
end
end
end
```
In this example, the `age_must_be_over_18` method checks if the user's age is less than 18. If so, it adds an error to the `age` attribute with a custom message. This error prevents any further Avo action on the record and notifies the user of the issue.
## In a Join Table
Consider a join table `TeamMembership` which links `Team` and `User` models. You might want to add a custom validation to ensure some business logic is enforced.
```ruby
# app/models/team_membership.rb
class TeamMembership < ApplicationRecord
belongs_to :team
belongs_to :user
validate :custom_validation
private
def custom_validation
if user.banned?
errors.add(:user, "is banned.")
end
end
end
```
In this example, the `custom_validation` method is called whenever a `TeamMembership` record is validated. If the conditions in this method are not met, an error is added to the `user` attribute with a custom message. This error prevents any further Avo action on the record and notifies the user of the issue.
---
# Resource tools
Similar to adding custom fields to a resource, you can add custom tools. A custom tool is a partial added to your resource's `Show` and `Edit` views.
## Generate a resource tool
Run `bin/rails generate avo:resource_tool post_info`. That will create two files. The configuration file `app/avo/resource_tools/post_info.rb` and the partial file `app/views/avo/resource_tools/_post_info.html.erb`.
The configuration file holds the tool's name and the partial path if you want to override it.
```ruby
class Avo::ResourceTools::PostInfo < Avo::BaseResourceTool
self.name = "Post info"
# self.partial = "avo/resource_tools/post_info"
end
```
The partial is ready for you to customize further.
```erb
<%= render Avo::PanelComponent.new title: "Post info" do |c| %>
<% c.with_tools do %>
<%= a_link('/avo', icon: 'heroicons/solid/academic-cap', style: :primary) do %>
Dummy link
<% end %>
<% end %>
<% c.with_body do %>
πͺ§ This partial is waiting to be updated
You can edit this file here app/views/avo/resource_tools/post_info.html.erb.
The resource tool configuration file should be here app/avo/resource_tools/post_info.rb.
<%
# In this partial, you have access to the following variables:
# tool
# @resource
# @resource.model
# form (on create & edit pages. please check for presence first)
# params
# Avo::Current.context
# current_user
%>
<% end %>
<% end %>
<%= render Avo::PanelComponent.new(title: @resource.model.name) do |c| %>
<% c.with_tools do %>
<%= a_link('/admin', icon: 'heroicons/solid/academic-cap', style: :primary) do %>
Primary
<% end %>
<% end %>
<% c.with_body do %>
<% if form.present? %>
<%= form.label :fish_type %>
<%= form.text_field :fish_type, value: 'default type of fish', class: input_classes %>
<%= form.label :properties %>
<%= form.text_field :properties, multiple: true, value: 'property 1', class: input_classes %>
<%= form.text_field :properties, multiple: true, value: 'property 2', class: input_classes %>
<% form.fields_for :information do |information_form| %>
<%= form.label :information_name %>
<%= information_form.text_field :name, value: 'information name', class: input_classes %>
This is going to be passed to the model
<%= form.label :information_history %>
<%= information_form.text_field :history, value: 'information history', class: input_classes %>
This is going to be passed to the model
<%= form.label :information_age %>
<%= information_form.text_field :age, value: 'information age', class: input_classes %>
This is NOT going to be passed to the model
<% end %>
<% end %>
<% end %>
<% end %>
<%= render Avo::PanelComponent.new title: "Post info" do |c| %>
<% c.with_body do %>
This variable was declared in the initializer:
<%= tool.foo %>
This is a method called on the tool:
<%= tool.custom_method_call %>
<% end %>
<% end %>
```
You can add those targets to your controllers and use them in your JS code.
### Field inputs as targets
Similar to the wrapper element, inputs in the `Edit` and `New` views get the `[FIELD_NAME][FIELD_TYPE]InputTarget`. On more complex fields like the searchable, polymorphic `belongs_to` field, where there is more than one input, the target attributes are attached to all `input`, `select`, and `button` elements.
```ruby
# Inputs get the `data-[CONTROLLER]-target="nameTextInput"` attribute and can be targeted using nameTextInputTarget
field :name, as: :text
# Inputs get the `data-[CONTROLLER]-target="createdAtDateTimeInput"` attribute and can be targeted using createdAtDateTimeInputTarget
field :created_at, as: :date_time
# Inputs get the `data-[CONTROLLER]-target="hasSkillsTagsInput"` attribute and can be targeted using hasSkillsTagsInputTarget
field :has_skills, as: :tags
```
### All controllers receive the `view` value
All stimulus controllers receive the `view` attribute in the DOM.
```html{4-5}
```
Now you can use that inside your Stimulus JS controller like so:
```js{5,9}
import { Controller } from '@hotwired/stimulus'
export default class extends Controller {
static values = {
view: String,
}
async connect() {
console.log('view ->', this.viewValue)
}
}
```
The possible values are `index`, `show`, `edit`, or `new`
## Assign Stimulus controllers to actions
Similarly as to resource, you can assign stimulus controller to an action. To do that you can use the `stimulus_controllers` option on the action file.
```ruby
class Avo::Actions::ShowCurrentTime < Avo::BaseAction
self.stimulus_controllers = "city-in-country"
end
```
You can add more and separate them by a space character.
```ruby
class Avo::Actions::ShowCurrentTime < Avo::BaseAction
self.stimulus_controllers = "course-resource select-field association-fields"
end
```
The same way as for the resources, Avo will add stimulus target data attributes to [all field wrappers](#field-wrappers-as-targets) and [all input fields](#field-inputs-as-targets).
Unlike with the resource, Avo will not add a specific default controller for each type of the view (`index`, `show`, `edit`).
Same way, the controllers will not receive the `view` attribute in the DOM, [as in case of resources](#all-controllers-receive-the-view-value).
## Attach HTML attributes
This section has moved.
## Composing the attributes together
You can use the attributes together to make your fields more dynamic.
```ruby{3-9}
field :has_skills, as: :boolean, html: {
edit: {
input: {
data: {
# On click run the toggleSkills method on the toggle-fields controller
action: "input->toggle-fields#toggleSkills",
}
}
}
}
field :skills, as: :tags, html: {
edit: {
wrapper: {
# hide this field by default
classes: "hidden"
}
}
}
```
```js
// toggle_fields_controller.js
import { Controller } from "@hotwired/stimulus";
export default class extends Controller {
static targets = ["skillsTagsWrapper"]; // use the target Avo prepared for you
toggleSkills() {
this.skillsTagsWrapperTarget.classList.toggle("hidden");
}
}
```
## Pre-made stimulus methods
Avo ships with a few JS methods you may use on your resources.
### `resource-edit#toggle`
On your `Edit` views, you can use the `resource-edit#toggle` method to toggle the field visibility from another field.
```ruby{5-7}
field :has_country, as: :boolean, html: {
edit: {
input: {
data: {
action: "input->resource-edit#toggle", # use the pre-made stimulus method on input
resource_edit_toggle_target_param: "countrySelectWrapper", # target to be toggled
# resource_edit_toggle_targets_param: ["countrySelectWrapper"] # add more than one target
}
}
}
}
field :country, as: :select, options: Course.countries.map { |country| [country, country] }.to_h
```
```
Done π Now you have a controller connecting to a custom Resource tool or Avo tool (or Avo views).
---
# Custom asset pipeline
Avo plays well with most Rails asset pipelines.
| Asset pipeline | Avo compatibility |
|---------------|------------|
| [importmap](https://github.com/rails/importmap-rails) | β
Fully supported |
| [Propshaft](https://github.com/rails/propshaft) | β
Fully supported |
| [Sprockets](https://github.com/rails/sprockets) | β
Fully supported |
| [Webpacker](https://github.com/rails/webpacker) | π» Only with Sprockets or Propshaft |
There are two things we need to mention when communicating about assets.
1. Avo's assets
2. You custom assets
## Avo's assets
We chose to impact your app, and your deploy processes as little as possible. That's why we bundle up Avo's assets when we publish on [rubygems](https://rubygems.org/gems/avo), so you don't have to do anything else when you deploy your app. Avo doesn't require a NodeJS, or any kind of any other special environment in your deploy process.
Under the hood Avo uses TailwindCSS 3.0 with the JIT engine and bundles the assets using [`jsbundling`](https://github.com/rails/jsbundling-rails) with `esbuild`.
## Exclude servings Avo assets from a CDN?
If you utilize a Content Delivery Network (CDN) for serving assets and you want to exclude Avo paths from the default asset host you may use the following code snippet.
```ruby
config.action_controller.asset_host = Proc.new do |source|
# Exclude assets under the "/avo" path from CDN
next nil if source.start_with?("/avo")
# Set the general asset host (CDN) using an environment variable
ENV.fetch("ASSET_HOST")
end
```
This configuration ensures that assets are served through the specified CDN, except for those under the `/avo` path. Adjust the paths and environment variable as needed for your application.
## Your custom assets
Avo makes it easy to use your own styles and javascript through your already set up asset pipeline. It just hooks on to it to inject the new assets to be used in Avo.
## Use TailwindCSS utility classes
Please follow the dedicated TailwindCSS integration guide.
## Add custom JS code and Stimulus controllers
There are more ways of dealing with JS assets, and Avo handles that well.
## Use Importmap to add your assets
Importmap has become the default way of dealing with assets in Rails 7. For you to start using custom JS assets with Avo and importmap you should run this install command `bin/rails generate avo:js:install`. That will:
- create your `avo.custom.js` file as your JS entrypoint;
- add it to the `app/views/avo/partials/_head.html.erb` partial so Avo knows to load it;
- pin it in your `importmap.rb` file so `importmap-rails` knows to pick it up.
## Use `js-bundling` with `esbuild`
`js-bundling` gives you a bit more flexibility and power when it comes to assets. We use that under the hood and we'll use it to expose your custom JS assets.
When you install `js-bundling` with `esbuild` you get this npm script `"build": esbuild app/javascript/*.* --bundle --sourcemap --outdir=app/assets/builds --public-path=assets`. That script will take all your JS entrypoint files under `app/javascript` and bundle them under `assets/builds`.
```bash
bin/rails generate avo:js:install --bundler esbuild
```
That command will:
- eject the `_head.html.erb` file;
- add the `avo.custom.js` asset to it;
- create the `avo.custom.js` file under `app/javascript` which will be your entrypoint.
That will be picked up by the `build` script and create it's own `assets/builds/avo.custom.js` file that will, in turn, be picked up by sprockets or propshaft and loaded into your app.
## Use `js-bundling` with `rollup` or `webpack`
Avo supports the other bundlers too but we just don't have a generator command to configure them for you. If you use the other bundlers and have configured them to use custom assets, then please [open up a PR](https://github.com/avo-hq/avo) and help the community get started faster.
## Manually add your CSS and JS assets
In order to manually add your assets you have to eject the `_pre_head.html.erb` partial (`bin/rails generate avo:eject --partial :pre_head`), create the asset files (examples below), and add the asset files from your pipeline to the `_pre_head` partial. Then, your asset pipeline will pick up those assets and use add them to your app.
:::warning
You should add your custom styles to `_pre_head.html.erb`, versus `_head.html.erb` to avoid overriding Avo's default styles. This
The order in which Avo loads the partials and asset files is this one:
1. `_pre_head.html.erb`
2. Avo's CSS and JS assets
3. `_head.html.erb`
:::
This integration is built for Tailwind CSS 4.
:::
Avo ships with precompiled styles that are easy to use and work out of the box, so most apps do not need to care about extra build steps.
When Avo detects `tailwindcss-ruby`, it automatically enables this integration and builds an app-level Avo stylesheet with zero (or close to zero) configuration.
If you have `tailwindcss-ruby` installed (or `tailwindcss-rails`, which depends on `tailwindcss-ruby`) but you do **not** use custom Tailwind/CSS classes in custom tools, ejected components, custom fields, or other extended UI areas, you can opt out and keep using only Avo's precompiled styles.
When enabled, this integration compiles a stylesheet that includes:
- Avo core styles
- loaded Avo plugin styles
- your host app Avo styles from `app/assets/stylesheets/avo/**/*.css`
- utility classes discovered under your Rails `app/` directory (configurable; see below), plus Avo and plugin sources
The output file is:
`app/assets/builds/avo/application.css`
This integration writes to the same logical Avo stylesheet path (`avo/application`) so your app always loads one stylesheet entrypoint.
## Auto-enable behavior
Add `tailwindcss-ruby` to your app:
```ruby
gem "tailwindcss-ruby"
```
Once present, Avo will:
- auto-build in development
- hook into `assets:precompile` in production
:::tip
We highly recommend running this integration through `bin/dev` with a `Procfile.dev` watcher process:
```bash
web: bin/rails server -p 3000
avo_css: bin/rails avo:tailwindcss:watch
```
This keeps your Avo Tailwind build running in parallel with the Rails server, so style changes are compiled automatically while you work without extra manual steps.
:::
## Add your custom Avo styles
Add your Avo-specific stylesheets under `app/assets/stylesheets/avo/`.
Every CSS file in this path is included in the final `avo/application.css` build.
For example:
```css
/* app/assets/stylesheets/avo/buttons.css */
@layer components {
.avo-btn-highlight {
@apply px-3 py-2 rounded-md bg-indigo-600 text-white;
}
}
```
## Disable integration (opt-out)
If your app has `tailwindcss-ruby` (directly or via `tailwindcss-rails`) but you do not need Avo custom utility coverage, disable the integration in your initializer:
```ruby
Avo.configure do |config|
config.tailwindcss_integration_enabled = false
end
```
Default is `true`.
The default is intentionally `true` to preserve the zero-configuration experience: if your app has `tailwindcss-ruby` and you start adding classes/styles in custom Avo UI extension points, this integration should just work without you needing to think about setup details.
## Host content scan paths (`tailwindcss_content_sources`)
Avo writes Tailwind v4 `@source` directives into `tmp/avo/avo.tailwind.input.css` so the compiler can see utility classes used in templates and Ruby/HTML. **By default**, the host-side scan is limited to `Rails.root.join("app")` (the usual Rails tree: views, components, `app/avo` resources, and similar).
That keeps discovery focused on application code and avoids scanning unrelated directories under the project root.
Configure extra roots (or override the list entirely) in `config/initializers/avo.rb`:
```ruby
Avo.configure do |config|
config.tailwindcss_content_sources = [
Rails.root.join("app"),
Rails.root.join("lib", "components")
]
end
```
Each entry may be an **absolute** path or a path **relative to** `Rails.root`. Directories that do not exist are skipped.
To include the **entire project root** in the host scan (everything under `Rails.root`), set:
```ruby
config.tailwindcss_content_sources = [Rails.root]
```
## Debugging
If classes are missing from `avo/application.css`, check these files first:
- input file generated by Avo: `tmp/avo/avo.tailwind.input.css`
- output file generated by Tailwind: `app/assets/builds/avo/application.css`
How it works, in short:
- Avo generates `tmp/avo/avo.tailwind.input.css` on each build/watch cycle.
- That input file imports Avo/plugin `application.css` files and your host styles from `app/assets/stylesheets/avo/**/*.css`.
- It also adds `@source` entries for Avo, loaded plugins, and your configured host directories (default: `Rails.root.join("app")`) so Tailwind can discover utility classes from templates and code.
- Tailwind then compiles everything into `app/assets/builds/avo/application.css`.
Quick checks:
- confirm the integration is enabled (`config.tailwindcss_integration_enabled = true`);
- ensure `tailwindcss-ruby` is installed (directly or via `tailwindcss-rails`);
- verify your custom styles are under `app/assets/stylesheets/avo/`;
- run with the watcher (`bin/dev`) so changes are rebuilt continuously.
---
# Dashboards
:::warning
You must manually require the `chartkick` gem in your `Gemfile`.
```ruby
# Create beautiful JavaScript charts with one line of Ruby
gem "chartkick"
```
:::
There comes the point in your app's life when you need to display the data in an aggregated form like a metric or chart. That's what Avo's Dashboards are all about.
## Generate a dashboard
Run `bin/rails g avo:dashboard my_dashboard` to get a shiny new dashboard.
```ruby
class Avo::Dashboards::MyDashboard < Avo::Dashboards::BaseDashboard
self.id = 'my_dashboard'
self.name = 'Dashy'
self.description = 'The first dashbaord'
self.grid_cols = 3
def cards
card Avo::Cards::ExampleMetric
card Avo::Cards::ExampleAreaChart
card Avo::Cards::ExampleScatterChart
card Avo::Cards::PercentDone
card Avo::Cards::AmountRaised
card Avo::Cards::ExampleLineChart
card Avo::Cards::ExampleColumnChart
card Avo::Cards::ExamplePieChart
card Avo::Cards::ExampleBarChart
divider label: "Custom partials"
card Avo::Cards::ExampleCustomPartial
card Avo::Cards::MapCard
end
end
```
`self.name` is what is going to be displayed to the user as the dashboard name.
```ruby
self.name = "Dashy"
```
---
# Cards
Cards are one way of quickly adding custom content for your users.
Cards can be used on dashboards or resources, we'll refer to both of them as "parent" since they're hosting the cards.
You can add three types of cards to your parent: `partial`, `metric`, and `chartkick`.
## Base settings
All cards have some standard settings like `id`, which must be unique, `label` and `description`. The `label` will be the title of your card, and `description` will show a tiny question mark icon on the bottom right with a tooltip with that description.
Each card has its own `cols` and `rows` settings to control the width and height of the card inside the parent's grid. They can have values from `1` to `6`.
All this settings can be called as an lambda.
The lambda will be executed using `Avo::ExecutionContext`. Within this blocks, you gain access to all attributes of `Avo::ExecutionContext` along with the `parent`, `resource`, `dashboard` and `card`.
```ruby{2-7}
class Avo::Cards::UsersMetric < Avo::Cards::MetricCard
self.id = "users_metric"
self.label = -> { "Users count" }
self.description = -> { "Users description" }
self.cols = 1
self.rows = 1
self.display_header = true
end
```
Sets the display title for the page.
```ruby{3}
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
self.title = "Application Settings"
end
```
Provides a description that appears below the page title.
```ruby{3}
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
self.description = "Manage your application settings and preferences"
end
```
Customizes the label displayed in the Avo menu entry and page sidebar menu entry.
**Default behavior:**
- If `navigation_label` is not set, it defaults to the `title`
- If `title` is not set, it takes the last namespace from the class and humanizes it
```ruby{3}
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
self.navigation_label = "App Configuration"
end
```
This is particularly useful when you want different text in navigation menus than what's displayed as the page title, or when you want to shorten long titles for better menu presentation.
## Page Methods
Define sub-pages that belong to this page. This method is used to register child pages and configure their relationship to the parent.
:::warning Boot-time Parsing
The `def navigation` method is parsed only once during application boot. Do not use conditional logic (if/else statements) or dynamic content inside this method, as it will not be re-evaluated during runtime.
:::
```ruby{3-5}
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
def navigation
# ...
end
end
```
This method is used to register sub pages that belong to this page. The `page` method supports three different types of declarations:
#### 1. Class-based pages (backed by a file)
The traditional approach where you reference an existing page class.
```ruby
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
def navigation
page Avo::Pages::Settings::General # [!code focus]
end
end
```
#### 2. Virtual pages that render a form
Create a "virtual" page that directly renders a form without requiring a separate page file. If title and description are not provided, the page will use the form's title and description.
```ruby
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
def navigation
page form: Avo::Forms::Profiles # [!code focus]
end
end
```
#### 3. Virtual pages with custom content
Create a "virtual" page with a custom title and content block that can contain multiple forms.
```ruby
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
def navigation
page "Settings", # [!code focus]
description: "Manage your application settings and preferences", # [!code focus]
content: -> do # [!code focus]
form Avo::Forms::General # [!code focus]
form Avo::Forms::Integrations # [!code focus]
end # [!code focus]
end
end
```
### Page Options
When defining pages, you can pass additional options:
#### `default`
Marks a page as the default one to display when the main page is accessed. Available for all page types.
**Default value**: `false`
**Possible values**: `true` or `false`
```ruby
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
def navigation
page Avo::Pages::Settings::General, default: true # [!code focus]
page form: Avo::Forms::Profiles
page "Custom Settings",
content: -> { form Avo::Forms::Custom },
default: false
end
end
```
Define forms that should be displayed on this page. Forms are the primary way users interact with your page's functionality.
:::warning Boot-time Parsing
The `def content` method is parsed only once during application boot. Do not use conditional logic (if/else statements) or dynamic content inside this method, as it will not be re-evaluated during runtime.
:::
```ruby{3-5}
# app/avo/pages/settings/general.rb
class Avo::Pages::Settings::General < Avo::Forms::Core::Page
def content
# ...
end
end
```
You can define multiple forms on a single page, and they will be displayed in the order you declare them.
This method is used to register forms that should be displayed on this page.
It expects the form class as the first argument.
```ruby
# app/avo/pages/settings/general.rb
class Avo::Pages::Settings::General < Avo::Forms::Core::Page
def content
form Avo::Forms::Settings::AppSettings # [!code focus]
form Avo::Forms::Settings::ProfileSettings # [!code focus]
end
end
```
## Complete Example
Here's a complete example showing a settings page with multiple sub-pages:
```ruby
# Main settings page
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
self.title = "Settings"
self.description = "Manage your application settings"
self.navigation_label = "App Settings"
def navigation
page Avo::Pages::Settings::General, default: true
page form: Avo::Forms::UserProfiles
page "Integrations",
content: -> do
form Avo::Forms::Settings::SlackIntegration
form Avo::Forms::Settings::EmailIntegration
end
page Avo::Pages::Settings::Security
end
end
```
```ruby
# General settings sub-page
# app/avo/pages/settings/general.rb
class Avo::Pages::Settings::General < Avo::Forms::Core::Page
self.title = "General Settings"
self.description = "Basic application configuration"
def content
form Avo::Forms::Settings::AppSettings
form Avo::Forms::Settings::CompanyInfo
end
end
```
```ruby
# Notifications sub-page
# app/avo/pages/settings/notifications.rb
class Avo::Pages::Settings::Notifications < Avo::Forms::Core::Page
self.title = "Notifications"
self.description = "Configure notification preferences"
def content
form Avo::Forms::Settings::EmailNotifications
form Avo::Forms::Settings::SlackIntegration
end
end
```
## Adding Pages to the Menu
Sets the display title for the form.
```ruby{3}
# app/avo/forms/app_settings.rb
class Avo::Forms::AppSettings < Avo::Forms::Core::Form
self.title = "Application Settings"
end
```
Provides a description that appears below the form title.
```ruby{3}
# app/avo/forms/app_settings.rb
class Avo::Forms::AppSettings < Avo::Forms::Core::Form
self.description = "Manage your application configurations"
end
```
## Form Methods
Define the structure and fields of your form. This method uses the same field syntax as Avo resources and actions, supporting all field types, panels, clusters, and layout components.
:::tip
When using `panel` to group fields, you **must** use the `main_panel` for one of the panels where you want to display the save button.
:::
```ruby{3-5}
# app/avo/forms/user_preferences.rb
class Avo::Forms::UserPreferences < Avo::Forms::Core::Form
def fields
# Define form fields here
end
end
```
Add individual fields to your form. Supports all Avo field types and options.
```ruby
# app/avo/forms/user_preferences.rb
class Avo::Forms::UserPreferences < Avo::Forms::Core::Form
def fields
field :email, as: :text, required: true # [!code focus]
field :notifications, as: :boolean, default: true # [!code focus]
field :theme, as: :select, options: { light: "Light", dark: "Dark" } # [!code focus]
end
end
```
**Field Options**
All standard Avo field options are supported
Process form submission and define the response. This method is called when the form is submitted and receives form data through the `params` object.
Currently, the `handle` method is executed in the context of the controller method that receives the form request. This means that you can use any of the methods available in the controller to process the form data. **This is something experimental and might change in the future.**
This experiment is to see if by not building a heavy DSL for forms, we can make it easier to use and maintain.
The main point is that since it is the controller method, everything is available and possible to the developer by using rails syntax.
If we build a heavy DSL for the `handle` method like we do for actions, it and might feel restrictive to the developer in some cases.
If you have any feedback, please share it with us.
Right now the only pre-defined methods available in the controller are:
- `default_response` - Standard redirect back turbo stream response
```ruby{3-8}
# app/avo/forms/user_preferences.rb
class Avo::Forms::UserPreferences < Avo::Forms::Core::Form
def handle
# Process form data
# Access form data via params
# Set flash messages and redirect
default_response
end
end
```
## Field Types and Layout
Forms support all Avo field types and layout components:
### Basic Fields
```ruby
def fields
field :name, as: :text
field :email, as: :text, required: true
field :age, as: :number
field :active, as: :boolean
field :bio, as: :textarea
field :role, as: :select, options: { admin: "Admin", user: "User" }
end
```
### Panels and Organization
```ruby
def fields
main_panel "Personal Information" do
field :first_name, as: :text
field :last_name, as: :text
field :email, as: :text
end
panel "Preferences", description: "Customize your experience" do
field :theme, as: :select, options: { light: "Light", dark: "Dark" }
field :notifications, as: :boolean
end
end
```
### Clusters for Inline Layout
```ruby
def fields
main_panel do
cluster do
field :first_name, as: :text
field :last_name, as: :text
end
end
end
```
### Working with Records
You can bind form fields to existing records:
```ruby
def fields
field :first_name, record: Avo::Current.user
field :last_name, record: Avo::Current.user
field :email, record: Avo::Current.user
end
```
## Form Submission Handling
### Processing Form Data
```ruby
def handle
# Access form parameters
app_name = params[:app_name]
maintenance_mode = params[:maintenance_mode]
# Update application settings
Rails.application.config.app_name = app_name
cookies[:maintenance_mode] = maintenance_mode
# Set success message
flash[:notice] = "Settings updated successfully"
# Return standard response
default_response
end
```
### Flash Messages
```ruby
def handle
# Informative message
flash[:notice] = "Operation completed successfully"
# Error message
flash[:error] = "Something went wrong"
# Success with timeout
flash[:success] = { body: "Saved successfully", timeout: 3000 }
# Warning message without dismissing
flash[:warning] = { body: "Something went wrong", timeout: :forever }
default_response
end
```
### Working with Models
```ruby
def handle
# Update current user
current_user.update(params.permit(:first_name, :last_name, :email))
# Create new records
Post.create(title: params[:title], body: params[:body])
# Complex data processing
if params[:import_data]
ImportService.new(params[:file]).process
end
flash[:notice] = "Data processed successfully"
default_response
end
```
## Complete Examples
### User Profile Settings Form
```ruby
# app/avo/forms/profile_settings.rb
class Avo::Forms::ProfileSettings < Avo::Forms::Core::Form
self.title = "Profile Settings"
self.description = "Update your personal information"
def fields
main_panel do
cluster do
with_options stacked: true, record: Avo::Current.user do
field :first_name, as: :text, required: true
field :last_name, as: :text, required: true
end
end
field :email, as: :text, required: true, record: Avo::Current.user
field :phone, as: :text, record: Avo::Current.user
end
panel "Preferences" do
field :theme, as: :select,
options: { light: "Light", dark: "Dark", auto: "Auto" },
default: "auto"
field :email_notifications, as: :boolean, default: true
field :timezone, as: :select, options: ActiveSupport::TimeZone.all.map { |tz| [tz.name, tz.name] }
end
end
def handle
# Update user profile
current_user.update(params.permit(:first_name, :last_name, :email, :phone))
# Update preferences (assuming a preferences model)
current_user.preferences.update(
theme: params[:theme],
email_notifications: params[:email_notifications],
timezone: params[:timezone]
)
flash[:notice] = "Profile updated successfully"
default_response
end
end
```
### Application Settings Form
```ruby
# app/avo/forms/app_settings.rb
class Avo::Forms::AppSettings < Avo::Forms::Core::Form
self.title = "Application Settings"
self.description = "Configure global application settings"
def fields
main_panel do
field :app_name, as: :text,
default: -> { Rails.application.class.module_parent_name },
required: true
field :app_url, as: :text,
default: -> { request.base_url },
placeholder: "https://yourapp.com"
field :maintenance_mode, as: :boolean, default: false
end
panel "Email Configuration" do
field :support_email, as: :text,
default: "support@yourapp.com",
required: true
field :from_email, as: :text,
default: "noreply@yourapp.com",
required: true
end
panel "Feature Flags" do
field :enable_registrations, as: :boolean, default: true
field :enable_api_access, as: :boolean, default: false
field :max_file_upload_size, as: :number,
default: 10,
help_text: "Maximum file size in MB"
end
end
def handle
# Store in application configuration or settings model
settings = {
app_name: params[:app_name],
app_url: params[:app_url],
maintenance_mode: params[:maintenance_mode],
support_email: params[:support_email],
from_email: params[:from_email],
enable_registrations: params[:enable_registrations],
enable_api_access: params[:enable_api_access],
max_file_upload_size: params[:max_file_upload_size]
}
# Update application settings (your implementation)
ApplicationSettings.update_all(settings)
# Or store in Rails credentials
# Rails.application.credentials.update(settings)
flash[:success] = {
body: "Application settings updated successfully",
timeout: 5000
}
default_response
end
end
```
### Data Import Form
```ruby
# app/avo/forms/data_import.rb
class Avo::Forms::DataImport < Avo::Forms::Core::Form
self.title = "Import Data"
self.description = "Upload and import data from CSV files"
def fields
main_panel do
field :import_type, as: :select,
options: {
users: "Users",
products: "Products",
orders: "Orders"
},
required: true
field :csv_file, as: :file,
required: true,
help_text: "Select a CSV file to import"
field :skip_header_row, as: :boolean,
default: true,
help_text: "Skip the first row if it contains headers"
end
panel "Import Options" do
field :update_existing, as: :boolean,
default: false,
help_text: "Update existing records if found"
field :send_notification, as: :boolean,
default: true,
help_text: "Send email notification when import completes"
end
end
def handle
import_type = params[:import_type]
csv_file = params[:csv_file]
options = {
skip_header_row: params[:skip_header_row],
update_existing: params[:update_existing]
}
# Process the import
begin
importer = DataImporter.new(import_type, csv_file, options)
result = importer.process
if params[:send_notification]
ImportNotificationMailer.import_completed(current_user, result).deliver_later
end
flash[:success] = {
body: "Import completed: #{result[:imported]} records imported, #{result[:skipped]} skipped",
timeout: 10000
}
rescue => e
flash[:error] = "Import failed: #{e.message}"
end
default_response
end
end
```
## Best Practices
**Keep forms focused**: Each form should handle a specific set of related functionality rather than trying to do everything.
**Use descriptive titles and descriptions**: Help users understand what the form does and what data is expected.
**Organize with panels**: Group related fields together using panels for better user experience.
**Validate input**: Always validate and sanitize form input in your handle method.
**Provide feedback**: Use flash messages to inform users about the results of their actions.
**Handle errors gracefully**: Wrap potentially failing operations in begin/rescue blocks.
**Use default values**: Provide sensible defaults for form fields when possible.
**Consider async processing**: For long-running operations, consider using background jobs and provide appropriate feedback to users.
---
# Guides and Tutorials
This section provides practical guidance and best practices for common scenarios when working with Avo Forms and Pages.
## Form Definition Approaches
When building forms in Avo, there are several approaches for organizing your form code. The recommended approach is to use the default generator approach. But in this guide we'll cover other approach as well.
### Approach 1: Default Generator Approach
Use the generator to create standalone form files in the `app/avo/forms/` directory.
```bash
rails generate avo:form user_profiles
```
This creates:
```ruby
# app/avo/forms/user_profiles.rb
class Avo::Forms::UserProfiles < Avo::Forms::Core::Form
self.title = "User Profiles"
self.description = "Manage your user profiles"
def fields
field :example, as: :text, default: "Hello World"
end
def handle
flash[:success] = { body: "Form submitted successfully", timeout: :forever }
flash[:notice] = params[:example]
default_response
end
end
```
Then reference it in your page:
```ruby
# app/avo/pages/settings/profiles.rb
class Avo::Pages::Settings::Profiles < Avo::Forms::Core::Page
def content
form Avo::Forms::UserProfiles
end
end
```
Or render it in a custom component:
```ruby
<%= render Avo::Forms::UserProfiles.component %>
```
### Approach 2: Inline Form Definitions
You can define forms directly within page classes using the page's namespace.
```ruby
# app/avo/pages/settings/integrations.rb
class Avo::Pages::Settings::Integrations < Avo::Forms::Core::Page
self.title = "Integrations"
self.description = "Manage your integrations"
def content
form ApiConfiguration
end
# Form defined inline within the page class
class ApiConfiguration < Avo::Forms::Core::Form
self.title = "API Configuration"
self.description = "Configure your API settings"
def fields
field :api_key, as: :text, required: true
field :api_endpoint, as: :text
field :webhook_url, as: :text
end
def handle
flash[:success] = "API Configuration updated successfully"
default_response
end
end
end
```
:::warning Namespace Confusion
When defining forms inline within page classes, it's not immediately clear that `Avo::Pages::Settings::Integrations::ApiConfiguration` is a form class rather than page. This can lead to confusion about the class's purpose and make code navigation more difficult. **This strategy is not recommended when you want to reuse the form in other pages or components.**
:::
## When to Use Each Approach
**Approach 1 (Default Generator)**: Good starting point for most forms. Easy to generate and maintain.
**Approach 2 (Inline)**: Best for simple, page-specific forms that won't be reused elsewhere.
## Page Organization Approaches
In addition to form definition approaches, you can also choose how to organize your pages:
### Virtual Pages
Instead of creating separate page files for every form, you can use virtual pages:
```ruby
# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
def navigation
# Virtual page that renders a single form
page form: Avo::Forms::UserProfiles
# Virtual page with multiple forms
page "Integrations",
content: -> do
form Avo::Forms::SlackIntegration
form Avo::Forms::EmailIntegration
end
end
end
```
**Virtual pages are ideal when:**
- You have simple forms that don't need dedicated page files
- You want to group related forms together without file proliferation
- You're building settings or configuration interfaces with many small forms
---
# Mount Avo API
This document explains how to mount and configure the Avo API in your Rails application.
## Overview
The `mount_avo_api` method is a convenient Rails route helper that mounts the Avo API engine into your application's routing system. It provides a RESTful API for all your Avo resources, allowing external applications to interact with your data programmatically.
:::warning IMPORTANT
There is a caveat when mounting the API that requires attention:
If you have `mount_avo` inside an `authenticate` block (like `authenticate :user`), you **must** mount the API outside and before that authentication block.
**Why?** When the API is mounted inside an authentication block, all API endpoints will require the same authentication as your web interface, which breaks API functionality for external clients using API tokens.
**This do not mean that API can't use authentication, check the Authentication page for more information.**
**Correct setup:**
```ruby
# config/routes.rb
Rails.application.routes.draw do
# Mount Avo API FIRST - outside any authentication blocks
mount_avo_api
# Mount Avo web interface with authentication
authenticate :user do
mount_avo
end
end
```
**Incorrect setups:**
```ruby
# config/routes.rb
Rails.application.routes.draw do
# β Don't do this - API will require web authentication
authenticate :user do
mount_avo_api # This breaks API token authentication
mount_avo
end
end
```
Configure collaboration settings for your resource. This hash contains author and watchers configuration.
```ruby{3-21}
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
self.collaboration = {
author: {
current_author: -> { current_user },
name_property: :name,
},
watchers: [
{
property: :name,
message: -> { "This property has been updated #{property}: #{old_value} -> #{new_value}" }
},
{
property: :status,
i18n_message_key: "avo.collaboration.custom_property_changed_html",
},
{
property: :stage,
}
]
}
def fields
# ...
end
end
```
- **`current_author`**: A lambda that returns the current user/author object
- **`name_property`**: The property on the author object that contains their display name
Watchers monitor changes to specific properties and can generate automatic timeline entries when those properties change.
Each watcher can have:
- **`property`**: The property name to watch for changes (required)
- **`message`**: A lambda that generates a custom message when the property changes. Available variables: `property`, `old_value`, `new_value`
- **`i18n_message_key`**: An internationalization key for the message instead of a custom lambda
If neither `message` nor `i18n_message_key` is provided, a default message will be generated.
#### I18n Example
When using `i18n_message_key`, define your translations in your locale files:
```yaml
en:
hello: "Hello world"
avo:
collaboration:
custom_property_changed_html: changed %{property} to %{new_value} [Custom]
```
The message can use interpolation variables like `%{property}`, `%{old_value}`, and `%{new_value}`.
##### Safe HTML Translations
When your translation messages contain HTML markup (as shown in the example above), Rails automatically treats them as safe HTML when the translation key ends with `_html`. This follows Rails' [safe HTML translations](https://guides.rubyonrails.org/i18n.html#using-safe-html-translations) convention, allowing you to include styling and formatting in your collaboration timeline messages without additional escaping.
The `collaboration_timeline` method renders the collaboration timeline component at the specific position where it's defined within your resource's fields.
```ruby{13}
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
self.collaboration = {
# ...
}
def fields
field :id, as: :id
field :name
field :status
field :stage, as: :select, options: ["Not Started", "In Progress", "Completed"]
collaboration_timeline
end
end
```
This DSL method will display the collaboration timeline (showing comments, status updates, and property changes) wherever you place it in your resource definition. You can position it among your other fields to control where the timeline appears in your resource's layout.
## Customizing collaboration models for your business logic
Sometimes, the default collaboration models aren't quite enough for your specific use case. You might want to add custom associations, validations, or callbacks to align with your application's domain logic.
You can safely extend `Avo::Collaboration::Action`, `Avo::Collaboration::Comment`, and `Avo::Collaboration::Entry` in an initializer, similar to how you would extend other Avo provided models:
```ruby{7-86}
# config/initializers/avo.rb
Avo.configure do |config|
# ... other config options ...
end
Rails.configuration.to_prepare do
# For actions generated by watchers (property changes, status updates, etc.)
Avo::Collaboration::Action.class_eval do
after_create :slack_notification
private
def slack_notification
SlackNotificationService.notify(message: "New action created: #{body}")
end
end
# For user-authored comments in the collaboration timeline
Avo::Collaboration::Comment.class_eval do
validates :body, presence: true, length: { maximum: 5000 }
before_validation :sanitize_body
private
def sanitize_body
self.body = HtmlSanitizer.sanitize(body)
end
end
# Wrapper entry that unifies both comments and actions via delegated_type :entryable
Avo::Collaboration::Entry.class_eval do
after_create :discord_notification
private
def discord_notification
DiscordNotificationService.notify(message: "New action created: #{body}")
end
end
end
```
This approach lets you integrate collaboration events with your domain models while keeping the core Avo functionality intact. Add only the associations and callbacks that make sense for your application.
---
# Authorization
Control who can view, create, and manage collaboration timeline entries using Avo's authorization system. The collaboration feature provides specific authorization methods to fine-tune access to different aspects of the collaboration timeline.
## Authorization Methods
Controls whether a user can view the collaboration timeline on a resource.
```ruby{3-6}
# app/policies/project_policy.rb
class ProjectPolicy < ApplicationPolicy
def collaboration_view_timeline?
# Only allow users who can view the record to see the timeline
show?
end
end
```
Controls whether a user can create new timeline entries (write messages and comments).
```ruby{3-6}
# app/policies/project_policy.rb
class ProjectPolicy < ApplicationPolicy
def collaboration_create_entry?
# Only allow team members to create timeline entries
current_user.team_member? && show?
end
end
```
Controls whether a user can destroy timeline entries. The `record` parameter can be either an action entry (automatically generated when watched attributes change) or a message entry (manually created by users).
```ruby{3-10}
# app/policies/project_policy.rb
class ProjectPolicy < ApplicationPolicy
def collaboration_destroy_entry?
# Users can only destroy their own message entries
# Admins can destroy any entry
return true if current_user.admin?
# Only allow destroying message entries, not action entries
record.is_a?(Avo::Collaboration::Comment) && record.author == current_user
end
end
```
---
# Notifications
Avo Notifications is an in-app notification system for your Avo admin panel. It lets you send targeted or global notifications to your admin users, complete with action buttons, severity levels, and optional real-time delivery via ActionCable.
Notifications appear in a bell icon dropdown in the navbar and can also be browsed through a full Avo resource page with scopes, filters, and bulk actions.
## Requirements
- `avo` (core)
- ActionCable (optional, for real-time delivery)
## Installation
:::info
Follow these steps in order. The installer generates migrations, an initializer, and an Avo resource for you.
:::
### 1. Install the gem
Add the following to your `Gemfile`:
```ruby
gem "avo-notifications", source: "https://packager.dev/avo-hq/"
```
Then
```bash
bundle install
```
### 2. Run the installer
```bash
bin/rails generate avo:notifications install
```
This creates:
- A migration for the `avo_notifications` table
- A migration to add `avo_notifications_last_read_at` to your users table
- An initializer at `config/initializers/avo_notifications.rb`
- An Avo resource for managing notifications
### 3. Run migrations
```bash
bin/rails db:migrate
```
### 4. Include the concern in your User model
```ruby
class User < ApplicationRecord
include Avo::Notifications::HasNotifications # [!code ++] [!code focus]
end
```
This adds helper methods for reading notification state on the user (covered in [Reading notifications](#reading-notifications)).
## Configuration
After installation, configure the gem in `config/initializers/avo_notifications.rb`:
```ruby
Avo::Notifications.configure do |config|
# How long notifications are kept before cleanup deletes them
config.ttl = 30.days
# Enable real-time delivery via ActionCable
config.realtime = true
# Max notifications shown in the bell dropdown
config.dropdown_limit = 10
# The model class used for notification recipients
config.user_class = "User"
# Method called on the sender to display their name
config.user_display_name_method = :name
end
```
## Sending notifications
Use `Avo::Notifications.send` (aliased as `Avo::Notifications.notify`) to create and deliver notifications.
### Basic usage
```ruby
Avo::Notifications.send( # [!code focus]
to: user, # [!code focus]
title: "Welcome to the admin panel!", # [!code focus]
body: "You now have access to all features.", # [!code focus]
level: :info # [!code focus]
) # [!code focus]
```
| Parameter | Required | Description |
| ---------- | -------- | ------------------------------------------------------------ |
| `title` | Yes | Notification title (max 255 characters) |
| `to` | No | Recipient user. Omit for a global notification |
| `body` | No | Longer description text |
| `level` | No | Severity: `:info`, `:success`, `:warning`, `:error` (default `:info`) |
| `url` | No | URL to navigate to when the notification title is clicked |
| `sender` | No | The user who sent the notification |
| `buttons` | No | Array of action buttons (max 3) |
### Targeted vs global notifications
**Targeted** notifications are sent to a specific user by passing the `to:` parameter. **Global** notifications omit `to:` and are visible to all admin users.
```ruby
# Targeted β only this user sees it
Avo::Notifications.send(
to: @user,
title: "Your export is ready",
level: :success
)
# Global β all admin users see it
Avo::Notifications.send(
title: "System maintenance tonight at 10 PM",
level: :warning
)
```
### Notification levels
Each notification has a level that controls its icon and color in the UI:
| Level | Icon | Color |
| ---------- | ------------------- | ------ |
| `:info` | Info circle (blue) | Blue |
| `:success` | Check circle (green)| Green |
| `:warning` | Alert triangle | Amber |
| `:error` | Alert circle (red) | Red |
### Adding action buttons
Notifications can include up to 3 action buttons. Each button needs a `label` and `url`, and optionally a `method` (defaults to `"get"`).
```ruby
Avo::Notifications.send(
to: @user,
title: "Project review pending",
level: :info,
buttons: [ # [!code focus]
{ label: "Approve", url: "/projects/#{@project.id}/approve", method: "post" }, # [!code focus]
{ label: "Reject", url: "/projects/#{@project.id}/reject", method: "post" }, # [!code focus]
{ label: "View", url: "/projects/#{@project.id}" } # [!code focus]
] # [!code focus]
)
```
Supported `method` values: `get`, `post`, `patch`, `put`, `delete`.
### From Avo actions
```ruby
class Avo::Actions::ApproveProject < Avo::BaseAction
self.name = "Approve project"
def handle(query:, fields:, current_user:, **args)
query.each do |project|
project.approve!
Avo::Notifications.send( # [!code focus]
to: project.owner, # [!code focus]
title: "Your project was approved", # [!code focus]
body: "#{current_user.name} approved '#{project.name}'.", # [!code focus]
level: :success, # [!code focus]
sender: current_user, # [!code focus]
url: "/admin/projects/#{project.id}" # [!code focus]
) # [!code focus]
end
succeed "#{query.count} project(s) approved."
end
end
```
### From model callbacks
```ruby
class Order < ApplicationRecord
after_update :notify_status_change
private
def notify_status_change
return unless saved_change_to_status?
Avo::Notifications.send( # [!code focus]
to: user, # [!code focus]
title: "Order ##{id} status changed to #{status}", # [!code focus]
level: :info, # [!code focus]
url: "/admin/orders/#{id}" # [!code focus]
) # [!code focus]
end
end
```
### From background jobs
```ruby
class ProcessExportJob < ApplicationJob
def perform(export_id, user_id)
export = Export.find(export_id)
user = User.find(user_id)
export.process!
Avo::Notifications.send( # [!code focus]
to: user, # [!code focus]
title: "Your export is ready", # [!code focus]
body: "#{export.name} has finished processing.", # [!code focus]
level: :success, # [!code focus]
url: export.download_url # [!code focus]
) # [!code focus]
end
end
```
## Reading notifications
### Query methods
```ruby
# Get notifications for a user (targeted + global), newest first
Avo::Notifications.for_user(user, limit: 10)
# Count unread notifications
Avo::Notifications.unread_count(user)
# Mark a single notification as read
Avo::Notifications.mark_as_read(notification, user: current_user)
# Mark all notifications as read for a user
Avo::Notifications.mark_all_as_read(user)
```
### User model methods
After including the `HasNotifications` concern, your User model gains these methods:
```ruby
user.unread_avo_notifications_count
# => 5
user.mark_all_avo_notifications_read!
# Marks all targeted notifications as read and updates avo_notifications_last_read_at
user.avo_notification_unread?(notification)
# => true/false β works for both targeted and global notifications
```
:::info
**How read state works:** Targeted notifications track read state via a `read_at` timestamp on the notification itself. Global notifications are considered "read" if they were created before the user's `avo_notifications_last_read_at` timestamp.
:::
## Bell component
The bell icon automatically appears in your Avo navbar when the gem is installed. It shows:
- A bell icon with an unread count badge (hidden when all notifications are read)
- A dropdown panel with the most recent notifications (limited by `dropdown_limit`)
- A "Mark all as read" link when there are unread notifications
- A "View all notifications" link to the full notification resource
No additional configuration is needed β the component renders automatically for logged-in users.
## Real-time delivery
When `config.realtime = true` (the default), notifications are broadcast via ActionCable using Turbo Streams. The bell dropdown updates automatically without a page refresh.
### How it works
Two ActionCable streams are used:
- **Personal stream** β delivers targeted notifications to the specific recipient
- **Global stream** (`avo_notifications:global`) β delivers global notifications to all connected users
The Stimulus controller `notifications-cable` handles subscribing to both streams and processing incoming Turbo Stream messages.
### ActionCable setup
Make sure ActionCable is configured in your Rails app. A typical `config/cable.yml`:
```yaml
development:
adapter: async
production:
adapter: redis
url: redis://localhost:6379/1
```
:::warning
If ActionCable is not available or not configured, real-time delivery is silently skipped β notifications still work, they just require a page refresh to appear. Broadcasting errors are logged but never raise exceptions.
:::
## Notification resource
The installer generates an Avo resource at `app/avo/resources/avo_notification.rb` that gives you a full management interface for notifications.
### Scopes
- **All** β every notification for the current user
- **Unread** β only unread notifications
- **Read** β only read notifications
### Filter
- **Level** β filter by notification level (info, success, warning, error)
### Bulk actions
- **Mark as read** β marks selected notifications as read
- **Mark as unread** β clears the read state on targeted notifications
- **Delete** β permanently removes selected notifications
:::info
The notification resource has `visible_on_sidebar = false` by default. Notifications are accessed through the bell dropdown's "View all" link. You can change this in the generated resource if you prefer sidebar access.
:::
## Cleanup
Over time, expired notifications accumulate in the database. Use the built-in rake task to clean them up:
```bash
bin/rails avo_notifications:cleanup
```
This deletes all notifications past their expiry date (based on the `expires_at` column, which is set from the `ttl` configuration when a notification is created).
**Recommended:** schedule this as a daily cron job:
```bash
# Daily at 2 AM
0 2 * * * cd /path/to/app && bin/rails avo_notifications:cleanup
```
---
# Media Library
VIDEO
## How to enable it
The Media Library feature is disabled by default (until we release the stable version). To enable it, you need to do the following:
```ruby{4}
# config/initializers/avo.rb
if defined?(Avo::MediaLibrary)
Avo::MediaLibrary.configure do |config|
config.enabled = true
end
end
```
This is the killswitch of the whole feature.
When disabled, the Media Library will not be available to anyone. It will hide the menu item, block the all the routes, and hide media the library icons from the editors.
## Hide menu item
You can hide the menu item from the sidebar by setting the `visible` option to `false`.
```ruby
# config/initializers/avo.rb
if defined?(Avo::MediaLibrary)
Avo::MediaLibrary.configure do |config|
config.visible = false
end
end
```
You may also use a block to conditionally show the menu item. You'll have access to the `Avo::Current` object and you can use it to show the menu item based on the current user.
```ruby
# config/initializers/avo.rb
if defined?(Avo::MediaLibrary)
Avo::MediaLibrary.configure do |config|
config.visible = -> { Avo::Current.user.is_developer? }
end
end
```
This will hide the menu item from the sidebar if the current user is not a developer.
## Add it to the menu editor
The Media Library is a menu item in the sidebar. You can add it to the menu editor by using the `media_library` helper.
```ruby
# config/initializers/avo.rb
Avo.configure do |config|
config.main_menu = lambda {
link_to 'Media Library', avo.media_library_index_path
}
end
```
## Use it with the rich text editors
The Media Library will seamlessly integrate with all the rich text editors.
The `cache_hash` method is used to compute the cache key for each row.
More about this on the resource options page.
## Caching caveats
Avo caches each record on the ? at any time to open the shortcuts reference modal.
## Library
Avo uses [**@github/hotkey**](https://github.com/github/hotkey) under the hood β the same library that powers GitHub's own keyboard shortcuts. It handles multi-key sequences (e.g. `r r r`), modifier chords (e.g. `Mod+Enter`), and fires a `hotkey-fire` DOM event that Avo listens to before triggering the bound element's click.
Hotkeys are attached declaratively via `data-hotkey` attributes on HTML elements:
```html
New post
```
For alternatives (Mac vs. non-Mac), space-separate the variants:
```html
Save
```
The library is initialised once on page load and re-applied on every `turbo:load` and `turbo:frame-render` event so shortcuts survive Turbo navigations.
## Global shortcuts
These shortcuts are always available, regardless of the current page.
| Keys | Action |
| ------------------------------------------------------------ | ------------------------------------------- |
| ? | Open/close the keyboard shortcuts modal |
| Cmd +K / Ctrl +K | Focus the global search |
| Cmd +\\ / Ctrl +\\ | Toggle the sidebar |
| r r r | Reload the page (preserves scroll position) |
| Esc | Close modal / unfocus field |
## Page-level shortcuts
### Index view
| Keys | Action |
| --------------------------- | ------------------------------- |
| / | Focus the resource search input |
| C | Create a new record |
| A | Open the actions menu |
| β / β | Navigate table rows |
| β΅ | Open the focused row |
| Space | Select / deselect row |
| Esc | Unfocus the current selection |
| V T | Switch to table view |
| V G | Switch to grid view |
| V M | Switch to map view |
### Show view
| Keys | Action |
| ------------ | ----------------- |
| B | Go back |
| E | Edit the record |
| D | Delete the record |
### Edit view
| Keys | Action |
| ---------------------------------------------------------- | ------------------------- |
| Cmd +β΅ / Ctrl +β΅ | Save / submit the form |
| Esc | Unfocus the current field |
| B | Go back |
### Action modal
| Keys | Action |
| ---------------------------------------------------------- | ------------------------ |
| Cmd +β΅ / Ctrl +β΅ | Run the action |
| Esc | Cancel / close the modal |
### Confirmation modal
| Keys | Action |
| ----------------------------------- | ------------------------ |
| Esc | Cancel / close the modal |
| Comma + Enter | Run the action |
## Some shortcuts are hidden in association panels
When a resource is rendered **inside an association panel** (i.e. as a `has_many`, `has_one`, or similar relation on another record's show page), certain shortcuts are intentionally suppressed:
- **Create** (C ) β hidden because the index panel is embedded; hitting C on a show page that already has its own create shortcut would be ambiguous. Also the user might have multiple create shortcuts for different has_many associations.
- **Actions** (A ) β hidden for the same reason.
- **Edit** (E ) and **Delete** (D ) β hidden because these controls belong to the _show_ view of a top-level resource, not to an association row.
Think of it as "I am nested" β and nested views never receive conflicting hotkeys.
## Guard: no shortcuts while typing
All shortcut handlers check that the keyboard event did not originate from a focusable input element:
```js
const TYPING_SELECTOR = "input, textarea, select, [contenteditable]";
if (event.target instanceof Element && event.target.closest(TYPING_SELECTOR)) {
return;
}
```
This means users can type freely in search boxes, filters, and form fields without triggering shortcuts.
## Sidebar menu hotkeys
The `avo-menu` DSL supports a `hotkey:` option on any item type, letting users jump directly to a sidebar section from anywhere in the admin panel.
```ruby
# config/initializers/avo.rb
Avo.configure do |config|
config.main_menu = -> {
section "Content", icon: "tabler/outline/files" do
resource :post, hotkey: "g p"
resource :category, hotkey: "g c"
link "Analytics", path: "/avo/analytics", hotkey: "g a"
end
}
end
```
The hotkey string follows `@github/hotkey` syntax β use space-separated keys for sequences.
For `resource` items, the hotkey can also be set on the resource class itself:
```ruby
class Avo::Resources::Post < Avo::BaseResource
self.hotkey = "g p"
end
```
The menu item automatically renders a `` badge next to the label and registers the binding.
## Visual feedback
When a hotkey fires on a button or link, Avo adds a `kbd--called` CSS class to the `` badge for one animation frame β long enough to paint a "cold press" visual β before triggering the navigation. This gives users tactile confirmation that the shortcut was recognised.
The class is cleaned up on the next `turbo:load` event.
---
# `Avo::Current`
`Avo::Current` is based on the `Current` pattern Rails exposes using [`ActiveSupport/CurrentAttributes`](https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html).
On each request Avo will set some values on it.
This is what will be returned by the `current_user_method` that you've set in your initializer.
Equivalent of `request.params`.
The Rails `request`.
The `context` that you configured in your initializer evaluated in `Avo::ApplicationController`.
An instance of [`ActionView::Rendering`](https://api.rubyonrails.org/classes/ActionView/Rendering.html#method-i-view_context) off of which you can run any methods or variables that are available in your partials.
```ruby
view_context.link_to "Avo", "https://avohq.io"
```
The `locale` of the app.
You can set the `tenant_id` for the current request.
You can set the `tenant` for the current request.
**Related:**
- Multitenancy
---
# Execution context
Avo enables developers to hook into different points of the application lifecycle using blocks.
That functionality can't always be performed in void but requires some pieces of state to set up some context.
Computed fields are one example.
```ruby
field :full_name, as: :text do
"#{record.first_name} #{record.last_name}"
end
```
In that block we need to pass the `record` so you can compile that value. We send more information than just the `record`, we pass on the `resource`, `view`, `view_context`, `request`, `current_user` and more depending on the block that's being run.
## How does the `ExecutionContext` work?
The `ExecutionContext` is an object that holds some pieces of state on which we execute a lambda function.
```ruby
module Avo
class ExecutionContext
attr_accessor :target, :context, :params, :view_context, :current_user, :request
def initialize(**args)
# If target don't respond to call, handle will return target
# In that case we don't need to initialize the others attr_accessors
return unless (@target = args[:target]).respond_to? :call
args.except(:target).each do |key,value|
singleton_class.class_eval { attr_accessor "#{key}" }
instance_variable_set("@#{key}", value)
end
# Set defaults on not initialized accessors
@context ||= Avo::Current.context
@params ||= Avo::Current.params
@view_context ||= Avo::Current.view_context
@current_user ||= Avo::Current.current_user
@request ||= Avo::Current.request
end
delegate :authorize, to: Avo::Services::AuthorizationService
# Return target if target is not callable, otherwise, execute target on this instance context
def handle
target.respond_to?(:call) ? instance_exec(&target) : target
end
end
end
# Use it like so.
SOME_BLOCK = -> {
"#{record.first_name} #{record.last_name}"
}
Avo::ExecutionContext.new(target: &SOME_BLOCK, record: User.first).handle
```
This means you could throw any type of object at it and it it responds to a `call` method wil will be called with all those objects.
## Common objects
The block you'll pass to be evaluated. It may be anything but will only be evaluated if it responds to a `call` method.
Aliased to `Avo::Current.context`.
Aliased to `Avo::Current.user`.
Aliased to `Avo::Current.view_context`.
Aliased to `Avo::Current.request`.
Aliased to `Avo::Current.params`.
You can pass any variable to the `ExecutionContext` and it will be available in that block.
This is how we can expose `view`, `record`, and `resource` in the computed field example.
```ruby
Avo::ExecutionContext.new(target: &SOME_BLOCK, record: User.first, view: :index, resource: resource).handle
```
Within the `ExecutionContext` you might want to use some of your already defined helpers. You can do that using the `helpers` object.
```ruby
# products_helper.rb
class ProductsHelper
# Strips the "CODE_" prefix from the name
def simple_name(name)
name.gsub "CODE_", ""
end
end
field :name, as: :text, format_using: -> { helpers.simple_name(value) }
```
---
# Execution context
[`Avo::Services::EncryptionService`](https://github.com/avo-hq/avo/blob/main/lib/avo/services/encryption_service.rb) it's used internally by Avo when is needed to encrypt sensible params.
One example is the select all feature, where we pass the query, encrypted, through params.
## How does the [`Avo::Services::EncryptionService`](https://github.com/avo-hq/avo/blob/main/lib/avo/services/encryption_service.rb) work?
The `EncryptionService` is an service that can be called anywhere on the app.
### Public methods
Used to encrypt data
Used to decrypt data
Object to be encrypted
A symbol with the purpose of encryption, can be anything, it just ***need to match when decrypting***.
```
## Secret key base
:::warning
[`Avo::Services::EncryptionService`](https://github.com/avo-hq/avo/blob/main/lib/avo/services/encryption_service.rb) fetches a secret key base to be used on the encrypt / decrypt process. Make sure that you have it defined in any of the following:
`ENV["SECRET_KEY_BASE"] || Rails.application.credentials.secret_key_base || Rails.application.secrets.secret_key_base`
:::
---
# Select All
The "Select All" feature is designed to enable users to select all queried records and perform actions on the entire selection. This feature is particularly useful when dealing with large datasets, allowing users to trigger actions on all queried records, not just the ones visible on the current page.
## How does it work?
Product information
Style: shiny
<% end %>
<% end %>
```
The name of the panel. It's displayed on the top under the breadcrumbs.
#### Type
`String`
Small text under the name that speaks a bit about what the panel does.
#### Type
`String`
A list of classes that should be applied to the panel container.
#### Type
`String`
A list of classes that should be applied to the body of panel.
#### Type
`String`
A hash of data attributes to be forwarded to the panel container.
#### Type
`Hash`
Toggles the breadcrumbs visibility. You can't customize the breadcrumbs yet.
#### Type
`Boolean`
## Slots
The component has a few slots where you customize the content in certain areas.
We created this slot as a place to put resource controls like the back, edit, delete, and detach buttons.
This slot will collapse under the title and description when the screen resolution falls under `1024px`.
The section is automatically aligned to the right using `justify-end` class.
```erb
<%= render Avo::PanelComponent.new(name: "Dashboard") do |c| %>
<% c.with_tools do %>
<%= a_link('/admin', icon: 'heroicons/solid/academic-cap', style: :primary) do %>
Admin
<% end %>
<% end %>
<% end %>
```
This is one of the main slots of the component where the bulk of the content is displayed.
```erb{2-4}
<%= render Avo::PanelComponent.new do |c| %>
<% c.with_body do %>
Something here.
<% end %>
<% end %>
```
Used when displaying the Grid view, it displays the data flush in the container and with no background.
```erb{2-4}
<%= render Avo::PanelComponent.new do |c| %>
<% c.with_bare_content do %>
Something here.
<% end %>
<% end %>
```
This is pretty much the same slot as `tools` but rendered under the `body` or `bare_content` slots.
```erb{2-4}
<%= render Avo::PanelComponent.new do |c| %>
<% c.with_footer_controls do %>
Something here.
<% end %>
<% end %>
```
The lowest available area at the end of the component.
```erb{2-4}
<%= render Avo::PanelComponent.new do |c| %>
<% c.with_footer do %>
Something here.
<% end %>
<% end %>
```
The sidebar will conveniently show things in a smaller area on the right of the `body`.
```erb{2-4}
<%= render Avo::PanelComponent.new do |c| %>
<% c.with_Sidebar do %>
Something tiny here.
<% end %>
<% end %>
```
---
# Native field components
One of the most important features of Avo is the ability to extend it pass the DSL. It's very important to us to enable you to add the features you need and create the best experience for your users.
That's why you can so easily create custom fields, resource tools, and custom tools altogether. When you need to augment the UI even more you can use your custom CSS and JS assets too.
When you start adding those custom views you might want to add your own fields, and you'd like to make them look like the rest of the app.
That's why Avo provides a way to use those fields beyond the DSL, in your own custom Rails partials.
## Declaring fields
When you generate a new resource tool you get access to the resource partial.
:::details Sample resource tool
```erb
<%= render Avo::PanelComponent.new title: "Post info" do |c| %>
<% c.with_tools do %>
<%= a_link('/avo', icon: 'heroicons/solid/academic-cap', style: :primary) do %>
Dummy link
<% end %>
<% end %>
<% c.with_body do %>
πͺ§ This partial is waiting to be updated
You can edit this file here app/views/avo/resource_tools/post_info.html.erb.
The resource tool configuration file should be here app/avo/resource_tools/post_info.rb.
<%
# In this partial, you have access to the following variables:
# tool
# @resource
# @resource.model
# form (on create & edit pages. please check for presence first)
# params
# Avo::Current.context
# current_user
%>
<% end %>
<% end %>
This option renders a dash `β` if the content inside responds to true on the `blank?` method.
In the example below, we'd like to show the field as a red checkmark even if the content is `nil`.
#### Default
`true`
```erb
<%= index_field_wrapper **field_wrapper_args, dash_if_blank: false do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
Wraps the content in a container with `flex items-center justify-center` classes making everything centered horizontally and vertically.
#### Default
`false`
```erb
<%= index_field_wrapper **field_wrapper_args, center_content: true do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
Removes the padding around the field allowing it to flow from edge to edge.
#### Default
`false`
```erb
<%= index_field_wrapper **field_wrapper_args, flush: false do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
The instance of the field. It's usually passed in with the `field_wrapper_args`.
```erb
<%= index_field_wrapper **field_wrapper_args do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
The instance of the resource. It's usually passed in with the `field_wrapper_args`.
```erb
<%= index_field_wrapper **field_wrapper_args do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
# Show & Edit field wrapper
This option renders a dash `β` if the content inside responds to true on the `blank?` method.
In the example below, we'd like to show the field as a red checkmark even if the content is `nil`.
#### Default
`true`
```erb
<%= field_wrapper **field_wrapper_args, dash_if_blank: false do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
This renders the field in a more compact way by removing the **Extra** area and decresing the width of the **Label** and **Content** areas.
This is enabled on the fields displayed in actions.
#### Default
`false`
```erb
<%= field_wrapper **field_wrapper_args, compact: true do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
Pass in some data attributes. Perhaps you would like to attach a StimulusJS controller to this field.
```erb
<%= field_wrapper **field_wrapper_args, data: {controller: "boolean-check"} do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
This removes the **Extra** area and renders the **Value** area full width.
This is used on fields that require a larger area to be displayed like WYSIWYG editors, `KeyValue`, or file fields.
#### Default
`false`
```erb
<%= field_wrapper **field_wrapper_args, full_width: true do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
The instance of the form that is going to be populated. It's usually passed in with the `field_wrapper_args` on the
The instance of the field. It's usually passed in with the `field_wrapper_args`.
```erb
<%= field_wrapper **field_wrapper_args do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
The text that is going to be displayed below the actual field on the
The text that is going to be displayed in the **Label** area. You might want to override it.
```erb
<%= field_wrapper **field_wrapper_args, label: "Post is published" do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
The instance of the resource. It's usually passed in with the `field_wrapper_args`.
```erb
<%= field_wrapper **field_wrapper_args do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
Display the field in a column layout with the label on top of the value
```erb
<%= field_wrapper **field_wrapper_args, style: "background: red" do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
The you might want to pass some styles to the wrapper to change it's looks.
```erb
<%= field_wrapper **field_wrapper_args, style: "background: red" do %>
<%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
The view where the field is diplayed so it knows if it's a
---
# `Avo::ApplicationController`
## On extending the `ApplicationController`
You may sometimes want to add functionality to Avo's `ApplicationController`. That functionality may be setting attributes to `Current` or multi-tenancy scenarios.
When you need to do that, you may feel the need to override it with your own version. That means you go into the source code, find `AVO_REPO/app/controllers/avo/application_controller.rb`, copy the whole thing into your own `YOUR_APP/app/controllers/avo/application_controller.rb` file inside your app, and add your own piece of functionality.
```ruby{10,14-16}
# Copied from Avo to `app/controllers/avo/application_controller.rb`
module Avo
class ApplicationController < ::ActionController::Base
include Pagy::Method
include Avo::ApplicationHelper
include Avo::UrlHelpers
protect_from_forgery with: :exception
around_action :set_avo_locale
before_action :multitenancy_detector
# ... more Avo::ApplicationController methods
def multitenancy_detector
# your logic here
end
end
end
```
That will work just fine until the next time we update it. After that, we might add a method, remove one, change the before/after actions, update the helpers and do much more to it.
**That will definitely break your app the next time when you upgrade Avo**. Avo's private controllers are still considered private APIs that may change at any point. These changes will not appear in the changelog or the upgrade guide.
## Responsibly extending the `ApplicationController`
There is a right way of approaching this scenario using Ruby modules or concerns.
First, you create a concern with your business logic; then you include it in the parent `Avo::ApplicationController` like so:
```ruby{6-8,11-13,18}
# app/controllers/concerns/multitenancy.rb
module Multitenancy
extend ActiveSupport::Concern
included do
before_action :multitenancy_detector
# or
prepend_before_action :multitenancy_detector
end
def multitenancy_detector
# your logic here
end
end
# configuration/initializers/avo.rb
Rails.configuration.to_prepare do
Avo::ApplicationController.include Multitenancy
end
```
With this technique, the `multitenancy_detector` method and its `before_action` will be included safely in `Avo::ApplicationController`.
:::info
If you'd like to add a `before_action` before all of Avo's before actions, use `prepend_before_action` instead. That will run that code first and enable you to set an account or do something early on.
:::
## Override `ApplicationController` methods
Sometimes you don't want to add methods but want to override the current ones.
For example, you might want to take control of the `Avo::ApplicationController.fill_record` method and add your own behavior.
TO do that you should change a few things in the approach we mentioned above. First we want to `prepend` the concern instead of `include` it and next, if we want to run a class method, we used `prepended` instead of `included`.
```ruby{5-8,10-12,14-17,23}
# app/controllers/concerns/application_controller_overrides.rb
module ApplicationControllerOverrides
extend ActiveSupport::Concern
# we use the `prepended` block instead of `included`
prepended do
before_action :some_hook
end
def some_hook
# your logic here
end
def fill_record
# do some logic here
super
end
end
# configuration/initializers/avo.rb
Rails.configuration.to_prepare do
# we will prepend instead of include
Avo::ApplicationController.prepend ApplicationControllerOverrides
end
```
**Related:**
- Multitenancy
---
# Asset manager
In your plugins or custom content you might want to add a new stylesheet or javascript file to be loaded inside Avo.
You can manually add them to the `_head.html.erb` or `_pre_head.html.erb` files or you can use the `AssetManager`.
Next, the asset manager will add them to the `` element of Avo's layout file.
## Add a stylesheet file
Use `Avo.asset_manager.add_stylesheet PATH`
Example:
```ruby
Avo.asset_manager.add_stylesheet "/public/magic_file.css"
Avo.asset_manager.add_stylesheet Avo::Engine.root.join("app", "assets", "stylesheets", "magic_file.css")
```
## Add a javascript file
Use `Avo.asset_manager.add_javascript PATH`
Example:
```ruby
Avo.asset_manager.add_javascript "/public/magic_file.js"
Avo.asset_manager.add_javascript Avo::Engine.root.join("app", "javascripts", "magic_file.js")
```
---
# Plugins
:::warning
This feature is in beta and we might change the API as we develop it.
These docs are in beta too, so please [ask for more information](https://github.com/avo-hq/avo/discussions) when you need it.
:::
## Overview
Plugins are a way to extend the functionality of Avo.
### Light layer
We are in the early days of the plugin system and we're still figuring out the best way to do it. This is why we have a light layer that you can use to extend the functionality of Avo.
This means we provide two hooks that you can use to extend the functionality of the Rails app, and a few Avo APIs to add scrips and stylesheets.
## Register the plugin
The way we do it is through an initializer. We mostly use the `engine.rb` file to register the plugin.
```ruby{8-15}
# lib/avo/feed_view/engine.rb
module Avo
module FeedView
class Engine < ::Rails::Engine
isolate_namespace Avo::FeedView
initializer "avo-feed-view.init" do
# Avo will run this hook on boot time
ActiveSupport.on_load(:avo_boot) do
# Register the plugin
Avo.plugin_manager.register :feed_view
# Register the mounting point
Avo.plugin_manager.mount_engine Avo::FeedView::Engine, at: "/feed_view"
end
end
end
end
end
```
This will add the plugin to a list of plugins which Avo will run the hooks on.
## Hook into Avo
```ruby
module Avo
module FeedView
class Engine < ::Rails::Engine
isolate_namespace Avo::FeedView
initializer "avo-feed-view.init" do
ActiveSupport.on_load(:avo_boot) do
Avo.plugin_manager.register :feed_view
# Add some concerns
Avo::Resources::Base.include Avo::FeedView::Concerns::FeedViewConcern
# Remove some concerns
Avo::Resources::Base.included_modules.delete(Avo::Concerns::SOME_CONCERN)
# Add asset files to be loaded by Avo
# These assets will be added to Avo's `application.html.erb` layout file
Avo.asset_manager.add_javascript "/avo-advanced-assets/avo_advanced"
Avo.asset_manager.add_stylesheet "/avo-kanban-assets/avo_kanban"
end
ActiveSupport.on_load(:avo_init) do
# Run some code on each request
Avo::FeedView::Current.something = VALUE
end
end
end
end
end
```
## Hooks
The `avo_boot` hook is called when the parent Rails application boots up. This is where you can register your scripts and stylesheets and also add your functionality to Avo.
We use it heavily to add our own concerns to the `Avo::BaseResource` and `Avo::BaseController` classes and even extend the `Avo::ApplicationController` class.
The `avo_init` hook is called on every request done inside Avo. You can use this hook to attach some code to the `Avo::App.context` object or do other things.
:::info
We don't use it as much in our plugins as we do in the `avo_boot` hook.
:::
## Avo `AssetManager`
We use the `AssetManager` to add our own asset files (JavaScript and CSS) to be loaded by Avo. They will be added in the `` section of Avo's layout file.
It has two methods:
```ruby
Avo.asset_manager.add_javascript "/avo-kanban-assets/avo_kanban"
```
This snippet will add the `/avo-kanban-assets/avo_kanban.js` file to the `` section of Avo's layout file.
```ruby
Avo.asset_manager.add_stylesheet "/avo-kanban-assets/avo_kanban"
```
This snippet will add the `/avo-kanban-assets/avo_kanban.css` file to the `` section of Avo's layout file.
## Using a middleware to surface asset files
One tricky thing to do with Rails Engines is to expose some asset files to the parent Rails app.
The way we do it is by using a middleware that will serve the files from the Engine's `app/assets/builds` directory.
So `app/assets/builds/feed_view.js` from the `feed_view` engine will be served by the parent Rails app at `/feed-view-assets/feed_view.js` with the following middleware added to your `engine.rb` file.
```ruby
module Avo
module FeedView
class Engine < ::Rails::Engine
isolate_namespace Avo::FeedView
initializer "avo-feed-view.init" do
ActiveSupport.on_load(:avo_boot) do
Avo.plugin_manager.register :feed_view
end
end
config.app_middleware.use(
Rack::Static,
urls: ["/feed-view-assets"], # π This is the path where the files will be served
root: root.join("app", "assets", "builds") # π This is the path where the files are located
)
end
end
end
```
:::info
Avo doesn't compile the assets in any way, but just adds them to the layout file. This means that the assets should be compiled and ready for the browser to use them.
We use [`jsbundling-rails`](https://github.com/rails/jsbundling-rails) with `esbuild` to compile the assets before packaging them in the `gem` file.
Please check out [the scripts](https://github.com/avo-hq/avo/blob/main/package.json) we use.
:::
## Create your own plugin
We don't yet have a generator for that but what we do is to create a new Rails Engine and add the plugin to it.
1. Run `rails plugin new feed-view`
1. Add the plugin to the `engine.rb` file
1. Register the plugin to the `lib/avo/feed_view/engine.rb` file
1. Optionally add assets
1. Add the plugin to your app's `Gemfile` using the `path` option to test it out
---
# Custom view types
Avo ships with three built-in view types for the resource index: **table**, **grid**, and **map**. You can restrict which ones are available per-resource, or create entirely new view types through plugins.
## Restricting available view types
By default, Avo displays all the configured view types on the view switcher. For example, if you have `map_view` and `grid_view` configured, both of them, along with the `table_view`, will be available on the view switcher.
However, there might be cases where you only want to make a specific view type available without removing the configurations for other view types. This can be achieved using the `view_types` class attribute on the resource. Note that when only one view type is available, the view switcher will not be displayed.
```ruby{3}
class Avo::Resources::City < Avo::BaseResource
# ...
self.view_types = :table
#...
end
```
If you want to make multiple view types available, you can use an array. The icons on the view switcher will follow the order in which they are declared in the configuration.
```ruby{3}
class Avo::Resources::City < Avo::BaseResource
# ...
self.view_types = [:table, :grid]
#...
end
```
You can also dynamically restrict the view types based on user roles, params, or other business logic. To do this, assign a block to the `view_types` attribute. Within the block, you'll have access to `resource`, `record`, `params`, `current_user`, and other default accessors provided by `ExecutionContext`.
```ruby{3-9}
class Avo::Resources::City < Avo::BaseResource
# ...
self.view_types = -> do
if current_user.is_admin?
[:table, :grid]
else
:table
end
end
#...
end
```
## Creating a custom view type through a plugin
You can register entirely new view types from a Rails Engine (Avo plugin). The view type will appear in the view switcher alongside the built-in ones and can be set as the default for any resource.
The process has three parts: **create the component**, **register the view type**, and **configure a resource to use it**.
### 1. Create the view type component
Every view type is a ViewComponent that inherits from `Avo::ViewTypes::BaseViewTypeComponent`. The base class provides these props automatically:
| Prop | Description |
| ----------------- | ------------------------------------------------------------- |
| `resources` | Array of Avo resource wrappers (call `.record` for the model) |
| `resource` | The Avo resource class |
| `pagy` | Pagination object |
| `query` | The current query |
| `turbo_frame` | The Turbo Frame ID |
| `index_params` | Current index parameters |
| `reflection` | Association reflection (if nested) |
| `parent_record` | Parent record (if nested) |
| `parent_resource` | Parent resource (if nested) |
| `actions` | Available actions |
Create your component class inside your engine's namespace:
```ruby
# app/components/my_plugin/view_types/timeline_view_type_component.rb
class MyPlugin::ViewTypes::TimelineViewTypeComponent < Avo::ViewTypes::BaseViewTypeComponent # [!code focus]
def grouped_resources
@resources.group_by { |r| r.record.created_at.to_date }
end
def empty?
@resources.blank?
end
end
```
Then create the template. You have full control over the HTML β render items however you like and include the paginator at the bottom:
```erb
<%# app/components/my_plugin/view_types/timeline_view_type_component.html.erb %>
<% if empty? %>
No records found.
<% else %>
<% grouped_resources.each do |date, resources| %>
<%= date.strftime("%B %d, %Y") %>
<% resources.each do |resource| %>
<%= resource.record.title %>
<% end %>
<% end %>
<% end %>
" \
"#{scoped_query.count}" \
" "
)
}
self.description = -> { "All the scheduled jobs." }
self.scope = -> { query.finished.invert_where }
self.visible = -> { true }
end
```
In this example we made the `name` option a callable block and are returning the name of the scope and a `span` with the count of the records.
We are also using the `sanitize` method to return it as HTML.
In order to make the counter stand out, we're using some Tailwind CSS classes that we have available in Avo. If you're trying different classes and they are not applying, you should consider adding the Tailwind CSS integration.
:::warning
This approach will have some performance implications as it will run the `count` query on every page load.
:::
---
# Export to CSV action
Even if we don't have a dedicated export to CSV feature, you may create an action that will take all the selected records and export a CSV file for you.
Below you have an example which you can take and customize to your liking. It even give you the ability to use custom user-selected attributes.
```ruby
# app/avo/actions/export_csv.rb
class Avo::Actions::ExportCsv < Avo::BaseAction
self.name = "Export CSV"
self.confirmation = true
self.standalone = true
def fields
# Add more fields here for custom user-selected columns
field :id, as: :boolean
field :created_at, as: :boolean
end
def handle(records:, fields:, resource:, **args)
# uncomment if you want to download all the records if none was selected
# records = resource.model_class.all if records.blank?
return error "No record selected" if records.blank?
# uncomment to get all the models' attributes.
# attributes = get_attributes_from_record records.first
# uncomment to get some attributes
# attributes = get_some_attributes
attributes = get_attributes_from_fields fields
# uncomment to get all the models' attributes if none were selected
# attributes = get_attributes_from_record records.first if attributes.blank?
file = CSV.generate(headers: true) do |csv|
csv << attributes
records.each do |record|
csv << attributes.map do |attr|
record.send(attr)
end
end
end
download file, "#{resource.plural_name}.csv"
end
def get_attributes_from_record(record)
record.class.columns_hash.keys
end
def get_attributes_from_fields(fields)
fields.select { |key, value| value }.keys
end
def get_some_attributes
["id", "created_at"]
end
end
```
data-controller="toggle-panel" <% end %>>
<% if _current_user.respond_to?(:avatar) && _current_user.avatar.present? %>
<%= image_tag _current_user.avatar, class: "h-12 rounded-full border-4 border-white mr-1" %>
<% end %>
<% if _current_user.respond_to?(:name) && _current_user.name.present? %>
<%= _current_user.name %>
<% elsif _current_user.respond_to?(:email) && _current_user.email.present? %>
<%= _current_user.email %>
<% else %>
Avo user
<% end %>
<% if main_app.respond_to?(destroy_user_session_path) %>
<%= svg 'chevron-down', class: "ml-1 h-4" %>
<% end %>
<% if main_app.respond_to?(destroy_user_session_path) %>
<% classes = "appearance-none bg-white text-left cursor-pointer text-green-600 font-semibold hover:text-white hover:bg-green-500 block px-4 py-1 w-full" %>
<% if I18n.locale == :en %>
<%= link_to "Switch to Portuguese", { set_locale: 'pt-BR' }, class: classes %>
<% else %>
<%= link_to "Switch to English", { set_locale: 'en' }, class: classes %>
<% end %>
<%= button_to t('avo.sign_out'), main_app.send(:destroy_user_session_path), method: :delete, form: { "data-turbo" => "false" }, class: classes %>
<% end %>
<%= avo_edit_field :body, as: :trix, form: f, help: "What should the review say", required: true %>
<%= avo_edit_field :user, as: :belongs_to, form: f, help: "Who created the review", required: true %>
<% end %>
<% end %>
```
### 6. Update the resource tool partial
It's time to put it all together. In the resource tool partial we're wrapping the whole thing with the `nested-form` controller div, creating a new `form` helper to reference the nested fields with `form.fields_for` and wrapping the "new" template so we can use replicate it using the `nested-form` package.
In the footer we'll also add the button that will add new reviews on the page.
```erb
<%= content_tag :div,data: { controller: 'nested-form', nested_form_wrapper_selector_value: '.nested-form-wrapper' } do %>
<%= render Avo::PanelComponent.new(name: "Reviews", description: "Create some reviews for this fish") do |c| %>
<% c.with_bare_content do %>
<% if form.present? %>
<%= form.fields_for :reviews, Review.new, multiple: true, child_index: 'NEW_RECORD' do |todo_fields| %>
<%= render "avo/partials/fish_review", f: todo_fields %>
<% end %>
<%= form.fields_for :reviews, Review.new, multiple: true do |todo_fields| %>
<%= render "avo/partials/fish_review", f: todo_fields %>
<% end %>
<% end %>
<% end %>
<% c.with_footer_tools do %>
<%= a_link 'javascript:void(0);', icon: 'plus', color: :primary, style: :outline, data: {action: "click->nested-form#add"} do %>
Add another review
<% end %>
<% end %>
<% end %>
<% end %>
Add Avo::Views::ResourceCustomIndexComponent template here
```
```rb
# test/components/avo/views/resource_custom_index_component_test.rb
# frozen_string_literal: true
require "test_helper"
class Avo::Views::ResourceCustomIndexeComponentTest < ViewComponent::TestCase
def test_component_renders_something_useful
# assert_equal(
# %(Hello, components! ),
# render_inline(Avo::Views::ResourceCustomIndexeComponent.new(message: "Hello, components!")).css("span").to_html
# )
end
end
```
:::tip
You can delete the generated test file `test/components/avo/views/resource_custom_index_component_test.rb` since we won't cover testing in this guide.
:::
## Use the custom component in a resource
Let's apply the new component to a specific resource. I'll use the `Movie` resource as an example.
Update the resource file (`Avo::Resources::Movie`) to use the new component via the `self.components` configuration:
```ruby
# app/avo/resources/movie.rb
class Avo::Resources::Movie < Avo::Resources::ArrayResource
self.components = { # [!code ++]
"Avo::Views::ResourceIndexComponent": Avo::Views::ResourceCustomIndexComponent # [!code ++]
} # [!code ++]
# ...
end
```
Now when you visit the Movies resource page, it will render the custom component, currently just showing the placeholder text.
Add Avo::Views::ResourceCustomIndexComponent template here
MovieFest 2025 β’ Discover what\'s trending this season in cinema πΏ
<%= render Avo::Views::ResourceIndexComponent.new(**@kwargs) %>
```
Now when you visit the Movies resource page, it will render the custom component that shows the original component and your custom message on top. πππ
<% if @index_message.present? %>
MovieFest 2025 β’ Discover what\'s trending this season in cinema πΏ
<%= @index_message %>
<% end %>
<%= render Avo::Views::ResourceIndexComponent.new(**@kwargs) %>
MovieFest 2025 β’ Discover what\'s trending this season in cinema πΏ'.html_safe # [!code ++]
end # [!code ++]
# ...
end
```
---
### Wrapping up
Adding contextual messages to index pages can go a long way in making your internal tool more helpful. With this approach, you've learned how to:
- Extend Avo's default index view component
- Add custom UI above the resource index table
- Apply the enhancement globally across all resources
- Keep it flexible using a simple per-resource DSL
This solution is modular, declarative, and easy to maintain. You can now provide dynamic guidance to your users where it makes the most sense.
The beauty of this approach is that it safely overrides and customizes the resource index component without requiring you to maintain the original index component on each version update. While we've focused on adding a message at the top, this pattern opens horizons for extending the index component in any direction, whether adding elements at the bottom, on the sides, or anywhere else your application needs. You get the flexibility of customization while continuing to benefit from Avo's ongoing improvements to the core components.
---
# Display counter indicator on tabs switcher
When a tab contains an association field you may want to show some counter indicator about how many records are on that particular tab. You can include that information inside tab's name.
" \
"#{counter}" \
" "
)
end
end
```
We are also using the `sanitize` method to return it as HTML.
In order to make the counter stand out, we're using some Tailwind CSS classes that we have available in Avo. If you're trying different classes and they are not applying, you should consider adding the Tailwind CSS integration.
:::warning
This approach will have some performance implications as it will run the `count` query on every page load.
:::
---
# Use markdown for help attributes
:::info User contribution
Recipe [contributed](https://github.com/avo-hq/avo/issues/1390#issuecomment-1302553590) by [dhnaranjo](https://github.com/dhnaranjo).
:::
Desmond needed a way to write markdown in the help field and built an HTML to Markdown compiler.
```ruby
module MarkdownHelpText
class Renderer < Redcarpet::Render::HTML
def header(text, level)
case level
when 1 then %(#{text} )
when 2 then %(#{text})
else
%(#{text} )
end
end
def paragraph(text)
%( #{text}
)
end
def block_code(code, language)
<<~HTML
#{code.chomp}
HTML
end
def codespan(code)
%(#{code})
end
def list(contents, list_type)
list_style = case list_type
when "ul" then "list-disc"
when "ol" then "list-decimal"
else "list-none"
end
%(<#{list_type} class="ml-8 mb-2 #{list_style}">#{contents})
end
end
def markdown_help(content, renderer: Renderer)
markdown = Redcarpet::Markdown.new(
renderer.new,
filter_html: false,
escape_html: false,
autolink: true,
fenced_code_blocks: true
).render(content)
%()
end
end
```
```ruby
field :description_copy, as: :markdown,
help: markdown_help(<<~MARKDOWN
# Dog
## Cat
### bird
paragraph about hats **bold hat**
~~~
class Ham
def wow
puts "wow"
end
end
~~~
`code thinger`
- one
- two
- three
MARKDOWN
)
```
`. That's because the compute field executes that method in a scope that's different from your application controller, thus not having that method present.
## The solution
The fix is to include the helper module in the `BaseField` and we can do that using this snippet somewhere in the app (you can add it in `config/initializers/avo.rb`).
```ruby
# config/initializers/avo.rb
Avo.configure do |config|
# Usual Avo config
end
module FieldExtensions
# Include a specific helper
include PostsHelper
end
Rails.configuration.to_prepare do
Avo::Fields::BaseField.include FieldExtensions
end
```
Or you can go wild and include all helpers programatically.
```ruby
# config/initializers/avo.rb
Avo.configure do |config|
# Usual Avo config
end
module FieldExtensions
# Include all helpers
helper_names = ActionController::Base.all_helpers_from_path Rails.root.join("app", "helpers")
helpers = ActionController::Base.modules_for_helpers helper_names
helpers.each do |helper|
send(:include, helper)
end
end
Rails.configuration.to_prepare do
Avo::Fields::BaseField.include FieldExtensions
end
```
Now you can reference all helpers in your `Resource` files.
---
## Generation Information
- **Generated at:** 2026-05-13T21:32:08.974Z
- **Total sections:** 167
### Source Files
- docs/4.0/index.md
- docs/4.0/technical-support.md
- docs/4.0/best-practices.md
- docs/4.0/agentic-engineering.md
- docs/4.0/installation.md
- docs/4.0/gem-server-authentication.md
- docs/4.0/license-troubleshooting.md
- docs/4.0/authentication.md
- docs/4.0/authorization.md
- docs/4.0/resources.md
- docs/4.0/array-resources.md
- docs/4.0/http-resources.md
- docs/4.0/record-previews.md
- docs/4.0/scopes.md
- docs/4.0/records-reordering.md
- docs/4.0/discreet-information.md
- docs/4.0/customizable-controls.md
- docs/4.0/avatar.md
- docs/4.0/cover.md
- docs/4.0/views.md
- docs/4.0/table-view.md
- docs/4.0/grid-view.md
- docs/4.0/map-view.md
- docs/4.0/controllers.md
- docs/4.0/breadcrumbs.md
- docs/4.0/fields.md
- docs/4.0/field-options.md
- docs/4.0/field-discovery.md
- docs/4.0/resource-header.md
- docs/4.0/resource-panels.md
- docs/4.0/resource-sidebar.md
- docs/4.0/tabs.md
- docs/4.0/fields/array.md
- docs/4.0/fields/avatar.md
- docs/4.0/fields/badge.md
- docs/4.0/fields/boolean.md
- docs/4.0/fields/boolean_group.md
- docs/4.0/fields/code.md
- docs/4.0/fields/country.md
- docs/4.0/fields/date.md
- docs/4.0/fields/date_time.md
- docs/4.0/fields/easy_mde.md
- docs/4.0/fields/external_image.md
- docs/4.0/fields/file.md
- docs/4.0/fields/files.md
- docs/4.0/fields/gravatar.md
- docs/4.0/fields/heading.md
- docs/4.0/fields/hidden.md
- docs/4.0/fields/id.md
- docs/4.0/fields/key_value.md
- docs/4.0/fields/location.md
- docs/4.0/fields/markdown.md
- docs/4.0/fields/money.md
- docs/4.0/fields/number.md
- docs/4.0/fields/password.md
- docs/4.0/fields/preview.md
- docs/4.0/fields/progress_bar.md
- docs/4.0/fields/radio.md
- docs/4.0/fields/record_link.md
- docs/4.0/fields/rhino.md
- docs/4.0/fields/select.md
- docs/4.0/fields/stars.md
- docs/4.0/fields/status.md
- docs/4.0/fields/tags.md
- docs/4.0/fields/text.md
- docs/4.0/fields/textarea.md
- docs/4.0/fields/time.md
- docs/4.0/fields/tip_tap.md
- docs/4.0/fields/trix.md
- docs/4.0/associations.md
- docs/4.0/associations/belongs_to.md
- docs/4.0/associations/has_one.md
- docs/4.0/associations/has_many.md
- docs/4.0/associations/has_and_belongs_to_many.md
- docs/4.0/actions/overview.md
- docs/4.0/actions/generate.md
- docs/4.0/actions/registration.md
- docs/4.0/actions/execution.md
- docs/4.0/actions/customization.md
- docs/4.0/actions/guides-and-tutorials.md
- docs/4.0/filters.md
- docs/4.0/basic-filters.md
- docs/4.0/dynamic-filters.md
- docs/4.0/customization.md
- docs/4.0/eject-views.md
- docs/4.0/custom-view-types.md
- docs/4.0/menu-editor.md
- docs/4.0/search/resource-search.md
- docs/4.0/search/global-search.md
- docs/4.0/i18n.md
- docs/4.0/branding.md
- docs/4.0/routing.md
- docs/4.0/multitenancy.md
- docs/4.0/custom-tools.md
- docs/4.0/custom-fields.md
- docs/4.0/custom-errors.md
- docs/4.0/resource-tools.md
- docs/4.0/stimulus-integration.md
- docs/4.0/custom-asset-pipeline.md
- docs/4.0/tailwindcss-integration.md
- docs/4.0/dashboards.md
- docs/4.0/cards.md
- docs/4.0/kanban-boards.md
- docs/4.0/forms-and-pages/overview.md
- docs/4.0/forms-and-pages/generator.md
- docs/4.0/forms-and-pages/pages.md
- docs/4.0/forms-and-pages/forms.md
- docs/4.0/forms-and-pages/guides-and-tutorials.md
- docs/4.0/rest-api/mount.md
- docs/4.0/rest-api/generators.md
- docs/4.0/rest-api/csrf-protection.md
- docs/4.0/rest-api/authentication.md
- docs/4.0/collaboration/overview.md
- docs/4.0/collaboration/authorization.md
- docs/4.0/notifications.md
- docs/4.0/media-library.md
- docs/4.0/cache.md
- docs/4.0/views-performance.md
- docs/4.0/internals.md
- docs/4.0/testing.md
- docs/4.0/keyboard-shortcuts.md
- docs/4.0/avo-current.md
- docs/4.0/execution-context.md
- docs/4.0/encryption-service.md
- docs/4.0/select-all.md
- docs/4.0/icons.md
- docs/4.0/internal-model-names.md
- docs/4.0/rails-engines-paths.md
- docs/4.0/native-components/avo-panel-component.md
- docs/4.0/native-field-components.md
- docs/4.0/field-wrappers.md
- docs/4.0/avo-application-controller.md
- docs/4.0/asset-manager.md
- docs/4.0/plugins.md
- docs/4.0/custom-view-types.md
- docs/4.0/guides.md
- docs/4.0/guides/act-as-taggable-on-integration.md
- docs/4.0/guides/acts_as_tenant_integration.md
- docs/4.0/guides/add-nested-fields-to-forms.md
- docs/4.0/guides/api-only-app.md
- docs/4.0/guides/attachment-policy-extension-for-pundit.md
- docs/4.0/guides/basic-authentication.md
- docs/4.0/guides/bulk_destroy_action_using_customizable_controls.md
- docs/4.0/guides/conditionally-render-styled-rows.md
- docs/4.0/guides/custom-ids.md
- docs/4.0/guides/custom-link-field.md
- docs/4.0/guides/display-and-edit-join-table-fields.md
- docs/4.0/guides/display-scope-record-count.md
- docs/4.0/guides/export-to-csv.md
- docs/4.0/guides/format-ruby-object-to-json.md
- docs/4.0/guides/generating-components-for-fields.md
- docs/4.0/guides/handle-404-responses-in-avo.md
- docs/4.0/guides/hide-field-labels.md
- docs/4.0/guides/how-to-use-phlex-components.md
- docs/4.0/guides/manage-information-heavy-resources.md
- docs/4.0/guides/multi-language-urls.md
- docs/4.0/guides/multilingual-content.md
- docs/4.0/guides/multitenancy.md
- docs/4.0/guides/nested-records-when-creating.md
- docs/4.0/guides/rails-authentication-scaffold.md
- docs/4.0/guides/rest-api-integration.md
- docs/4.0/guides/rolify-integration.md
- docs/4.0/guides/run-avo-on-the-root-path.md
- docs/4.0/guides/safely-override-resource-components.md
- docs/4.0/guides/tabs-counter-indicator.md
- docs/4.0/guides/use-markdown-in-help-attributes.md
- docs/4.0/guides/use-own-helpers-in-resource-files.md