Фильтруемый виджет

Фильтруемый виджет

Фильтруемый виджет позволяет фильтровать потомков элемента. Фильтрация выполняется путём применения класса ui-screen-hidden к тем потомкам, для которых функция обратного вызова фильтра, предоставленная через параметр виджета filterCallback, возвращает true.

Обратная совместимость

Фильтруемый виджет является обобщением расширения фильтра виджета listview , которое было доступно в jQuery Mobile 1.3. Он сохраняет совместимость API с фильтром listview. Его поведение также сделано совместимым с предыдущими версиями благодаря следующим устаревшим функциям:

• Если для фильтруемого виджета не предоставлен источник через атрибут data-input, он сгенерирует текстовое поле и разместит его перед элементом.
• Он предоставляет параметр filterPlaceholder, который устанавливает атрибут placeholder на сгенерированное текстовое поле.
• Он предоставляет параметр filterTheme, который устанавливает параметр theme на сгенерированное текстовое поле.
• Если на элементе, чьи потомки должны быть отфильтрованы, инициализирован виджет collapsibleset, selectmenu, controlgroup или listview, он синхронизирует параметры этих виджетов с сгенерированным текстовым полем, которое также предоставляет виджет текстового поля (например, такие параметры, как "corners" или "mini").
• Он обеспечивает специальную обработку для списков:
  • При фильтрации элементов списка виджет по умолчанию не будет скрывать элементы списка, помеченные как разделители, но
  • При фильтрации элементов списка виджет включает параметр hidedividers виджета списка, что приводит к автоматическому скрытию разделителей в категориях, где все элементы скрыты, благодаря новому расширению hidedividers.
  Вместе эти два поведения воспроизводят поведение фильтра списка jQuery Mobile 1.3.

Настройка

Чтобы сделать потомков элемента фильтруемыми, выполните следующие действия:

1. Создайте элемент, который будет служить источником для фильтруемого виджета. Это может быть любой элемент, который генерирует сигнал change и имеет значение, которое можно получить с помощью плагина jQuery .val(). Обычно это текстовое поле. Виджет реагирует на сигнал change , читая значение поля ввода после небольшой задержки и итерируя по всем потомкам, чтобы определить, следует ли их отображать или скрывать в соответствии с функцией обратного вызова фильтра, предоставленной.
2. Добавьте атрибут data-filter="true" к элементу, чьи потомки будут отфильтрованы.
3. Добавьте атрибут data-input к элементу, чьи потомки будут отфильтрованы. Значение атрибута — строка, содержащая селектор jQuery, который вернёт элемент, используемый в качестве источника фильтруемого виджета.
4. Добавьте дочерние элементы, которые будут отфильтрованы. Вы можете добавлять или удалять дочерние элементы в любое время, однако, когда вы добавляете или удаляете дочерние элементы, вы должны вызвать метод refresh на фильтруемом виджете, чтобы гарантировать, что новые потомки отображаются или скрываются в соответствии с последним введённым значением.

   Дочерние элементы могут иметь атрибут data-filtertext. В этом случае функция обратного вызова фильтра по умолчанию будет скрывать заданный дочерний элемент только в том случае, если значение атрибута data-filtertext не содержит введенную пользователем строку. Если атрибут data-filtertext отсутствует, дочерний элемент будет скрыт, если его текстовое содержимое не содержит введенной пользователем строки.

<form>
  <input type="text" data-type="search" id="filterable-input">
</form>
<form data-role="controlgroup" data-filter="true" data-input="#filterable-input">
  <label for="pizza">
    Pizza
    <input type="checkbox" id="pizza">
  </label>
  <label for="goulash">
    Goulash
    <input type="checkbox" id="goulash">
  </label>
  <label for="falafel">
    Falafel
    <input type="checkbox" id="falafel">
  </label>
  <label for="spring-rolls">
    Spring Rolls
    <input type="checkbox" id="spring-rolls">
  </label>
</form>

Режим "Показать"

Нормальное начальное состояние фильтруемого виджета — все потомки отображаются. В отличие от этого, фильтруемый виджет в режиме "Показать" изначально скрывает всех своих потомков. Однако, как только пользователь начинает фильтрацию, фильтруемый виджет отобразит только тех потомков, которые содержат введённый пользователем текст, независимо от того, находится ли фильтруемый виджет в режиме "Показать" или нет.

