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