Repeater repeater.js

Data viewer with paging, sorting, and searching. Must use at least one extension to display items. Fuel UX bundles a list view extension and thumbnail view extension, but you can build your own. The following example uses the list and thumbnail extensions.

Awesome Repeater
- of items
Per Page
    of

    Usage

    Because of its reliance upon a dataSource, you must initialize a repeater() via JavaScript:

    
  dataSource = function(options, callback){
    //...
  };

  $('#myRepeater').repeater({dataSource: dataSource});

    Markup

    Use the following markup to setup the repeater:

    
  <div class="repeater" id="myRepeater">
    <div class="repeater-header">
      <div class="repeater-header-left">
        <span class="repeater-title">Awesome Repeater</span>
        <div class="repeater-search">
          <div class="search input-group">
            <input class="form-control" type="search" placeholder="Search"/>
            <span class="input-group-btn">
              <button class="btn btn-default" type="button">
                <span class="glyphicon glyphicon-search"></span>
                <span class="sr-only">Search</span>
              </button>
            </span>
          </div>
        </div>
      </div>
      <div class="repeater-header-right">
        <div class="btn-group selectlist repeater-filters" data-resize="auto">
          <button class="btn btn-default dropdown-toggle" data-toggle="dropdown" type="button">
            <span class="selected-label">&nbsp;</span>
            <span class="caret"></span>
            <span class="sr-only">Toggle Filters</span>
          </button>
          <ul class="dropdown-menu" role="menu">
            <li data-value="all" data-selected="true"><a href="#">all</a></li>
            <li data-value="some"><a href="#">some</a></li>
            <li data-value="others"><a href="#">others</a></li>
          </ul>
          <input class="hidden hidden-field" name="filterSelection" readonly="readonly" aria-hidden="true" type="text"/>
        </div>
        <div class="btn-group repeater-views" data-toggle="buttons">
          <label class="btn btn-default active">
            <input name="repeaterViews" type="radio" value="list"><span class="glyphicon glyphicon-list"></span>
          </label>
          <label class="btn btn-default">
            <input name="repeaterViews" type="radio" value="thumbnail"><span class="glyphicon glyphicon-th"></span>
          </label>
        </div>
      </div>
    </div>
    <div class="repeater-viewport">
      <div class="repeater-canvas"></div>
      <div class="loader repeater-loader"></div>
    </div>
    <div class="repeater-footer">
      <div class="repeater-footer-left">
        <div class="repeater-itemization">
          <span><span class="repeater-start"></span> - <span class="repeater-end"></span> of <span class="repeater-count"></span> items</span>
          <div class="btn-group selectlist" data-resize="auto">
            <button class="btn btn-default dropdown-toggle" data-toggle="dropdown" type="button">
              <span class="selected-label">&nbsp;</span>
              <span class="caret"></span>
              <span class="sr-only">Toggle Dropdown</span>
            </button>
            <ul class="dropdown-menu" role="menu">
              <li data-value="5"><a href="#">5</a></li>
              <li data-value="10" data-selected="true"><a href="#">10</a></li>
              <li data-value="20"><a href="#">20</a></li>
              <li data-value="50" data-foo="bar" data-fizz="buzz"><a href="#">50</a></li>
              <li data-value="100"><a href="#">100</a></li>
            </ul>
            <input class="hidden hidden-field" name="itemsPerPage" readonly="readonly" aria-hidden="true" type="text"/>
          </div>
          <span>Per Page</span>
        </div>
      </div>
      <div class="repeater-footer-right">
        <div class="repeater-pagination">
          <button class="btn btn-default btn-sm repeater-prev" type="button">
            <span class="glyphicon glyphicon-chevron-left"></span>
            <span class="sr-only">Previous Page</span>
          </button>
          <label class="page-label" id="myPageLabel">Page</label>
          <div class="repeater-primaryPaging active">
            <div class="input-group input-append dropdown combobox">
              <input class="form-control" type="text" aria-labelledby="myPageLabel">
              <div class="input-group-btn">
                <button class="btn btn-default dropdown-toggle" data-toggle="dropdown" type="button">
                  <span class="caret"></span>
                  <span class="sr-only">Toggle Dropdown</span>
                </button>
                <ul class="dropdown-menu dropdown-menu-right"></ul>
              </div>
            </div>
          </div>
          <input class="form-control repeater-secondaryPaging" type="text" aria-labelledby="myPageLabel">
          <span>of <span class="repeater-pages"></span></span>
          <button class="btn btn-default btn-sm repeater-next" type="button">
            <span class="glyphicon glyphicon-chevron-right"></span>
            <span class="sr-only">Next Page</span>
          </button>
        </div>
      </div>
    </div>
  </div>

    Optional data attributes

    The repeater must be initialized via JavaScript, however it also accepts some optional data-attributes.

    data-staticheight="true"
    enables staticHeight on initialization.

    Options

    Pass options via JavaScript upon initialization.

    Name type default description
    dataSource function empty function Use this function to provide paging information and data for the repeater. Call this function prior to rendering the current view, passing a options object and callback function. Run the callback function once you gather the appropriate information to complete the rendering. Review more details on using dataSource below.
    dataSourceOptions object null Use this object to pass a parameter to a custom-defined dataSource function mentioned above. Then, use those values to customize the data that gets passed back into the repeater from your API. Suggested uses include sorting, filtering, and search values. This object is also valuable in custom renders when used as an object within the render methods's options parameter. Did you lose your custom dataSourceOptions when you changed the page within repeater? If you did, set preserveDataSourceOptions to true in order to keep them.
    defaultView string or number -1 Specifies the initial view the repeater will render (usually a string value equivalent to the desired repeater view extension). If set to -1, the repeater will check the .repeater-views button group for an .active class, using its input value as the defaultView setting.
    dropPagingCap number 10 Specifies the number of items allowed within the .repeater-primaryPaging drop-down menu. If the number of pages exceeds this amount, the code will use the .repeater-secondaryPaging input.
    preserveDataSourceOptions boolean false Sets whether defineddataSourceOptions get preserved or reset when the dataSource is called. For example, the dataSource function is called when navigating to another page. If you would like to keep previously defined settings such as search or filtering, then set to true. Setting to true is generally recommended when using dataSourceOptions to manipulate your data.
    staticHeight boolean or number -1
    • If true; height of CSS styles applied to repeater element will be used
    • If a positive number; that value will be used as height in pixels
    • If -1; value of data-staticheight attribute will be used if present
    • If false; height will be fluid, not static. Meaning reapeater contents will not be scrollable, and container must be big enough to show everything. Similar to CSS overflow: hidden.
    views object null Can be optionally used to configure multiple views, including those of the same view type (2 'list' views, 2 'thumbnail' views, etc) To utilize, first set the input values within .repeater-views to their appropriate view names. For multiple views of the same type, use the . operator as a separator, following the syntax [viewType].[viewName] (Ex: "list.view1") Then, within the views option object, add these view names as attributes. Each attribute can be an object, with it's own view plugin / repeater configuration. This configuration will then be honored by the repeater per view. Example: 
    