Чтобы включить режим "Показать", добавьте атрибут data-filter-reveal="true" к элементу, чьи потомки будут отфильтрованы.

Пример ниже иллюстрирует поведение фильтруемого виджета в режиме "Показать":

<form>
  <input type="text" data-type="search" id="filterable-input">
</form>
<form data-role="controlgroup" data-filter-reveal="true" data-filter="true" data-input="#filterable-input">
  <label for="pizza">
    Pizza
    <input type="checkbox" id="pizza">
  </label>
  <label for="goulash">
    Goulash
    <input type="checkbox" id="goulash">
  </label>
  <label for="falafel">
    Falafel
    <input type="checkbox" id="falafel">
  </label>
  <label for="spring-rolls">
    Spring Rolls
    <input type="checkbox" id="spring-rolls">
  </label>
</form>

Пользовательские фильтры

Параметр filterCallback фильтруемого виджета позволяет задать пользовательскую функцию обратного вызова. В примере ниже элементы фильтруются по их порядковому номеру, который можно указать с использованием соглашений о печати страниц, таких как "1,2" или "4-9", или оба ("1,2,4-9,12").

$.mobile.filterable.prototype.options.filterCallback = function( index, searchValue ) {
  var idx;
 
  if ( searchValue ) {
    searchValue = searchValue.split( "," );
    searchValue = $.map( searchValue, function( element ) {
      var ar = element.split( "-" );
        return ar.length === 1 ? parseInt( element ) :
          [ [ parseInt( ar[ 0 ] ), parseInt( ar[ 1 ] ) ] ];
    });
    for ( idx = 0 ; idx < searchValue.length ; idx++ ) {
      if ( ( $.type( searchValue[ idx ] ) === "number" &&
          index === searchValue[ idx ] ) ||
        ( $.type( searchValue[ idx ] ) === "array" &&
          index >= searchValue[ idx ][ 0 ] &&
          index <= searchValue[ idx ][ 1 ] ) ) {
        return false;
      }
    }
  }
 
  return !!searchValue;
};

Фильтруемый виджет выполняет фильтрацию по своим потомкам при инициализации, чтобы гарантировать, что начальный список отображаемых потомков соответствует начальному значению источника ввода. Установив атрибут data-enhanced="true", вы указываете фильтруемому виджету, что начальная фильтрация не должна выполняться. Это означает, что вы должны применить класс ui-screen-hidden к любым потомкам, которые должны быть изначально скрыты из-за начального значения поля поиска.

Примечание: Если элемент, чьи потомки должны быть отфильтрованы, также улучшен другим виджетом, например, listview или controlgroup, то вам необходимо предоставить предварительно отрендеренную разметку и для другого виджета, поскольку атрибут data-enhanced="true" повлияет на поведение инициализации и другого виджета.

В примере ниже предоставлена предварительно отрендеренная разметка для фильтруемого виджета. Атрибут data-filter-reveal="true" явно указан, поскольку присутствие класса ui-screen-hidden у всех потомков указывает на то, что они изначально скрыты. Виджет controlgroup, содержащий потомков, также предварительно отрендерен, поскольку атрибут data-enhanced="true" применим к виджету controlgroup в той же мере, как и к фильтруемому виджету.

<form>
  <input id="pre-rendered-filterable" data-type="search">
</form>
<div
  class="ui-controlgroup ui-controlgroup-vertical ui-corner-all"
  data-role="controlgroup"
  data-filter="true"
  data-input="#pre-rendered-filterable"
  data-filter-reveal="true"
  data-enhanced="true">
  <div class="ui-controlgroup-controls">
    <a href="index.html" class="ui-screen-hidden" data-role="button">General</a>
    <a href="settings.html" class="ui-screen-hidden" data-role="button">Settings</a>
    <a href="advanced.html" class="ui-screen-hidden" data-role="button">Advanced</a>
    <a href="notifications.html" class="ui-screen-hidden" data-role="button">Notifications</a>
  </div>
</div>