Dropdown

Design

Dropdowns are used to provide access to lesser used, but related actions, to a context. Putting lesser used actions within a dropdown helps to de-clutter the interface.

Example Name Comments
Basic The basic dropdown

Code

API: Unstable
Example Comment Code
The recommended Dropdown trigger is a button. To link a button to its Dropown, add the data-ace-dropdown-trigger attribute with the ID of the Dropdown. No further code is required as the Javascript will initialise automatically. 

                                                                                      <button type="button" class="ace-button" data-ace-dropdown-trigger="IDOFDROPDOWN"><span><span>Dropdown menu</span><span class="ace-icon ace-icon-control-arrowdown"></span></span></button>

                                                                                  <% 
                                                                                  ace.DropdownTrigger(Array(_
                                                                                      "dropdownid", "IDOFDROPDOWN",_
                                                                                      "text", "Dropdown menu"_
                                                                                  )) 
                                                                                  %>

Icon-only buttons can be used as Dropdown triggers. The menu icon is often used in this configuration.

 

                                                                                      <button type="button" class="ace-button ace-button-icon" data-ace-dropdown-trigger="IDOFDROPDOWN"><span><span class="ace-icon ace-icon-control-menu">More actions</span></span></button>

                                                                                  <% 
                                                                                  ace.DropdownTrigger(Array(_
                                                                                      "dropdownid", "IDOFDROPDOWN",_
                                                                                      "type", "icon",_
                                                                                      "icon", "control-menu",_
                                                                                      "iconText", "More actions"_
                                                                                  )) 
                                                                                  %>
12Mb Acrobat PDF

The Dropdown iteself is composed of the dropdown, optional content groups and dropdown menu(s). In its hidden state, the Dropdown should be rendered in the #hidden div at the end of the page, to ensure it does not affect layout.

To set an item's state to active, add the class ace-dropdown-menu-action-active.

 

                                                                                  <div id="triggerIdActive" class="ace-dropdown">
                                                                                    <!-- Style tag added for ACE Doc's example. Remove if you are copying code for use.-->
                                                                                    <div style="display:block; position:initial;" class="ace-dropdown-content">
                                                                                          <div class="ace-dropdown-content-group">
                                                                                                <ul class="ace-dropdown-menu">
                                                                                                      <li class="ace-dropdown-menu-action"><a href="#">Q&amp;A</a>
                                                                                                      </li>
                                                                                                      <li class="ace-dropdown-menu-action ace-dropdown-menu-action-active"><a href="#">Reports</a>
                                                                                                      </li>
                                                                                                      <li class="ace-dropdown-menu-action"><a href="#">Documents</a>
                                                                                                      </li>
                                                                                                </ul>
                                                                                          </div>
                                                                                    </div>
                                                                                  </div>

                                                                                  <%
                                                                                  ace.Dropdown(Array("id", "IDOFDROPDOWN"))
                                                                                    ace.DropdownContent(Array())
                                                                                      ace.DropdownContentGroup(Array())
                                                                                        ace.DropdownMenu(Array())
                                                                                          ace.DropdownMenuAction(Array(_
                                                                                            "text", "Q&A"_
                                                                                          ))
                                                                                          ace.DropdownMenuAction(Array(_
                                                                                            "active", true ,_
                                                                                            "text", "Reports"_
                                                                                          ))
                                                                                          ace.DropdownMenuAction(Array(_
                                                                                            "text", "Documents"_
                                                                                          ))
                                                                                        ace.DropdownMenuEnd
                                                                                      ace.DropdownContentGroupEnd
                                                                                    ace.DropdownContentEnd
                                                                                  ace.DropdownEnd 
                                                                                  %>

Reports

Dropdown content groups can have a heading. Add an H3 with the class ace-dropdown-content-heading above the Dropdown Menu.

Dropdown with disabled content.
Single Dropdown with multiple triggers and dynamic content.

By listening to the 'dropdown-open' event on the dropdown, you can change the content of the dropdown dynamically.

The event object will have a 'relatedTarget' property which is the element that triggered the dropdown opening.

Remember to keep in mind that a dropdown can be opened programmically, in which case it will use the last trigger that opened it as the relatedTarget, or null if it hasn't been opened before.


                                                        (function(){
                                                          document.getElementById('external-trigger').addEventListener('dropdown-open', function(e){
                                                            var triggerElement = e.detail.relatedTarget;
                                                            if(triggerElement){
                                                              document.getElementById('external-trigger-content').innerHTML = "This dropdown was opened by: " + triggerElement.innerHTML
                                                            }
                                                          });
                                                        })();

