README

Dialogs for Jaxon

Modals, alerts and confirmation dialogs for Jaxon with various javascript libraries.

Features

This package provides modal, alert and confirmation dialogs to Jaxon applications with various javascript libraries. 12 libraries are currently supported.

The javascript library to use for each function is chosen by configuration, and the package takes care of loading the library files into the page and generating the javascript code.

The URL and version number can be set individually for each javascript library.

Installation

Add the following lines in the composer.json file, and run the composer update command.

"require": {
    "jaxon-php/jaxon-core": "^5.3",
    "jaxon-php/jaxon-dialogs": "^5.1"
}

Configuration

This package defines 3 config options in the app.dialogs.default section to set the default library to be used.

modal: the default library for modal dialogs
alert: the default library for alerts
confirm: the default library for questions

The app.dialogs.confirm section defines options for the confirm dialog.

The app.dialogs.lib.use option allows to load additional libraries into the page, if they are used in the application.

The app.dialogs.lib.uri option defines the URI where to download the libraries files from.

Specific options can also be set for each library.

    'dialogs' => [
        'default' => [
            'modal' => 'bootstrap',  // Default library for modal dialogs
            'alert' => 'jconfirm', // Default library for alerts
            'confirm' => 'noty',    // Default library for questions
        ],
        'lib' => [
            'uri' => 'https://cdn.jaxon-php.org/libs',
            'use' => ['cute', 'toastr'], // Additional libraries in use
        ],
        // Confirm options
        'confirm' => [
            'title' => 'Confirm',   // The confirm dialog
            'yes' => 'Oh Yes',       // The text of the Yes button
            'no' => 'No way',        // The text of the No button
        ],
        // Options for the Toastr library
        'toastr' => [
            'options' => [
                'closeButton' => true,
                'positionClass' => 'toast-top-center'
            ],
        ],
        // Load a different version of the JQuery Confirm library from a different CDN
        'jconfirm' => [
            'uri' => 'https://cdnjs.cloudflare.com/ajax/libs',
            'subdir' => 'jquery-confirm',
            'version' => '3.3.2',
        ],
    ],

Usage

Modal dialogs

This plugin provides functions to show and hide modal dialogs, with a title, a content and zero or more buttons.

/**
 * Show a modal dialog.
 */
public function show($title, $content, array $buttons, array $options = []);

/**
 * Hide the modal dialog.
 */
public function hide();

The parameters of the show() methods are described as follow:

$title: is a one line text to be printed at the top of the dialog.
$content: the HTML content of the dialog.
$buttons: a list of buttons to be printed in the dialog. Each button is an array with the following entries:
- title: the text to be printed in the button.
- class: the CSS class or classes to be applied on the button.
- click: the javascript code to be executed on a click on this button. It can be defined using the Call Factory, or it can be set to close to close the dialog.
$options: an array of config options that are specific to the javascript library in use.

Example.

    public function showDialog()
    {
        // The dialog buttons
        $buttons = [[
            'title' => 'Close',
            'class' => 'btn',
            'click' => 'close'
        ]];
        // The HTML content of the dialog
        $content = "This modal dialog depends on application settings!!";
        // The dialog specific options
        $options = ['width' => 500];
        // Show the dialog
        $this->response()->dialog->show("Modal Dialog", $content, $buttons, $options);
    }

Alerts or notifications

This plugin provides functions to show 4 different types of alerts or notification messages.

/**
 * Print a success message.
 */
public function success($message, $title = null);

/**
 * Print an information message.
 */
public function info($message, $title = null);

/**
 * Print a warning message.
 */
public function warning($message, $title = null);

/**
 * Print an error message.
 */
public function error($message, $title = null);

Example.

    public function save($formValues)
    {
        if(!$this->validator->valid($formValues))
        {
            $this->response()->dialog->title("Error")->error("Invalid input");
            return;
        }
        $this->repository->save($formValues);
        $this->response()->dialog->title("Success")->success("Data saved!");
    }

Confirmation question

The confirm() function adds a confirmation question to a Jaxon request, which will then be called only if the user answers yes to the given question.

/**
 * Add a confirmation question to the request
 */
public function confirm($question, ...);

The first parameter, which is mandatory, is the question to ask.

The next parameters are optional; they allow the insertion of content from the web page in the confirmation question, using Jaxon or jQuery selectors and positional placeholders. They are specially useful when pieces of information from the web page need to be inserted in translated strings.

