Dropdowns in JTB_MD are interactive content areas that provide complex or simple data when users interact with an element called a trigger. These content areas aim to fulfill the need for displaying data or showing additional information in your projects while hiding themselves to make the project space-efficient.

Unlike traditional menu-style components, the content of Dropdowns can be anything, offering a dynamic solution for presenting diverse types of information within a compact and customizable space.

How to use

Unlike the conventional approach, JTB_MD takes a unique stance on dropdown elements, treating them as standalone entities linked to a trigger rather than being nested under triggers. While this approach may initially appear different, it brings numerous advantages, significantly impacting data presentation and positioning stages.

By default, all dropdown containers remain hidden behind the main body element during page initialization. To reveal them on the page, users simply need to interact with the corresponding trigger.

Creating & Linking

Creating a dropdown element is straightforward - simply craft an element with the .jtbDropdown class for container, then associate the dropdown with its trigger via adding the dropdown's ID to the trigger using the jtbDropdown attribute.

                    <!-- Trigger of dropdown -->
<button class='jtbButton' jtbDropdown='dd-1'>Click me!</button>

<!-- Dropdown element -->
<span class='jtbDropdown' id='dd-1'>Hello, I'm a dropdown container!</span>

The trigger element can be any type of DOM elements. In this documentation, we've used buttons for better alignment, but in the library, there is no limitation. Adding the jtbDropdown attribute is sufficient to make any element a dropdown trigger.

For a better experience, define your .jtbDropdown elements directly under your body element instead of nesting them into other elements. This helps prevent z-index issues and creates smoother experiences. For more information on z-indexes, check out the Z-index section.

Dropdown elements in JTB_MD serve as versatile containers, capable of housing any type of content. They dynamically position themselves based on their triggers, offering flexibility in both data and style, limited only by your creative imagination.

                    <!-- You can add any content. -->
<span class='jtbDropdown' id='...'>
    ...
</span>

Nesting

Like we've stated in the content section, anything can be included as content in dropdown containers. This rule works with other dropdown triggers too. To create a nested dropdowns, you can simply add their triggers to your desired dropdown containers.

                    <!-- First trigger --> 
<button class='jtbButton' jtbDropdown='dd-1'>Trigger 1</button>

<!-- Dropdown containers & nested triggers -->
<span class='jtbDropdown' id='dd-1'><button class='jtbButton' jtbDropdown='dd-2'>Trigger 2</button></span>
<span class='jtbDropdown' id='dd-2'><button class='jtbButton' jtbDropdown='dd-3'>Trigger 3</button></span>
<span class='jtbDropdown' id='dd-3'><button class='jtbButton' jtbDropdown='dd-4'>Trigger 4</button></span>
<span class='jtbDropdown' id='dd-4'><button class='jtbButton' jtbDropdown='dd-5'>Trigger 5</button></span>
<span class='jtbDropdown' id='dd-5'>No limit...</span>

At this point, it's important to note that dropdown elements have listeners that check whether the user is interacting with other elements in the DOM. If a click is triggered by the user outside of trigger or container, unrelated dropdowns automatically close to provide a smoother user experience. This rule also applies to nested dropdowns. If the user interacts with layer 3 of multi-layer dropdowns, layers 4 and above will close automatically.

Offsetting

To create offset between yout trigger and dropdown container, you can add offset attribute with desired offset in pixels to your .jtbDropdown element.

                    <!-- Dropdown with offset (16px) -->
<span class='jtbDropdown' id='...' offset='16'>...</span>

Positioning

When it comes to positioning containers, JTB_MD leverages the jtbPositioning plugin of the library, which handles all the heavy lifting for you.

During the positioning stage, the plugin seamlessly integrates with two fundamental principles that hold significant value:

Overflow prevention: The plugin automatically adjusts the dropdown containers' size if there is a possibility for an overflow.
Flipping: In cases where overflow prevention is not possible, the plugin strategically positions the container on the optimal edge of the trigger to maximize visibility within the viewport.

With these two principles JTB_MD aims to make dropdowns stay on screen as much as possible and provide a smooth user experience.

To set a default position for your containers, prioritized by the plugin, add the position attribute to your .jtbContainer element and specify the desired side. Possible values are TL | TC | TR | RT | RC | RB | BR | BC | BL | LB | LC | LT where each letter are the first letter of edges.

                    <!-- Dropdown with specified position (TOP - LEFT) -->
<span class='jtbDropdown' id='...' position='BR'>...</span>

