cf7-grid-layout / assets / jquery-toggles / README.md

README.md in Smart Grid-Layout Design for Contact Form 7 4.12, at assets/jquery-toggles/README.md

178 lines 5.3 KB

Raw Download Zip

1	# jQuery Toggles
2
3	[](https://david-dm.org/simontabor/jquery-toggles![Dependencies](https://david-dm.org/simontabor/jquery-toggles.svg)](https://david-dm.org/simontabor/jquery-toggles](https://david-dm.org/simontabor/jquery-toggles)
4	[](https://david-dm.org/simontabor/jquery-toggles![Dev Dependencies](https://david-dm.org/simontabor/jquery-toggles/dev-status.svg)](https://david-dm.org/simontabor/jquery-toggles](https://david-dm.org/simontabor/jquery-toggles)
5	![Bower](https://img.shields.io/bower/v/jquery-toggles.svg)
6	[](https://gitter.im/simontabor/jquery-toggles![Join the chat at https://gitter.im/simontabor/jquery-toggles](https://img.shields.io/badge/gitter-join%20chat-blue.svg)](https://gitter.im/simontabor/jquery-toggles](https://gitter.im/simontabor/jquery-toggles)
7
8	[](https://www.npmjs.com/package/jquery-toggles![NPM](https://nodei.co/npm/jquery-toggles.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/jquery-toggles](https://www.npmjs.com/package/jquery-toggles)
9
10	Want to create easy toggle buttons that you can click, drag, animate, use to toggle checkboxes and more? Yeah.
11
12	Examples can be seen [](http://simontabor.com/toggles/here](http://simontabor.com/toggles/](http://simontabor.com/toggles/).
13
14	## Usage
15
16	### Step 1: Include it in your page
17
18	Include the CSS at the start:
19
20	```html
21	<head>
22	<title>My cool page</title>
23
24	<link rel="stylesheet" href="css/toggles.css">
25	<link rel="stylesheet" href="css/toggles-modern.css">
26
27	<!-- ALL OF THE THEMES -->
28	<!-- <link rel="stylesheet" href="css/toggles-all.css"> -->
29
30	<!-- ALL OF THE CSS AND THEMES IN ONE FILE -->
31	<!-- <link rel="stylesheet" href="css/toggles-full.css"> -->
32	```
33
34	And the JS at the end:
35
36	```html
37	<script src="js/toggles.js" type="text/javascript"></script>
38	<!-- MINIFIED JS - recommended for production -->
39	<!-- <script src="js/toggles.min.js" type="text/javascript"></script> -->
40	</body>
41	</html>
42	```
43
44	### Step 2: Create your element
45
46	You need to specify the class for the specific theme you want to use. In this case we are using `toggle-modern`. The `toggle` class is simply what we will use as our selector to initialize it.
47
48	```html
49	<div class="toggle toggle-modern">
50	```
51
52	The themes we could have used are:
53
54	* soft
55	* light
56	* dark
57	* iphone
58	* modern
59
60	Of course, you can write your own themes/tweak the styling.
61
62	### Step 3: Initialize!
63
64	Now we just need to initialize the element we made to make it toggleable!
65
66	```javascript
67
68	// Simplest way:
69	$('.toggle').toggles();
70
71
72	// With options (defaults shown below)
73	$('.toggle').toggles({
74	drag: true, // allow dragging the toggle between positions
75	click: true, // allow clicking on the toggle
76	text: {
77	on: 'ON', // text for the ON position
78	off: 'OFF' // and off
79	},
80	on: true, // is the toggle ON on init
81	animate: 250, // animation time (ms)
82	easing: 'swing', // animation transition easing function
83	checkbox: null, // the checkbox to toggle (for use in forms)
84	clicker: null, // element that can be clicked on to toggle. removes binding from the toggle itself (use nesting)
85	width: 50, // width used if not set in css
86	height: 20, // height if not set in css
87	type: 'compact' // if this is set to 'select' then the select style toggle will be used
88	});
89
90
91	// Getting notified of changes, and the new state:
92	$('.toggle').on('toggle', function(e, active) {
93	if (active) {
94	console.log('Toggle is now ON!');
95	} else {
96	console.log('Toggle is now OFF!');
97	}
98	});
99
100	```
101
102	## Advanced Usage
103
104	### Setting toggle states
105
106	```javascript
107	// initiate a new Toggles class
108	$('.toggles').toggles({
109	on: true
110	});
111
112	// the underlying Toggles class can be accessed
113	var myToggle = $('.toggles').data('toggles');
114
115	console.log(myToggle.active); // true
116	myToggle.toggle();
117	console.log(myToggle.active); // false
118
119	// set the state to 'false'
120	// will not do anything if the state is already false
121	myToggle.toggle(false);
122	console.log(myToggle.active); // false
123
124	// passing a boolean in place of options on an active toggle element
125	// will set the state
126	$('.toggles').toggles(true);
127	console.log(myToggle.active); // true
128
129	// the toggle-active data attribute stores the state too
130	console.log($('.toggles').data('toggle-active')); // true
131
132	// myToggle.toggle(state, noAnimate, noEvent)
133
134	// don't animate the change
135	myToggle.toggle(false, true);
136
137	// change the state without triggering an event
138	myToggle.toggle(true, false, true);
139	```
140
141	### Using data-toggle-\* attributes on the element
142
143	Any of the following options can be set using data-toggle attributes: `on`, `drag`, `click`, `width`, `height`, `animate`, `easing`, `type`, `checkbox`
144	```html
145	<div class="toggles" data-toggle-on="true" data-toggle-height="20" data-toggle-width="60"></div>
146	```
147	```javascript
148	$('.toggles').toggles();
149	```
150
151	### Disabling user interaction
152
153	It can be useful to disable the toggle to stop users from changing the state. Set the `disabled` attribute on the toggle element to do this. Alternatively, you could use CSS to set `pointer-events: none`
154
155	```js
156	// your toggle element
157	var toggle = $('.toggle');
158
159	// initialise it
160	toggle.toggles();
161
162	// disable the toggle element (click + drag will no longer work)
163	toggle.toggleClass('disabled', true);
164
165	// setting the state via JS is NOT disabled, only user input
166	// toggle the toggle on
167	toggle.toggles(true);
168
169	// re-enable the toggle
170	toggle.toggleClass('disabled', false);
171	```
172
173	## Contributing
174
175	Make your JavaScript edits to `js/Toggles.js`. Any styling edits should be made to the relevent files in the `less` folder. JS edits must be compatible with Closure Compiler advanced optimisations - if you aren't able to code in this style then I'll happily tweak any pull requests/help out.
176
177	To build the files for release, run `make`. Again, if you struggle then I'll be able to build the files for you. (Note: use node v5)
178