In the example below, the user has to choose a color, and the selected color is inserted in the confirmation question.

Example with Jaxon selector.

<select class="form-control" id="colorselect" name="colorselect" onchange="<?php
    echo rq('HelloWorld')->setColor(je('colorselect')->rd()->select())
        ->confirm('Set color to {1}?', je('colorselect')->rd()->select()) ?>; return false;">
    <option value="black" selected="selected">Black</option>
    <option value="red">Red</option>
    <option value="green">Green</option>
    <option value="blue">Blue</option>
</select>

Example with jQuery selector.

<select class="form-control" id="colorselect" name="colorselect" onchange="<?php
    echo rq('HelloWorld')->setColor(jq('#colorselect')->val())
        ->confirm('Set color to {1}?', jq('#colorselect')->val()) ?>; return false;">
    <option value="black" selected="selected">Black</option>
    <option value="red">Red</option>
    <option value="green">Green</option>
    <option value="blue">Blue</option>
</select>

Supported libraries

This package currently supports the following javascript libraries, each implementing one or more interfaces.

Alertify

https://alertifyjs.com/

Dialog id: alertify
Implements: Modal, Alert, Confirm
Version: 1.14.0

Bootbox

https://bootboxjs.com/

Dialog id: bootbox
Implements: Modal, Alert, Confirm
Version: 6.0.0

Bootstrap 5

https://getbootstrap.com/docs/5.2/components/modal/

Dialog id: bootstrap5
Implements: Modal

Bootstrap 4

https://getbootstrap.com/docs/4.0/components/modal/

Dialog id: bootstrap4
Implements: Modal

Bootstrap 3

https://nakupanda.github.io/bootstrap3-dialog/

Dialog id: bootstrap3
Implements: Modal, Alert, Confirm
Version: 1.35.4

Butterup

https://butteruptoast.com

Dialog id: butterup
Implements: Alert, Confirm

CuteAlert

https://github.com/gustavosmanc/cute-alert/

Dialog id: cute
Implements: Alert, Confirm

IziToast

https://marcelodolza.github.io/iziToast/

Dialog id: izitoast
Implements: Alert, Confirm

jAlert

https://htmlguyllc.github.io/jAlert/

Dialog id: jalert
Implements: Alert, Confirm
Version: 4.9.1

JQuery-Confirm

https://craftpip.github.io/jquery-confirm/

Dialog id: jconfirm
Implements: Modal, Alert, Confirm
Version: 3.3.4

Notify

https://notifyjs.jpillora.com/

Dialog id: notify
Implements: Alert
Versions: 0.4.1

Noty

https://ned.im/noty/

Dialog id: noty
Implements: Alert, Confirm
Version: 3.1.4

Notyf

https://carlosroso.com/notyf/

Dialog id: notyf
Implements: Alert, Confirm

Quantum

https://quantumalert.cosmogic.com/

Dialog id: quantum
Implements: Alert, Confirm

Sweet Alert

Sweet Alert: https://sweetalert.js.org/

Dialog id: sweetalert
Implements: Alert, Confirm
Version: 2.1.2

Tingle

https://tingle.robinparisi.com/

Dialog id: tingle
Implements: Modal
Version: 0.16.0

Toastr

https://codeseven.github.io/toastr/

Dialog id: toastr
Implements: Alert
Version: 2.1.4

Adding a new library

Adding a new javascript library to the Dialogs plugin requires to provides some javascript and PHP code. Depending on the features in the library, the javascript code needs to implement functions to show dialog windows, alert messages or confirm questions. The required PHP class only implements functions to load the javascript code into the web page.

The javascript code

The jaxon.dialog.register() function of the Jaxon javascript library registers a new dialog library into the web application. It must be provided with the dialog library unique name and a callback returning a javascript object with one or more of the above functions.

    /**
     * Show the modal dialog
     *
     * @param {object} dialog The dialog parameters
     * @param {string} dialog.title The dialog title
     * @param {string} dialog.content The dialog HTML content
     * @param {array} dialog.buttons The dialog buttons
     * @param {array} dialog.options The dialog options
     * @param {function} cbDomElement A callback to call with the DOM element of the dialog content
     *
     * @returns {object}
     */
    self.show = ({ title, content, buttons, options }, cbDomElement) => {
        //
    };

