voogPagination

voogPagination is a jQuery-based front-end pagination plugin for the Voog CMS. It utilizes Voog's public API (https://www.voog.com/developers/api) and can be used to paginate elements, articles and comments. This plugin is js only, i.e. there are no default themes or CSS styles included.

Getting started

You can either use a package manager or download the latest release from this GitHub repo.

# Bower
bower install --save voogpagination

# NPM
npm install voogpagination

Initializing

<div class="js-paginatedArticles"></div>

<script>
  $(document).ready(function() {
    var settings = {
      parentId: {{page.id}}
    };
    $('.js-paginatedArticles').voogPagination(settings);
  });
</script>

Settings

Option	Type	Default	Description
ajaxErrorHandler	function	null	Called on ajax request errors. See the source and examples for reference.
cachePages	boolean	true	Whether to cache the fetched items.
dateFormatter	function	null	Overrides the itemTemplates function used for date formatting. See examples section for more info.
defaultNotifications	Object	{}	Contains the notification settings. All notifications are rendered inside the messageTemplate.
defaultNotifications.noItems	string	'No items to display.'	Shown when there are no items to render.
defaultNotifications.error	string	'Oops! Something went wrong! <br> Try refreshing the page or check back soon'	Shown as a general error message. May contain html tags.
enablePageUrls	boolean	true	Whether to display pagination queries in the url.
eventNameSpace	string	'.vp'	Used to namespace voogPagination's events.
hashPrefix	string	'page-'	Change the hash prefix. Only applicable if the urlFormat is set to 'hash'.
hashSuffix	string	''	Change the hash suffix. Only applicable if the urlFormat is set to 'hash'.
initClass	string	'voogPagination-initialized'	Html class attribute added to the pagination wrapper on initialization.
itemTemplate	function	null	Takes two aguments - item (either article, comment or element object) and dateFormatter (function). Has to return a string. See the examples section and the source for more info.
itemWrapper	function	null	Useful for when you don't want to override the entire item template, but just want to wrap every item in some html. See the examples section for more info.
itemType	string	'article'	Which type of items to paginate, possible values are: 'article', 'element' and 'comment'.
messageTemplate	function	null	Used for rendering notifications. See the examples section for more info.
navigation	Object	{}	Contains the navigation settings.
navigation.container	string	null	className or id of the container into where the navigation should be rendered. By default, navigation is rendered at the bottom of the items' parent element.
navigation.totalLength	number	9	The total number of navItems to render excluding thr first and last page links.
navigation.edgeLength	number	1	How many edge navitems should be rendered.
parentId	string	null	Id of the page from where the paginated items should be fetched, e.g. your blog id or elements page id. If you do not provide an id, all articles or elements will be fetched.
perPage	number	12	How many items to display per page.
queryKey	string	'page'	Change the query prefix. Only applicable if the urlFormat is set to 'singleQueryVar'.
queryVars	string	null	Useful for filtering and sorting paginated items. See Voog's documentation for all the possible values.
renderItemsOnFirstFetch	boolean	true	Whether to render the paginated items on initialize. You might want to set this to false if you are already rendering the items in your template. See the examples for more info.
requestUrlBuilder	function	null	Used to override defaultRequestUrlBuilder. See the source for more info.
startingPage	number	1	Which page to display at start.
urlFormat	string	'fullQuery'	In which format to display the query portion of the url. Possible values: 'fullQuery', 'singleQueryVar', 'hash'.
useHistoryPushState	boolean	true	Whether to use browsers history push state api to keep reference of previous queries and enable the browsers back and forward button functionality.

Methods

You can call methods through the voogPagination instance. e.g:

$('.js-pagedArticles').voogPagination('goToPage', 4);

Method	Argument	Description
currentInstance		Returns the current voogPagination instance.
goToPage	target: int	Go to page by number.
goToNextPage		Go to the next page.
goToPrevPage		Go to the previous page.
goToFirstPage		Go to the first page.
goToLastPage		Go to the last page.
destroy		Remove all the DOM nodes that were created by the current instance.
refresh		Rerender everything.

Events

Event	Params	Description
beforeUrlUpdate	event, voogPagination, {query, pageNr, urlFormat}	Triggered before updating the url.
afterUrlUpdate	event, voogPagination, {query, pageNr, urlFormat}	Triggered after updating the url.
fetchStart	event, voogPagination, {requestUrl, pageNr}	Triggered before the ajax request.
fetchDone	event, voogPagination, {res, status, xhr}	Triggered in the jQuery ajax done callback.
fetchFail	event, voogPagination, {xhr, status, errorThrown}	Triggered in the jQuery ajax fail callback.
beforeRender	event, voogPagination, params	Triggered before rendering items and nav.
initialized	event, voogPagination	Triggered after the plugin has been initialized.
afterRender	event, voogPagination, params	Triggered after rendering the items and nav.
beforeDestroy	event, voogPagination	Triggered before executing the destroy method.
afterDestroy	event, voogPagination	Triggered after executing the destroy method.

Examples

Paginating articles

<div class="js-paginatedArticles"></div>

<script>
  $(document).ready(function() {
    $('.js-paginatedArticles').voogPagination({
      parentId: {{page.id}},
    });
  });
