Merge branch 'main' of github.com:avo-hq/docs.avohq.io

Author: adrianthedev

docs/3.0/authorization.md

@@ -116,7 +116,7 @@ Controls whether the user can see the [records reordering](./records-reordering)
 
 <Option name="`search?`">
 
-Controls whether the user can see the global search input or the [resource search input](./search) on top of the <Index /> page.
+Controls whether the user can see the [resource search input](./search) on top of the <Index /> page.
 </Option>
 
 ## Associations
@@ -541,6 +541,105 @@ end
 ```
 </Option>
 
+## Explicit authorization
+
+<Option name="`explicit_authorization`">
+
+:::warning Option Renamed
+In versions between <Version version="3.13.4" /> and <Version version="3.13.6" />, this option is named `implicit_authorization`.
+:::
+
+<VersionReq version="3.13.4" />
+
+ This option gives you control over how missing policy classes or methods are handled during authorization checks in your Avo application.
+
+### Possible values
+
+**`true`**
+  - If a policy class or method is **missing** for a given resource or action, that action will automatically be considered **unauthorized**.
+  - This behavior enhances security by ensuring that any unconfigured or unhandled actions are denied by default.
+
+**`false`**
+  - If a policy class or method is **missing**, the action will be considered **authorized** by default.
+
+**`Proc`**
+  - You can also set `explicit_authorization` as a `Proc` to apply custom logic. Within this block, you gain access to all attributes of [`Avo::ExecutionContext`](execution-context)
+
+    For example:
+
+    ```ruby
+    config.explicit_authorization = -> {
+      current_user.access_to_admin_panel? && !current_user.admin?
+    }
+    ```
+
+    In this case, missing policies will be handled based on the condition: if the user has access to the admin panel but isn't an admin, the `explicit_authorization` will be enabled. This option allows you to customize authorization decisions based on the context of the current user or other factors.
+### Default
+
+- For **new applications** (starting from Avo `3.13.4`) the default value for `explicit_authorization` is `true`. This provides a more secure out-of-the-box experience by ensuring actions without explicit authorization are denied.
+
+- For **existing applications** upgrading to `3.13.4` or later the default value for `explicit_authorization` remains `false` to preserve backward compatibility. Existing applications will retain the permissive behavior unless explicitly changed.
+
+### Configuration:
+
+You can configure this setting in your `config/avo.rb` file:
+
+```ruby{4}
+Avo.configure do |config|
+  # Set to true to deny access when policies or methods are missing
+  # Set to false to allow access when policies or methods are missing
+  config.explicit_authorization = true
+end
+```
+
+### Examples:
+
+1. **When `explicit_authorization` is `true`**
+    - **Scenario**: You have a `Post` resource, but there is no policy class defined for it.
+    - **Result**: All actions for the `Post` resource (index, show, create, etc.) will be **unauthorized** unless you explicitly define a policy class and methods for those actions.
+
+    ---
+    - **Scenario**: You have a `Post` resource, and the policy class defined for it only defines the `show?` method.
+
+    ```ruby
+    class PostPolicy < ApplicationPolicy
+      def show?
+        user.admin?
+      end
+    end
+    ```
+    - **Result**: In this case, since the `PostPolicy` lacks an `index?` method, attempting to access the `index` action will be denied by default.
+
+2. **When `explicit_authorization: false`**
+    - **Scenario**: Same `Post` resource without a policy class.
+    - **Result**: All actions for the `Post` resource will be **authorized** even though there are no explicit policy methods. This could expose unintended behavior, as any unprotected action will be accessible.
+
+    ---
+
+    - **Scenario**: You have a `Post` resource, and the policy class defined for it only defines the `show?` method.
+    ```ruby
+    class PostPolicy < ApplicationPolicy
+      def show?
+        user.admin?
+      end
+    end
+    ```
+    - **Result**: In this case, missing methods like `index?` will allow access to the `index` action by default.
+
+
+### Migration Recommendations:
+
+- **For applications after from Avo `3.13.4`**
+
+    It is recommended to leave `explicit_authorization` set to `true`, ensuring all actions must be explicitly authorized to prevent unintentional access.
+
+- **For applications before from Avo `3.13.4`**
+
+    - If upgrading from an earlier version, carefully review your policies before enabling `explicit_authorization`. Missing policy methods that were previously allowing access will now deny access unless explicitly defined.
+
+    - It’s recommended to disable [`raise_error_on_missing_policy`](authorization.html#raise-errors-when-policies-are-missing) in production, though it's not mandatory. When `explicit_authorization` is set to `true`, the default behavior is to deny access for actions without a defined policy. In this case, it’s often better to show an unauthorized message to users rather than raise an error. However, keeping [`raise_error_on_missing_policy`](authorization.html#raise-errors-when-policies-are-missing) enabled in development can be helpful for identifying missing policy classes.
+</Option>
+
 ## Rolify integration
 
 Check out [this guide](guides/rolify-integration.md) to add rolify role management with Avo.

docs/3.0/cards.md

@@ -199,6 +199,20 @@ end
 
 <Image src="/assets/img/dashboards/prefix-suffix.jpg" width="651" height="168" alt="Avo Prefix & suffix" />
 
+<br>
+
+<VersionReq version="3.13" /> `prefix` and `suffix` became callable options.
+
+The blocks are executed using [`Avo::ExecutionContext`](execution-context). Within this blocks, you gain access to all attributes of [`Avo::ExecutionContext`](execution-context) along with the `parent`.
+
+```ruby{3,4}
+class Avo::Cards::UsersMetric < Avo::Cards::MetricCard
+  self.id = 'users_metric'
+  self.prefix = -> { params[:prefix] || parent.prefix }
+  self.suffix = -> { params[:suffix] || parent.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.

docs/3.0/common/associations_scope_option_common.md

@@ -14,4 +14,8 @@ field :user,
 ```
 
 Pass in a block where you attach scopes to the `query` object. The block gets executed in the [`ExecutionContext`](./../execution-context).
+
+With version 2.5.0, you'll also have access to the `parent` record so that you can use that to scope your associated models even better.
+
+Starting with version 3.12, access to `resource` and `parent_resource` was additionally provided.
 </Option>

docs/3.0/common/scopes_common.md

@@ -31,4 +31,6 @@ The `comments` query on the user `Index` page will have the `approved` scope att
 
 With version 2.5.0, you'll also have access to the `parent` record so that you can use that to scope your associated models even better.
 
+Starting with version 3.12, access to `resource` and `parent_resource` was additionally provided.
+
 All the `has_many` associations have the [`attach_scope`](./../associations/belongs_to#attach-scope) option available too.

docs/3.0/customization.md

@@ -73,7 +73,7 @@ That will render all `id` fields in the **Index** view as a link to that resourc
 
 <Image src="/assets/img/fields-reference/as-link-to-resource.jpg" width="694" height="166" alt="As link to resource" />
 
-## Resource controls on the left side
+## Resource controls on the left or both sides
 <DemoVideo demo-video="https://youtu.be/MfryUtcXqvU?t=706" />
 
 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.
@@ -84,9 +84,18 @@ Avo.configure do |config|
 end
 ```
 
-
 <Image src="/assets/img/customization/resource-controls-left.jpg" width="1206" height="920" alt="Resource controls on the left side" />
 
+<VersionReq version="3.13.7" class="mt-2" />
+
+You might want to render the controls on both sides
+
+```ruby{2}
+Avo.configure do |config|
+  config.resource_controls_placement = :both
+end
+```
+
 ## Container width
 
 ```ruby{2-3}
@@ -397,6 +406,15 @@ Avo.configure do |config|
 end
 ```
 
+<VersionReq version="3.13.5" /> `disabled_features` become callable. Within this block, you gain access to all attributes of [`Avo::ExecutionContext`](execution-context)
+
+```ruby{3}
+# config/initializers/avo.rb
+Avo.configure do |config|
+  config.disabled_features = -> { current_user.is_admin? ? [] : [:global_search] }
+end
+```
+
 After this setting, the global search will be hidden for users.
 
 Supported options:

docs/3.0/dynamic-filters.md

@@ -591,6 +591,88 @@ dynamic_filter :tags,
 
 </Option>
 
+<Option name="`fetch_values_from`">
+
+<VersionReq version="3.13" />
+
+:::warning
+This option is compatible **only** with `tags` filters.
+:::
+
+In some cases, you may need to retrieve values dynamically from an API. The `fetch_values_from` option allows you to provide a URL from which the filter will suggest values, functioning similarly to the `fetch_values_from` option in the tags field.
+
+When a user searches for a record, the filter's input will send a request to the server to fetch records that match the query.
+
+##### Default value
+
+`nil`
+
+:::info
+If you're using a `filterable` field the `fetch_values_from` are fetched from the field.
+
+```ruby
+field :tags, as: :tags,
+  fetch_values_from: -> { "/avo-filters/resources/cities/tags" }
+  filterable: true
+```
+:::
+
+#### Possible values
+
+- String
+```ruby
+fetch_values_from: "/avo-filters/resources/cities/tags"
+```
+
+- Proc that evaluates to a string.
+```ruby
+fetch_values_from: -> { "/avo-filters/resources/cities/tags" }
+```
+
+The string should resolve to an endpoint that returns an array of objects with the keys `value`, `label` and optionally `avatar`.
+
+::: code-group
+```ruby{3-19} [app/controllers/avo/skills_controller.rb]
+class Avo::CitiesController < Avo::ResourcesController
+  def tags
+    render json: [
+      {
+        value: 1,
+        label: "one",
+        avatar: "https://images.unsplash.com/photo-1560363199-a1264d4ea5fc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&w=256&h=256&fit=crop"
+      },
+      {
+        value: 2,
+        label: "two",
+        avatar: "https://images.unsplash.com/photo-1567254790685-6b6d6abe4689?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&w=256&h=256&fit=crop"
+      },
+      {
+        value: 3,
+        label: "three",
+        avatar: "https://images.unsplash.com/photo-1560765447-da05a55e72f8?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&w=256&h=256&fit=crop"
+      }
+    ]
+  end
+end
+```
+
+```ruby{5-11} [config/routes.rb]
+Rails.application.routes.draw do
+  # your routes...
+end
+
+if defined? ::Avo
+  Avo::Engine.routes.draw do
+    scope :resources do
+      get "cities/tags", to: "cities#tags"
+    end
+  end
+end
+```
+:::
+
+</Option>
+
 <Option name="`options`">
 <VersionReq version="3.10.10" />
 

docs/3.0/fields/password.md

@@ -11,6 +11,12 @@ The `Password` field renders a `input[type="password"]` element for that field.
 field :password, as: :password
 ```
 
+#### Revealable
+
+<VersionReq version="3.13.7" class="mt-2" />
+
+You can set the `revealable` to true to show an "eye" icon that toggles the password between hidden or visible.
+
 **Related:**
 - [Devise password optional](./../resources#devise-password-optional)
 

docs/3.0/fields/tags.md

@@ -242,7 +242,7 @@ When the user searches for a record, the field will perform a request to the ser
 
 #### Possible values
 
-Valid values are `nil`, a string, or a block that evaluates to a string. The string should resolve to an enddpoint that returns an array of objects with the keys `value` and `label`.
+Valid values are `nil`, a string, or a block that evaluates to a string. The string should resolve to an endpoint that returns an array of objects with the keys `value` and `label`.
 
 ::: code-group
 

docs/3.0/fields/trix.md

@@ -12,7 +12,6 @@ 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.
 
-
 <Image src="/assets/img/fields/trix.jpg" width="877" height="193" alt="Trix field" />
 
 Trix field is hidden from the `Index` view.
@@ -61,7 +60,6 @@ Enables file attachments.
 `nil`, or a symbol representing the `has_many_attachments` key on the model.
 </Option>
 
-
 ## File attachments
 
 <!-- @include: ./../common/files_gem_common.md-->
@@ -105,3 +103,18 @@ Trix integrates seamlessly with Action Text. It will automatically work with Act
 ## Demo app
 
 We prepared a [demo](https://trix.avodemo.com/) to showcase Trix's abilities to work with Action Text and Active Storage.
+
+## Javascript Alert Messages
+
+<VersionReq version="3.13.8" />
+
+You can customize the javascript alert messages for various actions in the Trix editor. Below are the default messages that can be translated or modified:
+
+```yml
+avo:
+  this_field_has_attachments_disabled: This field has attachments disabled.
+  you_cant_upload_new_resource: You can't upload files into the Trix editor until you save the resource.
+  you_havent_set_attachment_key: You haven't set an `attachment_key` to this Trix field.
+```
+
+Refer to the [default](https://github.com/avo-hq/avo/blob/main/lib/generators/avo/templates/locales/avo.en.yml) for more details.