Contents
breedjs logo

Get a little bit more of productivity with this awesome jQuery plugin!

Star

About

Write less. With BreedJS you won't spend your time writing repetitive HTML structures or developing complex functions to deal with filters, sorts and pagination. BreedJS takes care of this things for you with few commands. Learn how to use it checking the examples below and see which one fits to you. Visit the Github repo.

Download

Click here to download the last .min version.

Calling breed

HTML

<script src="path/to/breed.js"></script>

[HTML] attr:b-scope="scopeName"

Set the scope that you're going to work with.

HTML

<div b-scope="animals"></div>

[JS] setDefaultScope(scopeName)

Set the default scope when calling breed. Then you don't need to tell which scope you are using everytime you call breed.

Javascript

breed.setDefaultScope('animals')

HTML

<div b-scope="animals"></div>

[JS] breed.run(object)

Activate a scope. The commands you passed in the tag where you set the scope only will be activated after you call this function.

Javascript

var data = {
    animals_list: ["mouse", "cat", "dog"]
};
breed.run({
    scope: 'animals',
    input: data
});

HTML

<div b-scope="animals"></div>

Object keys

  • scope: Your scope. It's optional if you set a default.
  • input: Here you pass the data object that you're going to use in your scope.
  • runEnd [optional]: Here you set the after run() callback function.
  • pageChangeEnd [optional]: Here you set the after paginate() callback function.
  • sortEnd [optional]: Here you set the after sort() and sortAttr() callback function.
  • filterEnd [optional]: Here you set the after filter(), filterAttr() and filterSelector() callback function.

[HTML] Commands

Set commands to be executed when activate the scope.

attr:b-loop="value in values"

Loops the tag where the command is through a scope iterable variable. This command will also create the inner tags.

Javascript

var data = {
    animals_list: ["mouse", "cat", "dog"]
};
breed.run({
    scope: 'animals',
    input: data
});

HTML

Before run: 
<div b-scope="animals" b-loop="animal in animals_list"></div>
Result: 
<div b-scope="animals"></div>
<div b-scope="animals"></div>
<div b-scope="animals"></div>

Expressions

Its also possible to set javascript expressions between double brackets: {{your_expression}}. In this way, you can get more advantge over your loop command:

HTML

Before run: 
<div b-scope="animals" b-loop="animal in animals_list">
    {{"This is a " + animal}}
</div>
Result: 
<div b-scope="animals">This is a mouse</div>
<div b-scope="animals">This is a cat</div>
<div b-scope="animals">This is a dog</div>

Expressions can also be used inside attributes.

Loop index

You can access the loop index using the variable #index inside an expression.

HTML

Before run: 
<div b-scope="animals" id="{{#index}}" b-loop="animal in animals_list">
    {{"This is a " + animal}}
</div>
Result: 
<div b-scope="animals" id="0">This is a mouse</div>
<div b-scope="animals" id="1">This is a cat</div>
<div b-scope="animals" id="2">This is a dog</div>

Access level

In order to access global variables inside expressions, you just need no call it, but to access variables from scope data, you need to use # before the variable name.

Javascript

var hey = "Hey! ";
var data = {
    animals_list: ["mouse", "cat", "dog"],
    text: "This is a "
};
breed.run({
    scope: 'animals',
    input: data
});

HTML

