bladewindUI

Dropdown

This component tried killing two birds with one code by acting as both a form <select>...</select> and well, a dropdown menu. The main difference between this and the BladewindUI Dropmenu component is aesthetics and maybe simplicity. Arguably this component has the most attributes for a reason. A lot is happening but let's dive right in and display a basic dropdown.


Basic dropdown

The data attribute is what really drives the BladewindUI dropdown component. This attribute expects an array to be passed to it. Let's look at the basic structure of such an array using a list of five countries. We will build on this array structure as we go further in this documentation.

                
                <?php
                    $countries = [
                        [ 'label' => 'Benin',         'value' => 'bj' ],
                        [ 'label' => 'Burkina Faso',  'value' => 'bf' ],
                        [ 'label' => 'Ghana',         'value' => 'gh' ],
                        [ 'label' => 'Nigeria',       'value' => 'ng' ],
                        [ 'label' => 'Kenya',         'value' => 'ke' ]
                    ];
                
            

This structure is all you need to render a BladewindUI dropdown. The default array keys used to render the dropdown are label and value.

                
                    <x-bladewind.dropdown 
                        name="country"
                        data="{{ json_encode($countries) }}" />
                
            

 

Change Placeholder Text

                
                    <x-bladewind.dropdown 
                        name="country2"
                        placeholder="What is your nationality"
                        data="{{ json_encode($countries) }}" />
                
            

 

Of course it is not feasible to always rewrite your arrays to use the value and label keys expected by the component. There is a solution. Assuming we changed our array to the structure below.

                
                <?php
                    $countries = [
                        [ 'country' => 'Benin',         'code' => 'bj' ],
                        [ 'country' => 'Burkina Faso',  'code' => 'bf' ],
                        [ 'country' => 'Ghana',         'code' => 'gh' ],
                        [ 'country' => 'Nigeria',       'code' => 'ng' ],
                        [ 'country' => 'Kenya',         'code' => 'ke' ]
                    ];
                
            

We changed our array keys from label and value to country and code. To render the dropdown now, you just need to set the label_key and value_key attributes. Using our array above we will end up with label_key="country" and value_key="code".


                
                    <x-bladewind.dropdown 
                        name="country"
                        label_key="country" 
                        value_key="code"
                        data="{{ json_encode($countries) }}" />
                
            

Just for some perspective, what we are trying to mimick here is the html implementation of a select form element.

                
                    <select name="country"...>
                        <option value="gh">Ghana</option>
                    </select>
                
            

 

Selected a Value By Default

Like with the regular HTML <select> field, it is possible to select a dropdown item by default when the page loads. Useful when editing records.

                
                    <x-bladewind.dropdown 
                        name="country-select"
                        selected_value="gh"
                        placeholder="What is your nationality"
                        data="{{ json_encode($countries) }}" />
                
            

 

With Country Flags

This is just a simple way for users who are displaying list of countries to display flags next to each country name. This implementation was ported from Semantic UI library's flags feature. Flags are rendered using the country's ISO code. Example: Ghana has an ISO code of GH. Nigeria has an ISO code of NG. You will need to specify the flag_key attribute on the dropdown. This should be the name of the key in your array that has the country codes.

Still working with our $countries array from above, our dropdown code will now be

                
                    <x-bladewind.dropdown 
                        name="country"
                        label_key="country" 
                        value_key="code"
                        flag_key="code"
                        data="{{ json_encode($countries) }}" />
                
            


For flags to work you will need to include the following stylesheet. It is deliberately not compiled into the core BladewindUI css because not everyone needs flags. <link href="{{ asset('bladewind/css/flags.css') }}" rel="stylesheet" />

 


With Images

You may wish to include images in your dropdown list. For example, your app allows you to assign tasks to employees. You may want your employee list to have the pictures of each person next to their name. You will need to specify the image_key attribute on the dropdown. This should be the name of the key in your array that has the image urls.