Most of the time the Dropdown goes in #hidden and the trigger sits elsewhere in the DOM. On some cases it is necessary to render the trigger and dropdown within a single element. In that case, use the special data-ace-dropdown-trigger value ^ to indicate the trigger is opening the parent (^ is pointing up...).

 

                                                                                      <div class="ace-dropdown">
                                                                                            <button type="button" class="ace-button" data-ace-dropdown-trigger="^"><span><span>Trigger</span><span class="ace-icon ace-icon-control-arrowdown"></span></span></button>
                                                                                            <div class="ace-dropdown-content"> 
                                                                                                  <div class="ace-dropdown-content-group">
                                                                                                        <ul class="ace-dropdown-menu">
                                                                                                                  <li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-add-generic"></span> Add</a></li>
                                                                                                                  <li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-action-remove"></span> Remove</a></li>
                                                                                                                  <li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-action-edit"></span> Edit</a></li>
                                                                                                        </ul>
                                                                                                  </div>
                                                                                            </div>
                                                                                      </div>

                                                                                  <%
                                                                                  ace.Dropdown(Array())
                                                                                    ace.DropdownTrigger(Array(_
                                                                                        "dropdownid", "^",_
                                                                                        "text", "Trigger inside dropdown"_
                                                                                    )) 
                                                                                    ace.DropdownContent(Array())
                                                                                      ace.DropdownContentGroup(Array())
                                                                                        ace.DropdownMenu(Array())
                                                                                          ace.DropdownMenuAction(Array(_
                                                                                            "icon", "add-generic",_
                                                                                            "text", "Add"_
                                                                                          ))
                                                                                          ace.DropdownMenuAction(Array(_
                                                                                            "icon", "action-remove",_
                                                                                            "active", true ,_
                                                                                            "text", "Remove"_
                                                                                          ))
                                                                                          ace.DropdownMenuAction(Array(_
                                                                                            "icon", "action-edit",_
                                                                                            "text", "Edit"_
                                                                                          ))
                                                                                        ace.DropdownMenuEnd
                                                                                      ace.DropdownContentGroupEnd
                                                                                    ace.DropdownContentEnd
                                                                                  ace.DropdownEnd 
                                                                                  %>
(boundary element) To set an element as a Dropdown's boundary, add the data-ace-dropdown-bounds attribute. Refer to the full boundary element demo below. 

                                                                                  <div data-ace-dropdown-bounds="true"></div>

If there is an existing element to use, pass through the attribute:


                                                                                  <%
                                                                                  ace.Foo(Array( _
                                                                                    ...
                                                                                    "data-ace-dropdown-bounds", "true", _
                                                                                    ...
                                                                                  ))
                                                                                  %>

Alternatively just write out the markup:


                                                                                  %><div data-ace-dropdown-bounds="true"></div><%

Dropdown inside boundary element

By default, Dropdowns will simply open where they fit within the overall viewport. By specifying an element as the Dropdown's bounding parent, you can keep the dropdown within the boundary of that element. This is useful when:

  • A parent element has overflow, and will cause the dropdown to clip if placed in the wrong place.
  • The design calls for a dropdown to fit within a certain area.
  • A parent element has its own scrolling applied, which may mean that the dropdown opens in a hidden area.

Some ACE components like Dialogs are automatically set as boundary elements for dropdowns, so you don't have to manually specify them.

This content should stay within the boundaries of the parent if possible 

                                <div data-ace-dropdown-bounds="true" class="boundarydropdowndemo">
                                      <div class="ace-dropdown">
                                            <button type="button" class="ace-button" data-ace-dropdown-trigger="^"><span><span>Dropdown</span><span class="ace-icon ace-icon-control-arrowdown"></span></span></button>
                                            <div class="ace-dropdown-content"> 
                                                  <div class="ace-dropdown-content-group">
                                                        <ul class="ace-dropdown-menu">
                                                                  <li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-add-generic"></span> Add</a></li>
                                                                  <li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-action-remove"></span> Remove</a></li>
                                                                  <li class="ace-dropdown-menu-action"><a href="#"><span class="ace-icon ace-icon-action-edit"></span> Edit</a></li>
                                                        </ul>
                                                  </div>
                                                  <div class="ace-dropdown-content-group">This content should stay within the boundaries of the parent if possible
                                                  </div>
                                            </div>
                                      </div>
                                </div>