Advanced
There’s a lot of cool stuff under the hood of jKit for advanced users. Here’s how to get most out of jKit.
Macros
Macros can make your life a lot easier if you need to use the same command and options more than once. There are two ways to define a macro. The first one is on plugin init:
<script type="text/javascript">
$('body').jKit({
'macros': {
'hide-if-empty': 'binding:selector=this;source=text;mode=css.display',
'smooth-blink': 'loop:speed1=2000;duration1=250;speed2=250;duration2=2000'
}
});
</script>
You can then use them like this:
...
The second way to define a macro is with the macro command:
[macro:name=hoverhide]
It creates a macro from the previously used command on the same element. Here’s a real example to get a better idea of how the macro command works:
When we’re using a macro, it is possible to overwrite any of the options which are defined in the macro. Here’s an example:
One last warning! If you name a macro the same as a built in command, you will overwrite that command, so please be carefull and give your macros unique names!
Events
Some commands trigger events on different actions. You can find all events a command can trigger on each of the command pages. Here’s how they work.
Let’s say we have an element which loads the latest jKit commits with the API command. Now we don’t want to show that div till the commits are actually finished loading. To make this possible we first add a command key “commits” to the api command so that we can call a specific element command. Next we add a show command that has the global “onevent” option. The API has an event “complete”, so with an onevent “commits.complete”, we will start this command only after the api has finished loading our commits. So now the div fades in nicely after the commits are fully loaded:
The command key is a special option of each command, you can add a key like above (commits) or by setting that option directly like this:
options.commandkey=commits
In the next example we are using events to show some content whenever the third slide of a slideshow is shown:
... our slideshow elements ...... content shown ...
Now you don’t always want to trigger a command every single time an event happens, for this reason there is a special option called “execute” to limit the number of times an event is triggered. By default this option is set to “always”. Other options are “once” and a number for the exact number of times. You can use it like this:
... content shown ...
Additionall there is an option “andonevent” that triggers a command not only on the specified event, but on page load as well, so it behaves like a normal command and like an event command at the same time.
Especially for the events there is a new special command. Similar as with the macro command, this isn’t a real command, but a way to do additional nice things. While the macro command stores the previous command in a macro, the reload command reloads the previous command on a specific event. Here’s an example:
...
This makes it possible to reload the same command after a while. In the above example the commits are again loaded ten seconds after the last commits were loaded.
And finally there is of course a way to get to this events with JavaScript:
$('body').on('commits.complete', function(){
alert('Latest commits completely loaded');
});
Easing Plugin
All commands that use animations have an option called “easing”. To get all the great easing options, you have to include this amazing easing plugin on your page (or some other easing plugin that may be around somewhere).
Dynamic Option Values
jKit makes it possible to use dynamic option values by adding the “*” character to the end of the value. You can either use global variables or global functions. Here’s an example where we limit the length of a string to the number stored in a global variable.
<script type="text/javascript"> var maxStringLengths = 25; </script>
1234567890123456789012345678901234567890123456789
Here’s how you would do the same thing using a global function:
<script type="text/javascript">
function maxStringLengths(){
return 25;
}
</script>
The second way is of course only usefull in case you don’t want to return the same value each time. And because “this” inside the function is the current element, you can actually do some very cool stuff with it.
As of jKit 1.1.10, there’s a second kind of dynamic option value that can be used without any additional JavaScript. Here’s an example:
data-jkit="[show:delay={rand|0-1000}]"
This will generate a random value between 0 and 1000 for the option “delay”. Here’s another exmaple:
data-jkit="[animation:to=height({rand|10-40}px),width({rand|20-500}px)]"
This will generate a random height and width for the “to” option. Currently only random values are possible with this style of dynamic values, but there will be more in future versions of jKit.
The Target Option
The target option is a special option that’s available on all commands. It allows you to target childrens of the current element, so it’s very usefull for stuff where you need to apply the same command to multiple elements. Here’s an example where we limit the character count for every li element:
- jkdhfajksdf fdsjafhkj fkha jkdfajkslhf jkshjhl
- jdhj ghs fdsgh jdsjg dflshg jfdghsjk jfdsjg
- dfjhdjsh dfjks fgjg dsjgdfs
Here are some example values for target:
- children: Selects the immediate children
- children.li: Selects the immediate children of element type “li”
- children.li.myclass: Selects the immediate children of element type “li” with class “myclass”
- each: Selects all containing elements (be carefull with this one!)
- each.h3: Selects all containing elements of type “h3”
Escaping
Sometimes you may need to use one of the protected characters inside an option value. In such a case, all you need is to escape the character with “”. Here’s an example where we escape the “=” character inside the condition option value:
Disable command
If you need to temporarily disable a specific command to test something, just add “//” in front of it like this:
data-jkit="[//limit:elements=chars;count=10;target=children]
Defaults
Each command comes with default settings. So for example this two lines do exactly the same:
To the top!
To the top!
You can define your own defaults on plugin init like this:
<script type="text/javascript">
$('body').jKit({
'commands': {
'showandhide': {
'delay': 0,
'speed': 500,
'duration': 10000,
'animation': 'fade',
'easing': 'linear'
},
'loop': {
'speed1': 500,
'speed2': 500,
'duration1': 2000,
'duration2': 2000,
'easing1': 'linear',
'easing2': 'linear',
'animation': 'fade'
}
}
});
</script>
You can find all the original defaults by looking at the jKit source code, they are right at the top.
Replacements
jKit is a pretty small library and we don’t want to make it bigger than about half the size of jQuery. This makes it impossible to create some big implementations for a command with tons of options and beautiful visuals. But don’t worry, there’s a way to replace the implementation of a command with an extended version. We will publish every command replacement right on the command page, so you always know what’s available.
You can easely add replacements on jKit init like this:
$('body').jKit({
'replacements': {
'encode': specialEncodeCommand
}
});
function specialEncodeCommand(that, type, options){
var s = this.settings; // we don't need this one, but I'll leave it here so you know how to get the plugin settings in case you need them
var $that = $(that);
this.executeCommand(that, type, options); // execute the original command
// now add some additional functionality:
if (options.format == 'uppercase'){
$that.html($that.html().toUpperCase());
}
}
</script>
As you can see, you don’t have to dublicate the whole commands code if you just want to add a little bit at the end, just use the following line to execute the original code first:
this.executeCommand(that, type, options);
jKit has a nice source code viewer, it will tell you a lot about how everything works. It should be the first thing you read before you start working on a replacement. You can find it over here: jKit Source
Plugins
Another great way to use more cool stuff that isn’t implemented inside jKit is with the plugin command. You can add plugins on init like this:
<script type="text/javascript">
$('body').jKit({
'plugins': {
date: { 'path': "plugins/datepicker/js/datepicker.js", 'fn': 'DatePicker' },
hint: { 'path': "plugins/jquery.ztinputhint-1.2.js", 'fn': 'ztInputHint' },
maxlength: { 'path': "plugins/maxlength/jquery.maxlength-min.js", 'fn': 'maxlength' },
grow: { 'path': "plugins/jquery.jgrow-0.4.js", 'fn': 'jGrow' },
confirm: { 'path': "plugins/jquery.confirm-1.3.js", 'fn': 'confirm' },
time: { 'path': "plugins/timePicker/jquery.timePicker.min.js", 'fn': 'timePicker' },
mask: { 'path': "plugins/jquery.maskedinput-1.2.2.min.js", 'fn': 'mask', 'option': 'mask' }
}
});
</script>
You can than use them like this:
There are basically two kinds of jQuery plugins you can use:
<script type="text/javascript">
$('#myElement').pluginName( { setting1: 'value1', setting2: 'value2' } );
$('#myElement').pluginName( option, { setting1: 'value1', setting2: 'value2' } );
</script>
If you are a plugin developer, follow this two patterns and your plugin should be jKit compatible!
Settings
jKit has some more settings which can be set on plugin init:
| Option | Values | Default | Description |
|---|---|---|---|
| prefix | String | “jkit” | The prefix used for all classes and ids jKit is using. |
| dataAttribute | String | “data-jkit” | The HTML 5 data attribute jKit is using. |
| activeClass | String | “active” | This class is set on active elements. |
| errorClass | String | “error” | This class is set on error elements. |
| successClass | String | “success” | This class is set on success elements. |
| ignoreFocus | Boolean | false | jKit only plays animations if the window is in focus. This is especially usefull on big pages with lots of things going on. You can switch off this behaviour if you want. |
| ignoreViewport | Boolean | false | jKit only plays animations if the element is inside the viewport (visible). This is especially usefull on big pages with lots of things going on. You can switch off this behaviour if you want. |
| keyNavigation | Boolean | true | Some commands support keyboard navigation. You can of course switch that off, as well. |
| touchNavigation | Boolean | true | This one isn’t implemented right now, but it is planned to add touch navigation, too. |
| delimiter | String | “,” | The default delimiter used by jKit commands. |
Links
To get the most out of jKit, it’s a good idea to have some knowledge about jQuery and JavaScript. That’s why we collected a list of the best Links for you. Here they are: Links