Language: ENCN

Search Bar

Search Bar allows user to search through List View elements. Or it can be used as a visual UI component for your custom search realization.

Search Bar Layout

Search Bar should be placed inside of ".page" right before ".page-content":

<div class="page">
    <!-- Search Bar -->
    <form class="searchbar">
        <div class="searchbar-input">
            <input type="search" placeholder="Search">
            <a href="#" class="searchbar-clear"></a>
        </div>
        <a href="#" class="searchbar-cancel">Cancel</a>
    </form>
    
    <!-- Search Bar overlay-->
    <div class="searchbar-overlay"></div>
    
    <!-- Page content -->
    <div class="page-content">
        <div class="content-block searchbar-not-found">
                Nothing found
        </div>
 
        <div class="list-block list-block-search searchbar-found">
            <ul>
                ... list view items ...
            </ul>
        </div>
    </div>
</div>

Where:

  • form class="searchbar" - main search bar wrapper. It is not necessary should be a FORM element, but recommended
    • div class="searchbar-input" - wrapper for search field and Cancel button
      • input type="search" - search field
      • a class="searchbar-clear" - button to clear field value and reset search results. Optional element
    • a class="searchbar-cancel" - Search Bar "Cancel" button that will deactivate Search Bar, reset search results and clear search field. Optional element
  • div class="searchbar-overlay" - Add this element right after search bar to enable dark overlay over page content when search bar is active. Optional element.
  • "list-block-search" - list block where we are going to search elements.
  • "searchbar-found" - element with this class will be displayed if Search Bar find elements that match to search query. Visible by default. Optional element.
  • "searchbar-not-found" - element with this class will be displayed if Search Bar doesn't find elements that match to search query. Hidden by default. Optional element.

Initialize Search Bar with JavaScript

Now, when we have Search Bar' HTML, we need to initialize it. We need to use related App's method:

myApp.searchbar(searchbarContainer, parameters) - initialize Search Bar with options

  • searchbarContainer - HTMLElement or string (with CSS Selector) of Search Bar container HTML element. Required.
  • parameters - object - object with Search Bar parameters. Optional.
  • Method returns initialized Search Bar instance

For example:

var mySearchbar = app.searchbar('.searchbar', {
    searchList: '.list-block-search',
    searchIn: '.item-title'
});   
Note that Search Bar container should be in DOM on a moment of initialization. So if you use it not on home page, you need to initialize it within page:init event or callback

Search Bar Parameters

Let's look on list of all available parameters:

Parameter Type Default Description
searchList string or HTMLElement CSS selector or HTML element of list block to search
searchIn string '.item-title' CSS selector of List View element's field where we need to search. Usually we search through element titles ('.item-title'). It is also to pass few elements for search like '.item-title, .item-text'
found string or HTMLElement CSS selector or HTMLElement of searchbar "found" element. If not specified, searchbar will look for .searchbar-found element on page
notFoud string or HTMLElement CSS selector or HTMLElement of searchbar "not-found" element. If not specified, searchbar will look for .searchbar-not-found element on page
overlay string or HTMLElement CSS selector or HTMLElement of searchbar overlay. If not specified, searchbar will look for .searchbar-overlay element on page
ignore string '.searchbar-ignore' CSS selector for items to be ignored by searchbar and always present in search results
customSearch boolean false When enabled searchbar will not search through any of list blocks specified by `searchList` and you will be able to use custom search functionality, for example, for calling external APIs with search results and for displaying them manually
removeDiacritics boolean false Enable to remove/replace diacritics (á, í, ó, etc.) during search
hideDividers boolean true If enabled, then search will consider item dividers and group titles and hide them if there are no found items right after them
hideGroups boolean true If enabled, then search will consider list view groups hide them if there are no found items inside of these groups
Callbacks
onSearch function (s) Callback function will be triggered during search (search field change).
onEnable function (s) Callback will be triggered when Search Bar becomes active
onDisable function (s) Callback will be triggered when Search Bar becomes inactive - when user clicks on "Cancel" button or on "searchbar-overlay" element
onClear function (s) Callback will be triggered when user clicks on Search Bar's "clear" element

