This is the official documentation of the agent_ruby Ruby agent.
Form layout
The form layout feature lets you organize your fields in pages or rows, and add separators or html blocks. This is especially useful if you have many fields to display, and you want to break down your action form into more manageable chunks !
Theses form elements are available since the version 1.0.0-beta.74 of the agent.
Layout items
Name
Nested elements
Description
None
Allow to add a horizontal separator between two form elements
None
Allow to show HTML content
Fields
Allow to put two (and only two) fields (and not layout elements) in a row
Fields & layouts elements (but no pages)
General properties
Some layouts items will have options, but here are the common properties to all the layout elements
Name
Usage
Expected value
Description
type
required
Layout
component
required
Separator, Row, HtmlBlock, or Page
The layout component
if_condition
optional
Separator element
Name
Usage
Expected value
Description
component
required
"Separator"
To enable this component
This item doesn't have specific options.
Example:
include ForestAdminDatasourceCustomizer::Decorators::Action::Types
include ForestAdminDatasourceCustomizer::Decorators::Action::Context
@create_agent.customize_collection('customer') do |collection|
collection.add_action(
'What\'s your name',
BaseAction.new(
scope: ActionScope::SINGLE,
form: [
{
type: FieldType::STRING,
label: 'firstName',
}
{
type: FieldType::LAYOUT,
component: 'Separator',
}
{
type: FieldType::STRING,
label: 'lastName',
}
]
) do |context, result_builder|
result_builder.success()
end
)
end
HTML Block element
Name
Usage
Expected value
Description
component
required
"HtmlBlock"
To enable this component
content
required
This is the HTML content to show
Example:
include ForestAdminDatasourceCustomizer::Decorators::Action::Types
include ForestAdminDatasourceCustomizer::Decorators::Action::Context
@create_agent.customize_collection('customer') do |collection|
collection.add_action(
'Boring form',
BaseAction.new(
scope: ActionScope::GLOBAL,
form: [
{
type: FieldType::STRING,
label: "firstName",
default_value: ->(context) { context.caller.first_name },
},
{
type: FieldType::STRING,
label: "lastName",
default_value: ->(context) { context.caller.last_name },
},
{
type: FieldType::LAYOUT,
component: 'HtmlBlock',
content: ->(context) {
'<div style="text-align:center;">
<p>
<strong>Hi #{ctx.form_values["firstName"]} #{ctx.form_values["lastName"]}</strong>,
<br/>here you can put
<strong style="color: red;">all the html</strong> you want.
</p>
</div>
<div style="display: flex; flex-flow: row wrap; justify-content: space-around;">
<a href="https://www.w3schools.com" target="_blank">
<img src="https://www.w3schools.com/html/w3schools.jpg">
</a>
<iframe src="https://www.youtube.com/embed/xHPKuu9-yyw?autoplay=1&mute=1"></iframe>
</div>,
'
},
}
# ...
]
) do |context, result_builder|
result_builder.success()
end
)
end
Row element
Name
Usage
Expected value
Description
component
required
"Row"
To enable this component
fields
required
Example:
include ForestAdminDatasourceCustomizer::Decorators::Action::Types
include ForestAdminDatasourceCustomizer::Decorators::Action::Context
@create_agent.customize_collection('customer') do |collection|
collection.add_action(
'Personal form',
BaseAction.new(
scope: ActionScope::GLOBAL,
form: [
# ...
{
type: FieldType::LAYOUT,
component: 'Row',
fields: [
{
label: 'gender',
type: FieldType::ENUM,
enum_values: ['M', 'F', 'other'],
},
{
label: 'specify',
description: 'you may specify here'
type: FieldType::STRING,
if_condition: ->(context) { context.form_values['gender'] == 'other' },
},
]
},
# ...
]
) do |context, result_builder|
result_builder.success()
end
)
end
Multi pages form
Description
The pages feature is a way to break up your action form into more manageable chunks, by showing only a subset of fields at the same time, and letting the user navigate between the pages.
Limitations
Please note this list of limitations:
You cannot mix fields and pages at the root of your form, or put nest a page in a page
The next (or previous) button is not clickable on the last (or first) page
If you're using if conditions in a page; keep in mind that if all the elements in your page are hidden, the page will automatically be removed. You can avoid this by behavior by adding an unconditional htmlBlock inside your page explaining why is your page empty.
Allow to use multi pages forms.
When using multi pages form, you must have only pages at the root of your form.
It differentiate a field from layout elements. See over values in
callable with parameter
Only display the field if the function returns true. This one is the exact same one as presented in
String or callable with parameter, returning a string formatted as html
This element is designed to work with only two inner fields. You can control the display of each field using the if_condition property. If only one field is displayed, it will occupy the entire line. However, if the conditions defined by the if_condition properties result in more than two fields being displayed, only the first two will be shown. If there is nothing inside, it will be removed.
Array of two
These two fields are the ones you want to display in a line
No layout elements are allowed in a Row component; only fields
The layout elements defined in this page and the fields defined
