scratch – Blame information for rev 79
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
79 | office | 1 | # Bootstrap Toggle |
2 | Bootstrap Toggle is a highly flexible Bootstrap plugin that converts checkboxes into toggles. |
||
3 | |||
4 | Visit http://www.bootstraptoggle.com for demos. |
||
5 | |||
6 | ## Getting Started |
||
7 | |||
8 | ### Installation |
||
9 | You can [download](https://github.com/minhur/bootstrap-toggle/archive/master.zip) the latest version of Bootstrap Toggle or use CDN to load the library. |
||
10 | |||
11 | `Warning` If you are using Bootstrap v2.3.2, use `bootstrap2-toggle.min.js` and `bootstrap2-toggle.min.css` instead. |
||
12 | |||
13 | ```html |
||
14 | <link href="https://gitcdn.github.io/bootstrap-toggle/2.2.0/css/bootstrap-toggle.min.css" rel="stylesheet"> |
||
15 | <script src="https://gitcdn.github.io/bootstrap-toggle/2.2.0/js/bootstrap-toggle.min.js"></script> |
||
16 | ``` |
||
17 | |||
18 | ### Bower Install |
||
19 | ```bash |
||
20 | bower install bootstrap-toggle |
||
21 | ``` |
||
22 | |||
23 | ## Usage |
||
24 | |||
25 | ### Basic example |
||
26 | Simply add `data-toggle="toggle"` to convert checkboxes into toggles. |
||
27 | |||
28 | ```html |
||
29 | <input type="checkbox" checked data-toggle="toggle"> |
||
30 | ``` |
||
31 | |||
32 | ### Stacked checkboxes |
||
33 | Refer to Bootstrap Form Controls documentation to create stacked checkboxes. Simply add `data-toggle="toggle"` to convert checkboxes into toggles. |
||
34 | |||
35 | ```html |
||
36 | <div class="checkbox"> |
||
37 | <label> |
||
38 | <input type="checkbox" data-toggle="toggle"> |
||
39 | Option one is enabled |
||
40 | </label> |
||
41 | </div> |
||
42 | <div class="checkbox disabled"> |
||
43 | <label> |
||
44 | <input type="checkbox" disabled data-toggle="toggle"> |
||
45 | Option two is disabled |
||
46 | </label> |
||
47 | </div> |
||
48 | ``` |
||
49 | |||
50 | ### Inline Checkboxes |
||
51 | Refer to Bootstrap Form Controls documentation to create inline checkboxes. Simply add `data-toggle="toggle"` to a convert checkboxes into toggles. |
||
52 | |||
53 | ```html |
||
54 | <label class="checkbox-inline"> |
||
55 | <input type="checkbox" checked data-toggle="toggle"> First |
||
56 | </label> |
||
57 | <label class="checkbox-inline"> |
||
58 | <input type="checkbox" data-toggle="toggle"> Second |
||
59 | </label> |
||
60 | <label class="checkbox-inline"> |
||
61 | <input type="checkbox" data-toggle="toggle"> Third |
||
62 | </label> |
||
63 | ``` |
||
64 | |||
65 | ## API |
||
66 | |||
67 | ### Initialize by JavaScript |
||
68 | Initialize toggles with id `toggle-one` with a single line of JavaScript. |
||
69 | |||
70 | ```html |
||
71 | <input id="toggle-one" checked type="checkbox"> |
||
72 | <script> |
||
73 | $(function() { |
||
74 | $('#toggle-one').bootstrapToggle(); |
||
75 | }) |
||
76 | </script> |
||
77 | ``` |
||
78 | |||
79 | ### Options |
||
80 | Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-on="Enabled"`. |
||
81 | |||
82 | ```html |
||
83 | <input type="checkbox" data-toggle="toggle" data-on="Enabled" data-off="Disabled"> |
||
84 | <input type="checkbox" id="toggle-two"> |
||
85 | <script> |
||
86 | $(function() { |
||
87 | $('#toggle-two').bootstrapToggle({ |
||
88 | on: 'Enabled', |
||
89 | off: 'Disabled' |
||
90 | }); |
||
91 | }) |
||
92 | </script> |
||
93 | ``` |
||
94 | |||
95 | Name|Type|Default|Description| |
||
96 | ---|---|---|--- |
||
97 | on|string/html|"On"|Text of the on toggle |
||
98 | off|string/html|"Off"|Text of the off toggle |
||
99 | size|string|"normal"|Size of the toggle. Possible values are `large`, `normal`, `small`, `mini`. |
||
100 | onstyle|string|"primary"|Style of the on toggle. Possible values are `default`, `primary`, `success`, `info`, `warning`, `danger` |
||
101 | offstyle|string|"default"|Style of the off toggle. Possible values are `default`, `primary`, `success`, `info`, `warning`, `danger` |
||
102 | style|string| |Appends the value to the class attribute of the toggle. This can be used to apply custom styles. Refer to Custom Styles for reference. |
||
103 | width|integer|*null*|Sets the width of the toggle. if set to *null*, width will be calculated. |
||
104 | height|integer|*null*|Sets the height of the toggle. if set to *null*, height will be calculated. |
||
105 | |||
106 | ### Methods |
||
107 | Methods can be used to control toggles directly. |
||
108 | |||
109 | ```html |
||
110 | <input id="toggle-demo" type="checkbox" data-toggle="toggle"> |
||
111 | ``` |
||
112 | |||
113 | Method|Example|Description |
||
114 | ---|---|--- |
||
115 | initialize|$('#toggle-demo').bootstrapToggle()|Initializes the toggle plugin with options |
||
116 | destroy|$('#toggle-demo').bootstrapToggle('destroy')|Destroys the toggle |
||
117 | on|$('#toggle-demo').bootstrapToggle('on')|Sets the toggle to 'On' state |
||
118 | off|$('#toggle-demo').bootstrapToggle('off')|Sets the toggle to 'Off' state |
||
119 | toggle|$('#toggle-demo').bootstrapToggle('toggle')|Toggles the state of the toggle |
||
120 | enable|$('#toggle-demo').bootstrapToggle('enable')|Enables the toggle |
||
121 | disable|$('#toggle-demo').bootstrapToggle('disable')|Disables the toggle |
||
122 | |||
123 | ## Events |
||
124 | |||
125 | ### Event Propagation |
||
126 | Note All events are propagated to and from input element to the toggle. |
||
127 | |||
128 | You should listen to events from the `<input type="checkbox">` directly rather than look for custom events. |
||
129 | |||
130 | ```html |
||
131 | <input id="toggle-event" type="checkbox" data-toggle="toggle"> |
||
132 | <div id="console-event"></div> |
||
133 | <script> |
||
134 | $(function() { |
||
135 | $('#toggle-event').change(function() { |
||
136 | $('#console-event').html('Toggle: ' + $(this).prop('checked')) |
||
137 | }) |
||
138 | }) |
||
139 | </script> |
||
140 | ``` |
||
141 | |||
142 | ### API vs Input |
||
143 | This also means that using the API or Input to trigger events will work both ways. |
||
144 | |||
145 | ```html |
||
146 | <input id="toggle-trigger" type="checkbox" data-toggle="toggle"> |
||
147 | <button class="btn btn-success" onclick="toggleOn()">On by API</button> |
||
148 | <button class="btn btn-danger" onclick="toggleOff()">Off by API</button> |
||
149 | <button class="btn btn-success" onclick="toggleOnByInput()">On by Input</button> |
||
150 | <button class="btn btn-danger" onclick="toggleOffByInput()">Off by Input</button> |
||
151 | <script> |
||
152 | function toggleOn() { |
||
153 | $('#toggle-trigger').bootstrapToggle('on') |
||
154 | } |
||
155 | function toggleOff() { |
||
156 | $('#toggle-trigger').bootstrapToggle('off') |
||
157 | } |
||
158 | function toggleOnByInput() { |
||
159 | $('#toggle-trigger').prop('checked', true).change() |
||
160 | } |
||
161 | function toggleOffByInput() { |
||
162 | $('#toggle-trigger').prop('checked', false).change() |
||
163 | } |
||
164 | </script> |
||
165 | ``` |
||
166 | |||
167 | ### Integration |
||
168 | |||
169 | #### [KnockoutJS](http://knockoutjs.com) |
||
170 | |||
171 | A binding for knockout is available here: [aAXEe/knockout-bootstrap-toggle](https://github.com/aAXEe/knockout-bootstrap-toggle) |
||
172 | |||
173 | ## Demos |
||
174 | |||
175 | Visit http://www.bootstraptoggle.com for demos. |