Search Bar Methods & Properties

After we initialize Search Bar we have its initialized instance in variable (like mySearchbar variable in example above) with helpful methods and properties:

Properties
mySearchbar.params Object with passed initialization parameters
mySearchbar.query Current search query (search input value)
mySearchbar.searchList Dom7 element with search list block.
mySearchbar.container Dom7 element with searchbar container HTML element.
mySearchbar.input Dom7 element with searchbar input HTML element
mySearchbar.active Boolean value that represents is searchbar enabled or disabled
Methods
mySearchbar.search(query); Force searchbar to search passed query
mySearchbar.enable(); Enable/activate searchbar
mySearchbar.disable(); Disable/deactivate searchbar
mySearchbar.clear(); Clear search query and update results
mySearchbar.destroy(); Destroy searchbar instance

Initialize Search Bar with HTML

If you don't need to use Search Bar methods and properties you can initialize it using HTML without JavaScript. You can do that just by adding additional "searchbar-init" class to .searchbar. In this case we may pass required parameters using data- attributes.

<div class="page">
    <!-- Search Bar with "searchbar-init" class for auto initialization -->
    <form class="searchbar searchbar-init" data-search-list=".list-block-search" data-search-in=".item-title" data-found=".searchbar-found" data-not-found=".searchbar-not-found">
        <div class="searchbar-input">
            <input type="search" placeholder="Search">
            <a href="#" class="searchbar-clear"></a>
        </div>
        <a href="#" class="searchbar-cancel">Cancel</a>
    </form>
    
    <div class="searchbar-overlay"></div>
    
    <div class="page-content">
        <div class="content-block searchbar-not-found">
                Nothing found
        </div>
 
        <div class="list-block list-block-search searchbar-found">
            <ul>
                ... list view items ...
            </ul>
        </div>
    </div>
</div> 

Parameters that used in camelCase, for example searchList, in data- attributes should be used as hypens-case as data-search-list

Access to Search Bar's Instance

If you initialize Search Bar using HTML it is still possible to access to Search Bar's instance. It is "f7Searchbar" property of searchbar's container HTML element:

var mySearchbar = $$('.searchbar')[0].f7Searchbar;
 
// Now you can use it
mySearchbar.search('Hello world');

Search Bar Example

In this example we use searchbar with auto initialization

<div data-page="home" class="page">
  <!-- Search Bar -->
  <form data-search-list=".list-block-search" data-search-in=".item-title" class="searchbar searchbar-init">
    <div class="searchbar-input">
      <input type="search" placeholder="Search"><a href="#" class="searchbar-clear"></a>
    </div><a href="#" class="searchbar-cancel">Cancel</a>
  </form>
 
  <!-- Search Bar overlay -->
  <div class="searchbar-overlay"></div>
 
  <div class="page-content">
    <!-- This block will be displayed if nothing found -->
    <div class="content-block searchbar-not-found">
      <div class="content-block-inner">Nothing found</div>
    </div>
 
    <!-- This block will be displayed if anything found, and this list block is used a searbar target -->
    <div class="list-block list-block-search searchbar-found">
      <ul>
        <li class="item-content">
          <div class="item-inner">
            <div class="item-title">Acura </div>
          </div>
        </li>
        <li class="item-content">
          <div class="item-inner">
            <div class="item-title">Audi</div>
          </div>
        </li>
        ...
      </ul>
    </div>
  </div>
</div>          

Search Bar JavaScript Events

Event Target Description
searchbar:search List View specified in "data-search-list"<div class="list-block"> Event will be triggered during search (search field change). Event detail contains search query (e.detail.query) and array of found HTML elements (e.detail.foundItems)
searchbar:clear List View specified in "data-search-list"<div class="list-block"> Event will be triggered when user clicks on Search Bar's "clear" element (a href="#" class="searchbar-clear")
searchbar:enable List View specified in "data-search-list"<div class="list-block"> Event will be triggered when Search Bar becomes active
searchbar:disable List View specified in "data-search-list"<div class="list-block"> Event will be triggered when Search Bar becomes inactive - when user clicks on "Cancel" button (a href="searchbar-cancel") or on "searchbar-overlay" element