Neoanthropic Preternatural Murmurings

    @wavevision/dependent-selectbox
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.5 • Public • Published

    Wavevision s.r.o.

    Dependent SelectBox

    CI Coverage Status PHPStan Nette Forms Naja

    Dependent select box component for nette/forms with naja extension on client side.

    Features:

    • strict typed
    • works on any form without customizing its renderer (no need for snippets)
    • supports form containers (unlimited depth, both for select box itself and its parents)
    • TypeScript and Naja powered client side with events emitted so you can attach listeners to them
    • conditional parents (make a form control become a select box's parent when some other control has a certain value)

    Installation

    Use Composer to get the Nette forms component

    composer require wavevision/dependent-selectbox

    Install the client side via Yarn

    yarn add @wavevision/dependent-selectbox

    or npm

    npm install --save @wavevision/dependent-selectbox

    Usage

    Server side

    Create a form that will be an instance of Wavevision\DependentSelectBox\Form\Form.

    If you don't want to / cannot inherit from our base form, just make sure the form you create uses Wavevision\DependentSelectBox\Form\DependentForm trait.

    Your form should also use Wavevision\DependentSelectBox\Form\DependentContainer to have its containers extended with the dependent select box too, however, if you already have your own implementation of Nette\Forms\Container, just make sure the container uses Wavevision\DependentSelectBox\Form\DependentControl trait.

    After this, your form and its containers will be extended with addDependentSelectBox method. This method accepts following arguments:

    Argument Type Description
    $name string name of the control
    $label string label for the control
    ...$parents Nette\Forms\Controls\BaseControl[] list of form controls whom's values will be treated as parent values to get the dependent data

    The method returns an instance of Wavevision\DependentSelectBox\DependentSelectBox.

    The recommended way of using the form is in a Control component.

    use Nette\Application\UI\Control;
    use Nette\Application\UI\Presenter;
    use Wavevision\DependentSelectBox\DependentComponent;
    use Wavevision\DependentSelectBox\DependentData;
    use Wavevision\DependentSelectBox\DependentValues;
    use Wavevision\DependentSelectBox\Form\Form;
    
    class FormComponent extends Control
    {
    
        // add 'loadDependenData' signal and a few utilities
        use DependentComponent;
    
        public function __construct()
        {
            $this->monitor(Presenter::class, function (): void {
                // setup form in component - optionally pass form name (default 'form')
                $this->dependentComponentSetup();
                if ($this->hasReceivedDependentSignal()) {
                    // if 'loadDependenData' signal received, do anything extra we need
                }
            });
        }
    
        protected function createComponentForm(): Form
        {
            // create your form as you are used to
            $form->addDependentSelectBox('name', 'Label', $form['someParentControl'])
                ->setDependentCallback(function (DependentValues $values): DependentData {
                    // get ArrayHash values, if you perfer array, use getRawValues
                    $formattedValues = $values->getValues();
                    $data = new DependentData();
                    if ($formattedValues->someParentControl === 'someDependentValue') {
                        $data->setItems(['firstItem' => 'firstValue']);
                    }
                    return $data;
                })
                // make the select box disabled when no values have been loaded
                ->setDisabledWhenEmpty()
                // if loaded values contain only one item, select it so the user does not have to
                ->setAutoSelectSingleValue()
                // if 'someOtherControl' has 'someValue', treat 'someControl' as parent
                ->addConditionalParent($form['someControl'], $form['someOtherControl'], 'someValue');
            // add form handlers etc.
            return $form;
        }
    }

    NOTE: You can use the form in a Presenter too, the only limitation is that you can only have one dependent form per page like this. If you wrap your form in a component (each using DependentComponent trait), you can then use as many forms on one page as you wish.

    Client side

    There are a few ways of integrating the client side into your project.

    1. Register dependent select box as Naja extension

    import naja from 'naja';
    import DependentSelectBox from '@wavevision/dependent-selectbox';
    
    naja.registerExtension(new DependentSelectBox());
    // add other extensions, initialize etc.

    As mentioned in features, the extension emits events you can attach listeners to.

    Event Description
    dependentSelectBoxLoading fires right after a parent changes and a request to server is being dispatched
    dependentSelectBoxLoaded fires when the data loading is finished

    Listeners for both events will receive a CustomEvent object containing detail with these properties:

    Property Type Description
    form HTMLFormElement the form in which the event has been triggered
    dependentSelectBoxes HTMLSelectElement[] an array of all dependent select boxes in the form

    The first event also contains request property, which is an object containing:

    Property Type Description
    trigger string HTML id of a parent that triggered the request
    values ParentsValues object with current values of parents and filled select boxes (HTML name properties of elements are used as keys)

    The latter one contains response object, in which keys are HTML id attributes of updated select boxes and values are objects with:

    Property Type Description
    disabled boolean select box state
    items string inner HTML of the select box

    Please, refer to Naja docs to find out more about its extensions.

    2. Import bundled version with Naja included

    If you don't use Naja elsewhere in your project an you don't want to set it up, this is your way to go.

    ⚠️ WARNING: This might collide with other Nette AJAX libraries, if used!

    import '@wavevision/dependent-selectbox/dist/dependentSelectBox.all';

    3. Use it directly in a script tag

    For old-school people only 😎.

    <script src="/path/to/assets/dependentSelectBox.all.js"></script>

    Keywords

    none

    Install

    npm i @wavevision/dependent-selectbox

    DownloadsWeekly Downloads

    42

    Version

    3.0.5

    License

    MIT

    Unpacked Size

    244 kB

    Total Files

    22

    Last publish

    Collaborators

    • vitrozsival