Add Tab Page

Let's add a new "Volunteer" tab page when managing a user. As you will see there is /src/Users/Opus/TabControls/Manage.php file within the system signifying a tab control component.

Within terminal, run the following create tab-control command:

apex create tab-page disaster users.manage volunteer-tab

This will create a new directory at /src/Disaster/Opus/TabControls/Users_Manage/ which contains two files -- VolunteerTab.html and VolunteerTab.php. Complete the below sections to fill in these two files.

/src/Disaster/Opus/TabControls/Users_Manage/VolunteerTab.php

At the top of the class within the use declarations, add the line:

[data-line=6]
use App\Disaster\Models\Volunteer;

Within the properties section of the class, change the $name property to "Volunteer" and change the $position property to "before Log".

Update the process() method to:

[data-line=115]
public function process(array $attr = []):void
{

    // Check for update
    if ($this->app->getAction() != 'update_volunteer') {
        return;
    }

    // Get volunteer
    $uuid = $this->app->post('manage_id');
    if (!$vol = Volunteer::whereId($uuid)) {
        return;
    }

    // Update
    $vol->location_id = (int) $this->app->post('location_id');
    $vol->profession = $this->app->post('profession');
    $vol->save();

    // Callout
    $this->view->addCallout('Successfully updated volunteer details.');
}

Every time the Volunteer tab is displayed when managing a user account, if the "submit" button is "update_volunteer" it will update the disaster_volunteers database tab with the volunteer's new information.

/src/Disaster/Opus/TabControls/Users_Manage/VolunteerTab.html

Open the file at /src/Disaster/Opus/TabControls/Users_Manage/VolunteerTab.html, and enter the following contents:

<h3>Volunteer</h3>

<s:function alias="display_form" form="disaster.volunteer" record_id="~user_id~">

This is the HTML contents of the new tab page, and simply displays a HTML form containing the volunteer's information, which we're going to develop out now.

HTML Form

Run the following create form CLI command to create the form class that will be displayed within the tab page:

apex create form disaster volunteer

Open the newly generated file at /src/Disaster/Opus/Forms/Volunteer.php, and at the top within the use declarations add the line:

[data-line=6]
use App\Disaster\Controllers\ProjectController;

Within the properties section of the class inject the ProjectController class. The injection attributes should look like:

[data-line=17]
#[Inject(FormBuilder::class)]
private FormBuilder $builder;

#[Inject(ProjectController::class)]
private ProjectController $proj_controller;

#[Inject(Db::class)]
private Db $db;

getFields() Method

Change the contents of the getFields() method to:

[data-line=42]
public function getFields(array $attr = []):array
{

    // Initialize
    $builder = $this->builder;
    $uuid = $attr['record_id'] ?? '';
    $location_id = 0;

    // Create location options
    if ($uuid != '') { 
        $location_id = $this->db->getField("SELECT location_id FROM disaster_volunteers WHERE uuid = %s", $uuid);
    }
    $loc_options = $this->proj_controller->createLocationOptions((string) $location_id);

    // Set form fields
    $form_fields = [
        'location_id' => $builder->select()->required()->options($loc_options)->label('Location'),
        'profession' => $builder->textbox(),
        'submit' => $builder->submit()->value('update_volunteer')->label('Update Volunteer Details')
    ];

    // Return
    return $form_fields;
}

This simply retrieves the location of the volunteer if a record_id attribute was included within the form HTML tag tag that dispays the form, generates the location options, then creates a HTML form with two fields and a submit button.

getRecord() Method

Change the two apostrophes within the getIdRow() method to "'disaster_volunteers'", so the full method should be:

[data-line=65]
public function getRecord(string $record_id):array
{

    // Get row
    if (!$row = $this->db->getIdRow('disaster_volunteers', $record_id)) { 
        $row = [];
    }

    // Return
    return $row;
}

If the record_id attribute is present within the HTML tag that displays the form, this method will be called and is expected to return an associative array of values to populate the form fields with. For full information on forms, please consult the HTML Forms page of the developer documentation.

Conclusion

If you don't already have a user created, create one via the Users->Create New User menu. You may then manage the user through the Users->Manage User menu, and will see the new "Volunteer" t was developed. It's just before the Log tab as defined within the $position property of the tab page's PHP class, and it displays the HTML form developed allowing the volunteer's information to be updated.