Skip to content

Commit

Permalink
Merge pull request #81 from avo-hq/updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@adrianthedev
adrianthedev authored Aug 7, 2023
2 parents 56f5755 + 1ac779e commit 327fcd8
Show file tree
Hide file tree
Showing 16 changed files with 192 additions and 160 deletions.
68 changes: 34 additions & 34 deletions docs/.vitepress/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,8 +110,8 @@ const config = {
text: "Configuration",
items: [
{text: "Installation", link: "/3.0/installation"},
// {text: "Authentication", link: "/3.0/authentication"},
// {text: "Authorization", link: "/3.0/authorization"},
{text: "Authentication", link: "/3.0/authentication"},
{text: "Authorization", link: "/3.0/authorization"},
],
},
{
Expand Down Expand Up @@ -157,15 +157,15 @@ const config = {
{
text: "Customize Avo",
items: [
// {text: "Customization options", link: "/3.0/customization"},
{text: "Customization options", link: "/3.0/customization"},
{text: "Grid view", link: "/3.0/grid-view"},
{text: "Map view", link: "/3.0/map-view"},
{text: "Custom view types", link: "/3.0/custom-view-types"},
// {text: "Menu editor", link: "/3.0/menu-editor"},
{text: "Menu editor", link: "/3.0/menu-editor"},
{text: "Search", link: "/3.0/search"},
// {text: "Actions", link: "/3.0/actions"},
// {text: "Localization (I18n)", link: "/3.0/localization"},
// {text: "Branding", link: "/3.0/branding"},
{text: "Actions", link: "/3.0/actions"},
{text: "Localization (I18n)", link: "/3.0/localization"},
{text: "Branding", link: "/3.0/branding"},
],
},
{
Expand All @@ -177,33 +177,33 @@ const config = {
// {text: "Advanced filters", link: "/3.0/filters/advanced-filters"},
],
},
// {
// text: "Custom content",
// items: [
// {text: "Custom views", link: "/3.0/custom-tools"},
// {text: "Custom fields", link: "/3.0/custom-fields"},
// {text: "Resource tools", link: "/3.0/resource-tools"},
// {text: "Stimulus JS integration", link: "/3.0/stimulus-integration"},
// {text: "Evaluation hosts", link: "/3.0/evaluation-hosts"},
// {text: "Custom asset pipeline", link: "/3.0/custom-asset-pipeline"},
// ],
// },
// {
// text: "Native Avo components",
// items: [
// {text: "Avo::PanelComponent", link: "/3.0/native-components/avo-panel-component"},
// {text: "Native field components", link: "/3.0/native-field-components"},
// {text: "Field wrappers", link: "/3.0/field-wrappers"},
// ],
// },
// {
// text: "Internals",
// items: [
// {text: "Testing", link: "/3.0/testing"},
// {text: "Avo::ApplicationController", link: "/3.0/avo-application-controller"},
// {text: "Avo.asset_manager", link: "/3.0/asset-manager"},
// ],
// },
{
text: "Custom content",
items: [
{text: "Custom views", link: "/3.0/custom-tools"},
{text: "Custom fields", link: "/3.0/custom-fields"},
{text: "Resource tools", link: "/3.0/resource-tools"},
{text: "Stimulus JS integration", link: "/3.0/stimulus-integration"},
// {text: "Evaluation hosts", link: "/3.0/evaluation-hosts"},
{text: "Custom asset pipeline", link: "/3.0/custom-asset-pipeline"},
],
},
{
text: "Native Avo components",
items: [
{text: "Avo::PanelComponent", link: "/3.0/native-components/avo-panel-component"},
{text: "Native field components", link: "/3.0/native-field-components"},
{text: "Field wrappers", link: "/3.0/field-wrappers"},
],
},
{
text: "Internals",
items: [
{text: "Testing", link: "/3.0/testing"},
{text: "Avo::ApplicationController", link: "/3.0/avo-application-controller"},
{text: "Avo.asset_manager", link: "/3.0/asset-manager"},
],
},
// {
// text: "Extending",
// items: [
Expand Down
2 changes: 1 addition & 1 deletion docs/3.0/actions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,7 @@ class Avo::Actions::DownloadFile < Avo::BaseAction
end
```

```ruby{5} [app/avo/resources/project_resource.rb]
```ruby{7} [app/avo/resources/project.rb]
class Avo::Resources::Project < Avo::BaseResource
def fields
# fields here
Expand Down
16 changes: 9 additions & 7 deletions docs/3.0/associations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,29 +28,31 @@ 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.
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 `Avo::Resources::SuperUser` should receive the underlying `model_class` so Avo knows which model it represents.

```ruby{4}
class SuperUserResource < Avo::BaseResource
class Avo::Resources::SuperUser < Avo::BaseResource
self.title = :name
self.includes = []
self.model_class = ::SuperUser
field :id, as: :id
field :name, as: :text
def fields
field :id, as: :id
field :name, as: :text
end
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.
You may want to use the `Avo::Resources::Person` to list all the records, but when your user clicks on a person, you want to use the inherited resources (`Avo::Resources::Sibiling` and `Avo::Resources::Spouse`) 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: false` 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.
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 `Avo::Resources::Person` 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: false` Use it on a `has_many` field. On the `Avo::Resources::Person` 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

Expand Down
4 changes: 2 additions & 2 deletions docs/3.0/authorization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -412,7 +412,7 @@ Now, Avo will use `avo_index?` instead of `index?` to manage the **Index** view

## Raise errors when policies are missing

The default behavior of Avo is to allow missing policies for resources silently. So, if you have a `User` model and a `UserResource` but don't have a `UserPolicy`, Avo will not raise errors regarding missing policies and authorize that resource.
The default behavior of Avo is to allow missing policies for resources silently. So, if you have a `User` model and a `Avo::Resources::User` but don't have a `UserPolicy`, Avo will not raise errors regarding missing policies and authorize that resource.

If, however, you need to be on the safe side of things and raise errors when a Resource is missing a Policy, you can toggle on the `raise_error_on_missing_policy` configuration.

Expand All @@ -436,7 +436,7 @@ Now, you'll have to provide a policy for each resource you have in your app, thu
By default, Avo will infer the policy from the model of the resource object. If you wish to use a different policy for a given resource, you can specify it directly in the resource using the `authorization_policy` option.

```ruby
class PhotoCommentResource < Avo::BaseResource
class Avo::Resources::PhotoComment < Avo::BaseResource
self.model_class = ::Comment
self.authorization_policy = PhotoCommentPolicy
# ...
Expand Down
34 changes: 19 additions & 15 deletions docs/3.0/custom-fields.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Please restart your rails server after adding a new custom field.
The `ProgressBarField` file is what registers the field in your admin.

```ruby
class ProgressBarField < Avo::Fields::BaseField
class Avo::Fields::ProgressBarField < Avo::Fields::BaseField
def initialize(name, **args, &block)
super(name, **args, &block)
end
Expand All @@ -43,13 +43,15 @@ end

Now you can use your field like so:

```ruby{6}
# app/avo/resources/progress_bar_field.rb
class ProjectResource < Avo::BaseResource
```ruby{7}
# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
self.title = :name
field :id, as: :id, link_to_resource: true
field :progress, as: :progress_bar
def fields
field :id, as: :id, link_to_resource: true
field :progress, as: :progress_bar
end
end
```
<img :src="('/assets/img/custom-fields/progress-show.jpg')" alt="Progress custom field" class="border mb-4" />
Expand Down Expand Up @@ -84,7 +86,7 @@ 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
class Avo::Fields::ProgressBarField < Avo::Fields::BaseField
attr_reader :max
attr_reader :step
attr_reader :display_value
Expand All @@ -103,9 +105,9 @@ end

The field-specific options can come from the field declaration as well.

```ruby{11-14,23}
```ruby{11-14,24}
# app/avo/fields/progress_bar_field.rb
class ProgressBarField < Avo::Fields::BaseField
class Avo::Fields::ProgressBarField < Avo::Fields::BaseField
attr_reader :max
attr_reader :step
attr_reader :display_value
Expand All @@ -121,12 +123,14 @@ class ProgressBarField < Avo::Fields::BaseField
end
end
# app/avo/resources/progress_bar_field.rb
class ProjectResource < Avo::BaseResource
# app/avo/resources/project.rb
class Avo::Resources::Project < 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: "%"
def fields
field :id, as: :id, link_to_resource: true
field :progress, as: :progress_bar, step: 10, display_value: true, value_suffix: "%"
end
end
```

Expand All @@ -136,7 +140,7 @@ 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
class Avo::Fields::ProgressBarField < Avo::Fields::BaseField
attr_reader :max
attr_reader :step
attr_reader :display_value
Expand Down Expand Up @@ -269,7 +273,7 @@ You should add the `:always_show` `attr_reader` and `@always_show` instance vari

```ruby{3,8}
# app/avo/fields/color_picker_field.rb
class ColorPickerField < Avo::Fields::BaseField
class Avo::Fields::ColorPickerField < Avo::Fields::BaseField
attr_reader :always_show
def initialize(id, **args, &block)
Expand Down
4 changes: 2 additions & 2 deletions docs/3.0/customization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -415,8 +415,8 @@ end
#### Using the `friendly` gem

::: code-group
```ruby [app/avo/resources/user_resource.rb]
class UserResource < Avo::BaseResource
```ruby [app/avo/resources/user.rb]
class Avo::Resources::User < Avo::BaseResource
self.find_record_method = -> {
# We have to add .friendly to the query
query.friendly.find! id
Expand Down
76 changes: 43 additions & 33 deletions docs/3.0/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ That depends on your setup:
1. If you have [Rails STI](https://guides.rubyonrails.org/association_basics.html#single-table-inheritance-sti), then it will work. Avo knows how to handle STI models. So you'll have two models and an Avo resource for each one. That will render two resources in your admin panel's sidebar.
2. You don't have Rails STI but something custom. Then the response is it depends. Because something custom is... custom, we offer a few mechanisms to get over that.

If you have one model, `User`, you'll have one Avo resource, `UserResource`.
If you have one model, `User`, you'll have one Avo resource, `Avo::Resources::User`.
Then you can customize different things based on your requirements. Like if for instance, you want to show only some types of users on the `Index` view, you can use [custom query scopes](https://docs.avohq.io/1.0/customization.html#custom-query-scopes) to hide specific types (if that's what you want to do).
Same if you want to [show/hide fields](https://docs.avohq.io/1.0/field-options.html#field-visibility) based on the resource type or type of user.

Expand Down Expand Up @@ -118,16 +118,18 @@ For convenience sake, we capture the `view_context` for you and set it to the `A

On the `Resource` and `Field` classes, it's already delegated for you, so you can just use `view_context`.

```ruby{6,9}
class CommentResource < Avo::BaseResource
field :id, as: :id
field :body,
as: :textarea,
format_using: -> do
view_context.content_tag(:div, style: 'white-space: pre-line') { value }
```ruby{7,10}
class Avo::Resources::Comment < Avo::BaseResource
def fields
field :id, as: :id
field :body,
as: :textarea,
format_using: -> do
view_context.content_tag(:div, style: 'white-space: pre-line') { value }
end
field :computed_field, as: :text do
view_context.link_to("Login", main_app.new_user_session_path)
end
field :computed_field, as: :text do
view_context.link_to("Login", main_app.new_user_session_path)
end
end
```
Expand All @@ -138,9 +140,11 @@ end

When adding content using the `textarea` field, you might see that the newlines are not displayed on the `Show` view.

```ruby{2}
class CommentResource < Avo::BaseResource
field :body, as: :textarea
```ruby{3}
class Avo::Resources::Comment < Avo::BaseResource
def fields
field :body, as: :textarea
end
end
```

Expand All @@ -151,26 +155,30 @@ You can change how you display the information by using the `format_using` optio

### Use `simple_format`

```ruby{5}
class CommentResource < Avo::BaseResource
field :body,
as: :textarea,
format_using: -> do
simple_format value
end
```ruby{6}
class Avo::Resources::Comment < Avo::BaseResource
def fields
field :body,
as: :textarea,
format_using: -> do
simple_format value
end
end
end
```

<img :src="('/assets/img/faq/newline/simple_format.png')" alt="Render new lines" class="border mb-4" />

### Use the `white-space: pre-line` style rule

```ruby{5}
class CommentResource < Avo::BaseResource
field :body,
as: :textarea,
format_using: -> do
content_tag(:div, style: 'white-space: pre-line') { value }
```ruby{6}
class Avo::Resources::Comment < Avo::BaseResource
def fields
field :body,
as: :textarea,
format_using: -> do
content_tag(:div, style: 'white-space: pre-line') { value }
end
end
end
```
Expand All @@ -179,13 +187,15 @@ end

### Use the `whitespace-pre-line` class

```ruby{5}
class CommentResource < Avo::BaseResource
field :body,
as: :textarea,
format_using: -> do
content_tag(:div, class: 'whitespace-pre-line') { value }
end
```ruby{6}
class Avo::Resources::Comment < Avo::BaseResource
def fields
field :body,
as: :textarea,
format_using: -> do
content_tag(:div, class: 'whitespace-pre-line') { value }
end
end
end
```

Expand Down
2 changes: 1 addition & 1 deletion docs/3.0/field-options.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ You can do that using this query.

::: code-group

```ruby{5} [app/avo/resources/post_resource.rb]
```ruby{5} [app/avo/resources/post.rb]
class Avo::Resources::Post < Avo::BaseResource
field :last_commented_at,
as: :date,
Expand Down
Loading

0 comments on commit 327fcd8

Please sign in to comment.