Difference between revisions of "Using Bootstrap in Joomla 4"

Latest revision as of 16:46, 25 March 2021

Under Construction

This article or section is in the process of an expansion or major restructuring. You are welcome to assist in its construction by editing it as well. If this article or section has not been edited in several days, please remove this template.
This article was last edited by Ceford (talk| contribs) 5 hours ago. (Purge)

Introduction

Joomla 4 introduces a modular approach for interactive components

• What is a modular approach?
• The functionality is broken down into individual components supported by individual files. There is no one file approach as it was with Bootstrap in Joomla 3. The modular approach is more efficient and offers performance gains (send only the code that is needed instead of delivering everything in case some page will need so component).

Using Interactive Components: Coders

• Load what you need per case! There are helper functions to set up individual components with appropriate arguments.

Using Interactive Components: Non-Coders

• Using components in articles is not so easy because the helper functions cannot be called from an article or custom html module. One possible solution is described at the end of this tutorial.

Bootstrap Components

Please note that as of Joomla Beta7-Dev there appear to be some problems with some of these components!

Alert

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.alert', '.selector');

• The .selector refers to the CSS selector for the alert. You can call this function multiple times with different CSS selectors
• No extra options available

Button

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.button', '.selector');

• The .selector refers to the CSS selector for the button. You can call this function multiple times with different CSS selectors
• No extra options available

Carousel

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.carousel', '.selector', []);

• The .selector refers to the CSS selector for the carousel. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for carousel

Options for the carousel can be:

• interval, number, default:5000, The amount of time to delay between automatically cycling an item. If false, carousel will not automatically cycle.
• keyboard, boolean, default:true Whether the carousel should react to keyboard events.
• pause, string|boolean, hover Pauses the cycling of the carousel on mouseenter and resumes the cycling of the carousel on mouseleave.
• slide, string|boolean, default:false Autoplays the carousel after the user manually cycles the first item. If "carousel", autoplays the carousel on load.

Collapse

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.collapse', '.selector', []);

• The .selector refers to the CSS selector for the collapse. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for collapse

Options for the collapse can be:

• parent, string, default:false If parent is provided, then all collapsible elements under the specified parent will be closed when this collapsible item is shown.
• toggle, boolean default:true Toggles the collapsible element on invocation

Dropdown

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.dropdown', '.selector', []);

• The .selector refers to the CSS selector for the dropdown. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for dropdown

Options for the collapse can be:

• flip, boolean, default:true Allow Dropdown to flip in case of an overlapping on the reference element
• boundary, string, default:scrollParent Overflow constraint boundary of the dropdown menu
• reference, string, default:toggle Reference element of the dropdown menu. Accepts toggle or parent
• display, string, default:dynamic By default, we use Popper for dynamic positioning. Disable this with static

Modal

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.modal', '.selector', []);

• The .selector refers to the CSS selector for the modal. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for modal

Options for the modal can be:

• backdrop, string|boolean default:true Includes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.
• keyboard, boolean default:true Closes the modal when escape key is pressed
• focus, boolean default:true Closes the modal when escape key is pressed

Offcanvas

Notice: as of Beta8-Dev this component is not present in Joomla!

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.offcanvas', '.selector', []);

• The .selector refers to the CSS selector for the offcanvas. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for offcanvas

Options for the offcanvas can be:

• backdrop, boolean, default:true Apply a backdrop on body while offcanvas is open
• keyboard, boolean, default:true Closes the offcanvas when escape key is pressed
• scroll, boolean, default:false Allow body scrolling while offcanvas is open

Popover

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.popover', '.selector', []);

• The .selector refers to the CSS selector for the popover. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for popover

Options for the popover can be:

• animation, boolean, default:true Apply a CSS fade transition to the popover
• container, string|boolean, default:false Appends the popover to a specific element. Eg.: body
• content, string, default:null Default content value if data-bs-content attribute isn't present
• delay, number, default:0 Delay showing and hiding the popover (ms) does not apply to manual trigger type
• html, boolean, default:true Insert HTML into the popover. If false, innerText property will be used to insert content into the DOM.
• placement, string, default:right How to position the popover - auto | top | bottom | left | right. When auto is specified, it will dynamically reorient the popover
• selector, string, default:false If a selector is provided, popover objects will be delegated to the specified targets.
• template, string, default:null Base HTML to use when creating the popover.
• title, string, default:null Default title value if title tag isn't present
• trigger, string, default:click How popover is triggered - click | hover | focus | manual
• offset, integer, default:0 Offset of the popover relative to its target.

