Address fields', as_html: true ``` #### Default `false` #### Possible values `true`, `false` --- # 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 `` element on the `Edit` and `New` page. > Hidden will only render on the `Edit` and `New` views. ### Example usage: ```ruby # Basic field :group_id, as: :hidden # With default field :user_id, as: :hidden, default: -> { current_user.id } # If the current_user is a admin # 1. Allow them to see and select a user. # 2. Remove the user_id field to prevent user_id it from overriding the user selection. # Otherwise set the user_id to the current user and hide the field. field :user, as: :belongs_to, visible: -> (resource:) { context[:current_user].admin? } field :user_id, as: :hidden, default: -> { current_user.id }, visible: -> (resource:) { !context[:current_user].admin? } ``` --- # ID The `id` field is used to show the record's id. By default, it's visible only on the `Index` and `Show` views. That is a good field to add the `as_link_to_resource` option to make it a shortcut to the record `Show` page. ```ruby field :id, as: :id ``` ## Options --- # KeyValue KeyValue field

The `KeyValue` field makes it easy to edit flat key-value pairs stored in `JSON` format in the database. ```ruby field :meta, as: :key_value ``` ## Options ## 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 by setting `disable_editing_keys` 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_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. ``` `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 ```

:::warning You need to add the `mapkick-rb` (not `mapkick`) gem to your `Gemfile` and have the `MAPBOX_ACCESS_TOKEN` environment variable with a valid [Mapbox](https://account.mapbox.com/auth/signup/) key. ::: ## Description By default, the location field is attached to one database column that has the coordinates in plain text with a comma `,` joining them (`latitude,longitude`). Ex: `44.427946,26.102451` Avo will take that value, split it by the comma and use the first element as the `latitude` and the second one as the `longitude`. On the view you'll get in interactive map and on the edit you'll get one field where you can edit the coordinates. ## Options --- # Markdown Trix field

The `Markdown` field renders a [EasyMDE Markdown Editor](https://github.com/Ionaru/easy-markdown-editor) and is associated with a text or textarea column in the database. `Markdown` field converts text within the editor into raw Markdown text and stores it back in the database. The Markdown field is hidden from the **Index** view. ```ruby field :description, as: :markdown ``` ## Options ## Enable spell checker --- # Number The `number` field renders a `input[type="number"]` element. ```ruby field :age, as: :number ``` ## Options ## 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 ``` Related: - Devise password optional --- # Progress bar The `ProgressBar` field renders a `progress` element on `Index` and `Show` views and and a `input[type=range]` element on `Edit` and `New` views. ```ruby field :progress, as: :progress_bar ``` Progress bar custom field on index

## Options ## Examples ```ruby field :progress, as: :progress_bar, max: 150, step: 10, display_value: true, value_suffix: "%" ``` Progress bar custom field edit

--- # Select The `Select` field renders a `select` field. ```ruby field :type, as: :select, options: { 'Large container': :large, 'Medium container': :medium, 'Tiny container': :tiny }, display_with_value: true, placeholder: 'Choose the type of the container.' ``` ## Options ## 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.

```ruby
field :body, as: :textarea
```

## Options

<Option name="`rows`">
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.
</Option>

---

# Time

![](/assets/img/fields/time.png)

The `Time` field is similar to the DateTime field and uses the time picker of flatpickr (without the calendar). You can use the `time_24hr` option for flatpickr to use the 24-hour format. Add the option `relative: false` if you want the time to stay absolute and not change based on the browser's timezone.

```ruby
field :starting_at,
  as: :time,
  picker_format: 'H:i',
  format: "HH:mm",
  relative: true,
  picker_options: {
    time_24hr: true
  }
```

Format the date shown to the user on the `Index` and `Show` views.

#### Default

`TT`

#### Possible values

Use [`luxon`](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) formatting tokens.
</Option>

<Option name="`picker_format`">
Format the date shown to the user on the `Edit` and `New` views.

#### Default

`H:i:S`

#### Possible values

Use [`flatpickr`](https://flatpickr.js.org/formatting) formatting tokens.
</Option>

<Option name="`picker_options`;">
Passes the options here to [flatpickr](https://flatpickr.js.org/).

#### Default

`{}`

#### Possible values

Use [`flatpickr`](https://flatpickr.js.org/options) options.

:::warning
These options may override other options like `picker_options`.
:::

</Option>

---

# 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.

Trix field is hidden from the `Index` view.

## Options

<Option name="`always_show`">
By default, the content of the `Trix` 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 Markdown to display the content by setting `always_show` to `true`.

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`attachments_disabled`">
Hides the attachments button from the Trix toolbar.

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`hide_attachment_filename`">
Hides the attachment's name from the upload output in the field value.

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`hide_attachment_filesize`">
Hides the attachment size from the upload output in the field value.

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`hide_attachment_url`">
Hides the attachment URL from the upload output in the field value.

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`attachment_key`">
Enables file attachments.

#### Default

`nil`

#### Possible values

`nil`, or a symbol representing the `has_many_attachments` key on the model.
</Option>

## 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`.

---

# Associations

One of the most amazing things about Ruby on Rails is how easy it is to create [Active Record associations](https://guides.rubyonrails.org/association_basics.html) between models. We try to keep the same simple approach in Avo too.

:::warning
It's important to set the `inverse_of` as often as possible to your model's association attribute.
:::

- Belongs to
 - Has one
 - Has many
 - Has many through
 - Has and blongs to many

## Single Table Inheritance (STI)

When you have models that share behavior and fields with STI, Rails will cast the model as the final class no matter how you query it.

```ruby
# app/models/user.rb
class User < ApplicationRecord
end

# app/models/super_user.rb
class SuperUser < User
end

# User.all.map(&:class) => [User, SuperUser]
```

For example, when you have two models, `User` and `SuperUser` with STI, when you call `User.all`, Rails will return an instance of `User` and an instance of `SuperUser`. That confuses Avo in producing the proper resource of `User`. That's why when you deal with STI, the final resource `SuperUserResource` should receive the underlying `model_class` so Avo knows which model it represents.

```ruby{4}
class SuperUserResource < Avo::BaseResource
  self.title = :name
  self.includes = []
  self.model_class = ::SuperUser

field :id, as: :id
  field :name, as: :text
end
```

## Link to child resource when using STI

Let's take another example. We have a `Person` model and `Sibling` and `Spouse` models that inherit from it.

You may want to use the `PersonResource` to list all the records, but when your user clicks on a person, you want to use the inherited resources (`SiblingResource` and `SpouseResource`) to display the details. The reason is that you may want to display different fields or resource tools for each resource type.

There are two ways you can use this:

1. `self.link_to_child_resource = true` Declare this option on the parent resource. When a user is on the <Index /> view of your the `PersonResource` and clicks on the view button of a `Person` they will be redirected to a `Child` or `Spouse` resource instead of a `Person` resource.
2. `field :peoples, as: :has_many, link_to_child_resource: true` Use it on a `has_many` field. On the `PersonResource` you may want to show all the related people on the <Show /> page, but when someone click on a record, they are redirected to the inherited `Child` or `Spouse` resource.

## Add custom labels to the associations' pages

You might want to change the name that appears on the association page. For example, if you're displaying a `team_members` association, your users will default see `Team members` as the title, but you'd like to show them `Members`.

You can customize that using fields localization.

---

# Belongs to

```ruby
field :user, as: :belongs_to
```

You will see three field types when you add a `BelongsTo` association to a model.

## Options

Turns the attach field/modal from a `select` input to a searchable experience

```ruby{4}
class CourseLink < Avo::BaseResource
  field :links,
    as: :has_many,
    searchable: true
end
```

:::warning
  Avo uses the **search feature** behind the scenes, so **make sure the target resource has the `search_query` option configured**.
:::

```ruby{3-5}
# app/avo/resources/course_link_resource.rb
class CourseLinkResource < Avo::BaseResource
  self.search_query = -> do
    scope.ransack(id_eq: params[:q], link_cont: params[:q], m: "or").result(distinct: false)
  end
end
```

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`allow_via_detaching`">
Keeps the field enabled when visiting from the parent record.

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`attach_scope`">
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. The block is executed in the `AssociationScopeHost`, so follow the docs to see what variables you have access to.
</Option>

<Option name="`polymorphic_as`">
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`.
</Option>

<Option name="`types`">
Sets the types the field can morph to.

#### Default

`[]`

#### Possible values

`[Post, Project, Team]`. Any array of model names.
</Option>

<Option name="`polymorphic_help`">
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.
</Option>

<Option name="`use_resource`">
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

`PostResource`, `PhotoCommentResource`, or any Avo resource class.
</Option>

## Overview

On the `Index` and `Show` views, Avo will generate a link to the associated record containing the `@title` value.

On the `Edit` and `New` views, Avo will generate a dropdown element with the available records where the user can change the associated model.

## Polymorphic `belongs_to`

To use a polymorphic relation, you must add the `polymorphic_as` and `types` properties.

```ruby{12}
class CommentResource < Avo::BaseResource
  self.title = :id

field :id, as: :id
  field :body, as: :textarea
  field :excerpt, as: :text, show_on: :index, as_description: true do |model|
    ActionView::Base.full_sanitizer.sanitize(model.body).truncate 60
  rescue
    ""
  end

field :commentable, as: :belongs_to, polymorphic_as: :commentable, types: [::Post, ::Project]
end
```

## Polymorphic help

When displaying a polymorphic association, you will see two dropdowns. One selects the polymorphic type (`Post` or `Project`), and one for choosing the actual record. You may want to give the user explicit information about those dropdowns using the `polymorphic_help` option for the first dropdown and `help` for the second.

```ruby{16-17}
class CommentResource < Avo::BaseResource
  self.title = :id

field :reviewable,
    as: :belongs_to,
    polymorphic_as: :reviewable,
    types: [::Post, ::Project, ::Team],
    polymorphic_help: "Choose the type of record to review",
    help: "Choose the record you need."
end
```

## Searchable `belongs_to`

There might be the case that you have a lot of records for the parent resource, and a simple dropdown won't cut it. This is where you can use the `searchable` option to get a better search experience for that resource.

```ruby{7}
class CommentResource < Avo::BaseResource
  self.title = :id

field :id, as: :id
  field :body, as: :textarea

field :user, as: :belongs_to, searchable: true
end
```

`searchable` works with `polymorphic` `belongs_to` associations too.

```ruby{7}
class CommentResource < Avo::BaseResource
  self.title = :id

field :id, as: :id
  field :body, as: :textarea

field :commentable, as: :belongs_to, polymorphic_as: :commentable, types: [::Post, ::Project], searchable: true
end
```

:::info
Avo uses the search feature behind the scenes, so **make sure the target resource has the `search_query` option configured**.
:::

```ruby
# app/avo/resources/post_resource.rb
class PostResource < Avo::BaseResource
  self.search_query = -> do
    scope.ransack(id_eq: params[:q], name_cont: params[:q], body_cont: params[:q], m: "or").result(distinct: false)
  end
end

# app/avo/resources/project_resource.rb
class ProjectResource < Avo::BaseResource
  self.search_query = -> do
    scope.ransack(id_eq: params[:q], name_cont: params[:q], country_cont: params[:q], m: "or").result(distinct: false)
  end
end
```

## Belongs to attach scope

When you edit a record that has a `belongs_to` association, on the edit screen, you will have a list of records from which you can choose a record to associate with.

For example, a `Post` belongs to a `User`. So on the post edit screen, you will have a dropdown (or a search field if it's [searchable](#searchable-belongs-to)) with all the available users. But that's not ideal. For example, maybe you don't want to show all the users in your app but only those who are not admins.

You can use the `attach_scope` option to keep only the users you need in the `belongs_to` dropdown field.

You have access to the `query` that you can alter and return it and the `parent` object, which is the actual record where you want to assign the association (the true `Post` in the below example).

```ruby
# app/models/user.rb
class User < ApplicationRecord
  scope :non_admins, -> { where "(roles->>'admin')::boolean != true" }
end

# app/avo/resources/post_resource.rb
class PostResource < Avo::BaseResource
  field :user, as: :belongs_to, attach_scope: -> { query.non_admins }
end
```

For scenarios where you need to add a record associated with that resource (you create a `Post` through a `Category`), the `parent` is unavailable (the `Post` is not persisted in the database). Therefore, Avo makes the `parent` an instantiated object with its parent populated (a `Post` with the `category_id` populated with the parent `Category` from which you started the creation process) so you can better scope out the data (you know from which `Category` it was initiated).

## Allow detaching via the association

When you visit a record through an association, that `belongs_to` field is disabled. There might be cases where you'd like that field not to be disabled and allow your users to change that association.

You can instruct Avo to keep that field enabled in this scenario using `allow_via_detaching`.

```ruby{11}
class CommentResource < Avo::BaseResource
  self.title = :id

field :id, as: :id
  field :body, as: :textarea

field :commentable,
    as: :belongs_to,
    polymorphic_as: :commentable,
    types: [::Post, ::Project],
    allow_via_detaching: true
end
```

---

# Has One

:::warning
It's important to set the `inverse_of` as often as possible to your model's association attribute.
:::

# Has One

The `HasOne` association shows the unfolded view of your `has_one` association. It's like peaking on the `Show` view of that associated record. The user can also access the `Attach` and `Detach` buttons.

```ruby
field :admin, as: :has_one
```

## Options

Turns the attach field/modal from a `select` input to a searchable experience

```ruby{4}
class CourseLink < Avo::BaseResource
  field :links,
    as: :has_many,
    searchable: true
end
```

:::warning
  Avo uses the **search feature** behind the scenes, so **make sure the target resource has the `search_query` option configured**.
:::

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`attach_scope`">
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. The block is executed in the `AssociationScopeHost`, so follow the docs to see what variables you have access to.
</Option>

## Show on edit screens

By default, `has_and_belongs_to_many` is only visible on the `Show` page. If you want to enable it on the `Edit` page, too, you need to add the `show_on: :edit` option.

:::warning
  Adding associations on the `New` screen is not currently supported. The association needs some information from the parent record that hasn't been created yet (because the user is on the `New` screen).
:::

You may use the redirect helpers to have the following flow:

1. User is on the `New` view. They can't see the association panels yet.
1. User creates the record.
1. They get redirected to the `Show`/`Edit` view, where they can see the association panels.
1. User attaches associations.

---

# 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{4}
class CourseLink < Avo::BaseResource
  field :links,
    as: :has_many,
    searchable: true
end
```

:::warning
  Avo uses the **search feature** behind the scenes, so **make sure the target resource has the `search_query` option configured**.
:::

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`attach_scope`">
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. The block is executed in the `AssociationScopeHost`, so follow the docs to see what variables you have access to.
</Option>

<Option name="`scope`">
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 `AssociationScopeHost`, so follow the docs to see what variables you have access to.
</Option>

<Option name="`description`">
Changes the text displayed under the association name.

![](/assets/img/associations/description-option.jpg)

#### Default

`nil`

#### Possible values

Any string.
</Option>

<Option name="`use_resource`">
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

`PostResource`, `PhotoCommentResource`, or any Avo resource class.
</Option>

<Option name="`discreet_pagination`">
Hides the pagination details when only there's only one page for that association.

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`hide_search_input`">
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`.
</Option>

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`.
</Option>

## Search query scope

If the resource used for the `has_many` association has the `search_query` block configured, Avo will use that to scope out the search query to that association.

For example, if you have a `Team` model that `has_many` `User`s, now you'll be able to search through that team's users instead of all of them.

You can target that search using `params[:via_association]`. When the value of `params[:via_association]` is `has_many`, the search has been mad inside a has_many association.

For example, if you want to show the records in a different order, you can do this:

```ruby
self.search_query = -> do
  if params[:via_association] == 'has_many'
    scope.ransack(id_eq: params[:q], m: "or").result(distinct: false).order(name: :asc)
  else
    scope.ransack(id_eq: params[:q], m: "or").result(distinct: false)
  end
end
```

## 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, `has_and_belongs_to_many` is only visible on the `Show` page. If you want to enable it on the `Edit` page, too, you need to add the `show_on: :edit` option.

You may use the redirect helpers to have the following flow:

## Add scopes to associations

When displaying `has_many` associations, you might want to scope out some associated records. For example, a user might have multiple comments, but on the user's `Show` page, you don't want to display all the comments, but only the approved ones.

```ruby{5,16,22}
# app/models/comment.rb
class Comment < ApplicationRecord
  belongs_to :user, optional: true

scope :approved, -> { where(approved: true) }
end

# app/models/user.rb
class User < ApplicationRecord
  has_many :comments
end

# app/avo/resources/user_resource.rb
class UserResource < Avo::BaseResource
  # Before v2.5.0
  field :comments, as: :has_many, scope: -> { approved }
end

# app/avo/resources/user_resource.rb
class UserResource < Avo::BaseResource
  # After v2.5.0
  field :comments, as: :has_many, scope: -> { query.approved }
end
```

The `comments` query on the user `Index` page will have the `approved` scope attached.

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.

All the `has_many` associations have the `attach_scope` option available too.

## Show/hide buttons

You will want to control the visibility of the attach/detach/create/destroy/actions buttons visible throughout your app. You can use the policy methods to do that.

Find out more on the authorization page.

---

# Has And Belongs To Many

The `HasAndBelongsToMany` association works similarly to `HasMany`.

```ruby
field :users, as: :has_and_belongs_to_many
```

## Options
<Option name="`searchable`">

Turns the attach field/modal from a `select` input to a searchable experience

```ruby{4}
class CourseLink < Avo::BaseResource
  field :links,
    as: :has_many,
    searchable: true
end
```

:::warning
  Avo uses the **search feature** behind the scenes, so **make sure the target resource has the `search_query` option configured**.
:::

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`attach_scope`">
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. The block is executed in the `AssociationScopeHost`, so follow the docs to see what variables you have access to.
</Option>

<Option name="`scope`">
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 `AssociationScopeHost`, so follow the docs to see what variables you have access to.
</Option>

<Option name="`description`">
Changes the text displayed under the association name.

![](/assets/img/associations/description-option.jpg)

#### Default

`nil`

#### Possible values

Any string.
</Option>

<Option name="`use_resource`">
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

`PostResource`, `PhotoCommentResource`, or any Avo resource class.
</Option>

<Option name="`discreet_pagination`">
Hides the pagination details when only there's only one page for that association.

#### Default

`false`

#### Possible values

`true`, `false`
</Option>

<Option name="`hide_search_input`">
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`.
</Option>

## Search query scope

If the resource used for the `has_many` association has the `search_query` block configured, Avo will use that to scope out the search query to that association.

For example, if you have a `Team` model that `has_many` `User`s, now you'll be able to search through that team's users instead of all of them.

You can target that search using `params[:via_association]`. When the value of `params[:via_association]` is `has_many`, the search has been mad inside a has_many association.

For example, if you want to show the records in a different order, you can do this:

## Show on edit screens

By default, `has_and_belongs_to_many` is only visible on the `Show` page. If you want to enable it on the `Edit` page, too, you need to add the `show_on: :edit` option.

You may use the redirect helpers to have the following flow:

### Searchable `has_and_belongs_to_many`

Similar to `belongs_to`, the `has_many` associations support the `searchable` option.

## Add scopes to associations

```ruby{5,16,22}
# app/models/comment.rb
class Comment < ApplicationRecord
  belongs_to :user, optional: true

scope :approved, -> { where(approved: true) }
end

# app/models/user.rb
class User < ApplicationRecord
  has_many :comments
end

# app/avo/resources/user_resource.rb
class UserResource < Avo::BaseResource
  # Before v2.5.0
  field :comments, as: :has_many, scope: -> { approved }
end

# app/avo/resources/user_resource.rb
class UserResource < Avo::BaseResource
  # After v2.5.0
  field :comments, as: :has_many, scope: -> { query.approved }
end
```

The `comments` query on the user `Index` page will have the `approved` scope attached.

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.

All the `has_many` associations have the `attach_scope` option available too.

## Show/hide buttons

You will want to control the visibility of the attach/detach/create/destroy/actions buttons visible throughout your app. You can use the policy methods to do that.

Find out more on the authorization page.

---

# 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 MyDashboard < Avo::Dashboards::BaseDashboard
  self.id = 'my_dashboard'
  self.name = 'Dashy'
  self.description = 'The first dashbaord'
  self.grid_cols = 3

card ExampleMetric
  card ExampleAreaChart
  card ExampleScatterChart
  card PercentDone
  card AmountRaised
  card ExampleLineChart
  card ExampleColumnChart
  card ExamplePieChart
  card ExampleBarChart
  divider label: "Custom partials"
  card ExampleCustomPartial
  card MapCard
end
```

## Settings

Each dashboard is a file. It holds information about itself like the `id`, `name`, `description`, and how many columns its grid has.

The `id` field has to be unique. The `name` is what the user sees in big letters on top of the page, and the `description` is some text you pass to give the user more details regarding the dashboard.

Using the ' grid_cols ' parameter, you may organize the cards in a grid with `3`, `4`, `5`, or `6` columns using the `grid_cols` parameter. The default is `3`.

## Cards

All cards have a few base settings and a few custom ones.

### 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 dashboard grid. They can have values from `1` to `6`.

```ruby{2-7}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.label = 'Users count'
  self.description = 'Users description'
  self.cols = 1
  self.rows = 1
  self.display_header = true
end
```

### Control the aggregation using ranges

You may also want to give the user the ability to query data in different ranges. You can control what's passed in the dropdown using the' ranges' attribute. The array passed here will be parsed and displayed on the card. All integers are transformed to days, and other string variables will be passed as they are.

You can also set a default range using the `initial_range` attribute.

```ruby{4,5}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.label = 'Users count'
  self.initial_range = 30
  self.ranges = {
    "7 days": 7,
    "30 days": 30,
    "60 days": 60,
    "365 days": 365,
    Today: "TODAY",
    "Month to date": "MTD",
    "Quarter to date": "QTD",
    "Year to date": "YTD",
    All: "ALL"
  }
end
```

### Keep the data fresh

If this dashboard is something you keep on the big screen, you must keep the data fresh at all times. That's easy using `refresh_every`. You pass the number of seconds you need to be refreshed and forget about it. Avo will do it for you.

```ruby{3}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.refresh_every = 10.minutes
end
```

### Hide the header

In cases where you need to embed some content that should fill the whole card (like a map, for example), you can choose to hide the label and ranges dropdown.

```ruby{3}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.display_header = false
end
```
<img :src="('/assets/img/dashboards/map_card.jpg')" alt="Avo Dashboard Map card" class="border mb-4" />

### Override card options from the dashboard

We found ourselves in the position to add a few cards that were the same card but with a slight difference. Ex: Have one `Users count` card and another `Active users count` card. They both count users, but the latter has an `active: true` condition applied.

Before, we'd have to duplicate that card and modify the `query` method slightly but end up with duplicated boilerplate code.
For those scenarios, we created the `options` attribute. It allows you to send arbitrary options to the card from the parent.

```ruby{6-8}
class Dashy < Avo::Dashboards::BaseDashboard
  self.id = "dashy"
  self.name = "Dashy"

card UsersCount
  card UsersCount, options: {
    active_users: true
  }
end
```

Now we can pick up that option in the card and update the query accordingly.

```ruby{9-11}
class UsersCount < Avo::Dashboards::MetricCard
  self.id = "users_metric"
  self.label = "Users count"

# You have access to context, params, range, current dashboard, and current card
  def query
    scope = User

if options[:active_users].present?
      scope = scope.active
    end

result scope.count
  end
end
```

That gives you an extra layer of control without code duplication and the best developer experience.

#### Control the base settings from the parent

Evidently, you don't want to show the same `label`, `description`, and other details for that second card from the first card;. Therefore, you can control the `label`, `description`, `cols`, `rows`, and `refresh_every` options from the parent declaration.

```ruby{7-11}
class Dashy < Avo::Dashboards::BaseDashboard
  self.id = "dashy"
  self.name = "Dashy"

card UsersCount
  card UsersCount,
    label: "Active users",
    description: "Active users count",
    cols: 2,
    rows: 2,
    refresh_every: 2.minutes,
    options: {
      active_users: true
    }
end
```

## Cards visibility

It's common to show the same dashboard to multiple types of users (admins, regular users). In that scenario you might want to hide some cards for the regular users and show them just to the admins.

You can use the `visible` option to do that. It can be a `boolean` or a `block` where you can access the `params`, `current_user`, `context`, `parent`, and `card` object.

```ruby{4-6}
class UsersCount < Avo::Dashboards::MetricCard
  self.id = "users_metric"
  self.label = "Users count"
  self.visible = -> do
    # You have access to context, params, parent (the current dashboard), and current card
    true
  end

def query
    result User.count
  end
end
```

You may also control the visibility from the dashboard class.

```ruby
class Dashy < Avo::Dashboards::BaseDashboard
  self.name = "Dashy"

card UsersCount, visible: -> { true }
end
```

## Card types

You can add three types of cards to your dashboard: `metric`, `chartkick`, and `partial`.

### Metric card

The metric card is your friend when you only need to display a simple significant number on your dashboard. Generate one run `bin/rails g avo:card:metric users_metric`.

#### Calculate results

To calculate your result, you may use the `query` method. After you run your query, use the `result` method to store the value that will be displayed on the card.

In the `query` method you have access to a few variables like `context` (the App context), `params` (the request params), `range` (the range that was requested), `dashboard` (the current dashboard the card is on), and current `card`.

```ruby{13-34,36}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.label = 'Users count'
  self.description = 'Some tiny description'
  self.cols = 1
  # self.rows = 1
  # self.initial_range = 30
  # self.ranges = [7, 30, 60, 365, 'TODAY', 'MTD', 'QTD', 'YTD', 'ALL']
  # self.prefix = '$'
  # self.suffix = '%'
  # self.refresh_every = 10.minutes

def query
    from = Date.today.midnight - 1.week
    to = DateTime.current

if range.present?
      if range.to_s == range.to_i.to_s
        from = DateTime.current - range.to_i.days
      else
        case range
        when 'TODAY'
          from = DateTime.current.beginning_of_day
        when 'MTD'
          from = DateTime.current.beginning_of_month
        when 'QTD'
          from = DateTime.current.beginning_of_quarter
        when 'YTD'
          from = DateTime.current.beginning_of_year
        when 'ALL'
          from = Time.at(0)
        end
      end
    end

result User.where(created_at: from..to).count
  end
end
```

#### Decorate the data using `prefix` and `suffix`

Some metrics might want to add a `prefix` or a `suffix` to display the data better.

```ruby{3,4}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.prefix = '$'
  self.suffix = '%'
end
```

### Chartkick card

A picture is worth a thousand words. So maybe a chart a hundred? Who knows? But creating charts in Avo is very easy with the help of the [chartkick](https://github.com/ankane/chartkick) gem.

You start by running `bin/rails g avo:card:chartkick users_chart`.

```ruby
class UserSignups < Avo::Dashboards::ChartkickCard
  self.id = 'user_signups'
  self.label = 'User signups'
  self.chart_type = :area_chart
  self.description = 'Some tiny description'
  self.cols = 2
  # self.rows = 1
  # self.chart_options = { library: { plugins: { legend: { display: true } } } }
  # self.flush = true
  # self.legend = false
  # self.scale = false
  # self.legend_on_left = false
  # self.legend_on_right = false

def query
    points = 16
    i = Time.new.year.to_i - points
    base_data =
      Array
        .new(points)
        .map do
          i += 1
          [i.to_s, rand(0..20)]
        end
        .to_h

data = [
      { name: 'batch 1', data: base_data.map { |k, v| [k, rand(0..20)] }.to_h },
      { name: 'batch 2', data: base_data.map { |k, v| [k, rand(0..40)] }.to_h },
      { name: 'batch 3', data: base_data.map { |k, v| [k, rand(0..10)] }.to_h }
    ]

result data
  end
end
```

#### Chart types

Using the `self.chart_type` class attribute, you can change the chart type. Supported types are `line_chart`, `pie_chart`, `column_chart`, `bar_chart`, `area_chart`, and `scatter_chart`.

#### Customize chart

Because the charts are being rendered with padding initially, we offset that before rendering to make the chart look good on the card. To disable that, you can set `self.flush = false`. That will set the chart loose for you to customize further.

After you set `flush` to `false`, you can add/remove the `scale` and `legend`. You can also place the legend on the left or right using `legend_on_left` and `legend_on_right`.

These are just some of the predefined options we provide out of the box, but you can send different [chartkick options](https://github.com/ankane/chartkick#options) to the chart using `chart_options`.

If you'd like to use [Groupdate](https://github.com/ankane/groupdate), [Hightop](https://github.com/ankane/hightop), and [ActiveMedian](https://github.com/ankane/active_median) you should require them in your `Gemfile`. Only `chartkick` is required by default.

`chart.js` is supported for the time being. So if you need support for other types, please reach out or post a PR (🙏 PRs are much appreciated).

### Partial card

You can use a partial card to add custom content to a card. Generate one by running `bin/rails g avo:card:partial custom_card`. That will create the card class and the partial for it.

```ruby{5}
class ExampleCustomPartial < Avo::Dashboards::PartialCard
  self.id = "users_custom_card"
  self.cols = 1
  self.rows = 4
  self.partial = "avo/cards/custom_card"
  # self.display_header = true
end
```
<img :src="('/assets/img/dashboards/custom_partial_card.jpg')" alt="Custom partial card" class="border mb-4" />

You may embed a piece of content from another app using an iframe. You can hide the header using the `self.display_header = false` option. That will render the embedded content flush to the container.

```ruby{5}
# app/avo/cards/map_card.rb
class MapCard < Avo::Dashboards::PartialCard
  self.id = "map_card"
  self.label = "Map card"
  self.partial = "avo/cards/map_card"
  self.display_header = false
  self.cols = 2
  self.rows = 4
end
```

```html

## Dividers

You may want to separate the cards. You can use dividers to do that.

```ruby{16}
class Dashy < Avo::Dashboards::BaseDashboard
  self.id = 'dashy'
  self.name = 'Dashy'
  self.description = 'The first dashbaord'
  self.grid_cols = 3

Dividers can be a simple line between your cards or have some text on them that you control using the `label` option.
When you don't want to show the line, you can enable the `invisible` option, which adds the divider but does not display a border or label.

## Dividers visibility

You might want to conditionally show/hide a divider based on a few factors. You can do that using the `visible` option.

```ruby
class Dashy < Avo::Dashboards::BaseDashboard
  self.name = "Dashy"

card UsersCount, visible: -> {
    # You have access to context, params, parent (the current dashboard)
    true
  }
end
```

## Dashboards visibility

You might want to hide specific dashboards from certain users. You can do that using the `visible` option. The option can be a boolean `true`/`false` or a block where you have access to the `params`, `current_user`, `context`, and `dashboard`.

If you don't pass anything to `visible`, the dashboard will be available for anyone.

```ruby{5-11}
class ComplexDash < Avo::Dashboards::BaseDashboard
  self.id = "complex_dash"
  self.name = "Complex dash"
  self.description = "Complex dash description"
  self.visible = -> do
    current_user.is_admin?
    # or
    params[:something] == 'something else'
    # or
    context[:your_param] == params[:something_else]
  end

card UsersCount
end
```

## Dashboards authorization

You can set authorization rules for dashboards using the `authorize` block.

```ruby{3-6}
class Dashy < Avo::Dashboards::BaseDashboard
  self.id = 'dashy'
  self.authorization = -> do
    # You have access to current_user, params, request, context, adn view_context.
    current_user.is_admin?
  end
end
```

---

# Cards

Cards are one way of quickly adding custom content for your users.

You can add three types of cards to your dashboard: `partial`, `metric`, and `chartkick`.

## Base settings

Each card has its own `cols` and `rows` settings to control the width and height of the card inside the dashboard grid. They can have values from `1` to `6`.

#### Control the aggregation using ranges

You can also set a default range using the `initial_range` attribute.

The ranges have been changed a bit since **version 2.8**. The parameter you pass to the `range` option will be directly passed to the [`options_for_select`](https://apidock.com/rails/v5.2.3/ActionView/Helpers/FormOptionsHelper/options_for_select) helper, so it behaves more like a regular `select_tag`.

```ruby{4-15}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.label = 'Users count'
  self.initial_range = 30
  self.ranges = {
    "7 days": 7,
    "30 days": 30,
    "60 days": 60,
    "365 days": 365,
    Today: "TODAY",
    "Month to date": "MTD",
    "Quarter to date": "QTD",
    "Year to date": "YTD",
    All: "ALL"
  }
end
```

#### Keep the data fresh

If this dashboard is something that you keep on the big screen, you need to keep the data fresh at all times. That's easy using `refresh_every`. You pass the number of seconds you need to be refreshed and forget about it. Avo will do it for you.

```ruby{3}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.refresh_every = 10.minutes
end
```

#### Hide the header

In cases where you need to embed some content that should fill the whole card (like a map, for example), you can choose to hide the label and ranges dropdown.

### Metric card

The metric card is your friend when you only need to display a simple big number on your dashboard. To generate one run `bin/rails g avo:card:metric users_metric`.

#### Calculate results

To calculate your result, you may use the `query` method. After you make the query, use the `result` method to store the value displayed on the card.

```ruby{23-47,36}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.label = 'Users count'
  self.description = 'Some tiny description'
  self.cols = 1
  # self.rows = 1
  # self.initial_range = 30
  # self.ranges = {
  #   "7 days": 7,
  #   "30 days": 30,
  #   "60 days": 60,
  #   "365 days": 365,
  #   Today: "TODAY",
  #   "Month to date": "MTD",
  #   "Quarter to date": "QTD",
  #   "Year to date": "YTD",
  #   All: "ALL",
  # }
  # self.prefix = '$'
  # self.suffix = '%'
  # self.refresh_every = 10.minutes

def query
    from = Date.today.midnight - 1.week
    to = DateTime.current

result User.where(created_at: from..to).count
  end
end
```

#### Decorate the data using `prefix` and `suffix`

Some metrics might want to add a `prefix` or a `suffix` to display the data better.

```ruby{3,4}
class UsersMetric < Avo::Dashboards::MetricCard
  self.id = 'users_metric'
  self.prefix = '$'
  self.suffix = '%'
end
```

### Chartkick card

A picture is worth a thousand words. So maybe a chart a hundred? Who knows? But creating charts in Avo is very easy with the help of the [chartkick](https://github.com/ankane/chartkick) gem.

You start by running `bin/rails g avo:card:chartkick users_chart`.

result data
  end
end
```

#### Chart types

Using the `self.chart_type` class attribute you can change the type of the chart. Supported types are `line_chart`, `pie_chart`, `column_chart`, `bar_chart`, `area_chart`, and `scatter_chart`.

#### Customize chart

After you set `flush` to `false`, you can add/remove the `scale` and `legend`. You can also place the legend on the left or right using `legend_on_left` and `legend_on_right`.

`chart.js` is supported for the time being. So if you need support for other types, please reach out or post a PR (🙏 PRs are much appreciated).

### Partial card

You can use a partial card to add custom content to a card. Generate one by running `bin/rails g avo:card:partial custom_card`. That will create the card class and the partial for it.

You can embed a piece of content from another app using an iframe. You can hide the header using the `self.display_header = false` option. That will render the embedded content flush to the container.

```html

---

# 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'`.

Since Avo 2.32.6 the `app_name` option is 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`.

### Per page steps

Similarly customize the per-page steps in the per-page picker with `config.per_page_steps = [12, 24, 48, 72]`.

### Resources via per page

For `has_many` associations you can control how many resources are visible in their `Index view` with `config.via_per_page = 8`.

### Default view type

The `ResourceIndex` component supports two view types `:table` and `:grid`. You can change that by `config.default_view_type = :table`. Read more on the grid view configuration page.

<div class="grid grid-flow-row sm:grid-flow-col sm:grid-cols-2 gap-2 w-full">
  <div class="w-full">
    <strong>Table view</strong>
    <img :src="('/assets/img/customization/table-view.png')" alt="Table view" class="border mb-4" />
  </div>
  <div class="w-full">
    <strong>Grid view</strong>
    <img :src="('/assets/img/customization/grid-view.jpg')" alt="Grid view" class="border mb-4" />
  </div>
</div>

## ID links to resource

On the **Index** view, each row has the controls component at the end, which allows the user to go to the **Show** and **Edit** views and delete that entry. If you have a long row and a not-so-wide display, it might not be easy to scroll to the right-most section to click the **Show** link.

You can enable the `id_links_to_resource` config option to make it easier.

```ruby{4}
Avo.configure do |config|
  config.root_path = '/avo'
  config.app_name = 'Avocadelicious'
  config.id_links_to_resource = true
end
```

That will render all `id` fields in the **Index** view as a link to that resource.

## Resource controls on the left side

By default, the resource controls are located on the right side of the record rows, which might be hidden if there are a lot of columns. You might want to move the controls to the left side in that situation using the `resource_controls_placement` option.

```ruby{2}
Avo.configure do |config|
  config.resource_controls_placement = :left
end
```

## Container width

```ruby{2-3}
Avo.configure do |config|
  config.full_width_index_view = false
  config.full_width_container = false
end
```

Avo's default main content is constrained to a regular [Tailwind CSS container](https://tailwindcss.com/docs/container). If you have a lot of content or prefer to display it full-width, you have two options.

### Display the `Index` view full-width

Using `full_width_index_view: true` tells Avo to display the **Index** view full-width.

### Display all views full-width

Using `full_width_container: true` tells Avo to display all views full-width.

## Cache resources on the `Index` view

Avo caches each resource row (or Grid item for Grid view) for performance reasons. You can disable that cache using the `cache_resources_on_index_view` configuration option. The cache key is using the record's `id` and `created_at` attributes and the resource file `md5`.

:::info
If you use the `visibility` option to show/hide fields based on the user's role, you should disable this setting.
:::

```ruby{2}
Avo.configure do |config|
  config.cache_resources_on_index_view = false
end
```

## Context

In the `Resource` and `Action` classes, you have a global `context` object to which you can attach a custom payload. For example, you may add the `current_user`, the current request `params`, or any other arbitrary data.

You can configure it using the `set_context` method in your initializer. The block you pass in will be instance evaluated in `Avo::ApplicationController`, so it will have access to the `current_user` method or `Current` object.

```ruby{2-8}
Avo.configure do |config|
  config.set_context do
    {
      foo: 'bar',
      params: request.params,
    }
  end
end
```

:::warning `_current_user`
It's recommended you don't store your current user here but using the `current_user_method` config.
:::

You can access the context data with `::Avo::App.context` object.

## Eject views

If you want to change one of Avo's built-in views, you can eject it, update it and use it in your admin.

### Prepared templates

We prepared a few templates to make it.

`bin/rails generate avo:eject :head` will eject the `_head.html.erb` partial.

```
▶ bin/rails generate avo:eject :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`
- `:footer` ➡️   `app/views/avo/partials/_footer.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.

#### Footer

The `_footer.html.erb` partial enables you to customize the footer of your admin.

#### 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 app/views/layouts/avo/application.html.erb
      create  app/views/layouts/avo/application.html.erb
```

:::warning
Once ejected, the views will not receive updates on new Avo releases. You must maintain them yourself.
:::

## Breadcrumbs

By default, Avo ships with breadcrumbs enabled.

You may disable them using the `display_breadcrumbs` configuration option.

```ruby{2}
Avo.configure do |config|
  config.display_breadcrumbs = false
end
```

The first item on the breadcrumb is **Home** with the `root_path` URL. You can customize that using the `set_initial_breadcrumbs` block.

```ruby{2-5}
Avo.configure do |config|
  config.set_initial_breadcrumbs do
    add_breadcrumb "Casa", root_path
    add_breadcrumb "Something else", something_other_path
  end
end
```

Avo uses the [breadcrumbs_on_rails](https://github.com/weppos/breadcrumbs_on_rails) gem under the hood.

### 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 "Custom tool"
  end
end
```

## Page titles

When you want to update the page title for a custom tool or page, you only need to assign a value to the `@page_title` instance variable in the controller method.

```ruby{3}
class Avo::ToolsController < Avo::ApplicationController
  def custom_tool
    @page_title = "Custom tool page title"
  end
end
```

Avo uses the [meta-tags](https://github.com/kpumuk/meta-tags) gem to compile and render the page title.

## Home path

When a user clicks your logo inside Avo or goes to the `/avo` URL, they will be redirected to one of your resources. You might want to change that path to something else, like a custom page. You can do that with the `home_path` configuration.

```ruby{2}
Avo.configure do |config|
  config.home_path = "/avo/dashboard"
end
```

### Use a lambda function for the home_path

You can also use a lambda function to define that path.

```ruby{2}
Avo.configure do |config|
  config.home_path = -> { avo.dashboard_path(:dashy) }
end
```

When you configure the `home_path` option, the `Get started` sidebar item will be hidden in the development environment.

Now, users will be redirected to `/avo/dashboard` whenever they click the logo. You can use this configuration option alongside the `set_initial_breadcrumbs` option to create a more cohesive experience.

```ruby{2-5}
Avo.configure do |config|
  config.home_path = "/avo/dashboard"
  config.set_initial_breadcrumbs do
    add_breadcrumb "Dashboard", "/avo/dashboard"
  end
end
```

## Mount Avo under a nested path

You may need to mount Avo under a nested path, something like `/uk/admin`. In order to do that, you need to consider a few things.

1. Move the engine mount point below any route for custom tools.

```ruby{7,10}
Rails.application.routes.draw do
  # other routes

authenticate :user, ->(user) { user.is_admin? } do
    scope :uk do
      scope :admin do
        get "dashboard", to: "avo/tools#dashboard" # custom tool added before engine
      end

mount Avo::Engine, at: Avo.configuration.root_path # engine mounted last
    end
  end
end
```

2. The `root_path` configuration should only be the last path segment.

```ruby
# 🚫 Don't add the scope to the root_path
Avo.configure do |config|
  config.root_path = "/uk/admin"
end

# ✅ Do this instead
Avo.configure do |config|
  config.root_path = "/admin"
end
```

3. Use full paths for other configurations.

```ruby
Avo.configure do |config|
  config.home_path = "/uk/admin/dashboard"

config.set_initial_breadcrumbs do
    add_breadcrumb "Dashboard", "/uk/admin/dashboard"
  end
end
```

## Custom `view_component` path

You may not keep your view components under `app/components` and want the generated field `view_component`s to be generated in your custom directory. You can change that using the `view_component_path` configuration key.

```ruby
Avo.configure do |config|
  config.view_component_path = "app/frontend/components"
end
```

## Custom query scopes

You may want to change Avo's queries to add sorting or use gems like [friendly](https://github.com/norman/friendly_id).
You can do that using `resolve_query_scope` for multiple records and `resolve_find_scope` when fetching one record.

### Custom scope for `Index` page

Using `resolve_query_scope` you tell Avo how to fetch the records for the `Index` view.

```ruby
class UserResource < Avo::BaseResource
  self.resolve_query_scope = ->(model_class:) do
    model_class.order(last_name: :asc)
  end
end
```

### Custom scope for `Show` and `Edit` pages

:::warning
The `resolve_find_scope` method is deprecated in favor of `find_record_method` (below).
:::

:::details If you're following the `friendly_id` example, you must also add the `friendly_id` configuration to the model definition.

```ruby
class User < ApplicationRecord
  extend FriendlyId
  friendly_id :name, use: :slugged
end
```

:::

### Custom find method for `Show` and `Edit` pages

Using `find_record_method` you tell Avo how to fetch one record for `Show` and `Edit` views and other contexts where a record needs to be fetched from the database.

This is very useful when you use something like `friendly` gem, custom `to_param` methods on your model, and even the wonderful `prefix_id` gem.

### Custom `to_param` method

The following example shows how you can update the `to_param` (to use the post name) method on the `User` model to use a custom attribute and then update the `UserResource` so it knows how to search for that model.

::: code-group

```ruby [app/avo/resources/user_resource.rb]
class PostResource < Avo::BaseResource
  self.find_record_method = ->(model_class:, id:, params:) do
    # If the id is an integer use the classic `find` method.
    # But if it's not an integer, search for that post by the slug.
    id.to_i == 0 ? model_class.find_by_slug(id) : model_class.find(id)
  end
end
```

```ruby [app/models/post.rb]
class Post < ApplicationRecord
  before_save :update_slug

def to_param
    slug || id
  end

def update_slug
    self.slug = name.parameterize
  end
end
```

:::

#### Using the `friendly` gem

::: code-group

```ruby [app/avo/resources/user_resource.rb]
class UserResource < Avo::BaseResource
  self.find_record_method = ->(model_class:, id:, params:) do
    # We have to add .friendly to the query
    model_class.friendly.find! id
  end
end
```

```ruby [app/models/user.rb]
class User < ApplicationRecord
  extend FriendlyId

friendly_id :name, use: :slugged
end
```

:::

#### Using `prefixed_ids` gem

You really don't have to do anything on Avo's side for this to work. You only need to add the `has_prefix_id` the model as per the documentation. Avo will know how to search for the record.

```ruby
class Course < ApplicationRecord
  has_prefix_id :course
end
```

## Disable features

You might want to disable some Avo features. You can do that using the `disabled_features` option.

```ruby{3}
# config/initializers/avo.rb
Avo.configure do |config|
  config.disabled_features = [:global_search]
end
```

After this setting, the global search will be hidden for users.

Supported options:

- `global_search`

## Customize profile name, photo, and title

You might see on the sidebar footer a small profile widget. The widget displays three types of information about the user; `name`, `photo`, and `title`.

### Customize the name of the user

Avo checks to see if the object returned by your `current_user_method` responds to a `name` method. If not, it will try the `email` method and then fall back to `Avo user`.

### Customize the profile photo

Similarly, it will check if that current user responds to `avatar` and use that as the `src` of the photo.

### Customize the title of the user

Lastly, it will check if it responds to the `avo_title` method and uses that to display it under the name.

### Customize the sign-out link

Please follow this guide in authentication.

## Skip show view

In the CRUD interface Avo adds the <Show /> view by default. This means that when your users will see the view icon to go to that detail page and they will be redirected to the <Show /> page when doing certain tasks (update a record, run an action, etc.).

You might not want that behavior and you might not use the <Show /> view at all and prefer to skip that and just use the <Edit /> view.
Adding `config.resource_default_view = :edit` to your `avo.rb` configuration file will tell Avo to skip it and use the <Edit /> view as the default resource view.

```ruby{3}
# config/initializers/avo.rb
Avo.configure do |config|
  config.resource_default_view = :edit
end
```

![](/assets/img/customization/skip_show_view.gif)

---

# Grid view

Some resources are best displayed in a grid view. We can do that with Avo using a `cover`, a `title`, and a `body`.

## Enable grid view

To enable grid view for a resource, you need to add the `grid` block. That will add the view switcher to the **Index** view.

```ruby
class PostResource < Avo::BaseResource
  # ...
  grid do
    cover :cover_photo, as: :file, link_to_resource: true
    title :name, as: :text, required: true, link_to_resource: true
    body :excerpt, as: :text
  end
end
```

## Make default view

To make the grid the default way of viewing a resource **Index**, we have to use the `default_view_type` class attribute.

```ruby{7}
class PostResource < Avo::BaseResource
  self.default_view_type = :grid
end
```

## Fields configuration

Besides the regular `field` methods, you should add a new `grid` block configuring the grid fields. The main difference is that the fields are not declared using the `field` class method but three new ones `cover`, `title`, and `body`

```ruby{9-13}
class PostResource < Avo::BaseResource
  self.default_view_type = :grid

field :id, as: :id
  field :name, as: :text, required: true
  field :body, as: :textarea
  field :cover_photo, as: :file, is_image: true

grid do
    cover :cover_photo, as: :file, is_image: true
    title :name, as: :text
    body :body, as: :textarea
  end
end
```

That will render the `Post` resource index view as a **Grid view** using the selected fields. Avo will also display a button to toggle between the view types `:grid` and `:table`.

These fields take the same options as those in the `fields` method, so you can configure them however you want.

For example, in the **Grid view**, you might want to truncate the `:body` to a certain length and use an external image for the cover you compute on the fly. And also, render the `:cover` and the `:title` fields as links to that resource with `link_to_resource: true`.

```ruby
grid do
  cover :logo, as: :external_image, link_to_resource: true do |model|
    if model.url.present?
      "//logo.clearbit.com/#{URI.parse(model.url).host}?size=180"
    end
  end
  title :name, as: :text, link_to_resource: true
  body :excerpt, as: :text do |model|
    begin
      ActionView::Base.full_sanitizer.sanitize(model.body).truncate 130
    rescue => exception
      ''
    end
  end
end
```

## Use a computed field for the `cover` field

A common use case is to have the assets stored on a separate model and would like to display an image from that related association.

```ruby
class Post < ApplicationRecord
  has_many :post_assets
end

class PostAssets < ApplicationRecord
  belongs_to :post

has_one_attached :image
end
```

Luckily, the `grid` display can be a computed field too

```ruby
 grid do
  cover :image, as: :file, is_image: true, link_to_resource: true do |model|
    # we find the first asset association and use it's image attachment
    model.post_assets.first.image
  end
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 attribtue to a resource. That will add the view switcher to the <Index /> view.

```ruby
class CityResource < Avo::BaseResource
  # ...
  self.map_view = {
    mapkick_options: {
      controls: true
    },
    record_marker: -> {
      {
        latitude: record.coordinates.first,
        longitude: record.coordinates.last,
        tooltip: record.name
      }
    },
    table: {
      visible: true,
      layout: :right
    }
  }
end
```

<Option name="`mapkick_options`">
The options you pass here are forwarded to the [`mapkick` gem](https://github.com/ankane/mapkick).
</Option>

<Option name="`record_marker`">
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`.
</Option>

<Option name="`table`">
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`.
</Option>

## Make it the default view

To make the map view the default way of viewing a resource on <Index />, we have to use the `default_view_type` class attribute.

```ruby{7}
class CityResource < Avo::BaseResource
  self.default_view_type = :map
end
```

---

# Menu editor

One common task you need to do is organize your sidebar resources into menus. You can easily do that using the menu editor in the initializer.

When you start with Avo, you'll get an auto-generated sidebar by default. That sidebar will contain all your resources, dashboards, and custom tools. To customize that menu, you have to add the `main_menu` key to your initializer.

```ruby{3-22}
# config/initializers/avo.rb
Avo.configure do |config|
  config.main_menu = -> {
    section "Resources", icon: "heroicons/outline/academic-cap" do
      group "Academia" do
        resource :course
        resource :course_link
      end

group "Blog", collapsable: true, collapsed: true do
        dashboard :dashy

resource :post
        resource :comment
      end
    end

section I18n.t('avo.other'), icon: "heroicons/outline/finger-print", collapsable: true, collapsed: true do
      link_to 'Avo HQ', path: 'https://avohq.io', target: :_blank
      link_to 'Jumpstart Rails', path: 'https://jumpstartrails.com/', target: :_blank
    end
  }
end
```

For now, Avo supports editing only two menus, `main_menu` and `profile_menu`. However, that might change in the future by allowing you to write custom menus for other parts of your app.

```ruby
# config/initializers/avo.rb
Avo.configure do |config|
  config.main_menu = -> {
    section I18n.t("avo.dashboards"), icon: "dashboards" do
      dashboard :dashy, visible: -> { true }
      dashboard :sales, visible: -> { true }

group "All dashboards", visible: false do
        all_dashboards
      end
    end

section "Resources", icon: "heroicons/outline/academic-cap" do
      group "Academia" do
        resource :course
        resource :course_link
      end

group "Blog" do
        resource :posts
        resource :comments
      end

group "Other" do
        resource :fish
      end
    end

section "Tools", icon: "heroicons/outline/finger-print" do
      all_tools
    end

group do
      link_to "Avo", path: "https://avohq.io"
      link_to "Google", path: "https://google.com", target: :_blank
    end
  }
  config.profile_menu = -> {
    link_to "Profile", path: "/profile", icon: "user-circle"
  }
end
```

## Menu item types

A few menu item types are supported `link_to`, `section`, `group`, `resource`, and `dashboard`. There are a few helpers too, like `all_resources`, `all_dashboards`, and `all_tools`.

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.

</Option>

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 `UserResource`.

```ruby
resource :posts
resource "CommentsResource"
```

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 = {"IsAdmin"=>["non_admins"]}

{ filters: Avo::Filters::BaseFilter.encode_filters(decoded_filter)}
end
```

</Option>

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"
```

</Option>

Sections are the big categories in which you can group your menu items. They take `name` and `icon` options.

```ruby
section "Resources", icon: "heroicons/outline/academic-cap" do
  resource :course
  resource :course_link
end
```

</Option>

Groups are smaller categories where you can bring together your items.

```ruby
group "Blog" do
  resource :posts
  resource :categories
  resource :comments
end
```

<Option name="`all_resources`">
Renders all resources.

```ruby
section "App", icon: "heroicons/outline/beaker" do
  group "Resources", icon: "resources" do
    all_resources
  end
end
```

</Option>

<Option name="`all_dashboards`">
Renders all dashboards.

```ruby
section "App", icon: "heroicons/outline/beaker" do
  group "Dashboards", icon: "dashboards" do
    all_dashboards
  end
end
```

</Option>

<Option name="`all_tools`">
Renders all tools.

```ruby
section "App", icon: "heroicons/outline/beaker" do
  group "All tools", icon: "tools" do
    all_tools
  end
end
```

</Option>

### `all_` helpers

```ruby
section "App", icon: "heroicons/outline/beaker" do
  group "Dashboards", icon: "dashboards" do
    all_dashboards
  end

group "Resources", icon: "resources" do
    all_resources
  end

group "All tools", icon: "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.
:::

## Item visibility

The `visible` option is available on all menu items. It can be a boolean or a block that has access to a few things:

- the `current_user`. Given that you set a way for Avo to know who the current user is, that will be available in that block call
- the `context` object.
- the `params` object of that current request
- the [`view_context`](https://apidock.com/rails/AbstractController/Rendering/view_context) object. The `view_context` object lets you use the route helpers. eg: `view_context.main_app.posts_path`.

```ruby
# config/initializers/avo.rb
Avo.configure do |config|
  config.main_menu = -> {
    resource :user, visible: -> do
      context[:something] == :something_else
    end
  }
end
```

## Add `data` attributes to items

You may want to add special data attributes to some items and you can do that using the `data` option. For example you may add `data: {turbo: false}` to make a regular request for a link.

```ruby{4}
# config/initializers/avo.rb
Avo.configure do |config|
  config.main_menu = -> {
    resource :user, data: {turbo: false}
  }
end
```

## Using authorization rules

When you switch from a generated menu to a custom one, you might want to keep using the same authorization rules as before. To quickly do that, use the `authorize` method in the `visible` option.

```ruby
# config/initializers/avo.rb
Avo.configure do |config|
  config.main_menu = -> {
    resource :team, visible: -> do
      # authorize current_user, MODEL_THAT_NEEDS_TO_BE_AUTHORIZED, METHOD_THAT_NEEDS_TO_BE_AUTHORIZED
      authorize current_user, Team, "index?", raise_exception: false
    end
  }
end
```

## Icons

For [`Section`](#section)s, you can use icons to make them look better. You can use some local ones that we used throughout the app and all [heroicons](https://heroicons.com/) designed by [Steve Schoger](https://twitter.com/steveschoger). In addition, you can use the `solid` or `outline` versions. We used the `outline` version throughout the app.

```ruby
section "Resources", icon: "heroicons/outline/academic-cap" do
  resource :course
end

section "Resources", icon: "heroicons/solid/finger-print" do
  resource :course
end

section "Resources", icon: "heroicons/outline/adjustments" do
  resource :course
end
```

### Icons on resource, dashboard, and link_to items

Since [2.36](https://avohq.io/releases/2.36) you can add icons to other menu items like `resource`, `dashboard`, and `link_to`.

```ruby
link_to "Avo", "https://avohq.io", icon: "globe"
```

## Collapsable sections and groups

When you have a lot of items they can take up a lot of vertical space. You can choose to make those sidebar sections collapsable by you or your users.

```ruby
section "Resources", icon: "resources", collapsable: true do
  resource :course
end
```

That will add the arrow icon next to the section to indicate it's collapsable. So when your users collapse and expand it, their choice will be stored in Local Storage and remembered in that browser.

### Default collapsed state

You can however, set a default collapsed state using the `collapsed` option.

```ruby
section "Resources", icon: "resources", collapsable: true, collapsed: true do
  resource :course
end
```

You might want to allow your users to hide certain items from view.

## Authorization

If you use the authorization feature, you will need an easy way to authorize your items in the menu builder.
For that scenario, we added the `authorize` helper.

```ruby{3}
Avo.configure do |config|
  config.main_menu = -> {
    resource :team, visible: -> {
      # authorize current_user, THE_RESOURCE_MODEL, THE_POLICY_METHOD, raise_exception: false
      authorize current_user, Team, "index?", raise_exception: false
    }
  }
end
```

Use it in the `visible` block by giving it the `current_user` (which is available in that block), the class of the resource, the method that you'd like to authorize for (default is `index?`), and tell it not to throw an exception.

Now, the item visibility will use the `index?` method from the `TeamPolicy` class.

## Profile menu

The profile menu allows you to add items to the menu displayed in the profile component. **The sign-out link is automatically added for you.**

You may add the `icon` option to the `profile_menu` links.

```ruby
# config/initializers/avo.rb
Avo.configure do |config|
  config.profile_menu = -> {
    link_to "Profile", path: "/profile", icon: "user-circle"
  }
end
```

## Forms in profile menu

It's common to have forms that `POST` to a path to do sign ut a user. For this scenario we added the `method` and `params` option to the profile item `link_to`, so if you have a custom sign out path you can do things like this.

```ruby
# config/initializers/avo.rb
Avo.configure do |config|
  config.profile_menu = -> {
    link_to "Sign out", path: main_app.destroy_user_session_path, icon: "user-circle", method: :post, params: {custom_param: :here}
  }
end
```

## Custom content in the profile menu

You might, however, wnat to add a very custom form or more items to the profile menu. For that we prepared the `_profile_menu_extra.html.erb` partial for you.

```bash
bin/rails generate avo:eject :profile_menu_extra
```

This will eject the partial and you can add whatever custom content you might need.

```erb
<%# Example link below %>
<%#= render Avo::ProfileItemComponent.new label: 'Profile', path: '/profile', icon: 'user-circle' %>
```

---

# Search

Finding what you're looking for fast is essential. That's why Avo leverages [ransack's](https://github.com/activerecord-hackery/ransack) powerful query language.

:::info
While we show you examples using `ransack`, you can use other search engines, so `ransack` is not mandatory.
:::

:::warning
If you're using the authorization feature, ensure [you authorize the action](#authorize-search).
:::

First, you need to add `ransack` as a dependency to your app (breaking change from Avo v1.10).

```ruby
# Gemfile
gem 'ransack'
```

## Enable search for a resource

To enable search for a resource, you need to add the `search_query` class variable to the resource file.

```ruby{3-5}
class UserResource < Avo::BaseResource
  self.title = :name
  self.search_query = -> do
    scope.ransack(id_eq: params[:q], first_name_cont: params[:q], last_name_cont: params[:q], m: "or").result(distinct: false)
  end

# fields go here
end
```

The `search_query` block passes over the `params` object that holds the `q` param, the actual query string. It also provides the `scope` variable on which you run the query. That ensures that the authorization scopes have been appropriately applied.

In this block, you may configure the search however strict or loose you need it. Check out [ransack's search matchers](https://github.com/activerecord-hackery/ransack#search-matchers) to compose the query better.

:::warning
If you're using ransack version 4 and up you must add `ransackable_attributes` and maybe more to your model in order for it to work. Read more about it [here](https://activerecord-hackery.github.io/ransack/going-further/other-notes/#authorization-allowlistingdenylisting).
:::

## Authorize search

Since Avo 2.29 search is authorized in policy files using the `search?` method.

```ruby
class UserPolicy < ApplicationPolicy
  def search?
    true
  end
end
```

If the `search?` method returns false, the search operation for that resource is not going to show up in the global search and the search box on index is not going to be displayed.

If you're using `search?` already in your policy file, you can alias it to some other method in you initializer using the `config.authorization_methods` config. More about that on the authorization page.

```ruby
Avo.configure do |config|
  config.authorization_methods = {
    search: 'avo_search?',
  }
  end
```

## Configure the search result

### Label

By default, the search results will be displayed as text. The text label will be the title column you previously configured.

You may configure that to be something more complex using the `as_label` option. That will take the final value of that field and display it as the label of the search result.

```ruby{9-11}
class PostResource < Avo::BaseResource
  self.title = :name
  self.search_query = -> do
    scope.ransack(id_eq: params[:q], m: "or").result(distinct: false)
  end

field :id, as: :id
  field :name, as: :text, required: true, as_label: true
  field :complex_name, as: :text, hide_on: :all, as_label: true do |model|
    "[#{model.id}]#{model.name}"
  end
end
```

Notice the `hide_on: :all` option used to hide the computed `complex_name` attribute from the rest of the views. That is because you **may or may not** want to show that attribute in other views.

### Description

<div class="rounded-md bg-blue-50 p-4">
  <div class="flex">
    <div class="flex-shrink-0">
      <svg class="h-5 w-5 text-blue-400" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor">
        <path fill-rule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z" clip-rule="evenodd" />
      </svg>
    </div>
    <div class="ml-3 flex-1 md:flex md:justify-between">
      <div class="text-sm leading-5 text-blue-700">
        Search Description is a <a href="https://avohq.io/purchase/pro" target="_blank" class="underline">pro</a> feature
      </div>
    </div>
  </div>
</div>

You might want to show more than just the title in the search result. Avo provides the `as_description` option to add some more information.

```ruby{12-16}
class PostResource < Avo::BaseResource
  self.title = :name
  self.search_query = -> do
    scope.ransack(id_eq: params[:q], m: "or").result(distinct: false)
  end

field :id, as: :id
  field :name, as: :text, required: true, as_label: true
  field :complex_name, as: :text, hide_on: :all, as_label: true do |model|
    "[#{model.id}]#{model.name}"
  end
  field :excerpt, as: :text, as_description: true do |model|
    ActionView::Base.full_sanitizer.sanitize(model.body).truncate 130
  rescue
    ""
  end
end
```

### Avatar

* Search Avatar is a [Pro feature](https://avohq.io/purchase/pro).

You may improve the results listing by adding an avatar to each search result. You do that by using the `as_avatar` attribute. This attribute has three options `:square`, `:rounded` or `:circle`. That influences the final roundness of the avatar.

```ruby{17}
class PostResource < Avo::BaseResource
  self.title = :name
  self.search_query = -> do
    scope.ransack(id_eq: params[:q], m: "or").result(distinct: false)
  end

### Header Help Text

You may improve the results listing header by adding a piece of text highlighting the fields you are looking for or any other instruction for the user. You do that by using the `search_query_help` attribute. This attribute takes a string and appends it to the title of the resource.

```ruby{6}
class PostResource < Avo::BaseResource
  self.title = :name
  self.search_query = -> do
    scope.ransack(id_eq: params[:q], m: "or").result(distinct: false)
  end
  self.search_query_help = "- search by id"

field :id, as: :id
end
```

## Resource search

When a resource has the `search_query` attribute, a new search input will be displayed on the `Index` view.

![](/assets/img/search/resource_search.jpg)

## Global search

Avo also has a global search feature. It will search through all the resources that have the `search_query` attribute present.

You open the global search input by clicking the trigger on the navbar or by using the <kbd>CMD</kbd> + <kbd>K</kbd> keyboard shortcut (<kbd>Ctrl</kbd> + <kbd>K</kbd> on windows).

### Hide the global search

If you, by any chance, want to hide the global search, you can do so using this setting 👇

```ruby{3}
# config/initializers/avo.rb
Avo.configure do |config|
  config.disabled_features = [:global_search]
end
```

## Hide a resource from the global search

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_from_global_search = true`.

```ruby{8}
class TeamMembershipResource < Avo::BaseResource
  self.title = :id
  self.includes = [:user, :team]
  self.visible_on_sidebar = false
  self.search_query = -> do
    scope.ransack(id_eq: params[:q], m: "or").result(distinct: false)
  end
  self.hide_from_global_search = true

field :id, as: :id
  field :user, as: :belongs_to
  field :team, as: :belongs_to
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{8}
class OrderResource < Avo::BaseResource
  self.search_query = -> do
    if params[:global]
      # Perform global search
      scope.ransack(id_eq: params[:q], m: "or").result(distinct: false)
    else
      # Perform resource search
      scope.ransack(id_eq: params[:q], details_cont: params[:q], m: "or").result(distinct: false)
    end
  end
end
```

## Search result path

By default, when a user clicks on a search result, they will be redirected to that record, but you can change that using the `search_result_path` option.

```ruby
class CityResource < Avo::BaseResource
  self.search_result_path = -> {
    # Return any path here. You have access to the search `record` the user clicked on.
    avo.resources_city_path record, custom: "yup"
  }
end
```

---

# Filters

Filters allow you to better scope the index queries for records you are looking for.

## Defining filters

Avo has two types of filters available at the moment [Boolean filter](#boolean-filter) and [Select filter](#select-filter).

### Filter values

Because the filters get serialized back and forth, the final `value`/`values` in the `apply` method will be stringified or have the keys stringified if they are hashes. You can declare them as regular hashes (with the keys symbolized) in the `options` method, but they will get stringified in the end.

## Boolean Filter

You generate one running `bin/rails generate avo:filter featured_filter`, creating a filter configuration file.

```ruby
class FeaturedFilter < 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 FeaturedFilter < 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 Filter

Select filters are similar to Boolean ones. For example, you generate one running `rails generate avo:filter published_filter --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 PublishedFilter < 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 PublishedFilter < 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
```

## Multiple select filter

You may also use a multiple select filter.

```ruby
class PostStatusFilter < 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
```

## Dynamic options

The select filter can also take dynamic options:

```ruby{15-17}
class AuthorFilter < Avo::Filters::SelectFilter
  self.name = 'Author'

def apply(request, query, value)
    query = query.where(author_id: value) if value.present?
    query
  end

# Example `applied_filters`
  # applied_filters = {
  #   "CourseCountryFilter" => {
  #     "USA" => true,
  #     "Japan" => true,
  #     "Spain" => false,
  #     "Thailand" => false,
  #   }
  # }
  def options
    # Here you have access to the `applied_filters` object too
    Author.select(:id, :name).each_with_object({}) { |author, options| options[author.id] = author.name }
  end
end
```

## Text Filter

You can add complex text filters to Avo by running `rails generate avo:filter name_filter --text`.

```ruby
class NameFilter < 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
```

## Default value

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.

## Registering filters

To add a filter to one of your resources, you need to declare it on the resource using the `filter` method to which you pass the filter class.

```ruby{8}
class PostResource < Avo::BaseResource
  self.title = :name
  self.search = :id

field :id, as: :id
  # other fields

filter PublishedFilter
end
```

## Dynamic filter options

You might want to compose more advanced filters, like when you have two filters, one for the country and another for cities, and you'd like to have the cities one populated with cities from the selected country.

Let's take the `CourseResource` as an example.

```ruby{3-5,7-14}
# app/models/course.rb
class Course < ApplicationRecord
  def self.countries
    ["USA", "Japan", "Spain", "Thailand"]
  end

def self.cities
    {
      USA: ["New York", "Los Angeles", "San Francisco", "Boston", "Philadelphia"],
      Japan: ["Tokyo", "Osaka", "Kyoto", "Hiroshima", "Yokohama", "Nagoya", "Kobe"],
      Spain: ["Madrid", "Valencia", "Barcelona"],
      Thailand: ["Chiang Mai", "Bangkok", "Phuket"]
    }
  end
end
```

We will create two filters—one for choosing countries and another for cities.

```ruby{3-4}
# app/avo/resources/course_resource.rb
class CourseResource < Avo::BaseResource
  filter CourseCountryFilter
  filter CourseCityFilter
end
```

The country filter is pretty straightforward. Set the query so the `country` field to be one of the selected countries and the `options` are the available countries as `Hash`.

```ruby{6,10}
# app/avo/filters/course_country_filter.rb
class CourseCountryFilter < Avo::Filters::BooleanFilter
  self.name = "Course country filter"

def apply(request, query, values)
    query.where(country: values.select { |country, selected| selected }.keys)
  end

def options
    Course.countries.map { |country| [country, country] }.to_h
  end
end
```

The cities filter has a few more methods to manage the data better, but the gist is the same. The `query` makes sure the records have the city value in one of the cities that have been selected.

The `options` method gets the selected countries from the countries filter (`CourseCountryFilter`) and formats them to a `Hash`.

```ruby{6,10}
# app/avo/filters/course_city_filter.rb
class CourseCityFilter < Avo::Filters::BooleanFilter
  self.name = "Course city filter"

def apply(request, query, values)
    query.where(city: values.select { |city, selected| selected }.keys)
  end

def options
    cities_for_countries countries
  end

private

# Get a hash of cities for certain countries
  # Example payload:
  # countries = ["USA", "Japan"]
  def cities_for_countries(countries_array = [])
    countries_array
      .map do |country|
        # Get the cities for this country
        Course.cities.stringify_keys[country]
      end
      .flatten
      # Prepare to transform to a Hash
      .map { |city| [city, city] }
      # Turn to a Hash
      .to_h
  end

# Get the value of the selected countries
  # Example payload:
  # applied_filters = {
  #   "CourseCountryFilter" => {
  #     "USA" => true,
  #     "Japan" => true,
  #     "Spain" => false,
  #     "Thailand" => false,
  #   }
  # }
  def countries
    if applied_filters["CourseCountryFilter"].present?
      # Fetch the value of the countries filter
      applied_filters["CourseCountryFilter"]
        # Keep only the ones selected
        .select { |country, selected| selected }
        # Pluck the name of the coutnry
        .keys
    else
      # Return empty array
      []
    end
  end
end
```

The `countries` method above will check if the `CourseCountryFilter` has anything selected. If so, get the names of the chosen ones. This way, you show only the cities from the selected countries and not all of them.

## React to filters

Going further with the example above, a filter can react to other filters. For example, let's say that when a user selects `USA` from the list of countries, you want to display a list of cities from the USA (that's already happening in `options`), and you'd like to select the first one on the list. You can do that with the `react` method.

```ruby{13-28}
# app/avo/filters/course_city_filter.rb
class CourseCityFilter < Avo::Filters::BooleanFilter
  self.name = "Course city filter"

def apply(request, query, values)
    query.where(city: values.select { |city, selected| selected }.keys)
  end

def options
    cities_for_countries countries
  end

# applied_filters = {
  #   "CourseCountryFilter" => {
  #     "USA" => true,
  #     "Japan" => true,
  #     "Spain" => false,
  #     "Thailand" => false,
  #   }
  # }
  def react
    # Check if the user selected a country
    if applied_filters["CourseCountryFilter"].present? && applied_filters["CourseCityFilter"].blank?
      # Get the selected countries, get their cities, and select the first one.
      selected_countries = applied_filters["CourseCountryFilter"].select do |name, selected|
        selected
      end

# Get the first city
      cities = cities_for_countries(selected_countries.keys)
      first_city = cities.first.first

# Return the first city as selected
      [[first_city, true]].to_h
    end
  end

private

# Get the value of the selected countries
  # Example `applied_filters` payload:
  # applied_filters = {
  #   "CourseCountryFilter" => {
  #     "USA" => true,
  #     "Japan" => true,
  #     "Spain" => false,
  #     "Thailand" => false,
  #   }
  # }
  def countries
    if applied_filters["CourseCountryFilter"].present?
      # Fetch the value of the countries filter
      applied_filters["CourseCountryFilter"]
        # Keep only the ones selected
        .select { |country, selected| selected }
        # Pluck the name of the coutnry
        .keys
    else
      # Return empty array
      []
    end
  end
end
```

After all, filters are applied, the `react` method is called, so you have access to the `applied_filters` object.
Using the applied filter payload, you can return the value of the current filter.

```ruby
def react
  # Check if the user selected a country
  if applied_filters["CourseCountryFilter"].present? && applied_filters["CourseCityFilter"].blank?
    # Get the selected countries, get their cities, and select the first one.
    selected_countries = applied_filters["CourseCountryFilter"]
      .select do |name, selected|
        selected
      end

# Get the first city
    cities = cities_for_countries(selected_countries.keys)
    first_city = cities.first.first

# Return the first city selected as a Hash
    [[first_city, true]].to_h
  end
end
```

Besides checking if the countries filter is populated (`applied_filters["CourseCountryFilter"].present?`), we also want to allow the user to customize the cities filter further, so we need to check if the user has added a value to that filter (`applied_filters["CourseCityFilter"].blank?`).
If these conditions are true, the country filter has a value, and the user hasn't selected any values from the cities filter, we can react to it and set a value as the default one.

Of course, you can modify the logic and return all kinds of values based on your needs.

## Empty message text

There might be times when you will want to show a message to the user when you're not returning any options. You may customize that message using the `empty_message` option.

```ruby{4}
# app/avo/filters/course_city_filter.rb
class CourseCityFilter < Avo::Filters::BooleanFilter
  self.name = "Course city filter"
  self.empty_message = "Please select a country to view options."

def apply(request, query, values)
    query.where(city: values.select { |city, selected| selected }.keys)
  end

def options
    if countries.present?
      []
    else
      ["Los Angeles", "New York"]
    end
  end

private

def countries
    # logic to fetch the countries
  end
end
```

## Keep filters panel open

There are scenarios where you wouldn't want to close the filters panel when you change the values. For that, you can use the `keep_filters_panel_open` resource option.

```ruby{2}
class CourseResource < Avo::BaseResource
  self.keep_filters_panel_open = true

field :id, as: :id
  field :name, as: :text
  field :country, as: :select, options: Course.countries.map { |country| [country, country] }.to_h
  field :city, as: :select, options: Course.cities.values.flatten.map { |country| [country, country] }.to_h
  field :links, as: :has_many, searchable: true, placeholder: "Click to choose a link"

filter CourseCountryFilter
  filter CourseCityFilter
end
```

## Visibility

You may want to manipulate your filter visibility on screens. You can do that using the `self.visible` attribute.

Inside the visible block you can acces the following variables:
```ruby
  self.visible = -> do
    #   You have access to:
    #   block
    #   context
    #   current_user
    #   params
    #   parent_model
    #   parent_resource
    #   resource
    #   view
    #   view_context
  end
```

## Filters arguments

Filters can have different behaviors according to their host resource. In order to achieve that, arguments must be passed like on the example below:

```ruby{9-11}
class FishResource < Avo::BaseResource
  self.title = :name

field :id, as: :id
  field :name, as: :text
  field :user, as: :belongs_to
  field :type, as: :text, hide_on: :forms

filter NameFilter, arguments: {
    case_insensitive: true
  }
end
```

Now, the arguments can be accessed inside `NameFilter` ***`apply` method*** and on the ***`visible` block***!

```ruby{4-6,8-14}
class NameFilter < Avo::Filters::TextFilter
  self.name = "Name filter"
  self.button_label = "Filter by name"
  self.visible = -> do
    arguments[:case_insensitive]
  end

def apply(request, query, value)
    if arguments[:case_insensitive]
      query.where("LOWER(name) LIKE ?", "%#{value.downcase}%")
    else
      query.where("name LIKE ?", "%#{value}%")
    end
  end
end
```

## Manually create encoded URLs

You may want to redirect users to filtered states of the <Index /> view from other places in your app. In order to create those filtered states you may use these helpers functions or Rails helpers.

### Rails helpers

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 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
```
</Option>

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 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
```
</Option>

### Standalone helpers

Decodes the `filters` param. This standalone method can be used anywhere.

#### Usage

```ruby
class 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
```
</Option>

Encodes a `filters` object into a serialized state that Avo understands. This standalone method can be used anywhere.

#### Usage

```ruby
class DummyAction < Avo::BaseAction
  self.name = "Dummy action"

def handle(**args)
    do_something_important

redirect_to avo.resources_users_path(filters: Avo::Filters::BaseFilter.encode_filters({"NameFilter"=>"Apple"}))
  end
end
```
</Option>

## Persistent filters

By default, when a user visits an <Index /> view of a resource the filters payload will be empty, so they will be set on their [default values](#default-value).

---

# Actions

Avo actions allow you to perform specific tasks on one or more of your records.

For example, you might want to mark a user as active/inactive and optionally send a message that may be customized by the person that wants to run the action.

Once you attach an action to a resource using the `action` method, it will appear in the **Actions** dropdown. By default, actions appear on the `Index`, `Show`, and `Edit` views. Versions previous to 2.9 would only display the actions on the `Index` and `Show` views.

!Actions dropdown

:::info
Since version <Version version="2.13" /> you may use the customizable controls feature to show the actions outside the dropdown.
:::

## Overview

You generate one running `bin/rails generate avo:action toggle_inactive`, creating an action configuration file.

```ruby
class ToggleInactive < Avo::BaseAction
  self.name = 'Toggle inactive'

field :notify_user, as: :boolean, default: true
  field :message, as: :text, default: 'Your account has been marked as inactive.'

def handle(**args)
    models, fields, current_user, resource = args.values_at(:models, :fields, :current_user, :resource)

models.each do |model|
      if model.active
        model.update active: false
      else
        model.update active: true
      end

# Optionally, you may send a notification with the message to that user from inside the action
      UserMailer.with(user: model).toggle_inactive(fields["message"]).deliver_later
    end

succeed 'Perfect!'
  end
end
```

You may add fields to the action just as you do it in a resource. Adding fields is optional. You may have actions that don't have any fields attached.

```ruby
field :notify_user, as: :boolean
field :message, as: :textarea, default: 'Your account has been marked as inactive.'
```

:::warning Files authorization
If you're using the `file` field on an action and attach it to a resource that's using the authorization feature, please ensure you have the `upload_{FIELD_ID}?` policy method returning `true`. Otherwise, the `file` input might be hidden.

More about this on the authorization page.
:::

!Actions

The `handle` method is where the magic happens. That is where you put your action logic. In this method, you will have access to the selected `models` (if there's only one, it will be automatically wrapped in an array) and the values passed to the `fields`.

```ruby
def handle(**args)
  models, fields = args.values_at(:models, :fields)

models.each do |model|
    if model.active
      model.update active: false
    else
      model.update active: true
    end

# Optionally, you may send a notification with the message to that user.
    UserMailer.with(user: model).toggle_inactive(fields["message"]).deliver_later
  end

succeed 'Perfect!'
end
```

## Registering actions

To add an action to one of your resources, you need to declare it on the resource using the `action` method.

```ruby{8}
class UserResource < Avo::BaseResource
  self.title = :name
  self.search = [:id, :first_name, :last_name]

field :id, as: :id
  # other fields

action ToggleActive
end
```

## Action responses

After an action runs, you may use several methods to respond to the user. For example, you may respond with just a message or with a message and an action.

The default response is to reload the page and show the _Action ran successfully_ message.

### Message responses

You will have four message response methods at your disposal `succeed`, `error`, `warn`, and `inform`. These will render the user green, red, orange, and blue alerts.

```ruby{4-7}
def handle(**args)
  # Demo handle action

succeed "Success response ✌️"
  warn "Warning response ✌️"
  inform "Info response ✌️"
  error "Error response ✌️"
end
```

:::warning
Since Avo 2.20 we deprecated the `fail` method in favor of `error`.
:::

### Run actions silently

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
def handle(**args)
  # Demo handle action

redirect_to "/admin/some-tool"
  silent
end
```

## Response types

After you notify the user about what happened through a message, you may want to execute an action like `reload` (default action) or `redirect_to`. You may use message and action responses together.

```ruby{14}
def handle(**args)
  models = args[:models]

models.each do |model|
    if model.admin?
      error "Can't mark inactive! The user is an admin."
    else
      model.update active: false

succeed "Done! User marked as inactive!"
    end
  end

reload
end
```

The available action responses are:

When you use `reload`, a full-page reload will be triggered.

```ruby{9}
def handle(**args)
  models = args[:models]

models.each do |project|
    project.update active: false
  end

succeed 'Done!'
  reload
end
```

</Option>
<Option name="`redirect_to`">

`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(**args)
  models = args[:models]

models.each do |project|
    project.update active: false
  end

succeed 'Done!'
  redirect_to avo.resources_users_path
end
```

You may want to redirect to another action. Here's an example of how to create a multi-step process, passing arguments from one action to another.
In this example the initial action prompts the user to select the fields they wish to update, and in the subsequent action, the chosen fields will be accessible for updating.

:::code-group
```ruby[PreUpdate]
class PreUpdate < Avo::BaseAction
  self.name = "Update"
  self.message = "Set the fields you want to update."

with_options as: :boolean do
    field :first_name
    field :last_name
    field :user_email
    field :active
    field :admin
  end

def handle(**args)
    arguments = Base64.encode64 Avo::Services::EncryptionService.encrypt(
      message: {
        render_first_name: args[:fields][:first_name],
        render_last_name: args[:fields][:last_name],
        render_user_email: args[:fields][:user_email],
        render_active: args[:fields][:active],
        render_admin: args[:fields][:admin]
      },
      purpose: :action_arguments
    )

redirect_to "/admin/resources/users/actions?action_id=Update&arguments=#{arguments}", turbo_frame: "actions_show"
  end
end
```

```ruby[Update]
class Update < Avo::BaseAction
  self.name = "Update"
  self.message = ""
  self.visible = -> do
    false
  end

{
    first_name: :text,
    last_name: :text,
    user_email: :text,
    active: :boolean,
    admin: :boolean
  }.each do |field_name, field_type|
    field field_name.to_sym, as: field_type, visible: -> (resource:) {
      Avo::Services::EncryptionService.decrypt(
        message: Base64.decode64(resource.params[:arguments]),
        purpose: :action_arguments
      ).dig("render_#{field_name}".to_sym)
    }
  end

def handle(models:, fields:, **args)
    non_roles_fields = fields.slice!(:admin)

models.each { |model| model.update!(non_roles_fields) }

fields.each do |field_name, field_value|
      models.each { |model|  model.update! roles: model.roles.merge!({"#{field_name}": field_value}) }
    end

succeed "User(s) updated!"
  end
end
```
:::

:::info `turbo_frame`
Notice the `turbo_frame: "actions_show"` present on the redirect of `PreUpdate` action. That argument is essential to have a flawless redirect between the actions.
:::
</Option>

<Option name="`turbo`">
There are times when you don't want to perform the actions with Turbo. In such cases, turbo should be set to false.
</Option>

`download` will start a file download to your specified `path` and `filename`.

**You need to set may_download_file to true for the download response to work like below**. That's required because we can't respond with a file download (send_data) when making a Turbo request.

If you find another way, please let us know 😅.

:::code-group

```ruby{3,19} [app/avo/actions/download_file.rb]
class DownloadFile < Avo::BaseAction
  self.name = "Download file"
  self.may_download_file = true

def handle(**args)
    models = args[:models]

filename = "projects.csv"
    report_data = []

models.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{5} [app/avo/resources/project_resource.rb]
class ProjectResource < Avo::BaseResource

# fields here

action DownloadFile
end
```
:::
</Option>

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 and the inputs filled in.

`keep_modal_open` will tell Avo to keep the modal open.

```ruby
class KeepModalOpenAction < Avo::BaseAction
  self.name = "Keep Modal Open"
  self.standalone = true

field :name, as: :text
  field :birthday, as: :date

def handle(**args)
    begin
    user = User.create args[:fields]
    rescue => error
      error "Something happened: #{error.message}"
      keep_modal_open
      return
    end

succeed "All good ✌️"
  end
end
```
</Option>

## Customization

```ruby{2-6}
class TogglePublished < Avo::BaseAction
  self.name = 'Mark inactive'
  self.message = 'Are you sure you want to mark this user as inactive?'
  self.confirm_button_label = 'Mark inactive'
  self.cancel_button_label = 'Not yet'
  self.no_confirmation = true
```

### Customize the message

You may update the `self.message` class attribute to customize the message if there are no fields present.

#### Callable message

Since version `2.21` you can pass a block to `self.message` where you have access to a baunch of variables.

```ruby
class ReleaseFish < Avo::BaseAction
  self.message = -> {
    # you have access to:
    # - params
    # - current_user
    # - context
    # - view_context
    # - request
    # - resource
    # - record
    "Are you sure you want to release the #{record.name}?"
  }
end
```

### Customize the buttons

You may customize the labels for the action buttons using `confirm_button_label` and `cancel_button_label`.

### No confirmation actions

You will be prompted by a confirmation modal when you run an action. If you don't want to show the confirmation modal, pass in the `self.no_confirmation = true` class attribute. That will execute the action without showing the modal at all.

## Standalone actions

You may need to run actions that are not necessarily tied to a model. Standalone actions help you do just that. Add `self.standalone` to an existing action or generate a new one using the `--standalone` option (`bin/rails generate avo:action global_action --standalone`).

```ruby{3}
class DummyAction < Avo::BaseAction
  self.name = "Dummy action"
  self.standalone = true

def handle(**args)
    fields, current_user, resource = args.values_at(:fields, :current_user, :resource)

# Do something here

succeed 'Yup'
  end
end
```

## Actions visibility

You may want to hide specific actions on screens, like a standalone action on the `Show` screen. You can do that using the `self.visible` attribute.

```ruby{4}
class DummyAction < Avo::BaseAction
  self.name = "Dummy action"
  self.standalone = true
  self.visible = -> { view == :index }

def handle(**args)
    fields, current_user, resource = args.values_at(:fields, :current_user, :resource)

# Do something here

succeed 'Yup'
  end
end
```

By default, actions are visible on the `Index`, `Show`, and `Edit` views, but you can enable them on the `New` screen, too (from version 2.9.0).

```ruby
self.visible = -> { view == :new }

# Or use this if you want them to be visible on any view
self.visible = -> { true }
```

Inside the visible block you can access the following variables:
```ruby
  self.visible = -> do
    #   You have access to:
    #   block
    #   context
    #   current_user
    #   params
    #   parent_resource (can access the parent_model by parent_resource.model)
    #   resource (can access the model by resource.model)
    #   view
    #   view_context
  end
```

## Actions authorization

:::warning
Using the Pundit policies, you can restrict access to actions using the `act_on?` method. If you think you should see an action on a resource and you don't, please check the policy method.

More info here
:::

## Actions arguments

Actions can have different behaviors according to their host resource. In order to achieve that, arguments must be passed like on the example below:

```ruby{9-11}
class FishResource < Avo::BaseResource
  self.title = :name

field :id, as: :id
  field :name, as: :text
  field :user, as: :belongs_to
  field :type, as: :text, hide_on: :forms

action DummyAction, arguments: {
    special_message: true
  }
end
```

Now, the arguments can be accessed inside `DummyAction` ***`handle` method*** and on the ***`visible` block***!

```ruby{4-6,8-14}
class DummyAction < Avo::BaseAction
  self.name = "Dummy action"
  self.standalone = true
  self.visible = -> do
    arguments[:special_message]
  end

def handle(**args)
    if arguments[:special_message]
      succeed "I love 🥑"
    else
      succeed "Success response ✌️"
    end
  end
end
```

---

# Localization (i18n)

Avo leverages Rails' powerful I18n translations module. When you run `bin/rails avo:install`, Rails will generate for you the `avo.en.yml` translation file. This file 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_resource.rb
class UserResource < 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{7}
# app/avo/resources/project_resource.rb
class ProjectResource < Avo::BaseResource
  self.title = :name

field :id, as: :id
  # ... other fields
  field :files, as: :files, translation_key: 'avo.field_translations.file'
end
```

```yaml{6-10}
# avo.es.yml
es:
  avo:
    dashboard: 'Dashboard'
    # ... other translation keys
    field_translations:
      file:
        zero: 'archivos'
        one: 'archivo'
        other: 'archivos'
```

## Setting the locale

Setting the locale for Avo is simple. Just use the `config.locale = :en` config attribute. Default is `nil` and will fall back to whatever you have configured in `application.rb`.

```ruby{2}
Avo.configure do |config|
  config.locale = :en # default is nil
end
```

That will change the locale only for Avo requests. The rest of your app will still use your locale set in `application.rb`. If you wish to change the locale for the whole app, you can use the `set_locale=pt-BR` param. That will set the default locale until you restart your server.

Suppose you wish to change the locale only for one request using the `force_locale=pt-BR` param. That will set the locale for that request and keep the `force_locale` param while you navigate Avo. Remove that param when you want to go back to your configured `default_locale`.

Check out our guide for multilingual records.

## Re-generate the locale

When updating Avo, please run `bin/rails generate avo:locales` to re-generate the locales file.

## FAQ

If you try to localize your resources and fields and it doesn't seem to work, please be aware of the following.

### Advanced localization is a Pro feature

Localizing strings in Avo will still work using Rails' `I18n` mechanism, but localizing files and resources require a `Pro` or above license.

The reasoning is that deep localization is a more advanced feature that usually falls in the commercial realm. So if you create commercial products or apps for clients and make revenue using Avo, we'd love to get your support to maintain it and ship new features going forward.

### The I18n.t method defaults to the name of that field/resource

Internally the localization works like so `I18n.t(translation_key, count: 1, default: default)` where the `default` is the computed field/resource name. So check the structure of your translation keys.

```yaml
# config/locales/avo.pt-BR.yml
pt-BR:
  avo:
    field_translations:
      file:
        zero: 'arquivos'
        one: 'arquivo'
        other: 'arquivos'
    resource_translations:
      user:
        zero: 'usuários'
        one: 'usuário'
        other: 'usuários'
```

---

# Branding

```ruby
Avo.configure do |config|
  config.branding = {
    colors: {
      background: "248 246 242",
      100 => "#C5F1D4",
      400 => "#3CD070",
      500 => "#30A65A",
      600 => "#247D43",
    },
    chart_colors: ['#FFB435', "#FFA102", "#CC8102", '#FFB435', "#FFA102", "#CC8102"],
    logo: "/avo-assets/logo.png",
    logomark: "/avo-assets/logomark.png",
    placeholder: "/avo-assets/placeholder.svg",
    favicon: "/avo-assets/favicon.ico"
  }
end
```

Using the branding feature, you can easily change the look of your app. You tweak it inside your `avo.rb` initializer in the `branding` attribute. It takes a hash with a few properties.

## Configure brand color

To customize the primary color of Avo, you must configure the `colors` key with four color variants. `100` for color hints, `500` for the base primary color, and `400` and `600` values for highlights.

```ruby{4-8}
Avo.configure do |config|
  config.branding = {
    colors: {
      background: "248 246 242",
      100 => "#C5F1D4",
      400 => "#3CD070",
      500 => "#30A65A",
      600 => "#247D43",
    }
  }
end
```

You may also customize the color of Avo's background using the `background` key.

![](/assets/img/branding/green.jpg)

![](/assets/img/branding/red.jpg)

![](/assets/img/branding/orange.jpg)

:::info
The color format can be hex (starting with `#`) or rgb (three groups split by a space, not a comma).
:::

Avo uses [Tailwinds color system](https://tailwindcss.com/docs/customizing-colors). You can generate your own using the tools below.

- [Palettte](https://palettte.app/)
 - [ColorBox](https://colorbox.io/)
 - [TailwindInk](https://tailwind.ink/)

Here are a few for you to choose from.

```ruby
config.branding = {
  colors: {
    # BLUE
    100 => "#CEE7F8",
    400 => "#399EE5",
    500 => "#0886DE",
    600 => "#066BB2",
    # RED
    100 => "#FACDD4",
    400 => "#F06A7D",
    500 => "#EB3851",
    600 => "#E60626",
    # GREEN
    100 => "#C5F1D4",
    400 => "#3CD070",
    500 => "#30A65A",
    600 => "#247D43",
    # ORANGE
    100 => "#FFECCC",
    400 => "#FFB435",
    500 => "#FFA102",
    600 => "#CC8102",
  }
}
```

## Customize the chart colors

For your dashboard, you can further customize the colors of the charts. You can do that using the `chart_colors` option. Pass in an array of colors, and Avo will do the rest.

```ruby
Avo.configure do |config|
  config.branding = {
    chart_colors: ['#FFB435', "#FFA102", "#CC8102", '#FFB435', "#FFA102", "#CC8102"],
  }
end
```

![](/assets/img/branding/chart-colors.jpg)

:::warning
The chart colors should be hex colors. They are forwarded to chart.js
:::

## Customize the logo

We want to make it easy to change the logo for your app, so we added the `logo` and `logomark` options to the branding feature.

The `logo` should be the "big" logo you want to display on the desktop version of your app, and `logomark` should be a squared-aspect image that Avo displays on the mobile version.

![](/assets/img/branding/logomark.gif)

## Customize the missing image placeholder

When you view the data in the <Index /> view in a grid, when the `cover` field does not have an image, an avocado is going to be displayed instead as a placeholder.

You might want to change that to something else using the `placeholder` option.

```ruby
Avo.configure do |config|
  config.branding = {
    placeholder: "/YOUR_PLACEHOLDER_IMAGE.jpg",
  }
end
```

## Customize the favicon

We want to make it easy to change the logo for your app, so we added the `favicon` option to the branding feature.
Overwrite it using an `.ico` file.

---

# Custom pages (custom tools)

You may use custom tools to create custom sections or views to add to your app.

## Generate tools

`bin/rails generate avo:tool dashboard` will generate the necessary files to show the new custom tool.

```bash{2-6}
▶ bin/rails generate avo:tool dashboard
      create  app/views/avo/sidebar/items/_dashboard.html.erb
      insert  app/controllers/avo/tools_controller.rb
      create  app/views/avo/tools/dashboard.html.erb
       route  namespace :avo do
  get "dashboard", to: "tools#dashboard"
end
```

### Controller

If this is your first custom tool, a new `ToolsController` will be generated for you. Within this controller, Avo created a new method.

```ruby
class Avo::ToolsController < Avo::ApplicationController
  def dashboard
  end
end
```

You can keep this action in this controller or move it to another controller and organize it differently.

### Route

```ruby{2-4}
Rails.application.routes.draw do
  namespace :avo do
    get "dashboard", to: "tools#dashboard"
  end

authenticate :user, ->(user) { user.admin? } do
    mount Avo::Engine => Avo.configuration.root_path
  end
end
```

The route generated is wrapped inside a namespace with the `Avo.configuration.root_path` name. Therefore, you may move it inside your authentication block next to the Avo mounting call.

### Sidebar item

The `_dashboard.html.erb` partial will be added to the `app/views/avo/sidebar/items` directory. All the files in this directory will be loaded by Avo and displayed in the sidebar. They are displayed alphabetically, so you may change their names to reorder the items.

### Customize the sidebar

If you want to customize the sidebar partial further, you can eject and update it to your liking. We're planning on creating a better sidebar customization experience later this year.

## Add assets

You might want to import assets (javascript and stylesheets files) when creating custom tools or fields. You can do that so easily from v1.3. Please follow this guide to bring your assets with your asset pipeline.

## Using helpers from your app

You'll probably want to use some of your helpers in your custom tools. To have them available inside your custom controllers inherited from Avo's `ApplicationController`, you need to include them using the `helper` method.

```ruby{3-5,10}
# app/helpers/home_helper.rb
module HomeHelper
  def custom_helper
    'hey from custom helper'
  end
end

# app/controllers/avo/tools_controller.rb
class Avo::ToolsController < Avo::ApplicationController
  helper HomeHelper

def dashboard
    @page_title = "Dashboard"
  end
end
```

```erb{13}
# app/views/avo/tools/dashboard.html.erb
<div class="flex flex-col">
  <%= render Avo::PanelComponent.new title: 'Dashboard', display_breadcrumbs: true do |c| %>
    <% c.with_tools do %>
      <div class="text-sm italic">This is the panels tools section.</div>
    <% end %>

<% c.with_body do %>
      <div class="flex flex-col justify-between py-6 min-h-24">
        <div class="px-6 space-y-4">
          <h3>What a nice new tool 👋</h3>

<%= custom_helper %>
        </div>
      </div>
    <% end %>
  <% end %>
</div>
```

### Using path helpers

Because you're in a Rails engine, you will have to prepend the engine object to the path.

#### For Avo paths

Instead of writing `resources_posts_path(1)` you have to write `avo.resources_posts_path(1)`.

#### For the main app paths

When you want to reference paths from your main app, instead of writing `posts_path(1)`, you have to write `main_app.posts_path`.

---

# Custom fields

Avo ships with 20+ well polished and ready to be used, fields out of the box.

When you need a field that is not provided by default, Avo makes it easy to add it.

## Generate a new field

Every new field comes with three [view components](https://viewcomponent.org/), `Edit` (which is also used in the `New` view), and `Show` and `Index`. There's also a `Field` configuration file.

`bin/rails generate avo:field progress_bar` generates the files for you.

:::info
Please restart your rails server after adding a new custom field.
:::

```bash{2-9}
▶ bin/rails generate avo:field progress_bar
      create  app/components/avo/fields/progress_bar_field
      create  app/components/avo/fields/progress_bar_field/edit_component.html.erb
      create  app/components/avo/fields/progress_bar_field/edit_component.rb
      create  app/components/avo/fields/progress_bar_field/index_component.html.erb
      create  app/components/avo/fields/progress_bar_field/index_component.rb
      create  app/components/avo/fields/progress_bar_field/show_component.html.erb
      create  app/components/avo/fields/progress_bar_field/show_component.rb
      create  app/avo/fields/progress_bar_field.rb
```

The `ProgressBarField` file is what registers the field in your admin.

```ruby
class ProgressBarField < Avo::Fields::BaseField
  def initialize(name, **args, &block)
    super(name, **args, &block)
  end
end
```

Now you can use your field like so:

```ruby{6}
# app/avo/resources/progress_bar_field.rb
class ProjectResource < Avo::BaseResource
  self.title = :name

field :id, as: :id, link_to_resource: true
  field :progress, as: :progress_bar
end
```
<img :src="('/assets/img/custom-fields/progress-show.jpg')" alt="Progress custom field" class="border mb-4" />

The generated view components are basic text fields for now.

```erb{1,9,14}
# app/components/avo/fields/progress_bar_field/edit_component.html.erb
<%= edit_field_wrapper field: @field, index: @index, form: @form, resource: @resource, displayed_in_modal: @displayed_in_modal do %>
  <%= @form.text_field @field.id,
    class: helpers.input_classes('w-full', has_error: @field.model_errors.include?(@field.id)),
    placeholder: @field.placeholder,
    disabled: @field.readonly %>
<% end %>

# app/components/avo/fields/progress_bar_field/index_component.html.erb
<%= index_field_wrapper field: @field do %>
  <%= @field.value %>
<% end %>

# app/components/avo/fields/progress_bar_field/show_component.html.erb
<%= show_field_wrapper field: @field, index: @index do %>
  <%= @field.value %>
<% end %>
```

You can customize them and add as much or as little content as needed. More on customization [below](#customize-the-views).

## 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 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,23}
# app/avo/fields/progress_bar_field.rb
class 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/progress_bar_field.rb
class ProjectResource < Avo::BaseResource
  self.title = :name

field :id, as: :id, link_to_resource: true
  field :progress, as: :progress_bar, step: 10, display_value: true, value_suffix: "%"
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 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 %>
    <div class="text-center text-sm font-semibold w-full leading-none mb-1">
      
      <%= @field.value %><%= @field.value_suffix if @field.value_suffix.present? %>
    </div>
  <% end %>

<progress max="<%= @field.max %>" value="<%= @field.value %>" class="block w-full"></progress>
<% end %>

# app/components/avo/fields/progress_bar_field/index_component.html.erb
<%= index_field_wrapper field: @field do %>
  
  <% if @field.display_value %>
    <div class="text-center text-sm font-semibold w-full leading-none mb-1">
      
      <%= @field.value %><%= @field.value_suffix if @field.value_suffix.present? %>
    </div>
  <% end %>

<progress max="<%= @field.max %>" value="<%= @field.value %>" class="block w-24"></progress>
<% end %>
```

For the `Edit` view, we're going to do something different. We'll implement a `range` input.

```erb{1}
# app/components/avo/fields/progress_bar_field/edit_component.html.erb
<%= edit_field_wrapper field: @field, index: @index, form: @form, resource: @resource, displayed_in_modal: @displayed_in_modal do %>
  
  <% if @field.display_value %>
    <div class="text-center text-sm font-semibold w-full leading-none mb-1">
      
      <span class="js-progress-bar-value-<%= @field.id %>"><%= @field.value %></span><%= @field.value_suffix if @field.value_suffix.present? %>
    </div>
  <% 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 %>

// Add an event listener for when the input is updated
input.addEventListener('input', updateValue);

// Update the value element with the value from the input
function updateValue(e) {
  log.textContent = e.target.value;
}
</script>
```
<img :src="('/assets/img/custom-fields/progress-edit.jpg')" alt="Progress bar custom field edit" class="border mb-4" />

## Field assets

Because there isn't just one standardized way of handling assets in Rails, we decided we won't provide **asset loading** support for custom fields for now. That doesn't mean that you can't use custom assets (javascript or CSS files), but you will have to load them in your own pipeline in dedicated Avo files.

In the example above, we added javascript on the page just to demonstrate the functionality. In reality, you might add that to a stimulus controller inside your own Avo dedicated pipeline (webpacker or sprockets).

Some styles were added in the asset pipeline directly.
```css
progress {
  @apply h-2 bg-white border border-gray-400 rounded shadow-inner;
}
progress[value]::-webkit-progress-bar {
  @apply bg-white border border-gray-500 rounded shadow-inner;
}
progress[value]::-webkit-progress-value{
  @apply bg-green-600 rounded;

}
progress[value]::-moz-progress-bar {
  @apply bg-green-600 rounded appearance-none;
}
```

## Use pre-built Stimulus controllers

Avo ships with a few Stimulus controllers that help you build more dynamic fields.

### Hidden input controller

This controller allows you to hide your content and add a trigger to show it. You'll find it in the Trix field.

You should add the `:always_show` `attr_reader` and `@always_show` instance variables to your field.

```ruby{3,8}
# app/avo/fields/color_picker_field.rb
class ColorPickerField < Avo::Fields::BaseField
  attr_reader :always_show

def initialize(id, **args, &block)
    super(id, **args, &block)

@always_show = args[:always_show] || false
    @allow_non_colors = args[:allow_non_colors]
  end
end
```

Next, in your fields `Show` component, you need to do a few things.

1. Wrap the field inside a controller tag
1. Add the trigger that will show the content.
1. Wrap the value in a div with the `hidden` class applied if the condition `@field.always_show` is `false`.
1. Add the `content` target (`data-hidden-input-target="content"`) to that div.

```erb{4-7,8}
# app/components/avo/fields/color_picker_field/show_component.html.erb

<%= show_field_wrapper field: @field, index: @index do %>
  <div data-controller="hidden-input">
    <% 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 %>
    <div <% unless @field.always_show %> class="hidden" <% end %> data-hidden-input-target="content">
      <div style="background-color: <%= @field.value %>"
        class="h-6 px-1 rounded-md text-white text-sm flex items-center justify-center leading-none"
      >
        <%= @field.value %>
      </div>
    </div>
  </div>
<% end %>
```

---

# 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 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
<div class="flex flex-col">
  <%= 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 %>
      <div class="flex flex-col p-4 min-h-24">
        <div class="space-y-4">
          <h3>🪧 This partial is waiting to be updated</h3>

<p>
            You can edit this file here <code class='p-1 rounded bg-gray-500 text-white text-sm'>app/views/avo/resource_tools/post_info.html.erb</code>.
          </p>

<p>
            The resource tool configuration file should be here <code class='p-1 rounded bg-gray-500 text-white text-sm'>app/avo/resource_tools/post_info.rb</code>.
          </p>

<%
            # 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::App.context
            # current_user
          %>
        </div>
      </div>
    <% end %>
  <% end %>
</div>
```

## Partial context

You might need access to a few things in the partial.

You have access to the `tool`, which is an instance of your tool `PostInfo`, and the `@resource`, which holds all the information about that particular resource (`view`, `model`, `params`, and others), the `params` of the request, the `Avo::App.context` and the `current_user`.
That should give you all the necessary data to scope out the partial content.

## Tool visibility

The resource tool is default visible on the `Show` view of a resource. You can change that using the visibility options (`show_on`, `only_on`).

```ruby
# app/avo/resources/post_resource.rb
class PostResource < Avo::BaseResource
  tool PostInfo, show_on: :edit
end
```

### Using path helpers

Because you're in a Rails engine, you will have to prepend the engine object to the path.

#### For Avo paths

Instead of writing `resources_posts_path(1)` you have to write `avo.resources_posts_path(1)`.

#### For the main app paths

When you want to reference paths from your main app, instead of writing `posts_path(1)`, you have to write `main_app.posts_path`.

## Add custom fields on forms

**From Avo 2.12**

You might want to add a few more fields or pieces of functionality besides the CRUD-generated fields on your forms. Of course, you can already create new custom fields to do it in a more structured way, but you can also use a resource tool to achieve more custom behavior.

You have access to the `form` object that is available on the new/edit pages on which you can attach inputs of your choosing. You can even achieve nested form functionality.

You have to follow three steps to enable this functionality:

1. Add the inputs in a resource tool and enable the tool on the form pages
2. Tell Avo which `params` it should permit to write to the model
3. Make sure the model is equipped to receive the params

In the example below, we'll use the `FishResource`, add a few input fields (they will be a bit unstyled because this is not the scope of the exercise), and do some actions with some of them.

We first need to generate the tool with `bin/rails g avo:resource_tool fish_information` and add the tool to the resource file.

```ruby{2}
class FishResource < Avo::BaseResource
  tool FishInformation, show_on: :forms
end
```

In the `_fish_information.html.erb` partial, we'll add a few input fields. Some are directly on the `form`, and some are nested with `form.fields_for`.

The fields are:

- `fish_type` as a text input
- `properties` as a multiple text input which will produce an array in the back-end
- `information` as nested inputs which will produce a `Hash` in the back-end

```erb{13-36}

<div class="flex flex-col">
  <%= 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 %>
      <div class="flex flex-col p-4 min-h-24">
        <div class="space-y-4">
          <% if form.present? %>
            <%= form.label :fish_type %>
            <%= form.text_field :fish_type, value: 'default type of fish', class: input_classes %>
            <br>

<%= 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 %>
            <br>

<% form.fields_for :information do |information_form| %>
              <%= form.label :information_name %>
              <%= information_form.text_field :name, value: 'information name', class: input_classes %>
              <div class="text-gray-600 mt-2 text-sm">This is going to be passed to the model</div>
              <br>
              <%= form.label :information_history %>
              <%= information_form.text_field :history, value: 'information history', class: input_classes %>
              <div class="text-gray-600 mt-2 text-sm">This is going to be passed to the model</div>
              <br>
              <%= form.label :information_age %>
              <%= information_form.text_field :age, value: 'information age', class: input_classes %>
              <div class="text-gray-600 mt-2 text-sm">This is NOT going to be passed to the model</div>
            <% end %>
          <% end %>
        </div>
      </div>
    <% end %>
  <% end %>
</div>
```

Next, we need to tell Avo and Rails which params are welcomed in the `create`/`update` request. We do that using the `extra_params` option on the `FishResource`. Avo's internal implementation is to assign the attributes you specify here to the underlying model (`model.assign_attributes params.permit(extra_params)`).

```ruby{2}
class FishResource < Avo::BaseResource
  self.extra_params = [:fish_type, :something_else, properties: [], information: [:name, :history]]

tool FishInformation, show_on: :forms
end
```

The third step is optional. You must ensure your model responds to the params you're sending. Our example should have the `fish_type`, `properties`, and `information` attributes or setter methods on the model class. We chose to add setters to demonstrate the params are called to the model.

```ruby
class Fish < ApplicationRecord
  self.inheritance_column = nil # required in order to use the type DB attribute

def fish_type=(value)
    self.type = value
  end

def properties=(value)
    # properties should be an array
    puts ["properties in the Fish model->", value].inspect
  end

def information=(value)
    # properties should be a hash
    puts ["information in the Fish model->", value].inspect
  end
end
```

If you run this code, you'll notice that the `information.information_age` param will not reach the `information=` method because we haven't allowed it in the `extra_params` option.

---

# Stimulus JS & HTML attributes

:::warning
This feature is in the **beta** phase. The API might change while seeing how the community uses it to build their apps.
This is not the **dependable fields** feature but a placeholder so we can observe and see what we need to ship to make it helpful to you.
:::

_What we'll be able to do at the end of reading these docs_

:::info
**Please note** that in order to have the JS code from your controllers loaded in Avo you'll need to add your asset pipeline using these instructions. It's really easier than it sounds. It's like you'd add a new JS file to your regular Rails app.
:::

<hr/>

One of the most requested features is the ability to make the forms more dynamic. We want to bring the first iteration of this feature through Stimulus JS integration.
This light layer will allow you to hook into the views and inject your functionality with Stimulus JS.

You'll be able to add your Stimulus controllers to the resource views (`Index`, `Show`, `Edit`, and `New`), attach `classes`, `style`, and `data` attributes to the fields and inputs in different views.

## Assign Stimulus controllers to resource views

To enable a stimulus controller to resource view, you can use the `stimulus_controllers` option on the resource file.

```ruby
class CourseResource < Avo::BaseResource
  self.stimulus_controllers = "course-resource"
end
```

You can add more and separate them by a space character.

```ruby
class CourseResource < Avo::BaseResource
  self.stimulus_controllers = "course-resource select-field association-fields"
end
```

Avo will add a `resource-[VIEW]` (`resource-edit`, `resource-show`, or `resource-index`) controller for each view.

### Field wrappers as targets

By default, Avo will add stimulus target data attributes to all field wrappers. The notation scheme uses the name and field type `[FIELD_NAME][FIELD_TYPE]WrapperTarget`.

```ruby
# Wrappers get the `data-[CONTROLLER]-target="nameTextWrapper"` attribute and can be targeted using nameTextWrapperTarget
field :name, as: :text

# Wrappers get the `data-[CONTROLLER]-target="createdAtDateTimeWrapper"` attribute and can be targeted using createdAtDateTimeWrapperTarget
field :created_at, as: :date_time

# Wrappers get the `data-[CONTROLLER]-target="hasSkillsTagsWrapper"` attribute and can be targeted using hasSkillsTagsWrapperTarget
field :has_skills, as: :tags
```

For example for the following stimulus controllers `self.stimulus_controllers = "course-resource select-field association-fields"` Avo will generate the following markup for the `has_skills` field above on the `edit` view.

```html{4-7}
<div class="relative flex flex-col md:flex-row md:items-center pb-2 md:pb-0 leading-tight min-h-14"
  data-field-id="has_skills"
  data-field-type="boolean"
  data-resource-edit-target="hasSkillsBooleanWrapper"
  data-course-resource-target="hasSkillsBooleanWrapper"
  data-select-field-target="hasSkillsBooleanWrapper"
  data-association-fields-target="hasSkillsBooleanWrapper"
>
  
</div>
```

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}
<div class="space-y-12"
  data-model-id="280"
  data-controller="resource-edit course-resource"
  data-resource-edit-view-value="edit"
  data-course-resource-view-value="edit"
>
  
</div>
```

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 ShowCurrentTime < Avo::BaseAction
  self.stimulus_controllers = "city-in-country"
end
```

You can add more and separate them by a space character.

```ruby
class 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

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.

Pass the `style` and `classes` attributes as strings, and the `data` attribute a Hash.

```ruby{4-11}
field :name, as: :text, html: {
  edit: {
    wrapper: {
      style: "background: red; text: white;" # string
      classes: "absolute h-[41px] w-full" # string
      data: {
        action: "input->resource-edit#toggle",
        resource_edit_toggle_target_param: "skills_tags_wrapper",
      } # Hash
    }
  }
}
```

### Declare the fields from the outside in

When you add these attributes, you need to think from the outside in. So first the `view` (`index`, `show`, or `edit`), next the element to which you add the attribute (`wrapper`, `label`, `content` or `input`), and then the attribute `style`, `classes`, or `data`.

**The `edit` value will be used for both the `Edit` and `New` views.**

There are two notations through which you can attach the attributes; `object` or `block` notation.

## The `object` notation

This is the simplest way of attaching the attribute. You usually use this when you want to add _static_ content and params.

```ruby{3-9}
field :has_skills,
  as: :boolean,
  html: {
    edit: {
      wrapper: {
        classes: "hidden"
      }
    }
  }
```

In this example, we're adding the `hidden` class to the field wrapper on the `Edit` and `New` views.

## The `block` notation

You can use the' block' notation if you need to do a more complex transformation to add your attributes. You'll have access to the `params`, `current_user`, `record`, and `resource` variables. It's handy in multi-tenancy scenarios and when you need to scope out the information across accounts.

```ruby{3-18}
field :has_skills,
  as: :boolean,
  html: -> do
    edit do
      wrapper do
        classes do
          "hidden"
        end
        data do
          if current_user.admin?
            {
              action: "click->admin#do_something_admin"
            }
          else
            {
              record: record,
              resource: resource,
            }
          end
        end
      end
    end
  end
```

For the `data`, `style`, and `classes` options, you may use the `method` notation alongside the block notation for simplicity.

```ruby{6,7}
field :has_skills,
  as: :boolean,
  html: -> do
    edit do
      wrapper do
        classes("hidden")
        data({action: "click->admin#do_something_admin"})
      end
    end
  end
```

## Where are the attributes added?

You can add attributes to the wrapper element for the `index`, `show`, or `edit` blocks.

## Index field wrapper

```ruby
field :name, as: :text, html: {
  index: {
    wrapper: {}
  }
}
```

## Show field wrapper

```ruby
field :name, as: :text, html: {
  show: {
    wrapper: {}
  }
}
```

## Show label target

```ruby
field :name, as: :text, html: {
  show: {
    label: {}
  }
}
```

## Show content target

```ruby
field :name, as: :text, html: {
  show: {
    content: {}
  }
}
```

## Edit field wrapper

```ruby
field :name, as: :text, html: {
  edit: {
    wrapper: {}
  }
}
```

## Edit label target

```ruby
field :name, as: :text, html: {
  edit: {
    label: {}
  }
}
```

## Edit content target

```ruby
field :name, as: :text, html: {
  edit: {
    content: {}
  }
}
```

## Edit input target

```ruby
field :name, as: :text, html: {
  edit: {
    input: {}
  }
}
```

## 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
```

### `resource-edit#disable`

Disable works similarly to toggle, with the difference that it disables the field instead of hiding it.

```ruby{5-7,16}
field :has_skills, as: :boolean, html: {
  edit: {
    input: {
      data: {
        action: "input->resource-edit#disable", # use the pre-made stimulus method on input
        resource_edit_disable_target_param: "countrySelectInput", # target to be disabled
        # resource_edit_disable_targets_param: ["countrySelectWrapper"] # add more than one target to disable
      }
    }
  }
}
field :country, as: :select, options: Course.countries.map { |country| [country, country] }.to_h
```

You may also target the `wrapper` element for that field if the target field has more than one input like the searchable polymorphic `belongs_to` field.

```ruby{6}
field :has_skills, as: :boolean, html: {
  edit: {
    input: {
      data: {
        action: "input->resource-edit#disable", # use the pre-made stimulus method on input
        resource_edit_disable_target_param: "countrySelectWrapper", # target the wrapper so all inputs are disabled
        # resource_edit_disable_targets_param: ["countrySelectWrapper"] # add more than one target to disable
      }
    }
  }
}
field :country, as: :select, options: Course.countries.map { |country| [country, country] }.to_h
```

### `resource-edit#debugOnInput`

For debugging purposes only, the `resource_edit` Stimulus JS controller provides the `debugOnInput` method that outputs the event and value for an action to the console. Use this just to make sure you targeted your fields correctly. It doesn't have any real use.

## Custom Stimulus controllers

The bigger purpose of this feature is to create your own Stimulus JS controllers to bring the functionality you need to the CRUD interface.

Below is an example of how you could implement a city & country select feature where the city select will have its options changed when the user selects a country:

1. Add an action to the country select to trigger a change.
1. The stimulus method `onCountryChange` will be triggered when the user changes the country.
1. That will trigger a fetch from the server where Rails will return an array of cities for the provided country.
1. The city field will have a `loading` state while we fetch the results.
1. The cities will be added to the `city` select field
1. If the initial value is present in the returned results, it will be selected.
1. All of this will happen only on the `New` and `Edit` views because of the condition we added to the `connect` method.

::: code-group

```ruby [app/avo/resources/course_resource.rb]
# app/avo/resources/course_resource.rb
class CourseResource < Avo::BaseResource
  self.stimulus_controllers = "course-resource"

field :id, as: :id
  field :name, as: :text
  field :country, as: :select, options: Course.countries.map { |country| [country, country] }.to_h, html: {
    edit: {
      input: {
        data: {
          course_resource_target: "countryFieldInput", # Make the input a target
          action: "input->course-resource#onCountryChange" # Add an action on change
        }
      }
    }
  }
  field :city, as: :select, options: Course.cities.values.flatten.map { |city| [city, city] }.to_h, html: {
    edit: {
      input: {
        data: {
          course_resource_target: "cityFieldInput" # Make the input a target
        }
      }
    }
  }
end
```

```ruby{4-6} [config/routes.rb]
Rails.application.routes.draw do
  if defined? ::Avo
    Avo::Engine.routes.draw do
      scope :resources do
        get "courses/cities", to: "courses#cities"
      end
    end
  end
end
```

```ruby{3} [app/controllers/avo/courses_controller.rb]
class Avo::CoursesController < Avo::ResourcesController
  def cities
    render json: get_cities(params[:country]) # return an array of cities based on the country we received
  end

private

def get_cities(country)
    return [] unless Course.countries.include?(country)

Course.cities[country.to_sym]
  end
end
```

```ruby [app/models/course.rb]
class Course < ApplicationRecord
  def self.countries
    ["USA", "Japan", "Spain", "Thailand"]
  end

```js [course_resource_controller.js]
import { Controller } from "@hotwired/stimulus";

const LOADER_CLASSES = "absolute bg-gray-100 opacity-10 w-full h-full";

export default class extends Controller {
  static targets = ["countryFieldInput", "cityFieldInput", "citySelectWrapper"];

static values = {
    view: String,
  };

// Te fields initial value
  static initialValue;

get placeholder() {
    return this.cityFieldInputTarget.ariaPlaceholder;
  }

set loading(isLoading) {
    if (isLoading) {
      // create a loader overlay
      const loadingDiv = document.createElement("div");
      loadingDiv.className = LOADER_CLASSES;
      loadingDiv.dataset.target = "city-loader";

// add the loader overlay
      this.citySelectWrapperTarget.prepend(loadingDiv);
      this.citySelectWrapperTarget.classList.add("opacity-50");
    } else {
      // remove the loader overlay
      this.citySelectWrapperTarget
        .querySelector('[data-target="city-loader"]')
        .remove();
      this.citySelectWrapperTarget.classList.remove("opacity-50");
    }
  }

async connect() {
    // Add the controller functionality only on forms
    if (["edit", "new"].includes(this.viewValue)) {
      this.captureTheInitialValue();

// Trigger the change on load
      await this.onCountryChange();
    }
  }

// Read the country select.
  // If there's any value selected show the cities and prefill them.
  async onCountryChange() {
    if (this.hasCountryFieldInputTarget && this.countryFieldInputTarget) {
      // Get the country
      const country = this.countryFieldInputTarget.value;
      // Dynamically fetch the cities for this country
      const cities = await this.fetchCitiesForCountry(country);

// Clear the select of options
      Object.keys(this.cityFieldInputTarget.options).forEach(() => {
        this.cityFieldInputTarget.options.remove(0);
      });

// Add blank option
      this.cityFieldInputTarget.add(new Option(this.placeholder));

// Add the new cities
      cities.forEach((city) => {
        this.cityFieldInputTarget.add(new Option(city, city));
      });

// Check if the initial value is present in the cities array and select it.
      // If not, select the first item
      const currentOptions = Array.from(this.cityFieldInputTarget.options).map(
        (item) => item.value
      );
      if (currentOptions.includes(this.initialValue)) {
        this.cityFieldInputTarget.value = this.initialValue;
      } else {
        // Select the first item
        this.cityFieldInputTarget.value =
          this.cityFieldInputTarget.options[0].value;
      }
    }
  }

// Private

captureTheInitialValue() {
    this.initialValue = this.cityFieldInputTarget.value;
  }

async fetchCitiesForCountry(country) {
    if (!country) {
      return [];
    }

this.loading = true;

const response = await fetch(
      `${window.Avo.configuration.root_path}/resources/courses/cities?country=${country}`
    );
    const data = await response.json();

this.loading = false;

return data;
  }
}
```

:::

This is how the fields behave with this Stimulus JS controller.

## Use Stimulus JS in a tool

There are a few steps you need to take in order to register the Stimulus JS controller in the current app context.

First, you need to have a JS entrypoint (ex: `avo.custom.js`) and have that loaded in the `_head` partial. For instructions on that please follow these steps to add it to your app (`importmaps` or `esbuild`).

### Set up a controller

```js
// app/javascript/controllers/sample_controller.js
import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  connect() {
    console.log("Hey from sample controller 👋");
  }
}
```

### Register that controller with the current Stimulus app

```js
// app/javascript/avo.custom.js
import SampleController from "controllers/sample_controller";

// Hook into the stimulus instance provided by Avo
const application = window.Stimulus;
application.register("course-resource", SampleController);

// eslint-disable-next-line no-console
console.log("Hi from Avo custom JS 👋");
```

### Use the controller in the Avo tool

```erb

<div data-controller="sample">
  
</div>
```

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. Your 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`.

## 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

We use TailwindCSS 3.0 with the JIT engine to style Avo, so on release we only pack the used Tailwind classes in our final css file. That's why, when you want to style your custom content (tools, resource tools, fields, or ejected partials), you won't have access to all of Tailwind's utility classes. It's a performance optimization.

But there's an easy way to overcome that limitation. You can add your own TailwindCSS process to watch for your the utility classes you use.

```bash
bin/rails generate avo:tailwindcss:install
```

That command will:

- install `tailwindcss-rails` gem if you haven't installed it yet;
- create a custom `avo.tailwind.css` file where you can further customize your Avo space;
- generate or enhance your `Procfile.dev` with the required compile `yarn avo:tailwindcss --watch` command, as per default `tailwindcss-rails` practices;
- add the resulting file in your `_pre_head.html.erb` file;
- prompt you to add the script your `package.json` file. **This is a manual step you need to do**.

Now, instead of running `bin/rails server`, you can run that Procfile with `bin/dev` or `foreman start -f Procfile.dev`.

:::info
You mileage may vary when running these tasks depending with your setup. The gist is that you need to run `yarn avo:tailwindcss` on deploy0time to compile the css file and `yarn avo:tailwindcss --watch` to watch for changes in development.
:::

:::warning Add rake task to compile the assets in production
This setup works perfectly on your local environment and needs to be run on production too. Add this rake task to have them compiled and ready in production.

```ruby
# lib/tasks/avo_assets.rake
namespace :avo do
  desc "Build Avo tailwind assets"
  task build_avo_tailwind: [:environment] do
    puts "Building Avo tailwind assets..."
    `yarn` # this might be optional if you run it before
    `yarn avo:tailwindcss`
  end
end

Rake::Task["assets:precompile"].enhance(["avo:build_avo_tailwind"])
```
:::

Inside `app/assets/stylesheets` you'll have a new `avo.tailwind.css` file that's waiting for you to customize. The default `tailwind.config.js` file should have the proper paths set up for purging and should be ready to go.

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .btn-primary {
    @apply py-2 px-4 bg-blue-200;
  }
}

*/
```

## 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.

:::info
If your project has a `esbuild.config.mjs` file (Jumpstart Pro uses that), please add `avo.custom.js` to the `entryPoints` variable.
:::

## 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 :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`
:::

!Avo and the asset pipeline

### Sprockets and Propshaft

Create `avo.custom.js` and `avo.custom.css` inside `app/javascripts` and `app/assets/stylesheets` with the desired scripts and styles.
Then add them to Avo using the `_pre_head.html.erb` partial (`rails generate avo:eject :pre_head`).

```erb
# app/views/avo/partials/_pre_head.html.erb

<%= javascript_include_tag 'avo.custom', defer: true %>
<%= stylesheet_link_tag 'avo.custom', media: 'all' %>
```

:::warning
Please ensure that when using `javascript_include_tag` you add the `defer: true` option so the browser will use the same loading strategy as Avo's and the javascript files are loaded in the right order.
:::

### Webpacker

:::warning
We removed support for webpacker. In order to use Avo with your assets you must install Sprockets or Propshaft in order to serve assets like SVG, CSS, or JS files.
:::

:::info
Instructions below are for Webpacker version 6. Version 5 has different paths (`app/javascript/packs`).
:::

Create `avo.custom.js` and `avo.custom.css` inside `app/packs/entrypoints` with the desired scripts and styles.
Then add them to Avo using the `_pre_head.html.erb` partial (`rails generate avo:eject :pre_head`).

```erb
# app/views/avo/partials/_pre_head.html.erb

<%= javascript_pack_tag 'avo.custom', defer: true %>
<%= stylesheet_pack_tag 'avo.custom', media: 'all' %>
```

---

# `Avo::PanelComponent`

The panel component is one of the most used components in Avo.

```erb
<%= render Avo::PanelComponent.new(title: @product.name, description: @product.description) do |c| %>
  <% c.with_tools do %>
    <%= a_link(@product.link, icon: 'heroicons/solid/academic-cap', style: :primary, color: :primary) do %>
      View product
    <% end %>
  <% end %>

<% c.with_body do %>
    <div class="flex flex-col p-4 min-h-24">
      <div class="space-y-4">
        <h3>Product information</h3>

<p>Style: shiny</p>
      </div>
    </div>
  <% end %>
<% end %>
```

![](/assets/img/native-components/avo-panel-component/index.jpg)

## Options

All options are optional. You may render a panel without options.

```erb
<%= render Avo::PanelComponent.new do |c| %>
  <% c.with_body do %>
    Something here.
  <% end %>
<% end %>
```

<Option name="`name`">
The name of the panel. It's displayed on the top under the breadcrumbs.

#### Type
`String`

![](/assets/img/native-components/avo-panel-component/name.jpg)
</Option>

<Option name="`description`">
Small text under the name that speaks a bit about what the panel does.

#### Type
`String`

![](/assets/img/native-components/avo-panel-component/description.jpg)
</Option>

<Option name="`classes`">
A list of classes that should be applied to the panel container.

#### Type
`String`

![](/assets/img/native-components/avo-panel-component/classes.jpg)
</Option>

<Option name="`body_classes`">
A list of classes that should be applied to the body of panel.

#### Type
`String`

![](/assets/img/native-components/avo-panel-component/body_classes.jpg)
</Option>

<Option name="`data`">
A hash of data attributes to be forwarded to the panel container.

#### Type
`Hash`

![](/assets/img/native-components/avo-panel-component/classes.jpg)
</Option>

<Option name="`display_breadcrumbs`">
Toggles the breadcrumbs visibility. You can't customize the breadcrumbs yet.

#### Type
`Boolean`

![](/assets/img/native-components/avo-panel-component/display_breadcrumbs.jpg)
</Option>

## Slots

The component has a few slots where you customize the content in certain areas.

<Option name="`tools`">
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 %>
```

![](/assets/img/native-components/avo-panel-component/tools-slot.jpg)
</Option>

<Option name="`body`">
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 %>
```

![](/assets/img/native-components/avo-panel-component/body-slot.jpg)
</Option>

<Option name="`bare_content`">
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 %>
```

![](/assets/img/native-components/avo-panel-component/grid-view.jpg)
</Option>

<Option name="`footer_tools`">
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 %>
```

![](/assets/img/native-components/avo-panel-component/footer-controls.jpg)
</Option>

<Option name="`footer`">
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 %>
```
</Option>

<Option name="`sidebar`">
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 %>
```
![](/assets/img/native-components/avo-panel-component/sidebar.png)
</Option>

<Option name="`bare_sidebar`">
Use this instead of `sidebar` to display content in a sidebar without the white background styling.

```erb{2-4}
<%= render Avo::PanelComponent.new do |c| %>
  <% c.with_bare_sidebar do %>
    Something tiny here.
  <% end %>
<% end %>
```
</Option>

---

# 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
<div class="flex flex-col">
  <%= 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 %>
      <div class="flex flex-col p-4 min-h-24">
        <div class="space-y-4">
          <h3>🪧 This partial is waiting to be updated</h3>
          <p>
            You can edit this file here <code class='p-1 rounded bg-gray-500 text-white text-sm'>app/views/avo/resource_tools/post_info.html.erb</code>.
          </p>
          <p>
            The resource tool configuration file should be here <code class='p-1 rounded bg-gray-500 text-white text-sm'>app/avo/resource_tools/post_info.rb</code>.
          </p>
          <%
            # 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::App.context
            # current_user
          %>
        </div>
      </div>
    <% end %>
  <% end %>
</div>
```
:::

You may add new fields using the `avo_show_field`, or `avo_edit_field` methods and use the arguments you are used to from resources.

```ruby
# In your resource file
field :name, as: :text
```

```erb

<%= avo_edit_field :name, as: :text %>
```

## The `form` option

If this is an <Edit /> or a <New /> view, you should pass it the `form` object that an Avo resource tool provides for you.

```erb
<%= avo_edit_field :name, as: :text, form: form %>
```

## The `value` option

When you are building a show field and you want to give it a value to show, use the `value` options

```erb
<%= avo_show_field(:photo, as: :external_image, value: record.cdn_image) %>
```

## Other field options

The fields take all the field options you are used to like, `help`, `required`, `readonly`, `placeholder`, and more.

```erb
<%= avo_edit_field :name, as: :text, form: form, help: "The user's name", readonly: -> { !current_user.is_admin? }, placeholder: "John Doe", nullable: true %>
```

## Component options

The field taks a new `component_options` argument that will be passed to the view component for that field. Please check out the field wrapper documentation for more details on that.

## `avo_field` helper

You may use the `avo_field` helper to conditionally switch from `avo_show_field` and `avo_edit_field`.

```erb
<%= avo_field :name, as: :text, view: :show %>
<%= avo_field :name, as: :text, view: :edit %>
<%= avo_field :name, as: :text, view: ExampleHelper.view_conditional %>
```

---

# Field wrappers

Each field display in your Avo resource has a field wrapper that helps display it in a cohesive way across the whole app.
This not only helps with a unitary design, but also with styling in a future theming feature.

:::info
You'll probably never have to use these components and helpers by themselves, but we'd like to document how they work as a future reference for everyone.
:::

# Index field wrapper

![](/assets/img/field-wrappers/index_field_wrapper.jpg)

Each field displayed on the <Index /> view is wrapped in this component that regulates the way content is displayed and makes it easy to control some options.

You may use the component `Avo::Index::FieldWrapperComponent` or the helper `index_field_wrapper`.

<Option name="`dash_if_blank`">
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 %>
```
</Option>

<Option name="`center_content`">
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 %>
```
</Option>

<Option name="`flush`">
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 %>
```
</Option>

<Option name="`field`">
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 %>
```
</Option>

<Option name="`resource`">
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 %>
```
</Option>

# Show & Edit field wrapper

![](/assets/img/field-wrappers/show_field_wrapper.jpg)
![](/assets/img/field-wrappers/edit_field_wrapper.jpg)

The <Show /> and <Edit /> field wrappers are actually the same component.

You may use the component `Avo::Index::FieldWrapperComponent` or the helper `field_wrapper`.

## Field wrapper areas

![](/assets/img/field-wrappers/field_wrapper_areas.jpg)

Each field wrapper is divided in three areas.

### Label

This is where the field name is being displayed. This is also where the required asterisk is added for required fields.

### Value

This area holds the actual value of the field or it's representation. The falue can be simple text or more advanced types like images, advanced pickers, and content editors.

At the bottom the help text is going to be shown on the <Edit /> view and below it the validation error.

### Extra

This space is rarely used and it's there just to fill some horizontal space so the content doesn't span to the whole width and maintain its readability. With the introduction of the sidebar, this space will be ignored

## Options

#### Default

`true`

```erb
<%= field_wrapper **field_wrapper_args, dash_if_blank: false do %>
  <%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
</Option>

<Option name="`compact`">
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 %>
```
</Option>

<Option name="`data`">
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 %>
```
</Option>

<Option name="`full_width`">
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 %>
```
</Option>

<Option name="`form`">
The instance of the form that is going to be populated. It's usually passed in with the `field_wrapper_args` on the <Edit /> view.

```erb
<%= field_wrapper **field_wrapper_args do %>
  <%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
</Option>

<Option name="`field`">
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 %>
```
</Option>

<Option name="`help`">
The text that is going to be displayed below the actual field on the <Edit /> view.

```erb
<%= field_wrapper **field_wrapper_args, help: "Specify if the post is published or not." do %>
  <%= render Avo::Fields::Common::BooleanCheckComponent.new checked: @field.value %>
<% end %>
```
</Option>

<Option name="`label`">
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 %>
```
</Option>

<Option name="`resource`">
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 %>
```
</Option>

<Option name="`stacked`">
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 %>
```
</Option>

![](/assets/img/field-wrappers/stacked_field.jpg)

<Option name="`style`">
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 %>
```
</Option>

<Option name="`view`">
The view where the field is diplayed so it knows if it's a <Show /> or <Edit /> view. 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 %>
```
</Option>

---

# Testing

:::info
We know the testing guides aren't very detailed, and some testing helpers are needed. So please send your feedback [here](https://github.com/avo-hq/avo/discussions/1168).
:::

Testing is an essential aspect of your app. Most Avo DSLs are Ruby classes, so regular testing methods should apply.

## Testing Actions

Given this `ReleaseFish`, this is the `spec` that tests it.

```ruby
class ReleaseFish < Avo::BaseAction
  self.name = "Release fish"
  self.message = "Are you sure you want to release this fish?"

field :message, as: :textarea, help: "Tell the fish something before releasing."

def handle(**args)
    args[:models].each do |model|
      model.release
    end

succeed "#{args[:models].count} fish released with message '#{args[:fields][:message]}'."
  end
end

```

```ruby
require 'rails_helper'

RSpec.feature ReleaseFish, type: :feature do
  let(:fish) { create :fish }
  let(:current_user) { create :user }
  let(:resource) { UserResource.new.hydrate model: fish }

it "tests the dummy action" do
    args = {
      fields: {
        message: "Bye fishy!"
      },
      current_user: current_user,
      resource: resource,
      models: [fish]
    }

action = described_class.new(model: fish, resource: resource, user: current_user, view: :edit)

expect(action).to receive(:succeed).with "1 fish released with message 'Bye fishy!'."
    expect(fish).to receive(:release)

action.handle **args
  end
end
```

---

# `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::Backend
    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{5-7,9-11,15-18}
# app/controllers/concerns/multitenancy.rb
module Multitenancy
  extend ActiveSupport::Concern

included do
    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`.

---

# Evaluation hosts

Avo is a package that does a lot of meta-programming. That means we have a lot of custom functionality passed from the host app to Avo to be executed at different points in time. That functionality can't always be performed in void but requires some pieces of state. We're going to talk all about them below.
You'll probably never be going to implement the hosts yourself, but you'll want to know what they contain and how they work.

Usually, this happens using lambdas. That's why we created the concept of a `Host`.

## What's a host?

A `Host` is an object that holds some pieces of state on which we execute a lambda function.

```ruby
require "dry-initializer"

# This object holds some data that is usually needed to compute blocks around the app.
module Avo
  module Hosts
    class BaseHost
      extend Dry::Initializer

option :context, default: proc { Avo::App.context }
      option :params, default: proc { Avo::App.params }
      option :view_context, default: proc { Avo::App.view_context }
      option :current_user, default: proc { Avo::App.current_user }
      # This is optional because we might instantiate the `Host` first and later hydrate it with a block.
      option :block, optional: true
      delegate :authorize, to: Avo::Services::AuthorizationService

def handle
        instance_exec(&block)
      end
    end
  end
end

# Use it like so.
Avo::Hosts::BaseHost.new(block: &some_block).handle
```

## `BaseHost`

The `BaseHost` holds some of the most basic pieces of state like the request `params`, Avo's `context` object, the [`view_context`](https://apidock.com/rails/AbstractController/Rendering/view_context) object, and the `current_user`.

As the name states, this is the base host. All other hosts are inherited from it.

### `params`

The `params` object is the regular [`params`](https://guides.rubyonrails.org/action_controller_overview.html#parameters) object you are used to.

### Avo's `context` object

As you progress throughout building your app, you'll probably configure a `context` object to hold some custom state you need. For example, in `BaseHost` you have access to this object.

### The `view_context` object

The [`view_context`](https://apidock.com/rails/AbstractController/Rendering/view_context) object can be used to create the route helpers you are used to (EX: `posts_path`, `new_comment_path`, etc.).

When dealing with the `view_context` you have to lean on the object to get those paths. Also, because we are operating under an engine (Avo), the paths must be prefixed with the engine name. Rails' is `main_app`. So if you'd like to output a route to your app `/comments/5/edit`, instead of writing `edit_comment_path 5`, you'd write `view_context.main_app.edit_comment_path 5`.

### The current user

Provided that you set up the `:current_user_method`, you'll have access to that output using `current_user` in this block.

## Evaluating the block

We talked about the host and the pieces of state it holds; now, let's talk about how we can use it.

You're not going to use it when building with Avo. Instead, it's used internally when you pass a block to customize the behavior. For example, it's used when declaring the `visibility` block on `dashboards` or when you try pre-filling the suggestions for the `tags` field.

Not all blocks you declare in Avo will be executed in a `Host`. We started implementing `Host`s since v2.0 after the experience gained with v1.0. We plan on refactoring the old block to hosts at some point, but that's going to be a breaking change, so probably in v3.0.
You'll probably be prompted in the docs on each block if it's a `Host` or not.

Different hosts have different pieces of state.

## `RecordHost`

The `RecordHost` inherits from `BaseHost` and has the `record` available. The `record` is the model class instantiated with the DB information (like doing `User.find 1`) in that context.

## `ViewRecordHost`

The `ViewRecordHost` inherits from `RecordHost` and has the `view` object available too.

## `ResourceViewRecordHost`

The `ResourceViewRecordHost` inherits from `ViewRecordHost` and has the `resource` object available too.

## `AssociationScopeHost`

The `AssociationScopeHost` inherits from `BaseHost` and has the `parent` and the `query` objects available. The `parent` is the instantiated model on which the block is given and the `query` is the actual query that is going to run.
---

## Generation Information

- **Generated at:** 2026-05-13T21:32:09.000Z
- **Total sections:** 70

### Source Files

- docs/2.0/index.md
- docs/2.0/rails-and-hotwire.md
- docs/2.0/licensing.md
- docs/2.0/technical-support.md
- docs/2.0/installation.md
- docs/2.0/authentication.md
- docs/2.0/authorization.md
- docs/2.0/cache.md
- docs/2.0/resources.md
- docs/2.0/controllers.md
- docs/2.0/field-options.md
- docs/2.0/records-reordering.md
- docs/2.0/tabs.md
- docs/2.0/resource-sidebar.md
- docs/2.0/customizable-controls.md
- docs/2.0/fields/area.md
- docs/2.0/fields/badge.md
- docs/2.0/fields/boolean.md
- docs/2.0/fields/boolean_group.md
- docs/2.0/fields/code.md
- docs/2.0/fields/country.md
- docs/2.0/fields/date.md
- docs/2.0/fields/date_time.md
- docs/2.0/fields/external_image.md
- docs/2.0/fields/file.md
- docs/2.0/fields/files.md
- docs/2.0/fields/gravatar.md
- docs/2.0/fields/heading.md
- docs/2.0/fields/hidden.md
- docs/2.0/fields/id.md
- docs/2.0/fields/key_value.md
- docs/2.0/fields/location.md
- docs/2.0/fields/markdown.md
- docs/2.0/fields/number.md
- docs/2.0/fields/password.md
- docs/2.0/fields/progress_bar.md
- docs/2.0/fields/select.md
- docs/2.0/fields/status.md
- docs/2.0/fields/tags.md
- docs/2.0/fields/text.md
- docs/2.0/fields/textarea.md
- docs/2.0/fields/time.md
- docs/2.0/fields/trix.md
- docs/2.0/associations.md
- docs/2.0/associations/belongs_to.md
- docs/2.0/associations/has_one.md
- docs/2.0/associations/has_many.md
- docs/2.0/associations/has_and_belongs_to_many.md
- docs/2.0/dashboards.md
- docs/2.0/cards.md
- docs/2.0/customization.md
- docs/2.0/grid-view.md
- docs/2.0/map-view.md
- docs/2.0/menu-editor.md
- docs/2.0/search.md
- docs/2.0/filters.md
- docs/2.0/actions.md
- docs/2.0/localization.md
- docs/2.0/branding.md
- docs/2.0/custom-tools.md
- docs/2.0/custom-fields.md
- docs/2.0/resource-tools.md
- docs/2.0/stimulus-integration.md
- docs/2.0/custom-asset-pipeline.md
- docs/2.0/native-components/avo-panel-component.md
- docs/2.0/native-field-components.md
- docs/2.0/field-wrappers.md
- docs/2.0/testing.md
- docs/2.0/avo-application-controller.md
- docs/2.0/evaluation-hosts.md