Before run: 
<div b-scope="animals" b-loop="animal in animals_list">
    <b>{{hey}}</b> {{#text + animal}}
</div>
Result: 
<div b-scope="animals"><b>Hey!</b> This is a mouse</div>
<div b-scope="animals"><b>Hey!</b> This is a cat</div>
<div b-scope="animals"><b>Hey!</b> This is a dog</div>

End loop event

Just pass your function to loopEnd key inside the run object to be called when the loop is over:

Javascript

breed.run({
    scope: 'animals',
    input: data,
    loopEnd: function(){
        //here goes your code
    }
});

attr:b-paginate="page_length"

This command will paginate the DOM elements at your scope that you created with b-loop. Paginating works with filters and sorts.

Javascript

var data = {
    animals_list: ["bee", "mouse", "cat", "dog", "wolf", "lion"]
};
breed.run({
    scope: 'animals',
    input: data
});

HTML

Before run: 
<div b-scope="animals" b-loop="animal in animals_list" b-paginate="3">{{animal}}</div>
Result: 
<div b-scope="animals">bee</div>
<div b-scope="animals">mouse</div>
<div b-scope="animals">cat</div>
<div style="display:none;" b-scope="animals">dog</div>
<div style="display:none;" b-scope="animals">wolf</div>
<div style="display:none;" b-scope="animals">lion</div>

[JS] breed.paginate(object)

That's the function that really makes the pagination happen. Whenever you want to change pages, that's the one to be called.

Object keys

  • scope: Your scope. It's optional if you set a default.
  • page: Here you pass the number of the page that you want to go. You also can pass "next" or "previous" to go to the next or the previous page, respectivaly.
  • page_length [optional]: If you want to change how many items you show per page, you can change this value here.

Javascript

breed.paginate({
    scope: 'animals',
    page: 2
});

HTML

<div style="display:none;" b-scope="animals">bee</div>
<div style="display:none;" b-scope="animals">mouse</div>
<div style="display:none;" b-scope="animals">cat</div>
<div b-scope="animals">dog</div>
<div b-scope="animals">wolf</div>
<div b-scope="animals">lion</div>

[JS] breed.setPageLength(object)

This function changes how many items is shown per page.

Object keys

  • scope: Your scope. It's optional if you set a default.
  • page_length: Set the new value here.

Javascript

breed.setPageLength({
    scope: 'animals',
    page_length: 6
});

In our example, that's going to result at showing all elements.

[JS] breed.getPageCount(scope)

This function returns how many pages there are in your scope.

Javascript

breed.getPageCount('animals');

If in our example the page_length value is 3, then this function will return 2.

[JS] breed.getActualPage(scope)

This function returns the actual page.

Javascript

breed.getActualPage('animals');

The first page index is 1. So if you are at page 2, for example, you'll get 2 from this function.

End page change event

Just pass your function to pageChangeEnd key inside the run object to be called when the page change process is over:

Javascript

breed.run({
    scope: 'animals',
    input: data,
    pageChangeEnd: function(){
        //here goes your code
    }
});

Sorting

Sorting can be very easy, simple and flexible with BreedJS. With few key configurations, you will be able to sort everything you want. Sort works with filters and pagination.

[JS] breed.sort(obj)

Consider this example:

Javascript

var data = {
    animals_list: [
        {name: 'dog', age: 4},
        {name: 'cat', age: 7},
        {name: 'fish', age: 1}
    ]
};

breed.run({
    scope: 'animals',
    input: data
});

HTML

<div b-scope="animals" b-loop="animal in animals_list">{{animal.name}}</div>

This will generate divs with animals' name.

Everytime we want to sort these divs, we can do just like so:

Javascript

breed.sort({
    scope: 'animals'
});

The result is going to be:

HTML

<div b-scope='animals'>cat</div>
<div b-scope='animals'>dog</div>
<div b-scope='animals'>fish</div>

We sorted this scope by the divs text.

This sort function can be more flexible. Let us take a look at sort options:

Object keys

  • scope: Your scope. It's optional if you set a default.
  • reverse [optional]: Set this to true to sort in reverse order.
  • selector [optional]: If you want to sort by a text of a inner tag, pass here the value of the attribute b-sort, so we can find this tag to get its text.
  • rule [optional]: Pass here a function that will modify the text to be analyzed.

Using the selector option

Let's take a look at selector option. Consider this example:

HTML

<tr b-scope="animals" b-loop="animal in animals_list">
    <td b-sort="name">{{animal.name}}</td>
    <td b-sort="age">{{animal.age}}</td>
</tr>

This will generate table rows with animals name and age info. We put the b-sort attribute in order to sort the row by name or by age.

Now, if we want to sort it by name, we do this:

Javascript

breed.sort({
    scope: 'animals',
    selector: 'name' //the value inside the attribute b-sort
});

And that's the result:

HTML

<tr b-scope="animals">
    <td b-sort="name">cat</td>
    <td b-sort="age">7</td>
</tr>
<tr b-scope="animals">
    <td b-sort="name">dog</td>
    <td b-sort="age">4</td>
</tr>
<tr b-scope="animals">
    <td b-sort="name">fish</td>
    <td b-sort="age">1</td>
</tr>

Using the rule option

You can edit the analyzed text using the rule option:

Javascript

breed.sort({
    scope: 'animals',
    selector: 'age',
    rule: function(age){
        return age == 1 ? age : -1 * (age % 2);
    }
});

That's going to apply the rule for each age value and sort based on it. See the result:

HTML

<tr b-scope="animals">
    <td b-sort="name">cat</td>
    <td b-sort="age">7</td> <!-- The rule result is -1 --> 
</tr>
<tr b-scope="animals">
    <td b-sort="name">dog</td>
    <td b-sort="age">4</td> <!-- The rule result is 0 -->
</tr>
<tr b-scope="animals">
    <td b-sort="name">fish</td>
    <td b-sort="age">1</td> <!-- The rule result is 1 -->
</tr>

[JS] breed.sortAttr(obj)

You can have all the breed.sort() features at breed.sortAttr() function, but in sortAttr you don't sort by the tag inner text value, you sort by a given attribute.

Object keys

  • scope: Your scope. It's optional if you set a default.
  • attr: The attribute name that you want to sort by.
  • reverse [optional]: Set this to true to sort in reverse order.
  • selector [optional]: If you want to sort by a attribute value of a inner tag, pass here the value of the attribute b-sort, so we can find the tag where your attribute is.
  • rule [optional]: Pass here a function that will modify the text to be analyzed.

Consider this example:

HTML

<tr b-scope="animals" b-loop="animal in animals_list">
    <td age="{{animal.age}}">{{animal.name}}</td>
</tr>

Now, we want to sort this by the attribute age. This can be easily done with this command:

Javascript

breed.sortAttr({
    scope: 'animals',
    attr: 'age'
});

And we got this result:

HTML

<tr b-scope="animals">
    <td age="1">fish</td>
</tr>
<tr b-scope="animals">
    <td age="4">dog</td>
</tr>
<tr b-scope="animals">
    <td age="7">cat</td>
</tr>

Combining attr and selector options

Now consider this other example:

HTML

<tr age="{{animal.age}}" b-scope="animals" b-loop="animal in animals_list">
    <td age="{{animal.age == 1 ? animal.age : -1 * (animal.age % 2)}}" b-sort="name">{{animal.name}}</td>
</tr>

We want to sort by the age attribute inside td tag. But using just the attr option, It will sort by the tr tag. To solve this, we back with b-sort attribute to help BreedJS find what attribute you're talking about. See:

Javascript

breed.sort({
    scope: 'animals',
    attr: 'age',
    selector: 'name' 
});

Result:

HTML

<tr age="7" b-scope="animals">
    <td age="-1" b-sort="name">cat</td>
</tr>
<tr age="4" b-scope="animals">
    <td age="0" b-sort="name">dog</td>
</tr>
<tr age="1" b-scope="animals">
    <td age="1" b-sort="name">fish</td>
</tr>

End sort event

We provide a callback option for anykind of sort you do:

Javascript

breed.run({
    scope: 'animals',
    input: data,
    sortEnd: function(){
        //here goes your code
    }
});

Filtering

Filter things usually can be very hard. But with BreedJS, It gets very simple and really flexible to your needs. Filter works with pagination and sorting.

[JS] breed.filter(object)

Consider this data for our examples:

Javascript

var data = {
    animals_list: [
        {name: 'dog', age: 6},
        {name: 'cat', age: 3},
        {name: 'fish', age: 1},
        {name: 'camel', age: 9},
        {name: 'flamingo', age: 2}
    ]
};

breed.run({
    scope: 'animals',
    input: data
});

HTML

<div b-scope="animals" b-loop="animal in animals_list">{{animal.name}}</div>

This will generate divs with animals' name.

Everytime we want to filter these divs, we can do just like so:

Javascript

breed.filter({
    scope: 'animals',
    key: 'ca'
});

And that's gonna be the result:

HTML

<div style="display:none;" b-scope="animals">dog</div>
<div b-scope="animals">cat</div>
<div style="display:none;" b-scope="animals">fish</div>
<div b-scope="animals">camel</div>
<div style="display:none;" b-scope="animals">flamingo</div>

We filtered this scope by the divs text.

This filter function can be more flexible. Let us take a look at filter options:

Object keys

  • scope: Your scope. It's optional if you set a default.
  • key: That's your filter key.
  • exclusion [optional]: Set this to true to filter by exclusion.
  • field [optional]: If you want to filter by a text of a inner tag, pass here the value of the attribute b-filter, so we can find this tag to get its text.
  • rule [optional]: Pass here a function that will set a rule to filter your elements.
  • sensitive [optional]: Set this to true to make the filter case sensitive.

Using the field option

Let's take a look at field option. Consider this example:

HTML

<tr b-scope="animals" b-loop="animal in animals_list">
    <td b-filter="name">{{animal.name}}</td>
    <td b-filter="age">{{animal.age}}</td>
</tr>

This will generate table rows with animals name and age info. We put the b-filter attribute in order to filter the row by name or by age.

Now, if we want to filter it by name, we do this:

Javascript

breed.filter({
    scope: 'animals',
    field: 'name', //the value inside the attribute b-filter
    key: 'dog'
});

And that's the result:

HTML

<tr b-scope="animals">
    <td b-filter="name">dog</td>
    <td b-filter="age">6</td>
</tr>
<tr style="display:none;" b-scope="animals">
    <td b-filter="name">cat</td>
    <td b-filter="age">3</td>
</tr>
<tr style="display:none;" b-scope="animals">
    <td b-filter="name">fish</td>
    <td b-filter="age">1</td>
</tr>
<tr style="display:none;" b-scope="animals">
    <td b-filter="name">camel</td>
    <td b-filter="age">9</td>
</tr>
<tr style="display:none;" b-scope="animals">
    <td b-filter="name">flamingo</td>
    <td b-filter="age">2</td>
</tr>

Using the rule option

You can edit the filter pattern using the rule option:

Javascript

breed.sort({
    scope: 'animals',
    field: 'age',
    rule: function(age){
        return age < 4;
    }
});

That's going to apply the rule for the filter checking. See the result:

HTML

<tr style="display:none;" b-scope="animals">
    <td b-filter="name">dog</td>
    <td b-filter="age">6</td>
</tr>
<tr b-scope="animals">
    <td b-filter="name">cat</td>
    <td b-filter="age">3</td>
</tr>
<tr b-scope="animals">
    <td b-filter="name">fish</td>
    <td b-filter="age">1</td>
</tr>
<tr style="display:none;" b-scope="animals">
    <td b-filter="name">camel</td>
    <td b-filter="age">9</td>
</tr>
<tr b-scope="animals">
    <td b-filter="name">flamingo</td>
    <td b-filter="age">2</td>
</tr>

Only ages less than 4 got displayed.

Stacking filters

With BreedJS, you can stack filters (filter of the filter) in a very neat way.

Consider this new situation:

Javascript

var data = {
    people: [
        {name: 'john', age: 18, birth: '23/06/1998'},
        {name: 'josh', age: 13, birth: '12/04/2003'},
        {name: 'jake', age: 20, birth: '11/09/1996'},
        {name: 'jason', age: 19, birth: '13/08/1997'},
        {name: 'james', age: 17, birth: '24/05/1999'}
    ]
};

breed.run({
    scope: 'people',
    input: data
});

HTML

<tr b-scope="people" b-loop="person in people">
    <td b-filter="name">{{person.name}}</td>
    <td b-filter="age">{{person.age}}</td>
    <td b-filter="birth">{{person.birth}}</td>
</tr>

Now, we want to filter it by name and birthdate. So we do:

Javascript

function compare(date){
    return Date.parse(date) < Date.parse('01/01/2000');
}

breed.filter({
    scope: 'people',
    field: ['name', 'birth'],
    rule: ['jo', compare]
});
When stacking, field and rule options must match. 'jo' is for 'name' and compare() is for 'birth'.

Here is the result:

HTML

<tr b-scope="people">
    <td b-filter="name">john</td>
    <td b-filter="age">18</td>
    <td b-filter="birth">23/06/1998</td>
</tr>
<tr style="display:none;" b-scope="people">
    <td b-filter="name">josh</td>
    <td b-filter="age">13</td>
    <td b-filter="birth">12/04/2003</td>
</tr>
<tr style="display:none;" b-scope="people">
    <td b-filter="name">jake</td>
    <td b-filter="age">20</td>
    <td b-filter="birth">11/09/1996</td>
</tr>
<tr style="display:none;" b-scope="people">
    <td b-filter="name">jason</td>
    <td b-filter="age">19</td>
    <td b-filter="birth">13/08/1997</td>
</tr>
<tr style="display:none;" b-scope="people">
    <td b-filter="name">james</td>
    <td b-filter="age">17</td>
    <td b-filter="birth">24/05/1999</td>
</tr>

Data that contains 'jo' and has birthdate before 01/01/2000 got displayed.

If you don't have any rule function, you can set the key array on key option as well.

[JS] breed.filterAttr(object)

You can have all the breed.filter() features at breed.filterAttr() function, but in filterAttr you don't filter by the tag inner text value, you filter by a given attribute.

Object keys

  • scope: Your scope. It's optional if you set a default.
  • key: That's your filter key.
  • attr: The attribute name that you want to filter by.
  • exclusion [optional]: Set this to true to filter by exclusion.
  • field [optional]: If you want to filter by an attribute value of a inner tag, pass here the value of the attribute b-filter, so we can find the tag where your attribute is.
  • rule [optional]: Pass here a function that will set a rule to filter your elements.
  • sensitive [optional]: Set this to true to make the filter case sensitive.

Still with the people data example, let's do just like so:

HTML

<tr b-scope="people" b-loop="person in people">
    <td age="{{person.age}}">{{person.name}}</td>
</tr>

Now, we want to filter this by the attribute age. This can be easily done with this command:

Javascript

breed.filterAttr({
    scope: 'people',
    attr: 'age',
    rule: function(age){
        return age < 19;
    }
});

And that's the result:

HTML

<tr b-scope="people">
    <td age="18">john</td>
</tr>
<tr b-scope="people">
    <td age="13">josh</td>
</tr>
<tr style="display:none;" b-scope="people">
    <td age="20">jake</td>
</tr>
<tr style="display:none;" b-scope="people">
    <td age="19">jason</td>
</tr>
<tr b-scope="people">
    <td age="17">james</td>
</tr>

Combining attr and field options

Now consider this other example:

HTML

<tr age="{{person.age}}" b-scope="people" b-loop="person in people">
    <td age="{{person.age - 1}}" b-filter="name">{{person.name}}</td>
</tr>

We want to filter by the age attribute inside td tag. But using just the attr option, It will filter by the tr tag. To solve this, we back with b-filter attribute to help BreedJS find what attribute you're talking about. See:

Javascript

breed.filterAttr({
    scope: 'people',
    attr: 'age',
    field: 'name',
    rule: function(age){
        return age < 19;
    }
});

And that's the result:

HTML

<tr age="18" b-scope="people">
    <td age="17">john</td>
</tr>
<tr age="13" b-scope="people">
    <td age="12">josh</td>
</tr>
<tr age="20" style="display:none;" b-scope="people">
    <td age="19">jake</td>
</tr>
<tr age="19" b-scope="people">
    <td age="18">jason</td>
</tr>
<tr age="17" b-scope="people">
    <td age="16">james</td>
</tr>

[JS] breed.filterSelector(object)

Here we give you freedom to select the information that you want to filter. In this function you pass a jQuery selector to find the element(s) you want to. This function will check the element inner text to filter. This function has the same features of filter.

Object keys

  • scope: Your scope. It's optional if you set a default.
  • key: That's your filter key.
  • selector: The jQuery selector to find elements that you want to filter.
  • exclusion [optional]: Set this to true to filter by exclusion.
  • rule [optional]: Pass here a function that will set a rule to filter your elements.
  • sensitive [optional]: Set this to true to make the filter case sensitive.

Using the people data example, check this out:

HTML

<tr b-scope="people" b-loop="person in people">
    <td>{{person.name}}</td>
    <td>{{person.age}}</td>
</tr>

In this example, we want to build a very generic filter. We want to give a filter key that will validade even for name and age at the same time. To do so, we do this:

Javascript

breed.filterSelector({
    scope: 'people',
    selector: 'td',
    key: ['18', 'jake'] //note that I'm stacking filters here
});

Using td as a selector, I'm joining name and age, because They are the inner text of td tag. Here is the result:

HTML

<tr b-scope="people">
    <td>john</td>
    <td>18</td>
</tr>
<tr style="display:none;" b-scope="people">
    <td>josh</td>
    <td>13</td>
</tr>
<tr b-scope="people">
    <td>jake</td>
    <td>20</td>
</tr>
<tr style="display:none;" b-scope="people">
    <td>jason</td>
    <td>19</td>
</tr>
<tr style="display:none;" b-scope="people">
    <td>james</td>
    <td>17</td>
</tr>

End filter event

We provide a callback option for anykind of filter you do:

Javascript

breed.run({
    scope: 'people',
    input: data,
    filterEnd: function(){
        //here goes your code
    }
});

[JS] breed.watch(variable_name, [object])

We give you a little way to watch a variable that you want and print it at your page. See:

Javascript

var my_value = null;
breed.watch('my_value');
$("#txt").keyup(function() {
    my_value = $(this).val();
});

HTML

<input id="txt" type="text"><b-var var="my_value"></b-var>

The result:

Note that you have to use the b-var tag with an attribute var whose value is the variable name.

Watch an object

You can watch a custom object by passing it in the function:

Javascript

var person = {name: 'John', age: 20};
breed.watch('name', person);
breed.watch('age', person);
$("#name").keyup(function() {
    person.name = $(this).val();
});
$("#age").keyup(function() {
    person.age = $(this).val();
});

HTML

<tr>
    <td><b-var var="name"></b-var></td>
    <td><b-var var="age"></b-var></td>
</tr>

Then you get:

Name Age
John 20

Utils

Some functions that can be useful.

[JS] breed.utils.hasWord(key, string, [sensitive])

This function checks if a string has an entire word:

Javascript

breed.utils.hasWord('foo', 'foo boo bar'); // returns true
breed.utils.hasWord('fo', 'foo boo bar'); // returns false

Pass true to the third arg to case sensitive.

[JS] breed.utils.removeAccents(string)

This function removes accents of a string:

Javascript

breed.utils.removeAccents('ãñáéíóô'); // returns 'anaeioo'