jQuery plugin: cron

Introduction

jquery-cron is a jQuery plugin for presenting a simplified interface for users to specify cron entries.

Instead of having to specify the five elements of a cron entry (minute, hour, day of month, month, day of week), jquery-cron provides a simpler interface for users to enter the more common combinations. For example:

Generated cron entry:

Or, with useGentleSelect enabled:

Generated cron entry:

In addition, the customValues option can be used to provide a list of canned cron entries. This allow users to cater for common use cases as well as enable more complex cron entries.

There is much room for improvements and we welcome contributions and bug fixes. Feel free to fork the project and send us pull requests!

Download

TODO

Usage

To use this plugin, one simply needs to load jQuery and the JS/CSS scripts for jquery-cron: 

<script type="text/javascript"
        src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>

<script type="text/javascript" src="cron/jquery-cron.js"></script>

<link type="text/css" href="cron/jquery-cron.css" rel="stylesheet" />

If used with useGentleSelect you'll also need:

<script type="text/javascript" src="gentleSelect/jquery-gentleSelect.js"></script>
<link type="text/css" href="gentleSelect/jquery-gentleSelect.css" rel="stylesheet" />

then attach it to an empty <div> on DOM ready: 

<script type="text/javascript">
$(document).ready(function() {
    $('#selector').cron(); // apply cron with default options
});
</script>
<!--- somewhere within <body> -->
<div id='selector'></div>

There are several ways one can utilise the generated cron entry:

  1. Interrogating the object : See value method and onChange option.
  2. AJAX POST : See the url_set option.
  3. embed in existing form (not recommended) : The UI is rendered as a series of <select> boxes within the <div>. Therefore, one can (in theory) embed the whole <div> within a form and on submission interrogate the appropriate fields. The generated fiels will have the names:
    • cron-period : possible values are "minute, hour, day, week, month, year"
    • cron-mins : only relevant when cron-period = "hour"
    • cron-time-hour : only relevant when cron-period = "day, week, month, year"
    • cron-time-min : only relevant when cron-period = "day, week, month, year"
    • cron-dom : only relevant when cron-period = "month, year"
    • cron-month : only relevant when cron-period = "year"
    • cron-dow : only relevant when cron-period = "week"

Options

initial

The initial option allows you the set the initial cron value. If an initialll value is not set, a default value of "* * * * *" is used.

After the object has been set up, you can still update the value using the value method.

url_set

You can asynchronously submit the current value to you backend script by specifying then the URL using the url_set option.

If this option is set, a "save" icon will appear when changes are made allowing users to submit their changes to the backend for processing.

jquery-cron will submit the values {"cron": ??} using a POST request via AJAX. If a non-error HTTP response is received, the save is considered to be successfule and the "save" icon will be hidden until the next change is made.

onChange

You can set a callback function using the onChange option. The function will be called each time the value changes. For instance, the example in the introduction is implemented as using: 

$('#example1').cron({
    initial: "42 3 * * 5",
    onChange: function() {
        $('#example1-val').text($(this).cron("value"));
    }
});

useGentleSelect

Tells the plugin to use gentleSelect to show dropdown options instead of the default select inputs. 

$('#example1').cron({
    initial: "42 3 * * 5",
    onChange: function() {
        $('#example1-val').text($(this).cron("value"));
    },
    useGentleSelect: true // default: false
});

Generated cron entry:

effectOpts

You can change the effects used when displaying/hiding the selection menu by changing the parameters in effectOpts. These values will be used as the default options for gentleSelect.

The following parameters can be set:

For example, the following uses the fade effect with a slower animation speed: 

$('#example2').cron({
    initial: "42 3 * * 5",
    effectOpts: {
        openEffect: "fade",
        openSpeed: "slow"
    }
});

Customising individual select boxes

It is possible to customise each of the generated select boxes by sending additional options to its instance of gentleSelect. All attributes support by jquery-gentleSelect can be specified.

The following are the options to use for each select menu:

For example, to change the title of the "Day of Month" select box which appears for monthly and yearly crons: 

$('#selector').cron({
    initial: "42 3 * * 5",
    domOpts: {
        title: "N-th day of the month"
    }
});

Adding custom values

Additional entries can be included in the period selection using the customValues option. This allows you to specify more complex cron entries that is not currently expressible using the current setup.

For example, the following adds two additional entries to the selection: 

$('#selector').cron({
    initial: "*/5 * * * *",
    customValues: {
        "5 Minutes" : "*/5 * * * *",
        "2 Hours on Weekends" : "0 */2 * * 5,6"
    }
});

Generated cron entry:

Caveats:

Methods

value

The value method enables you to set/get the current cron value. 

// Initialise a cron objecy
var cron_field = $('#selector').cron();

// Updating the value of an existing cron object
cron_field.cron("value", "12 23 * * *");

// calling the method with the extra argument returns the current value
var current_value = cron_field.cron("value")
Fork me on GitHub