The cbDomElement callback is very important. The Jaxon library needs to parse any HTML code inserted in the page, in order to process its custom attributes. This callback does that, and thus needs to be provided with the root HTML element inserted in the page when showing the dialog window.

    /**
     * Hide the modal dialog
     *
     * @returns {void}
     */
    self.hide = () => {
        //
    };

    /**
     * Show an alert message
     *
     * @param {object} alert The alert parameters
     * @param {string} alert.type The alert type
     * @param {string} alert.message The alert message
     * @param {string} alert.title The alert title
     *
     * @returns {void}
     */
    self.alert = ({ type, message, title }) => {
        //
    };

    /**
     * Ask a confirm question to the user.
     *
     * @param {object} confirm The confirm parameters
     * @param {string} confirm.question The question to ask
     * @param {string} confirm.title The question title
     * @param {object} callback The confirm callbacks
     * @param {callback} callback.yes The function to call if the answer is yes
     * @param {callback=} callback.no The function to call if the answer is no
     *
     * @returns {void}
     */
    self.confirm = ({ question, title }, { yes: yesCb, no: noCb = () => {} }) => {
        //
    };

Note: the js/ dir in this repo contains the javascript codes for the already supported dialog libraries.

The abstract PHP class

The PHP class must extend the Jaxon\Dialogs\Dialog\AbstractLibrary abstract class, and implement at least one of the Jaxon\App\Dialog\Library\AlertInterface, Jaxon\App\Dialog\Library\ConfirmInterface, or Jaxon\App\Dialog\Library\ModalInterface interfaces, depending on the features it provides.

The Jaxon\Dialogs\Dialog\AbstractLibrary abstract class implements the Jaxon\Dialogs\Dialog\LibraryInterface interface, and provides default implementations for the methods it defines.

The public function getName(): string method returns the unique name of the dialog library. It will namely be used in the config options to identify the library.

The public function getBaseUrl(): string method returns a base URL for the library javascript and CSS files. The public function helper() returns a helper which implements defaults for the class functions. These two methods are not part of the Jaxon\Dialogs\Dialog\LibraryInterface interface.

The public function getCssUrls(): array method returns an array of URLs to the library CSS files. Its default implementation returns the values in the protected $aCssFiles property, prefixed with the getBaseUrl() value.

The public function getCssCode(): string method returns raw CSS code for the dialog library, without the <style> tag. Its default implementation returns an empty string.

The public function getJsUrls(): array method returns an array of URLs to the library javascript files. Its default implementation returns the values in the protected $aJsFiles property, prefixed with the getBaseUrl() value.

The public function getJsCode(): string method returns raw javascript code for the dialog library, without the <script> tag. Its default implementation returns the content of the dialog library file in the js/ dir in the repository.

The public function getJsOptions(): array method returns an array of custom javascript options for the dialog library. Its default implementation returns the values defined in the Dialogs plugin options, as decribed above.

The other interfaces

Depending on the javascript library features, the class must implement one or more of the following three interfaces. These interfaces are empty, and thay just give an indication of which features are implemented by the library.

For windows and modal dialogs.

interface ModalInterface
{
}

For notifications alerts.

interface AlertInterface
{
}

For confirmation questions.

interface ConfirmInterface
{
}

Helper

The Jaxon\App\Dialog\Library\AbstractDialogLibrary base class provides default implementations for some methods of the Jaxon\App\Dialog\Library\LibraryInterface interface, as well as a Jaxon\App\Dialog\Library\DialogLibraryHelper object, returned by the helper() method, which gives access to the dialog config options, and templates.

Registration

After it is defined, the library class needs to be configured and registered before it can be used in the application.

The class can be registered when starting the library.

use function Jaxon\Dialogs\dialog;

dialog()->registerLibrary(\Path\To\My\Plugin::class, 'myplugin');

Or declared in the dialog section of the Jaxon configuration.

    'dialogs' => [
        'default' => [
            'modal' => 'myplugin', // Default library for modal dialogs
            'alert' => 'myplugin', // Default library for alerts
            'confirm' => 'myplugin', // Default library for confirm questions
        ],
        'lib' => [
            'ext' => [
                'myplugin' => \Path\To\My\Plugin::class,
            ],
        ],
        'myplugin' => [         // Plugin config options
            'options' => [
               'position' => 'center',
            ],
        ],
    ],

Contribute

Issue Tracker: github.com/jaxon-php/jaxon-dialogs/issues
Source Code: github.com/jaxon-php/jaxon-dialogs

License

The package is licensed under the BSD license.

jaxon-php / jaxon-dialogs

Maintainers

Package info

Statistics

Security