$('#myRepeater').repeater({
  views: {
    'list.view1': {
      dropPagingCap: 20,
      list_infiniteScroll: true,
      list_selectable: 'multi'
    },
    'list.view2': {
      dataSource: function(options, callback){ ... },
      dropPagingCap: 30,
      list_selectable: true
    }
  },
  ...
});

    Methods

    .repeater('clear');
    Clears the repeater of current data. Accepts an optional options object. 
    $('#myRepeater').repeater('clear');
    $('#myRepeater').repeater('clear', {preserve: true});
    Attribute type description
    clearInfinite boolean optional -- if true, preserve must also be set to true to have an effect. If infinite scrolling is enabled, setting to true will clear all non data-preserved elements. Defaults to false.
    preserve boolean optional If true, only items that don't have the data-preserve attribute will be removed. Otherwise, all items will be removed. Defaults to false.
    .repeater('destroy')
    Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
    .repeater('infiniteScrolling');
    Enables or disabled infinite scrolling within the repeater. Used primarily by view extensions. Accepts an optional options object. 
    $('#myRepeater').repeater('infiniteScrolling');
    $('#myRepeater').repeater('infinitescrolling', true, {hybrid: true, percentage: 60});
    Argument type description
    enable boolean If set to true, this function will enable infinite scrolling. Defaults to false.
    options object Optional. Specifies the desired infinite scrolling settings. View the infinite scroll documentation for more details on available features. Your code will ignore the dataSource option on this object in favor of the dataSource on the repeater.
    .repeater('render');
    Calls the dataSource and renders the repeater data. Accepts an optional options object. 
    $('#myRepeater').repeater('render');
    $('#myRepeater').repeater('render', {'changeView': 'widescreen', 'preserve': true});
    Attribute type description
    changeView string If set to a string value, this attribute will change the current repeater view to be rendered. Defaults to undefined.
    clearInfinite boolean Passed to the clear method - see above for description.
    pageIncrement number or null Use a number value to determine the amount by which the current page will increment or decrement. If null the current page will reset to 0.
    preserve boolean Passed to the clear method - see above for description.
    .repeater('resize');
    Resizes the repeater based on staticHeight presence and value

    Data Source

    Call the dataSource function prior to rendering data for the current view. Receives an options object and callback function as arguments. The options object provides context for which data should return. Please review the dataSourceOptions option if the dataSource needs to be manipulated (such as for a custom render, to search, to sort, or to filter). Use the callback to continue onward with rendering.

    The options object can vary in content depending on the view extension used. Many objects share these common attributes in options object format:

    Attribute type description
    filter object Provides context for the selected .repeater-filters drop-down item representing data filtering. The object contains a text attribute for the displayed text and a value attribute for the value of the selected item.
    pageIndex number Represents the current page of data. pageIndex is a zero-based index into an array and may need to be manipulated before requesting more data, if the server request is a one-based index.
    pageSize number Provides context for the selected .repeater-itemization dropdown item value, representing the number of data items to be displayed
    search string Provides context for the entered .repeater-search search box, representing the desired user search value. Only present if the object includes a search value.
    view string Provides context for the selected .repeater-views button group item, representing the current view. Used to determine view-specific return data.

    The dataSource's callback function should run after gathering the desired data for rendering. This function requires the code to pass a data object as an argument. Contents of the object will vary depending on the view extension used. The attributes below include common expected attributes:

    Attribute type description
    count number Provides the number of returned in the data to the repeater. Use this value as the text value for the .repeater-count element.
    end number Provides the end index of current displayed data items to the repeater. Use this value as the text value for the .repeater-end element.
    page number Sets the current repeater page. Also shown in the .repeater-primaryPaging or .repeater-secondaryPaging element. page is 0-based.
    pages number Provides the number of available pages of data to the repeater. Use this value as the text value for the .repeater-pages element. pages is 1-based.
    start number Provides the starting index of current displayed data items to the repeater. Use this value as the text value for the .repeater-start element.

    The default values are { count: 0, end: 0, items: [], page: 0, pages: 1, start: 0 }.

    Events

    Event Type Description
    disabled.fu.repeater Fires whenever the repeater is disabled.
    enabled.fu.repeater Fires whenever the repeater is enabled.
    filtered.fu.repeater Fires whenever the repeater is filtered via the dropdown. Passes a filter value argument.
    nextClicked.fu.repeater Fires whenever the repeater next page button is clicked.
    pageChanged.fu.repeater Fires whenever the repeater page is changed via primary or secondary paging. NOTE: if the paged via primary paging, an array is passed back as a parameter, containing the value and data, respectively. If secondary paging causes the change, only a value is passed as an argument.
    pageSizeChanged.fu.repeater Fires whenever the repeater page size is changed. Passes a value argument.
    previousClicked.fu.repeater Fires whenever the repeater previous page button is clicked.
    rendered.fu.repeater Fires whenever the repeater has rendered data returned from the dataSource. Passses an object containing data, options, and renderOptions.
    resized.fu.repeater Fires whenever the repeater is resized.
    searchChanged.fu.repeater Fires whenever the repeater search control is used.
    viewChanged.fu.repeater Fires whenever the repeater view is switched. Passes the currentView as an argument.

    All repeater events are fired on the .repeater classed element.

    
  $('#myRepeater').on('resized.fu.repeater', function () {
  // do something…
  });

    Fuel UX Dependencies

    Repeater Extensions

    The repeater uses a view framework that allows for extensions to represent data in different ways. By default, Fuel UX comes with two repeater view extensions (list and thumbnail). Each extension provides additional options and requires different return data from the dataSource to render appropriately. For information on using extensions, visit the extensions page. You can also learn how to write your own repeater extension.

    Examples

    Data viewer with paging, sorting, and searching using list and thumbnail extensions. Can be extended further for various other renderings.

    Live examples:

    Further Reading

    Awesome Repeater
    - of items
    Per Page
      of 
      
  <div class="fu-example section">
    <div class="repeater" id="myRepeater" data-staticheight="400">
      <div class="repeater-header">
        <div class="repeater-header-left">
          <span class="repeater-title">Awesome Repeater</span>
          <div class="repeater-search">
            <div class="search input-group">
              <input class="form-control" type="search" placeholder="Search"/>
              <span class="input-group-btn">
                <button class="btn btn-default" type="button">
                  <span class="glyphicon glyphicon-search"></span>
                  <span class="sr-only">Search</span>
                </button>
              </span>
            </div>
          </div>
        </div>
        <div class="repeater-header-right">
          <div class="btn-group selectlist repeater-filters" data-resize="auto">
            <button class="btn btn-default dropdown-toggle" data-toggle="dropdown" type="button">
              <span class="selected-label">&nbsp;</span>
              <span class="caret"></span>
              <span class="sr-only">Toggle Filters</span>
            </button>
            <ul class="dropdown-menu" role="menu">
              <li data-value="all" data-selected="true"><a href="#">all</a></li>
              <li data-value="bug"><a href="#">bug</a></li>
              <li data-value="dark"><a href="#">dark</a></li>
              <li data-value="dragon"><a href="#">dragon</a></li>
              <li data-value="electric"><a href="#">electric</a></li>
              <li data-value="fairy"><a href="#">fairy</a></li>
              <li data-value="fighting"><a href="#">fighting</a></li>
              <li data-value="fire"><a href="#">fire</a></li>
              <li data-value="flying"><a href="#">flying</a></li>
              <li data-value="ghost"><a href="#">ghost</a></li>
              <li data-value="grass"><a href="#">grass</a></li>
              <li data-value="ground"><a href="#">ground</a></li>
              <li data-value="ice"><a href="#">ice</a></li>
              <li data-value="normal"><a href="#">normal</a></li>
              <li data-value="poison"><a href="#">poison</a></li>
              <li data-value="psychic"><a href="#">psychic</a></li>
              <li data-value="rock"><a href="#">rock</a></li>
              <li data-value="steel"><a href="#">steel</a></li>
              <li data-value="water"><a href="#">water</a></li>
            </ul>
            <input class="hidden hidden-field" name="filterSelection" readonly="readonly" aria-hidden="true" type="text"/>
          </div>
          <div class="btn-group repeater-views" data-toggle="buttons">
            <label class="btn btn-default active">
              <input name="repeaterViews" type="radio" value="list"><span class="glyphicon glyphicon-list"></span>
            </label>
            <label class="btn btn-default">
              <input name="repeaterViews" type="radio" value="thumbnail"><span class="glyphicon glyphicon-th"></span>
            </label>
          </div>
        </div>
      </div>
      <div class="repeater-viewport">
        <div class="repeater-canvas"></div>
        <div class="loader repeater-loader"></div>
      </div>
      <div class="repeater-footer">
        <div class="repeater-footer-left">
          <div class="repeater-itemization">
            <span><span class="repeater-start"></span> - <span class="repeater-end"></span> of <span class="repeater-count"></span> items</span>
            <div class="btn-group selectlist" data-resize="auto">
              <button class="btn btn-default dropdown-toggle" data-toggle="dropdown" type="button">
                <span class="selected-label">&nbsp;</span>
                <span class="caret"></span>
                <span class="sr-only">Toggle Dropdown</span>
              </button>
              <ul class="dropdown-menu" role="menu">
                <li data-value="5"><a href="#">5</a></li>
                <li data-value="10" data-selected="true"><a href="#">10</a></li>
                <li data-value="20"><a href="#">20</a></li>
                <li data-value="50" data-foo="bar" data-fizz="buzz"><a href="#">50</a></li>
                <li data-value="100"><a href="#">100</a></li>
              </ul>
              <input class="hidden hidden-field" name="itemsPerPage" readonly="readonly" aria-hidden="true" type="text"/>
            </div>
            <span>Per Page</span>
          </div>
        </div>
        <div class="repeater-footer-right">
          <div class="repeater-pagination">
            <button class="btn btn-default btn-sm repeater-prev" type="button">
              <span class="glyphicon glyphicon-chevron-left"></span>
              <span class="sr-only">Previous Page</span>
            </button>
            <label class="page-label" id="myPageLabel">Page</label>
            <div class="repeater-primaryPaging active">
              <div class="input-group input-append dropdown combobox">
                <input class="form-control" type="text" aria-labelledby="myPageLabel">
                <div class="input-group-btn">
                  <button class="btn btn-default dropdown-toggle" data-toggle="dropdown" type="button">
                    <span class="caret"></span>
                    <span class="sr-only">Toggle Dropdown</span>
                  </button>
                  <ul class="dropdown-menu dropdown-menu-right"></ul>
                </div>
              </div>
            </div>
            <input class="form-control repeater-secondaryPaging" type="text" aria-labelledby="myPageLabel">
            <span>of <span class="repeater-pages"></span></span>
            <button class="btn btn-default btn-sm repeater-next" type="button">
              <span class="glyphicon glyphicon-chevron-right"></span>
              <span class="sr-only">Next Page</span>
            </button>
          </div>
        </div>
      </div>
    </div>
  </div>