v2.8.1
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.
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="$countries" />
data to the component. Note there is no colon before the data attribute and in this case the data is passed as a json encoded string.
<x-bladewind::dropdown
name="country"
data="{{ json_encode($countries) }} />
<x-bladewind::dropdown
name="country2"
placeholder="What is your nationality"
:data="$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="$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>
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="$countries" />
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="$countries" />
<link href="{{ asset('vendor/bladewind/css/flags.css') }}" rel="stylesheet" />
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="$staff" />
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="$countries" />
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;
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" />
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.
The table below shows a comprehensive list of all the attributes available for the Dropdown component.
| 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 | [] | Array of elements to be displayed in the component. This should be an array. See above examples. Ignore this attribute if you prefer to use data instead. |
| data | [] | Json encoded array of elements to be displayed in the component. Ignore this attribute if you prefer to use :data instead.. |
| 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. |
<x-bladewind::dropdown
name="country"
placeholder="What is your nationality"
onselect="confirmSelection"
:data="$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" />
resources > views > components > bladewind > dropdown.blade.phppublic/vendor/bladewind/assets/js/dropdown.js