Let us create a new array of employees with the needed information.

                
                <?php
                    $staff = 
                    [
                        [ 
                            'id' => '1001',   
                            'name' => 'Adam Nsiah',             
                            'picture' => '/path/to/the/image/file' 
                        ],
                        [ 
                            'id' => '1005',   
                            'name' => 'Alfred Rowe', 
                            'picture' => '/path/to/the/image/file' 
                        ],
                        [ 
                            'id' => '1002',   
                            'name' => 'Abdul Razak Ibrahim',    
                            'picture' => '/path/to/the/image/file' 
                        ],
                        [ 
                            'id' => '1003',   
                            'name' => 'Michael K. Ocansey',     
                            'picture' => '/path/to/the/image/file' 
                        ],
                        [
                            'id' => '1004',
                            'name' => 'Michael Sarpong',            
                            'picture' => '/path/to/the/image/file' 
                        ],
                    ]
                
            

                
                    <x-bladewind.dropdown 
                        name="staff"
                        label_key="name" 
                        value_key="id"
                        image_key="picture"
                        data="{{ json_encode($staff) }}" />
                
            


 

Searchable Dropdown

Assuming we had a very long list of items in our dropdown, say all countries of the world, or list of employees, it will be tedious to scroll down the list to find what you are looking for. The BladewindUI dropdown has an attribute that makes the component searchable. searchable="true". By default this is turned off.

Let's now increase our list of countries from five to ten. The new array will be

                
                <?php
                    $countries = [
                        [ 'country' => 'Benin',         'code' => 'bj' ],
                        [ 'country' => 'Burkina Faso',  'code' => 'bf' ],
                        [ 'country' => 'Cameroon',      'code' => 'cm' ],
                        [ 'country' => 'Congo',         'code' => 'cd' ],
                        [ 'country' => 'Gambia',        'code' => 'gm' ],
                        [ 'country' => 'Ghana',         'code' => 'gh' ],
                        [ 'country' => 'Ivory Coast',   'code' => 'ci' ],
                        [ 'country' => 'Nigeria',       'code' => 'ng' ],
                        [ 'country' => 'Kenya',         'code' => 'ke' ]
                        [ 'country' => 'Togo',          'code' => 'tg' ],
                    ];
                
            

                
                    <x-bladewind.dropdown
                         name="country4" 
                         searchable="true" 
                         label_key="country" 
                         value_key="code" 
                         flag_key="code" 
                         data="{{ json_encode($countries)}}" />
                
            

 

Onselect Action

Every BladewindUI dropdown component you display creates as part of the dropdown html the following hidden form field <input type="hidden" name="the-input-name-you-provide" />. When you select an item from the dropdown, the hidden input field is updated with the value of what you selected. The value will be whatever you specified as your value_key. When you submit a form that has any BladewindUI dropdown, you can access the value of the dropdown by specifying the name you used on the dropdown. Consider the example below.

                    
                        <form ...>
                        ...
                        <x-bladewind.dropdown name="country" ... />
                        </form>
                    
                

After submitting the form the value of the country dropdown can be accessed using any of the following regular ways Laravel allows you to access data from the request class.

                    
                        $request->get('country');
                        $request->input('country');
                        $request->country;
                    
                


Redirecting to URLs

As stated earlier on in this document, the BladewindUI dropdown component is killing two birds with one code. You may not always need the dropdown for collecting user input. You could use the dropdown as a menu or navigation. In this case you will want the user to be sent to a url when a dropdown item is selected. To achieve this you will need to specify the url_key attribute. This key will need to exist in your data array. When a dropdown item is selected, the url specified for that item will be called. By default urls that point within your app will open in the same browser window. External links will open in a new window.

Our $countries array has been updated with urls to the Wikipedia pages for each country. We then set the url_key attribute on the dropdown. This has automatically turned our dropdown component into a menu and not form <select>.

                    
                    <?php
                        $countries = [
                            [ 
                                'country' => 'Benin',         
                                'code' => 'bj',     
                                'url' => 'https://url-to-wikipedia-page' 
                            ],
                            [ 
                                'country' => 'Burkina Faso',  
                                'code' => 'bf',     
                                'url' => 'https://url-to-wikipedia-page' 
                            ],
                            [ 
                                'country' => 'Cameroon',      
                                'code' => 'cm',     
                                'url' => 'https://url-to-wikipedia-page' 
                            ],
                            [ 
                                'country' => 'Congo',         
                                'code' => 'cd',     
                                'url' => 'https://url-to-wikipedia-page' 
                            ],
                            [ 
                                'country' => 'Gambia',        
                                'code' => 'gm',     
                                'url' => 'https://url-to-wikipedia-page' 
                            ],
                            [ 
                                'country' => 'Ghana',         
                                'code' => 'gh',     
                                'url' => 'https://url-to-wikipedia-page' 
                            ],
                            [ 
                                'country' => 'Ivory Coast',   
                                'code' => 'ci',     
                                'url' => 'https://url-to-wikipedia-page' 
                            ],
                            [ 
                                'country' => 'Nigeria',       
                                'code' => 'ng',     
                                'url' => '#basic' 
                            ],
                            [ 
                                'country' => 'Kenya',         
                                'code' => 'ke',     
                                'url' => 'https://url-to-wikipedia-page' 
                            ],
                            [ 
                                'country' => 'Togo',          
                                'code' => 'tg',     
                                'url' => 'https://url-to-wikipedia-page' 
                            ],
                        ];
                    
                

                    
                        <x-bladewind.dropdown
                            name="country5" 
                            data="{{ json_encode($countries) }}"
                            url_key="url" 
                            flag_key="value" />
                    
                


