release vue-paginate v3.0.0

README.md

@@ -1,20 +1,16 @@
 # vue-paginate
 
-> This plugin helps you use pagination on lists within seconds!
+> This version only works with Vue 2.0. For Vue 1.0, check out the [1.0 branch](https://github.com/TahaSh/vue-paginate/tree/1.0).
 
-**Please note that this version only works for Vue 1.0. The next version will support Vue 2.0 which is currently under development — thanks for your patience :).**
-
-It's basically a directive with a bunch of methods defined on the vm. When you
-use this directive on some list, it'll be sliced according to the number of
-items per page, which you specify. Then, you'll work with those slices using the methods & data that automatically gets defined on the vm — not all vms, only the one you used the directive in.
+The idea of `vue-paginate` is pretty simple. You give it an array of items; specify how many items per page; then get your list of items paginated!
 
 ## Setup
 
 ```
 npm install vue-paginate --save
 ```
 
-You have two ways to setup *vue-paginate*:
+You have two ways to setup `vue-paginate`:
 
 #### CommonJS (Webpack/Browserify)
 
@@ -38,124 +34,211 @@ Include it directly with a `<script>` tag. In this case, you don't need to write
 
 ## Usage
 
-Here's an example:
+`vue-paginate` consists of two main components: `Paginate` and `PaginateLinks`. And both get registered globally once the plugin is installed.
 
-```js
+To paginate any list of data, we have to follow these three small steps:
+
+1. Register the name of the paginated list.
+2. Use `Paginate` component to paginate and display the paginated list.
+3. Use `PaginateLinks` component to display the links for the pagination.
+
+Now, let’s see them in an example:
+
+### Example
+
+In this example, we have a small list of items registered in our data list.
+
+``` js
 new Vue({
   el: '#app',
   data: {
-    langs: ['PHP', 'JavaScript', 'HTML', 'CSS', 'Ruby', 'Python']
+    langs: ['JavaScript', 'PHP', 'HTML', 'CSS', 'Ruby', 'Python', 'Erlang']
   }
-});
+})
 ```
 
-```html
-<!-- data -->
-<ul v-paginate:3="langs">
-  <li v-for="lang in langs">
-    {{ lang }}
-  </li>
-</ul>
+Now, let’s see how we can paginate this list to display two items per page.
 
-<!-- links -->
-<ul>
-  <li v-for="langLink in langsLinks">
-    <a @click="changeLangsPage(langLink)" href="#">
-      {{ langLink }}
-    </a>
+First step is to register the name of our future paginated list. We register it by adding it to an array called `paginate`.
+
+``` js
+new Vue({
+  el: '#app',
+  data: {
+    langs: ['JavaScript', 'PHP', 'HTML', 'CSS', 'Ruby', 'Python', 'Erlang'],
+    paginate: ['languages']
+  }
+})
+```
+
+Note that you can name it the same as the original list – I named it differently here just for the sake of clarity.
+
+Second step is to use the `Paginate` component to paginate the list. Since it was globally registered by the plugin, you don’t have to import it.
+
+This component requires at least two props to be passed. The `name` of the registered paginated list – `languages` in this case. And the `list` that you want to paginate – `langs` in this case.
+
+After that, you start using the paginated list inside the body of that `<paginate>` component. And, you get access to the paginated list using the method `paginated('languages')`.
+
+Here’s how it looks in action:
+
+``` html
+<paginate
+  name="languages"
+  :list="langs"
+  :per="2"
+>
+  <li v-for="lang in paginated('languages')">
+    {{ lang }}
   </li>
-</ul>
+</paginate>
 ```
 
-That's it!
+Note how we specified the number of items per page using the `per` prop. If we didn’t specify it here, it would use the default value instead, which is `3` items per page.
+
+That’s it! Now your list has been paginated successfully. And you still have access to the original `langs` list if you need it.
 
-#### How it works?
+However, we still don’t have a way to navigate through those pages. Here’s where `PaginateLinks` component comes into play.
+
+All that component needs to know is the name of the registered paginated list. We pass that using its `for` prop. Like this:
+
+``` html
+<paginate-links for="languages"></paginate-links>
+```
 
-When you try the previous example, you'll get two pages, each one contains three items. We specified that by using `:3` argument, which means we want to show 3 items per page!
+So, that was the third step!
 
-In the links section, we used a variable named `langsLinks`. This one is
-generated for us by the plugin, which follows the convention `[listName]Links`.
-This variable contains an array of all pages' numbers that we need to navigate the content of the list.
+### Types of paginate links
 
-So, to show the links, we ran a loop and used each one in the method `changeLangsPage()` (which also follows a convention: `change[listName]Page`). This method takes the page number and return all items in that page.
+`vue-paginate` provides us with three different types of pagination links:
 
-#### Use Next/Prev buttons
+1. Full list of links. This is the default behavior, which displays all available page links from page 1 to N.
+2. Simple links. It contains only two links: *Previous* and *Next*.
+3. Limited links. It limits the number of displayed links, and provides left and right arrows to help you navigate between them.
 
-In some cases, you'll want to navigate pages using next/prev links instead of
-page numbers.
+#### Full links
 
-To do that, all you have to do is to use the methods `next[listName]Page` &
-`prev[listName]Page`.
+To use this you don’t have to do anything; this is the default behavior.
 
-Like this:
+#### Simple links
 