Scrollspy

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.scrollspy', '.selector', []);

• The .selector refers to the CSS selector for the scrollspy. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for scrollspy

Options for the Scrollspy can be:

• offset number Pixels to offset from top when calculating position of scroll.
• method string Finds which section the spied element is in.
• target string Specifies element to apply Scrollspy plugin.

Tab

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tabs', '.selector', []);

• The .selector refers to the CSS selector for the tab. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for tab

Options for the Tab can be:

Tooltip

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tooltip', '.selector', []);

• The .selector refers to the CSS selector for the tooltip. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for tooltip

Options for the tooltip can be:

• animation, boolean apply a css fade transition to the popover
• container, string|boolean Appends the popover to a specific element: { container: body }
• delay, number|object delay showing and hiding the popover (ms) - does not apply to manual trigger type If a number is supplied, delay is applied to both hide/show Object structure is: delay: { show: 500, hide: 100 }
• html, boolean Insert HTML into the popover. If false, jQuery's text method will be used to insert content into the dom.
• placement, string|function how to position the popover - top | bottom | left | right
• selector string If a selector is provided, popover objects will be delegated to the specified targets.
• template, string Base HTML to use when creating the popover.
• title, string|function default title value if title tag isn't present
• trigger, string how popover is triggered - hover | focus | manual
• constraints, array An array of constraints - passed through to Popper.
• offset, string Offset of the popover relative to its target.

Toast

Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the javascript part):

\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.toast', '.selector', []);

• The .selector refers to the CSS selector for the toast. You can call this function multiple times with different CSS selectors
• The third argument refers to the options available for toast

Options for the toast can be:

• animation, boolean, deafult:true Apply a CSS fade transition to the toast
• autohide, boolean, deafult:true Auto hide the toast
• delay, number , deafult:5000 Delay hiding the toast (ms)

Using Components in Articles

The HTML mark-up for most components can be included in an article or a module that can itself be included in an article. The snag is that the HTMLHelper call to set up the Javascript support cannot be included there. Here is one possible solution for (mostly) non-coders who do know HTML. The steps involved:

• Create a mod_custom template override.
• Add a mod_custom module containing the component markup and trigger classes.
• Include the module in an article.

The mod_custom template override

• In the Administrator interface go to System → Site Templates → Cassiopeia Details and Files.
• Select Create Overrides → mod_custom → default.php.
• On the line following defined('_JEXEC') or die; add the following code:

$module_class = $params->get('moduleclass_sfx');
if (!empty($module_class))
{
    $classes = explode(' ', $module_class);
    foreach ($classes as $class)
    {
        switch ($class)
        {
          case 'bs-alert':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.alert', '.alert');
            break;
          case 'bs-button':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.button', '.btn');
            break;
          case 'bs-carousel':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.carousel', '.selector', []);
            break;
          case 'bs-collapse':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.collapse', '.selector', []);
            break;
          case 'bs-dropdown':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.dropdown', '.selector', []);
            break;
          case 'bs-modal':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.modal', '.selector', []);
            break;
          case 'bs-offcanvas':
            // Not Found
            //\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.offcanvas', '.btn', []);
            break;
          case 'bs-popover':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.popover', '.btn', []);
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.popover', 'a', []);
            break;
          case 'bs-scrollspy':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.scrollspy', '.selector', []);
            break;
          case 'bs-tab':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tab', '.selector', []);
            break;
          case 'bs-tooltip':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tooltip', '.btn', []);
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tooltip', 'a', []);
            break;
          case 'bs-toast':
            \Joomla\CMS\HTML\HTMLHelper::_('bootstrap.toast', '.selector', []);
            break;
          default:
            // do nothing
        }
    }
}