Appending Selected Value to URL

You can also append the value that was selected by the user to the URL when using the dropdown as a menu by setting append_value_to_url="true". By default this is turned off.

                
                    <x-bladewind.dropdown
                        ...
                        append_value_to_url="true" />
                
            

If you select a country, say Ghana, from the dropdown above you will notice it appends value=gh in the URL. By default we use the key value. To change this to your preferred key, set the attribute append_value_to_url_as.

                
                    <x-bladewind.dropdown
                        ...
                        append_value_to_url="true"
                        append_value_to_url_as="code" />
                
            

Selecting any country from the dropdown above, say Ghana, will now pass code=gh in the URL.

 

Full List Of Attributes

The table below shows a comprehensive list of all the attributes available for the Dropdown component.

IMPORTANT: Projects running Laravel 8 please read this

Option Default Available Values
name bw-dropdown This name is assigned to the hidden input created for the dropdown. The name is then accessed when the dropdown is submitted in a form.
placeholder Select One Default text displayed on the dropdown
onselect blank Custom function to call when an item in the dropdown is selected. This should just be the name of the custom function, without parenthesis. For example assignToProject. The component appends the selected value and label to the function call as assignToProject(value, label)
data [] This should be a json encoded array. See above examples. json_encode($your_array).
value_key value Which key in your array should the dropdown pick its values from.
label_key label Which key in your array should the dropdown pick its values from.
flag_key blank When using the dropdown with flags, which key in your array should the dropdown pick the country ISO codes from. Flags are only rendered using the countries ISO codes.
image_key blank When using the dropdown with images, which key in your array should the dropdown pick its images from.
url_key blank When using the dropdown as a menu, which key in your array should the dropdown pick the URLs from. Internal URLs will open in the same browser window. External URLs will open in a new window.
append_value_to_url false When using the dropdown as a menu you can opt to append selected values to the URL. This is turned off by default.
true false.
append_value_to_url_as value When append_value_to_url="true", selected values are appended to the URL by default as value=value. To append selected values to the URL as a different variable name, set append_value_to_url_as to any string with no spaces.
data_serialize_as blank This is better explained with an example. In a form your dropdown has name="country". When the form is submitted the dropdown's value can be accessed as $request->country. If for some reason you want your dropdown to have its name but pass its value with a different name, set data_serialize_as. Picking up on the example, if we set, data_serialize_as="country_name", when the form is submitted we can access the value of the dropdown as $request->country_name.
required false Determines if an asterisk should be appended to the placeholder text to indicate the field is required.
true false.
selected_value blank Determines which value from the array should be selected by default when the dropdown loads. Useful when editing content. If you want an item in your array whose value=13 to be selected, set selected_value="13".
searchable false Makes the dropdown either searchable or not. A search box is placed above the dropdown items when set to true.
true false.
show_filter_icon false This is just a nifty addition that prepends a filter icon to the placeholder text when set to true.
true false.

 

Dropdown with all attributes defined

                
                    <x-bladewind.dropdown 
                        name="country"
                        placeholder="What is your nationality"
                        onselect="confirmSelection"
                        data="{{ json_encode($countries)}} "
                        value_key="code"
                        label_key="country"
                        flag_key="code"
                        image_key=""
                        url_key=""
                        append_value_to_url=""
                        append_value_to_url_as=""
                        data_serialize_as="country_id"
                        required="true"
                        selected_value="1001"
                        searchable="true"
                        show_filter_icon="false" />
                
            

 

The source file for this component is available in resources > views > components > bladewind > dropdown.blade.php

The javascript source file for this component is available in public/bladewind/assets/js/dropdown.js