NOTE: jQuery Simulate Extended is not actively developed anymore. It may still work but chances are high that some features are broken in recent browsers. For more information, see issue #39.

jQuery Simulate Extended Plugin 1.3.0

The jQuery Simulate Extended plugin (a.k.a. jquery-simulate-ext) provides methods for simulating complex user interactions based on the jQuery.simulate() plugin. The plugin provides simulation of:

Drag & Drop
Key Sequences
Key Combinations

Additionally, the extended plugin includes documentation and fixes for the jQuery simulate plugin itself.

Usage
- Example
- Demos
Documentation
Requirements
Compatibility
- Quirk Detection
Licensing

Usage

To use the jquery-simulate-ext plugin, you need to include (in the given order):

bililiteRange.js [if you want to use jquery.simulate.key-sequence.js or jquery.simulate.key-combo.js]
jquery-x.y.z.js
jquery.simulate.js
jquery.simulate.ext.js
jquery.simulate.drag-n-drop.js [if you want to simulate drag & drop]
jquery.simulate.key-sequence.js [if you want to simulate key sequences]
jquery.simulate.key-combo.js [if you want to simulate key combos]

The simulations are executed by calling the .simulate() function on a jQuery object. The simulation is then executed on all elements in the collection of the jQuery object (unless otherwise noted).

Synopsis: .simulate(type, options)
Parameters:
- type {String}: The type of the interaction to be simulated.
- options {Object}: An option object containing the options for the action to be simulated.

The types of simulated actions are:

From the jquery-simulate plugin:
- Mouse Events: "mousemove", "mousedown", "mouseup", "click", dblclick", "mouseover", "mouseout", "mouseenter", "mouseleave", "contextmenu"
- Key Events: "keydown", "keyup", "keypress"
- "focus"
- "blur"
From the jquery-simulate-ext plugin:
- Drag & Drop: "drag-n-drop", "drag", "drop"
- "key-sequence"
- "key-combo"

Example:

$('input[name="testInput"]').simulate("key-sequence", {sequence: "asdf"});

Demos:

The demos folder contains a demonstration of most of the features of the simulate extended plugins.

Live demos can be found at jsFiddle and JS Bin where you can also play around with the plugin:

Documentation

The options and events for the different interactions are described in the files in the doc folder:

Global Options:

Options recognized by all jquery-simulate-ext plugins:

eventProps {Object}: Defines custom properties which will be attached to the simulated events.
Note: Trying to define default properties of events (e.g. type, bubbles, altKey, etc.) using this option might not work since those properties are typically read-only.
Note: The dispatchEvent() function of all major browsers will remove custom properties from the event. Therefore, the jquery.simulate.js from the jquery-simulate-ext repository contains an option to use jQuery.trigger() instead of the native dispatchEvent(). This causes that the simulated event will only trigger event handlers attached using the same jQuery instance and not handlers attached using addEventListener() or using another versions of jQuery (see http://bugs.jquery.com/ticket/11047 for more information), but it's the only way to allow the custom properties to be used in the event handlers. To activate this option, define jQueryTrigger: true in the eventProps option object. For example:
```
$('#mySimulateTarget').simulate('key-sequence', {
    sequence: "my simulated text",
    eventProps: {
        jQueryTrigger: true,
        simulatedEvent: true
    }
});
```
Tip: As the example shows, this allows to flag the simulated events, which allows to distinguish the simulated events from real events in the event handlers. See issue #12 for more information.

Requirements

The plugin requires

jQuery 1.7.0+
jQuery Simulate
Note: With the current version of jquery.simulate.js, not all features of jquery-simulate-ext work correctly (see for example Drag & Drop within iframes). Therefore, the jquery-simulate-ext repository contains a fixed version of jquery.simulate.js at libs/jquery.simulate.js.
bililiteRange for the key-sequence and key-combo plugins

Compatibility

The plugins have been successfully tested with jQuery 1.7.2, 1.10.2, 2.1.0 and jQuery Simulate @485ca7192a, @25938de206. However, they should be compatible with other/future versions as well.

Quirk Detection

There are some issues with bililiteRange and some browsers. To workaround these issues, jquery-simulate-ext performs some quirk detections when the document is ready. Those quirk detections also contain temporary DOM manipulations. If you don't want those DOM manipulations to take place, you can disable the quirk detection by setting the flag ext_disableQuirkDetection in the jQuery.simulate object after jquery.simulate.js has been loaded but before any jquery-simulate-ext plugin is loaded. For example:

<!-- ... -->
<script type="text/javascript" src="https://github.com/j-ulrich/jquery-simulate-ext/raw/master/./libs/jquery.simulate.js"></script>
<script type="text/javascript">$.simulate.ext_disableQuirkDetection = true;</script>
<script type="text/javascript" src="https://github.com/j-ulrich/jquery-simulate-ext/raw/master/./src/jquery.simulate.ext.js"></script>
<script type="text/javascript" src="https://github.com/j-ulrich/jquery-simulate-ext/raw/master/./src/jquery.simulate.key-sequence.js"></script>
<!-- ... -->

For more information, see issue #9.

Licensing

Licensed under the MIT license.

j-ulrich / jquery-simulate-ext

readme