Helpdesk Form builder Modification

Before learning any modifications, visit the pages below to understand the form builder’s structure.

Adding a New Category Form

To add or modify a form, use the following facade method:

App\Form\Facades\FormCreator::addOrUpdateCategories($form, $form_sections);

For more information, check the file located at database/seeders/v_9_0_0_rc_3/NewFormSeeder.php, under the method createFormCategory().

Typically, when adding a new form, it will only contain the default form fields. Avoid creating custom fields directly from this method. Instead, use the web interface or the V3 API to add custom fields.

Adding a New Section to an Existing Form Category

To add a new section to an existing form category, use the following steps:

  1. Find the form category where you want to add the new section by fetching it through its category ID:
$existing_form = App\Form\Models\FormCategory::find(pass the category id where you have to add the new section);
  1. Define the new fields under the form_fields key, following the section format.
  2. Use the facade method to update the sections in the existing form category:
App\Form\Facades\FormCreator::addOrUpdateSections($existing_form, $form_sections);

Adding a New Form Field to an Existing Form Category

  1. First, find the form category where you want to add the new field:
$existing_form = App\Form\Models\FormCategory::find(pass the category id where you have to add the new section);
  1. Then, search for the specific section in which you want to add the field. Here’s an example query to get the first section of the existing form:
$existing_section = App\Form\Models\FormSection::where('category_type', $existing_form::class)->where('category_id', $existing_form->id)->first();

You can modify this query if you want to add the field to a different section.

  1. Now, you need to add two mandatory attributes for every form field: form_category_id and category_identifier. These values correspond to the existing form’s ID and category. A sample form field structure looks like this:
$form_fields = [[
    'key' => '',
    'title' => '',
    'data_type' => '',
    'api_info' => '',
    'sort_order' => 1,
    'required_for_agent' => 1,
    'required_for_user' => 1,
    'display_for_agent' => 1,
    'display_for_user' => 1,
    'is_deletable' => 0,
    'labels' => [[
        'label' => '',
        'language' => 'en'
    ]],
    'default' => 1,
    'is_observable' => 0,
    'is_filterable' => 1,
    'is_configurable' => 1,
    'is_user_config' => 1,
    'is_agent_config' => 1,
    'column' => 'first',
    'is_active' => 1,
    'is_edit_visible' => 1,
    'form_category_id' => $existing_form->id,
    'category_identifier' => $existing_form->category
]];
  1. Finally, use this method to save the new form field to the existing section:
App\Form\Facades\FormCreator::saveFormFields($existing_section, $form_fields, $existing_form->category);

Handling Nested Fields in Custom Form Fields

If the custom field supports adding nested fields (e.g., for select, checkbox, or radio types), you need to append an options attribute to the form field structure. Here’s an example format for the options attribute:

$options = [[
    'value' => 'one',
    'labels' => [[
        'label' => 'one',
        'language' => 'en'
    ]],
],
[
    'value' => 'two',
    'labels' => [[
        'label' => 'two',
        'language' => 'en'
    ]],
    'nodes' => [[
        'key' => '',
        'title' => '',
        'data_type' => '',
        'api_info' => '',
        'sort_order' => 1,
        'required_for_agent' => 1,
        'required_for_user' => 1,
        'display_for_agent' => 1,
        'display_for_user' => 1,
        'is_deletable' => 0,
        'labels' => [[
            'label' => '',
            'language' => 'en'
        ]],
        'default' => 1,
        'is_observable' => 0,
        'is_filterable' => 1,
        'is_configurable' => 1,
        'is_user_config' => 1,
        'is_agent_config' => 1,
        'column' => 'first',
        'is_active' => 1,
        'is_edit_visible' => 1,
        'form_category_id' => $existing_form->id,
        'category_identifier' => $existing_form->category
    ]]
]];

After appending options to the form field structure, it will look like this:

$form_fields = [[
    'key' => '',
    'title' => '',
    'data_type' => '',
    'api_info' => '',
    'sort_order' => 1,
    'required_for_agent' => 1,
    'required_for_user' => 1,
    'display_for_agent' => 1,
    'display_for_user' => 1,
    'is_deletable' => 0,
    'labels' => [[
        'label' => '',
        'language' => 'en'
    ]],
    'default' => 1,
    'is_observable' => 0,
    'is_filterable' => 1,
    'is_configurable' => 1,
    'is_user_config' => 1,
    'is_agent_config' => 1,
    'column' => 'first',
    'is_active' => 1,
    'is_edit_visible' => 1,
    'form_category_id' => $existing_form->id,
    'category_identifier' => $existing_form->category,
    'options' => $options 
]];

Note: Nested fields are only supported for radio, select, and checkbox data types.

Explanation of Key Concepts:

  1. addOrUpdateCategories: This method is used to either add a new form category or update an existing one. It takes $form and $form_sections as parameters to define the category and its sections.
  2. addOrUpdateSections: This method allows adding new sections to an existing form category. You can define multiple fields in the form_fields key of the section format.
  3. saveFormFields: This is the method responsible for adding new form fields to an existing section. It ensures that the fields are saved under the correct form category and section.
  4. Nested Fields: Fields like radio buttons, checkboxes, or select dropdowns can have nested fields, represented using the options attribute. Each option has a value, and label, and may also contain additional form fields (nodes) associated with it.

By following these steps, you can easily extend or modify the existing form structure within the product, ensuring seamless integration and accurate field management.