Trigger States

To change the stage of dropdown containers, JTB_MD adds or removes .show class into the dropdowns. Likewise, for the triggers, the library adds or removes .open class to them. If you need to differentiate the triggers which are on the open state you can use these classes.

                    <!-- Custom trigger styling for open states -->
<style>
    [jtbDropdown].open{
        background: lightblue;
    }
</style>

Styling

By default dropdown elements are blank containers that has no display attributes or pre-defined styles. However, to make them more inline with the library, .5rem 1rem padding is defined as their initial paddings. To override this or make your dropdowns more stylish, you can simply override this attribute or define your related styling in your elements.

Never forget that you can leverage all classes from the Utilities section to seamlessly integrate elements with your design. However, the following pre-defined classes within dropdowns have been crafted to simplify your design workflow.

Removing Borders

To create a borderless dropdown element, simply apply the .jtbDropdown-borderless class.

                    <!-- Borderless Dropdown -->
<span class='jtbDropdown jtbDropdown-borderless' id='...'>...</span>

Rectangular

To make your dropdown container rectangular (with no border radius), apply the .jtbDropdown-rect class to it.

                    <!-- Rectangular Dropdown -->
<span class='jtbDropdown jtbDropdown-rect' id='...'>...</span>

Javascript Plugin

In JTB_MD, the actions and methods that dropdowns can perform are defined in the jtbDropdown plugin. Ensure that you haven't manually removed it from your project to utilize its functionalities properly.

For detailed information on plugins, refer to the JavaScript section.

Methods

In jtbDropdown plugin of JTB_MD there are three methods available. Instead of letting library automatically handle the work, if you want to do that manually, you can call any of them whenever you want.

Show

To make a specific dropdown visible on your DOM, you can invoke the plugin with the "show" parameter. You can trigger the method as: $(dropdown).jtbDropdown('show', callbackFunction); where:

$(dropdown) represents the dropdown element that you want to make visible,
callbackFunction (optional) stands for the function that you want to call after the visibility fully changed.

                        /*----- To Show hidden dropdown -----*/
$("#dropdownID").jtbDropdown("show");

Hide

To hide a specific dropdown in your DOM, you can invoke the plugin with the "hide" parameter. You can trigger the method as: $(dropdown).jtbDropdown('hide', callbackFunction); where:

$(dropdown) represents the dropdown element that you want to make hidden,
callbackFunction (optional) stands for the function that you want to call after the visibility fully changed.

                        /*----- To Hide visible dropdown -----*/
$("#dropdownID").jtbDropdown("hide");

Toggle

To toggle visibility of a specific dropdown on your DOM (hide if visible and make it visible if hidden), utilize the jtbDropdown() function with the "toggle" parameter. You can trigger the method as: $(dropdown).jtbDropdown('toggle', callbackFunction); where:

$(dropdown) represents the dropdown element that you want to toggle visibility,
callbackFunction (optional) stands for the function that you want to call after the visibility fully changed.

                        /*----- To Toggle visibility of dropdown -----*/
$("#dropdownID").jtbDropdown("toggle");

Callbacks

The jtbDropdown plugin offers two ways to specify a callback function on dropdowns' actions.

Defining Listeners

All the methods that a dropdown perform (show | hide | toggle) has listeners that can be triggered via adding their attributes into .jtbDropdown element.

onShow: An attribute used to define a function that will be triggered after the dropdown becomes visible.
onHide: An attribute used to define a function that will be triggered after the dropdown becomes invisible.
onToggle: An attribute used to define a function that will be triggered after the dropdown changed visibility.

By default, the dropdown elements utilize the toggle method of the plugin to change their visibility when their triggers are clicked. If you define a function for its listener, it will be triggered by the library every time the method is invoked.

                        /*----- Triggering callback via attributes. -----*/
<span class='jtbDropdown' id='...' onToggle='showProcessDone();'>...</span>

Dynamic Callbacks

If you call methods of the plugin manually, you can supply the function name or the function itself into the method as a second parameter.

                        /*----- Toggle Dropdown and callback (Providing Function Name) -----*/
$("#dropdownID").jtbDropdown("toggle", showProcessDone);

/*----- Toggle Dropdown and callback (Providing Function Directly) -----*/
$("#dropdownID").jtbDropdown("toggle", function(){
    alert('Process done boss.');
});

Hello! Hello! Hello! Hello! Hello! Hello! I have no borders I'm rectengular Hello, I'm a dropdown container!