This code searches for class names set in mod_custom and makes the HTMLHelper call to set up the Javascript support. Note that the last item in each call is a selector that may or may not be used to trigger action. Many of the components are triggered by data attributes in the mark-up and they do not use the selectors here. For some, the selector is needed. For example, it makes sense to use the .btn class and the a tag to trigger Tooltips.

A mod_custom Module for a Modal Component

• Go to Content → Site Modules → New.
• Select the Custom module.
• Fill out the form:
  • Title: Demo Modal
  • In the Position field type in demomodal for use in an article;
  • Module Content: Toggle Editor for plain text entry.
  • Paste in the following code from the Bootstrap documentation:

<h2>Modal</h2>
<!-- Button trigger modal -->
<p><button class="btn btn-primary" type="button" data-bs-toggle="modal" data-bs-target="#exampleModal"> Launch demo modal </button></p>
<!-- Modal -->
<div id="exampleModal" class="modal fade" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h5 id="exampleModalLabel" class="modal-title">Modal title</h5>
<button class="btn-close" type="button" data-bs-dismiss="modal" aria-label="Close"></button></div>
<div class="modal-body">...</div>
<div class="modal-footer">
<button class="btn btn-secondary" type="button" data-bs-dismiss="modal">Close</button> 
<button class="btn btn-primary" type="button">Save changes</button></div>
</div>
</div>
</div>

• • Select the Advanced tab and in the Module Class field enter bs-modal
  • Optional: set Ttitle to Hide to use the H2 in the pasted code.
  • Save and Close (do not worry that the modal looks all wrong in the editor).

Create an Article and Menu Item

• Create a new article, Demo Modal, and in plain text entry mode set the content to

  <div>{loadposition demomodal}</div>
  

• Create a Single Article menu item.
• Test it:

A Modal Component containing a Carousel

• Create a new Custom module with a new Title: Demo Modal Carousel
• Position: demomodalcarousel
• Advance tab → Module Class: bs-modal bs-carousel
• Module Custom content in plain text:

<h2>Modal with Carousel</h2>
<div class="mod-custom custom">
	<!-- Button trigger modal --> 
	<button class="btn btn-primary" type="button" data-bs-toggle="modal" data-bs-target="#exampleModal"> Launch demo modal </button>
</div>
<div id="exampleModal" class="modal fade" style="display: none;" tabindex="-1" aria-hidden="true">
	<div class="modal-dialog" role="document">
		<div class="modal-content">
			<div class="modal-header">
				<button class="close" type="button" data-bs-dismiss="modal" aria-label="Close"> 
					<span aria-hidden="true">×</span> 
				</button>
			</div>
			<div class="modal-body">
				<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="carousel">
					<div class="carousel-indicators">
						<button class="active" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" aria-current="true" aria-label="Slide 1"></button> 
						<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button> 
						<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
					</div>
					<div class="carousel-inner">
						<div class="carousel-item active">
							<img class="d-block w-100" src="images/sampledata/cassiopeia/nasa1-1200.jpg" alt="..." />
							<div class="carousel-caption d-none d-md-block">
								<h5>First slide label</h5>
								<p>Some representative placeholder content for the first slide.</p>
							</div>
						</div>
						<div class="carousel-item">
							<img class="d-block w-100" src="images/sampledata/cassiopeia/nasa2-1200.jpg" alt="..." />
							<div class="carousel-caption d-none d-md-block">
								<h5>Second slide label</h5>
								<p>Some representative placeholder content for the second slide.</p>
							</div>
						</div>
						<div class="carousel-item">
							<img class="d-block w-100" src="images/sampledata/cassiopeia/nasa3-1200.jpg" alt="..." />
							<div class="carousel-caption d-none d-md-block">
								<h5>Third slide label</h5>
								<p>Some representative placeholder content for the third slide.</p>
							</div>
						</div>
					</div>
					<button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev"> 
						<span class="visually-hidden">Previous</span> 
					</button> 
					<button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next"> 
						<span class="visually-hidden">Next</span> 
					</button>
				</div>
			</div>
		</div>
	</div>
</div>

• Create a new Article with <div>{loadposition demomodalcarousel}</div> in the content.
• Create a new single article menu item: Demo Modal Carousel
• Test it: