CRUD Sections

Once you have created a new Crud Config, you need to set up the form so that you can update Models through the CMS.

Sections are comprised of Fields. For Field-specific information, see their relevant page in the Field Types menu.

Section Types

Enso provides different types of Section that save information in different ways.

  • Section: This will save data directly onto the Model, saving data into columns matching each Field's name (unless the field specifies otherwise).
  • FlexibleContentSection: This will save a formatted version of the Field data input through this this Section. As the name suggests, this is used to provide flexible storage for undefined and extensible data sets, such as repeater fields and content over which the user has control of the format.
  • JsonDataSection: This will save the content of all Fields on the Section onto a single json column in the database (which shares the name of the Section). This is useful when you have arbitrary (but known) and different pieces of data to store against different isntances of the same Model, such as where a 'File' could be an Image with dimensions, or something else with different properties. If used in this way, you also requires additional logic to give only the correct Fields in create & edit Forms based on some identifying feature of the Model being edited.
  • CollectionSection: This will save each Field as it's own Model. This is used Settings in Enso currently.
  • HasOneSection: This will save all field data in the section to the HasOne relation of the crud item, specified as the name of the section.
  • BelongsToSection: As above, but for a BelongsToS relation.

New Sections

Fields are added to Sections as an ordered list. Each Field on a Section must have a unique snake_case name. You add one or more Fields to a Section in the create method of the config.

NOTE: It is technically possible to add a Field that has a duplicate name to a Field on a different section. This is intentional as different Section Types save differently and be required (although it is preferred that you don't). However, doing so with two Sections of the same type will cause the 'first' value to always be over-written by later values. Use with Caution

$section = Section::make('main');

$section->addField(TextField::make('text_field'));

$section->addFields([
    SlugField::make('slug'),
    WysiwygField::make('description'),
]);

You can add edit-only Fields by extending and altering the edit method. However, in some circumstances it might be more user-friendly to add edit-only fields ad fields that are disabled/read-only on create pages, but functional on edit pages. This type of logic should be performed here.

public function edit(Form $form)
{
    $form = $this->create($form);

    $form->getSection('main')->addFields([
        TextField::make('new_field'),
    ]);

    return $form;
}

Extending Existing Sections

By default, addFields appends them to the Fields list. When creating new Sections for a Crud Form, you can simply change the order of your code that you add Fields with to change the order that they appear on the page. When extending existing Cruds (for example, Enso's built-in User Crud), you can use additional functions to add Fields in specific places.

$form = parent::create($form);

$section = $form->getSection('main');

$section->prependField(TextField::make('section_a'));

$section->addFieldBefore('title', TextField::make('section_c'));

$section->addFieldAfter('description', TextField::make('section_d'));

// This is included for deliberate specificity, but essentially does the same as `addField`.
$section->appendField(TextField::make('final_field'));

You may want to change existing Fields. You can get Sections from a Form in two ways. Once you have found the Field you wish to alter, you can make changes directly to that Field. As they are objects, they reference the same instance as the one in the Section's Field list, and you subsequently don't need to replace the original Field on the Section with the one you have updated.

$fields = $section->getFields();
// ... returns a collection you can filter/search by

$field = $section->getField('field_name');

// ... modify $field

You may want to remove Fields that a no longer relevant, You can remove them with removeField.

$section->removeField'field_name');

Finally, you may wish to transfer Fields from one Section to another. Perhaps you are looking to move a subset of it's Fields to a different Section because grouping data differently will be more appropriate for the app you are building. To achieve this, you can use extractField. This will remove the Field with the provided name from the internal Fields list, and return it for you to use add elsewhere:

$field = $section->extractField('field_name');

$other_section->addField($field);