gromit/oc-popupbuilder-plugin

Controller behavior for building popups

1.1.1 2023-10-03 13:03 UTC

Requires

• php: >=7.2
• composer/installers: ~1.0

MIT

• Sergey Kasyanov

README

Plugin provides PopupController controller behavior for easy creating popups on OctoberCMS backend pages.

Creating popups

Add PopupController behavior to your controller.

use GromIT\PopupBuilder\Behaviors\PopupController;

class MyController extends Controller
{
    public $implement = [
        PopupController::class
    ]; 
    
    public $popupConfig = 'config_popup.yaml'; 
}

You can add multiple configurations.

public $popupConfig = [
    'popup1' => 'config_popup_1.yaml',
    'popup2' => 'config_popup_2.yaml',
]; 

For render open popup button call popupRenderOpenBtn() method from controller.

popupRenderOpenBtn() receives two optional parameters. First is a definition of popup, second is extra data for request-data attribute.

<?= $this->popupRenderOpenBtn('popup1', [
    'modelId'   => 1,
    'paramName' => 'paramValue',
]) ?>

Or you can write html by yourself.

<button class="btn btn-primary"
        data-control="popup"
        data-handler="onOpenPopup"
        data-size="medium"
        data-request-data="popupDefinition: 'popup1', modelId: '1', paramName: 'paramValue'">
    Open popup
</button>

Popup types

PopupController supports 3 types of popups:

• content - popup with static content.

• msg - popup with message like static flash message.

• form - popup with custom form.

Popup config

Common options

Common options for popups of all types:

type is required for every popup config.

openBtnLabel is required for render open popup button.

Msg

Config for msg popup must contain both of these options.

Content

Config for content popup must contain content or contentPartial.

Form

Config for form popup must contain actionOnClick and form options.

If your form popup config has buttons property, ten next properties will be ignored:

• actionBtnLabel
• actionBtnClass
• actionOnClick
• loadIndicator
• confirm
• closeOnSuccess
• successCallback
• requestData

Each element in buttons has these properties:

Overrides

There are methods for the override.

public function getPopupFormModel(string $definition, ?string $modelClass): \October\Rain\Database\Model
{
}

public function getPopupContent(string $definition, ?bool $below = false): ?string
{
}

public function getPopupTitle(string $definition): ?string
{
}

You can use it for override title and content of popups and form model of form popups.

Below param of getPopupContent() is for overriding the contentBelow.

Complex example

Below is example of using PopupController for make simple wizard. For doing this you can use popup id.

# vendor/plugin/controllers/mycontroller/step1_popup.yaml

type: form
openBtnLabel: Start wizard
actionBtnLabel: Submit step1
actionOnClick: onSubmitStep1
form:
    fields:
        first_name:
            label: Name
        last_name:
            label: Surname
popupId: wizard

# vendor/plugin/controllers/mycontroller/step2_popup.yaml

type: form
actionBtnLabel: Submit step2
actionOnClick: onSubmitStep2
inset: true
form:
    fields:
        bio:
            label: Bio

# vendor/plugin/controllers/mycontroller/result_popup.yaml

type: content
content: Will be overriden in controller
inset: true

// vendor/plugin/controllers/MyController.php

use GromIT\PopupBuilder\Behaviors\PopupController;

class MyController extends Controller
{
    public $implement = [
        PopupController::class
    ]; 
    
    public $popupConfig = [
        'step1'        => 'step1_popup.yaml',
        'step2'        => 'step2_popup.yaml',
        'result_popup' => 'result_popup.yaml',
    ];
    
    public function index() {
        
    }
    
    public function onSubmitStep1() {
        // do something with post()
        // #wizard - popupId of step1 popup
        return [
            '#wizard' => $this->popupRender('step2')
        ];
    }
    
    public function onSubmitStep2() {
        // do something with post()
        // #wizard - popupId of step1 popup
        return [
            '#wizard' => $this->popupRender('result_popup')
        ];
    }
    
    public function getPopupContent(string $definition, ?bool $below = false): ?string
    {
        if ($definition === 'result_popup') {
            return '<pre>' . print_r(post(), true) . '</pre>';
        }
        
        return $this->asExtension(PopupController::class)->getPopupContent($definition, $below);
    }
}

<!-- vendor/plugin/controllers/mycontroller/index.htm -->
<?= $this->popupRenderOpenBtn('step1') ?>