</script>

Paginating comments

<div class="js-paginatedComments"></div>

<script>
  $(document).ready(function() {
    $('.js-paginatedComments').voogPagination({
      itemType: 'comment',
      parentId: {{article.id}}
    });
  });
</script>

Paginating elements

<div class="js-paginatedItems"></div>

<script>
  $(document).ready(function() {
    $('.js-paginatedItems').voogPagination({
      itemType: 'element',
      parentId: {{page.id}}
    });
  });
</script>

Custom date formatting

Vanilla js

var settings = {
  dateFormatter: function(dateString) {
    var date = new Date(dateString);
    var day = date.getDate();
    var month = date.getMonth() + 1;
    var year = date.getFullYear();
    if (day < 10) {
      day = '0' + day;
    }
    if (month < 10) {
      month = '0' + month;
    }
    return day + '.' + month + '.' + year;
  }
}

With moment.js

var settings = {
  dateFormatter: function(dateString) {
    return moment.utc(item.values.datetime).format('DD.MM.YYYY');
  }
}

Custom notifications

var settings = {
  defaultNotifications: {
    noItems: 'There are no comments yet',
    error: 'Something went bork. <br> Try refreshing the page or check back soon'
  }
}

Ajax error handling

var settings = {
  ajaxErrorHandler: function (renderer, messageTemplate, data) {
    console.log(data);
    renderer(messageTemplate('Some witty and unhelpful error message', 'error'));
  }
}

Custom item templates

A custom template for elements

var settings = {
  itemTemplate: function (item, dateFormatter) {
    var title = '<div class="eventTile_title">' + item.title + '</div>';
    var category = '<div class="eventTile_category">' + item.values.category + '</div>';
    var date = '<div class="eventTile_info">' + dateFormatter(item.values.datetime) + '</div>';
    var location = '<div class="eventTile_location">' + item.values.location + '</div>';
    var button = '<div class="eventTile_button"><a href="' + item.public_url + '">Read more</a></div>';
    var templateString = '<div class="eventTile ' + item.values.category + '">' +
      title +
      category +
      date +
      location +
      button +
      '</div>';
    return templateString;
  }
}

Custom message templates

var settings = 
  messageTemplate = function (message, type) {
    type = type || 'info';
    var typeClass = 'notification-info';
    if (type === 'error') {
      typeClass = 'notification-error';
    }
    var templateString = '<div class="message ' + typeClass + '">' +
      message +
      '</div>';
    return templateString;
  }
}

Wrapping paginated items

var settings = {
  itemWrapper: function (item, index) {
    return '<div class="col-sm-4" data-item-nr="' + index + '">' + item + '</div>';
  }
}

Navigation settings

var settings = {
  navigation: {
    container: '.js-pageNav',
    totalLength: 6,
    edgeLength: 1
  }
}

Sorting and filtering

<div class="catFilter js-eventFilter">
  <label class="catFilter_item" for="category1">
    <input id="category1" type="radio" value="category-1" name="catFilter">
    Category 1
  </label>
  <label class="catFilter_item" for="category2">
    <input id="category2" type="radio" value="category-2" name="catFilter">
    Category 2
  </label>
  <label class="catFilter_item" for="category3">
    <input id="category3" type="radio" value="category-3" name="catFilter">
    Category 3
  </label>
</div>

$('.js-eventFilter input').each(function (index, element) {
  $(element).change(function () {
    // Get current voogPaginations instance
    var paginationInstance = $('.js-pagedItems').voogPagination('currentInstance');

    // Update the settings dynamically
    paginationInstance.options.queryVars = 'q.element.values.category.$matches=' + 
      $(this).val() +
      '&q.element.values.datetime.$gteq=' +
      moment().format('YYYY-MM-DD') +
      '&s=element.values.datetime.$asc';

    // Fetch the first page using the new query vars.
    $('.js-pagedItems').voogPagination('goToFirstPage');
  });
});

Pre rendering in liquid

<div class="events js-paginatedEvents">
  {% elementscontext edicy_model="Event" %}
    {% for event in elements %}
      <div class="eventTile {{ event.category }}">
        <div class="eventTile_title" data-mh="eventTile">{{ event.title }}</div>
        <div class="eventTile_category" data-mh="eventTile">{{ event.category }}</div>
        <div class="eventTile_info" data-mh="eventTile">{{ event.datetime | date: "%Y.%m.%d %H:%M" }}</div>
        <div class="eventTile_button" data-mh="eventTile">
          <a href="{{ event.url }}">Read more</a>
        </div>
      </div>
    {% endfor %}
  {% endelementscontext %}
<div>

<script>
  $(document).ready(function() {
    $('.js-paginatedEvents').voogPagination({
      itemType: 'element',
      parentId: {{page.id}},
      renderItemsOnFirstFetch: false
    });
  });
</script>

Browser support

Browser	Version
Chrome	Latest
Firefox	Latest
IE	10+
Edge	Latest
Safari	6.1

Dependencies

jQuery 1.7

License

Copyright (c) 2017 Mats-Joonas Kulla

Licensed under the MIT license.