Guides and Tutorials

This section provides practical guidance and best practices for common scenarios when working with Avo Forms and Pages.

Form Definition Approaches

When building forms in Avo, there are several approaches for organizing your form code. The recommended approach is to use the default generator approach. But in this guide we'll cover other approach as well.

Approach 1: Default Generator Approach

Use the generator to create standalone form files in the app/avo/forms/ directory.

rails generate avo:form user_profiles

This creates:

# app/avo/forms/user_profiles.rb
class Avo::Forms::UserProfiles < Avo::Forms::Core::Form
  self.title = "User Profiles"
  self.description = "Manage your user profiles"

  def fields
    field :example, as: :text, default: "Hello World"
  end

  def handle
    flash[:success] = { body: "Form submitted successfully", timeout: :forever }
    flash[:notice] = params[:example]

    default_response
  end
end

Then reference it in your page:

# app/avo/pages/settings/profiles.rb
class Avo::Pages::Settings::Profiles < Avo::Forms::Core::Page
  def content
    form Avo::Forms::UserProfiles
  end
end

Or render it in a custom component:

<%= render Avo::Forms::UserProfiles.component %>

Approach 2: Inline Form Definitions

You can define forms directly within page classes using the page's namespace.

# app/avo/pages/settings/integrations.rb
class Avo::Pages::Settings::Integrations < Avo::Forms::Core::Page
  self.title = "Integrations"
  self.description = "Manage your integrations"

  def content
    form ApiConfiguration
  end

  # Form defined inline within the page class
  class ApiConfiguration < Avo::Forms::Core::Form
    self.title = "API Configuration"
    self.description = "Configure your API settings"

    def fields
      field :api_key, as: :text, required: true
      field :api_endpoint, as: :text
      field :webhook_url, as: :text
    end

    def handle
      flash[:success] = "API Configuration updated successfully"
      default_response
    end
  end
end

Namespace Confusion

When defining forms inline within page classes, it's not immediately clear that Avo::Pages::Settings::Integrations::ApiConfiguration is a form class rather than page. This can lead to confusion about the class's purpose and make code navigation more difficult. This strategy is not recommended when you want to reuse the form in other pages or components.

When to Use Each Approach

Approach 1 (Default Generator): Good starting point for most forms. Easy to generate and maintain.

Approach 2 (Inline): Best for simple, page-specific forms that won't be reused elsewhere.

Page Organization Approaches

In addition to form definition approaches, you can also choose how to organize your pages:

Virtual Pages

Instead of creating separate page files for every form, you can use virtual pages:

# app/avo/pages/settings.rb
class Avo::Pages::Settings < Avo::Forms::Core::Page
  def navigation
    # Virtual page that renders a single form
    page form: Avo::Forms::UserProfiles

    # Virtual page with multiple forms
    page "Integrations",
      content: -> do
        form Avo::Forms::SlackIntegration
        form Avo::Forms::EmailIntegration
      end
  end
end

Virtual pages are ideal when:

• You have simple forms that don't need dedicated page files
• You want to group related forms together without file proliferation
• You're building settings or configuration interfaces with many small forms