-```html
-<!-- links -->
-<a @click="prevLangsPage()" href="#">
-  Prev
-</a>
+For this, we use the `simple` prop, which accepts an object that contains the names of the *Previous* and *Next* links. For example:
 
-<a @click="nextLangsPage()" href="#">
-  Next
-</a>
+``` html
+<paginate-links
+  for="languages"
+  :simple="{
+    prev: 'Back',
+    next: 'Next'
+  }"
+></paginate-links>
 ```
 
-#### Accessing the full version
 
-This plugin operates on the original data that you've defined in your vm. This
-means, you'll no longer have access to the full version (before slicing).
+#### Limited links
 
-However, before the plugin does its slicing, it stores the full version in
-another list named `full[listName]`. So, for this example it would be
-`fullLangs`.
+To activate this mode, you just need to specify the limit using the `limit` prop. Like this:
 
-#### Limit the number of displayed links
+``` html
+<paginate-links
+  for="languages"
+  :limit="2"
+></paginate-links>
+```
 
-When your number of pages gets bigger, it becomes unpractical to display all of your links. What we prefer to do instead is to limit the number of links displayed in the links section. Doing that with this plugin is a cinch!
+### Paginate container
 
-All you have to do is to use `limited[listName]Links` in place of `[listName]Links`. As a default, your links will be limited to `4`, but of course you can change it by using the parameter `limit` along with `v-paginate`. For example:
+The default element `vue-paginate` uses for the `<paginate>` container is `UL`. But, of course, you can change it to whatever you want using the `tag` prop. And the same is true for its class using the `class` prop.
 
 ``` html
-<!-- Data -->
-<section v-paginate:2="posts" limit="2">
-  <ul v-for="post in posts">
-    <li>{{ post }}</li>
-  </ul>
-</section>
-
-<!-- Links -->
-<ul class="links">
-  <li v-for="postLink in limitedPostsLinks">
-    <a :class="{active: currentPostsPage == postLink}" href="#" @click="changePostsPage(postLink)">{{ postLink }}</a>
+<paginate
+  name="languages"
+  :list="langs"
+  :per="2"
+  tag="div"
+  class="paginate-langs"
+>
+  <li v-for="lang in paginated('languages')">
+    {{ lang }}
   </li>
-</ul>
+</paginate>
 ```
 
-#### Updating the full list manually
+### Updating the full list
+
+Since this plugin is built using the components system, you get all the flexibility and power that regular Vue components provide. I’m talking here specifically about the reactivity system.
+
+So, when you want to update the original list (e.g. `langs`), just update it; everything will work seamlessly!
+
+### Filtering the paginated list
 
-In many cases you will find the need to change/assign the content of the list manually — for example from an Ajax response. You can do that simply by changing the value of the full version of the list `full[listName]`. For example, here's how you would change your list content when performing an Ajax request:
+There’s nothing special the plugin does to support list filtering. It’s your responsibility to filter the list you pass to `<paginate>` component via `list` prop.
+
+So, if we were to filter the list (or any other operation), we would have something similar to this:
 
 ``` js
-this.$http.get('/posts')
-  .then(function (response) {
-    this.fullPosts = response.data;
+// Assume we have a text box bound to `searchLangs` data via v-model for example.
+computed: {
+  fLangs () {
+    const re = new RegExp(this.searchLangs, 'i')
+    return this.langs.filter(lang => lang.match(re))
   }
-);
+}
 ```
 
+Then just pass that `fLangs` to the `list` prop instead of the original `langs`.
+
+### Links customization
+
+In `vue-paginate`, you can customize every bit of your pagination links.
+
+But first, let’s see the html structure used for all link types:
+
+``` html
+<ul>
+  <li><a>1</a></li>
+  <li><a>2</a></li>
+  <!— … —>
+</ul>
+```
+
+Now, let’s see what CSS selectors we often need to use:
+
+#### All links containers:
+
+`ul.paginate-links`
+
+#### Specific links container:
+
+`ul.paginate-links.languages`
+
+`languages` here is the name of your paginated list.
+
+#### Current page:
+
+This only works for full & limited links.
+
+`ul.paginate-links > li.active > a`
+
+#### Previous & Next Links:
+
+Obviously, this is only for simple links.
+
+Previous –> `ul.paginate-links > li.prev > a`
+Next –> `ul.paginate-links > li.next > a`
+
+#### Disabled Next/Previous Links:
+
+`ul.paginate-links > li.disabled > a`
 
-## Conventions
+#### Limited Links:
 
-#### Methods
+Number links –> `ul.paginate-links > li.number > a`
+Left arrow –> `ul.paginate-links > li.left-arrow > a`
+Right arrow –> `ul.paginate-links > li.right-arrow > a`
+Ellipses –> `ul.paginate-links > li.ellipses > a`
 
-- `change[listName]Page`: Go to a specific page (using the page number).
-- `next[listName]Page`: Go to the next page.
-- `prev[listName]Page`: Go to the previous page.
+## License
 
-#### Data
+[MIT](http://opensource.org/licenses/MIT)
 
-- `[listName]Links`: Array of the needed links.
-- `limited[listName]Links`: Array of limited links.
-- `full[listName]`: The full version of the list (before slicing).
-- `current[listName]Page`: The current page of the list you're viewing (e.g. `currentLangsPage`).
-- `has[listName]Links`: A check to see if there's a need to display the links.
+Copyright (c) 2016 Taha Shashtari