{"id":19730512,"url":"https://github.com/begriffs/angular-paginate-anything","last_synced_at":"2025-04-13T07:46:56.467Z","repository":{"id":13468192,"uuid":"16158132","full_name":"begriffs/angular-paginate-anything","owner":"begriffs","description":"À la carte server-side pagination ","archived":false,"fork":false,"pushed_at":"2020-01-27T17:05:21.000Z","size":227,"stargazers_count":516,"open_issues_count":15,"forks_count":69,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-03-28T04:15:13.412Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/begriffs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-23T01:10:19.000Z","updated_at":"2025-03-23T13:09:28.000Z","dependencies_parsed_at":"2022-07-30T15:08:08.752Z","dependency_job_id":null,"html_url":"https://github.com/begriffs/angular-paginate-anything","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begriffs%2Fangular-paginate-anything","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begriffs%2Fangular-paginate-anything/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begriffs%2Fangular-paginate-anything/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begriffs%2Fangular-paginate-anything/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/begriffs","download_url":"https://codeload.github.com/begriffs/angular-paginate-anything/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247123106,"owners_count":20887261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T00:16:36.972Z","updated_at":"2025-04-04T05:08:02.557Z","avatar_url":"https://github.com/begriffs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"img/paginate-anything-logo.png\" alt=\"Logo\" align=\"right\" /\u003e\n## Angular Directive to Paginate Anything\n[![Build Status](https://travis-ci.org/begriffs/angular-paginate-anything.png?branch=master)](https://travis-ci.org/begriffs/angular-paginate-anything)\n\nAdd server-side pagination to any list or table on the page. This\ndirective connects a variable of your choice on the local scope with\ndata provied on a given URL. It provides a pagination user interface\nthat triggers updates to the variable through paginated AJAX requests.\n\nPagination is a distinct concern and should be handled separately from\nother app logic. Do it right, do it in one place. Paginate anything!\n\n### [DEMO](http://begriffs.github.io/angular-paginate-anything/)\n\n### Usage\n\nInclude with bower\n\n```sh\nbower install angular-paginate-anything\n```\n\nThe bower package contains files in the ```dist/```directory with the following names:\n\n- angular-paginate-anything.js\n- angular-paginate-anything.min.js\n- angular-paginate-anything-tpls.js\n- angular-paginate-anything-tpls.min.js\n\nFiles with the ```min``` suffix are minified versions to be used in production. The files with ```-tpls``` in their name have the directive template bundled. If you don't need the default template use the ```angular-paginate-anything.min.js``` file and provide your own template with the ```templateUrl``` attribute.\n\nLoad the javascript and declare your Angular dependency\n\n```html\n\u003cscript src=\"bower_components/angular-paginate-anything/dist/angular-paginate-anything-tpls.min.js\"\u003e\u003c/script\u003e\n```\n\n```js\nangular.module('myModule', ['bgf.paginateAnything']);\n```\n\nThen in your view\n\n```html\n\u003c!-- elements such as an ng-table reading from someVariable --\u003e\n\n\u003cbgf-pagination\n  collection=\"someVariable\"\n  url=\"'http://api.server.com/stuff'\"\u003e\n\u003c/bgf-pagination\u003e\n```\n\nThe `pagination` directive uses an external template stored in\n`tpl/paginate-anything.html`.  Host it in a place accessible to\nyour page and set the `templateUrl` attribute. Note that the `url`\nparam can be a scope variable as well as a hard-coded string.\n\n### Benefits\n\n* Attaches to anything — ng-repeat, ng-grid, ngTable etc\n* Server side pagination scales to large data\n* Works with any MIME type through RFC2616 Range headers\n* Handles finite or infinite lists\n* Negotiates per-page limits with server\n* Keeps items in view when changing page size\n* Twitter Bootstrap compatible markup\n\n### Directive Attributes\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003eName\u003c/th\u003e\n      \u003cth\u003eDescription\u003c/th\u003e\n      \u003cth\u003eAccess\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eurl\u003c/td\u003e\n      \u003ctd\u003eurl of endpoint which returns a JSON array\u003c/td\u003e\n      \u003ctd\u003eRead/write. Changing it will reset to the first page.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eurl-params\u003c/td\u003e\n      \u003ctd\u003emap of strings or objects which will be turned to ?key1=value1\u0026key2=value2 after the url\u003c/td\u003e\n      \u003ctd\u003eRead/write. Changing it will reset to the first page.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eheaders\u003c/td\u003e\n      \u003ctd\u003eadditional headers to send during request\u003c/td\u003e\n      \u003ctd\u003eWrite-only.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003epage\u003c/td\u003e\n      \u003ctd\u003ethe currently active page\u003c/td\u003e\n      \u003ctd\u003eRead/write. Writing changes pages. Zero-based.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eper-page\u003c/td\u003e\n      \u003ctd\u003e(default=`50`) Max number of elements per page\u003c/td\u003e\n      \u003ctd\u003eRead/write. The server may choose to send fewer items though.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eper-page-presets\u003c/td\u003e\n      \u003ctd\u003eArray of suggestions for per-page. Adjusts depending on server limits\u003c/td\u003e\n      \u003ctd\u003eRead/write.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eauto-presets\u003c/td\u003e\n      \u003ctd\u003e(default=`true`) Overrides per-page presets and client-limit to quantized values 1,2,5,10,25,50...\u003c/td\u003e\n      \u003ctd\u003eRead/write.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eclient-limit\u003c/td\u003e\n      \u003ctd\u003e(default=`250`) Biggest page size the directive will show. Server response may be smaller.\u003c/td\u003e\n      \u003ctd\u003eRead/write.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003elink-group-size\u003c/td\u003e\n      \u003ctd\u003e(default=`3`) Number of elements surrounding current page. \u003cimg src=\"img/link-group-size.png\" alt=\"illustration\" /\u003e\u003c/td\u003e\n      \u003ctd\u003eRead/write.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003enum-items\u003c/td\u003e\n      \u003ctd\u003eTotal items reported by server for the collection\u003c/td\u003e\n      \u003ctd\u003eRead-only.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003enum-pages\u003c/td\u003e\n      \u003ctd\u003enum-items / per-page\u003c/td\u003e\n      \u003ctd\u003eRead-only.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eserver-limit\u003c/td\u003e\n      \u003ctd\u003eMaximum results the server will send (Infinity if not yet detected)\u003c/td\u003e\n      \u003ctd\u003eRead-only.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003erange-from\u003c/td\u003e\n      \u003ctd\u003ePosition of first item in currently loaded range\u003c/td\u003e\n      \u003ctd\u003eRead-only.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003erange-to\u003c/td\u003e\n      \u003ctd\u003ePosition of last item in currently loaded range\u003c/td\u003e\n      \u003ctd\u003eRead-only.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003ereload-page\u003c/td\u003e\n      \u003ctd\u003eIf set to true, the current page is reloaded.\u003c/td\u003e\n      \u003ctd\u003eWrite-only.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003esize\u003c/td\u003e\n      \u003ctd\u003eTwitter bootstrap sizing `sm`, `md` (default), or `lg` for the navigation elements.\u003c/td\u003e\n      \u003ctd\u003eWrite-only.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003epassive\u003c/td\u003e\n      \u003ctd\u003eIf using more than one pagination control set this to 'true' on all but the first.\u003c/td\u003e\n      \u003ctd\u003eWrite-only.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003etransform-response\u003c/td\u003e\n      \u003ctd\u003eFunction that will get called once the http response has returned. See \u003ca href=\"https://docs.angularjs.org/api/ng/service/$http\"\u003eAngular's $https documentation for more information.\u003c/td\u003e\n      \u003ctd\u003eRead/write. Changing it will reset to the first page.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003emethod\u003c/td\u003e\n      \u003ctd\u003eType of request method. Can be either GET or POST. Default is GET.\u003c/td\u003e\n      \u003ctd\u003eRead/write.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003epost-data\u003c/td\u003e\n      \u003ctd\u003eAn array of data to be sent when method is set to POST.\u003c/td\u003e\n      \u003ctd\u003eRead/write.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eload-fn\u003c/td\u003e\n      \u003ctd\u003eA callback function to perform the request. Gets the http config as parameter and must return a promise.\u003c/td\u003e\n      \u003ctd\u003eWrite-only.\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n### Events\n\nThe directive emits events as pages begin loading (`pagination:loadStart`)\nor finish (`pagination:loadPage`) or errors occur (`pagination:error`).\nTo catch these events do the following:\n\n```js\n$scope.$on('pagination:loadPage', function (event, status, config) {\n  // config contains parameters of the page request\n  console.log(config.url);\n  // status is the HTTP status of the result\n  console.log(status);\n});\n```\n\nThe `pagination:loadStart` is passed the client request rather than\nthe server response.\n\nTo trigger a reload the `pagination:reload` event can be send:\n\n```js\nfunction () {\n  $scope.$broadcast('pagination:reload');\n}\n```\n\n### How to deal with sorting, filtering and facets?\n\nYour server is responsible for interpreting URLs to provide these\nfeatures.  You can connect the `url` attribute of this directive\nto a scope variable and adjust the variable with query params and\nwhatever else your server recognizes. Or you can use the `url-params`\nattribute to connect a map of strings or objects which will be\nturned to ?key1=value1\u0026key2=value2 after the url.  Changing the\n`url` or `url-params` causes the pagination to reset to the first\npage and maintain page size.\n\nExample:\n```js\n$scope.url = 'api/resources';\n$scope.urlParams = {\n  key1: \"value1\",\n  key2: \"value2\"\n};\n```\n\nWill turn into the URL of the resource that is being requested: `api/resources?key1=value1\u0026key2=value2`\n\n### What your server needs to do\n\nThis directive decorates AJAX requests to your server with some\nsimple, standard headers. You read these headers to determine the\nlimit and offset of the requested data. Your need to set response\nheaders to indicate the range returned and the total number of items\nin the collection.\n\nYou can write the logic yourself, or use one of the following server\nside libraries.\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003eFramework\u003c/th\u003e\n      \u003cth\u003eSolution\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eRuby on Rails\u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://github.com/begriffs/clean_pagination\"\u003ebegriffs/clean_pagination\u003c/a\u003e gem\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd rowspan=\"2\"\u003eNode.js\u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://github.com/polo2ro/node-paginate-anything\"\u003enode-paginate-anything\u003c/a\u003e module\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\u003ca href=\"https://github.com/begriffs/angular-paginate-anything/wiki/How-to-configure-NodeJS\"\u003eExpress JS from scratch howto\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eServiceStack for .NET\u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://github.com/begriffs/angular-paginate-anything/wiki/How-to-configure-ServiceStack-for-.NET\"\u003eService Stack .NET howto\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eASP.NET Web API\u003c/td\u003e\n      \u003ctd\u003e\u003ca href=\"https://github.com/begriffs/angular-paginate-anything/wiki/How-To-Configure-ASP.NET-Web-API\"\u003eASP.NET Web API howto\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\nFor a reference of a properly configured server, visit\n[pagination.begriffs.com](http://pagination.begriffs.com/).\n\nHere is an example HTTP transaction that requests the first twenty-five\nitems and a response that provides them and says there are one\nhundred total items.\n\nRequest\n\n```HTTP\nGET /stuff HTTP/1.1\nRange-Unit: items\nRange: 0-24\n```\n\nResponse\n\n```HTTP\nHTTP/1.1 206 Partial Content\nContent-Range: 0-24/100\nRange-Unit: items\nContent-Type: application/json\n\n[ etc, etc, ... ]\n```\n\nIn short your server parses the `Range` header to find the zero-based\nstart and end item. It includes a `Content-Range` header in the\nresponse disclosing the unit and range it chooses to return, along with the\ntotal items after a slash, where total items can be \"*\" meaning\nunknown or infinite.\n\nWhen there are zero elements to return your server should send\nstatus code 204 (no content), `Content-Range: */0`, and an empty\nbody (or `[]` if the endpoint normally returns a JSON array).\n\nTo do all this header stuff you'll need to enable CORS on your server.\nIn a Rails app you can do this by adding the following to `config/application.rb`:\n\n```ruby\nconfig.middleware.use Rack::Cors do\n  allow do\n    origins '*'\n    resource '*',\n      :headers =\u003e :any,\n      :methods =\u003e [:get, :options],\n      :expose =\u003e ['Content-Range', 'Accept-Ranges']\n  end\nend\n```\n\nFor a more complete implementation including other appropriate responses\nsee my [clean_pagination](https://github.com/begriffs/clean_pagination) gem.\n\n### Using the load-fn callback\n\nInstead of having paginate-anything handle the http requests there is the option of using a callback function to perform the requests. This might be helpful e.g. if the data does not come from http endpoints, further processing of the request needs to be done prior to submitting the request or further processing of the response is necessary.\n\nThe callback can be used as follows:\n\n```html\n\u003cbgf-pagination collection=\"data\" page=\"filter.page\" per-page=\"filter.perpage\" load-fn=\"callback(config)\"\u003e\u003c/bgf-pagination\u003e\n```\n\n```js\n$scope.callback = function (config) {\n  return $http(config);\n}\n\n// alternatively\n$scope.callback = function(config) {\n  return $q(function(resolve) {\n    resolve({\n      data: ['a', 'b'],\n      status: 200,\n      config: {},\n      headers: function(headerName) {\n        // fake Content-Range headers\n        return '0-1/*';\n      }\n    });\n  });\n}\n```\n\n### Further reading\n\n* [Hypertext Transfer Protocol (HTTP/1.1): Range Requests](http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p5-range-latest.html)\n* [RFC2616 Section 3.12, custom range units](http://www.ietf.org/rfc/rfc2616.txt)\n* [Beyond HTTP Header Links](http://blog.begriffs.com/2014/03/beyond-http-header-links.html)\n* [Heroku recommends Range headers for pagination](https://github.com/interagent/http-api-design#paginate-with-ranges)\n\n### Thanks\n\nThanks to [Steve Klabnik](https://twitter.com/steveklabnik) for\ndiscussions about doing hypermedia/HATEOAS right, and to [Rebecca\nWright](https://twitter.com/rebecca_wrights) for reviewing and\nimproving my original user interface ideas for the paginator.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbegriffs%2Fangular-paginate-anything","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbegriffs%2Fangular-paginate-anything","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbegriffs%2Fangular-paginate-anything/lists"}