README

A lightweight PHP library to generate dynamic Bootstrap modals effortlessly. Customize titles, content, buttons, and attributes programmatically, making it ideal for web applications with reusable and dynamic UI components.

Features

Dynamically create Bootstrap modals.
Customizable titles, body content, and footer buttons.
Fully compatible with Bootstrap 5.
Lightweight and easy to integrate.

Requirements

PHP 8.2 or higher.
Bootstrap 5 CSS and JavaScript files loaded in your project.

Installation

Install via Composer:

composer require ucscode/php-bs-modal

Usage

Here is an example of how to use the library:

Basic Example

require 'vendor/autoload.php';

use Ucscode\HtmlComponent\BsModal\BsModal;
use Ucscode\HtmlComponent\BsModal\BsModalButton;

$modal = new BsModal([
    'title' => 'Welcome Dev',
    'message' => 'This is a bootstrap message',
]);

After that, all you need to do is render it.

echo $modal->render();

That's it. Seriously!

BsModal Methods

NOTE: All the setter method can be called by passing an array to the BsModal instance, using the method name (without the set prefix) as the key

More Examples

$modal = new BsModal([
    'message' => 'This is an example of a modal',
    'closeButton' => false,
    'backdropStatic' => true,
    'closeOnEscape' => false,
    'verticalCenter' => true,
    'size' => 'sm',
    'buttons' => [
      new BsModalButton('Cancel'),
      new BsModalButton('Continue'),
    ]
])

You can dynamically update the modal properties

$modal->setTitle('Dynamic Modal')

$modal->setMessage('<p>This is dynamically generated content.</p>');

Adding or removing buttons

By default:

If true is not passed to the second parameter of BsModal,
If no custom button was added during the new BsModal instantiation,

An Ok button will be automatically added to the modal.

You can remove or add more custom buttons

$button = new BsModalButton();

Configure a button attributes

$configuredButton = new BsModalButton('Save Changes', BsModalButton::TYPE_ANCHOR, [
    'class' => 'btn btn-success',
    'onclick' => 'my_function',
]);

Add the buttons to the modal

$modal
    ->addButton($button)
    ->addButton($configuredButton)
    ->removeButton(0) // remove button at index 0
    ->removeButton($button) // remove the button instance
;

Rendering the modal

You can get the HTML string of the modal by calling the render() method

echo $modal->render();

Since the modal (and buttons) implements Stringable, you can render them directly

echo $modal;

Accessing the elements

The PHP Bootstrap Modal library is powered by UssElement which provides you with many benefits of manipulating the modal.
To access many section of the modal element, you can get the BsModalBuilder instance

$builder = $modal->getBuilder();

To access the modal element itself, you can get the container element from the builder

$modal->getBuilder()->getContainerElement();

BsModal::getElement() method also provides an easy access to the modal container

$modal->getElement();

Modifying element attributes

Since PHP bootstrap modal is composed of UssElements, you can easily query the elements and make significant updates.

$modal->getElement()->setAttribute('data-custom', 'example-value');

You can query DOM sections such as header, body, or footer

$modal->getElement()
    ->querySelector('.modal-header')
        ->getClassList()
            ->add('custom-header-class')
;

$modal->getElement()
    ->querySelector('.modal-body')
        ->setAttribute('id', 'custom-body-id')
;

Or as spoken earlier, you can access sections from the builder directly

$modal->getBuilder()
    ->getFooterElement()
        ->setVisible(false)
;

3. Rendering the Modal

The library generates valid HTML for a Bootstrap modal. You can insert the output into your HTML structure:

<div class="container">
    <?php 
        echo $modal->getTriggerButton()->render(); // The button to open the modal
        echo $modal->render(); // The modal itself
    ?>
</div>

Output Example

<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal">
  Open
</button>

<div class="modal fade" id="exampleModal" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h1 class="modal-title fs-5" id="exampleModalLabel">Modal title</h1>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

Auto Display

By default, the bootstrap modal will be hidden unless triggered by a button.
To automatically display the modal on page load, use the show option

$modal = new BsModal([
  'message' => 'This will display on page load',
  'show' => true,
])

After that, render it on the page using the $modal->render() method

Trigger Events

To trigger events on the modal, you can pass options prefixed with event:

$modal = new BsModal([
  'message' => "This will trigger multiple events",
  'event:show.bs.modal' => 'showFunc',
  'event:hidden.bs.modal' => 'hiddenFunc',
]);

The showFunc and hiddenFunc are functions that should have been defined in the javascript environment.
The process generates javascript event listener syntax similar to the ones below

element.addEventListener('show.bs.modal', showFunc);
element.addEventListener('hidden.bs.modal', hiddenFunc);

If the event values are not valid function names, the event will not be added

License

This library is open-source software licensed under the MIT license.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request with your changes.

Support

For any questions or issues, please open an issue on the GitHub repository.

ucscode / php-bs-modal

Maintainers

Details