From f72a94ae2879ebfc5206dd40d5db175e13113850 Mon Sep 17 00:00:00 2001 From: Jacob Thornton Date: Tue, 20 Dec 2011 23:28:48 -0800 Subject: [PATCH] update more readme changes - introduce target specificty convention to more plugins --- docs/javascript.html | 39 ++++++++++++++++++--------------------- js/README.md | 28 +++++++++++++++++++++++----- js/bootstrap-alert.js | 18 +++++++++++------- js/bootstrap-button.js | 2 +- js/bootstrap-carousel.js | 2 +- js/bootstrap-collapse.js | 2 +- js/bootstrap-dropdown.js | 14 ++++++++++---- js/bootstrap-modal.js | 12 ++++++------ js/bootstrap-popover.js | 4 ++-- js/bootstrap-scrollspy.js | 2 +- js/bootstrap-tab.js | 2 +- js/bootstrap-twipsy.js | 2 +- 12 files changed, 76 insertions(+), 51 deletions(-) diff --git a/docs/javascript.html b/docs/javascript.html index 45a7a2fe8a..8a9a203e74 100644 --- a/docs/javascript.html +++ b/docs/javascript.html @@ -112,7 +112,7 @@

What's included

Bring some of Bootstrap's primary components to life with custom jQuery plugins. We encourage you to extend and modify them to fit your specific development needs.

- +
@@ -186,7 +186,7 @@

Using bootstrap-modal

$('#myModal').modal(options)

Options

-
File
+
@@ -208,16 +208,11 @@ - - - - - -
Nametrue Closes the modal when escape key is pressed
showbooleantrueOpens modal on class initialization

Markup

-

You can activate modals on your page easily without having to write a single line of javascript. Just set data-toggle="modal" on a controller element with a data-target="#foo" or href="#foo" which corresponds to a modal element id, and when clicked, it will launch your modal. To add modal options, just include them as additoinal data attributes.

+

You can activate modals on your page easily without having to write a single line of javascript. Just set data-toggle="modal" on a controller element with a data-target="#foo" or href="#foo" which corresponds to a modal element id, and when clicked, it will launch your modal.

+

Also, to add options to your modal instance, just include them as additional data attributes on either the control element or the modal markup itself.

 <a class="btn" data-toggle="modal" href="#myModal" >Launch Modal</a>
@@ -240,7 +235,7 @@ $('#myModal').modal({ 
$('#myModal').modal('hide')

Events

Bootstrap's modal class exposes a few events for hooking into modal functionality.

- +
@@ -311,12 +306,14 @@ $('#myModal').on('hidden', function () {

Using boostrap-dropdown.js

$('.dropdown-toggle').dropdown()

Markup

-

To quickly add dropdown functionality to any element just add data-toggle="dropdown". Any valid bootstrap dropdown will automatically be activated.

+

To quickly add dropdown functionality to any element just add data-toggle="dropdown" and any valid bootstrap dropdown will automatically be activated.

+

Notice For added control and flexibility, optionally specify a data-target="#fat" or href="#fat" - this allows you to target specific dropdowns.

+ 
 <ul class="tabs">
   <li class="active"><a href="#">Home</a></li>
-  <li class="dropdown">
-    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Dropdown</a>
+  <li id="secondary" class="dropdown">
+    <a href="#secondary" class="dropdown-toggle" data-toggle="dropdown">Dropdown</a>
     <ul class="dropdown-menu">
       <li><a href="#">Secondary link</a></li>
       <li><a href="#">Something else here</a></li>
@@ -343,7 +340,7 @@ $('#myModal').on('hidden', function () {

Events

-
Event
+
@@ -571,7 +568,7 @@ $('a[data-toggle="tab"]').on('shown', function (e) {

Using bootstrap-twipsy.js

$('#example').twipsy(options)

Options

-
Event
+
@@ -661,7 +658,7 @@ $('a[data-toggle="tab"]').on('shown', function (e) {

Using boostrap-popover.js

$('#example').popover(options)

Options

-
Name
+
@@ -834,7 +831,7 @@ $('a[data-toggle="tab"]').on('shown', function (e) { $('.btn').button('complete') </scrip>

Demo

-
Name
+
@@ -903,7 +900,7 @@ $('a[data-toggle="tab"]').on('shown', function (e) {

Using bootstrap-collapse.js

$(".collapse").collapse()

Options

-
Stateful
+
@@ -953,7 +950,7 @@ $('#myCollapsible').collapse({

Bootstrap's collapse class exposes a few events for hooking into collapse functionality.

-
Name
+
diff --git a/js/README.md b/js/README.md index 061509fd3a..04dfb75df6 100644 --- a/js/README.md +++ b/js/README.md @@ -1,5 +1,5 @@ ## 2.0 BOOTSTRAP JS PHILOSOPHY -These are the high-level design rules which guide the development of Bootstrap's JS plugins. +These are the high-level design rules which guide the development of Bootstrap's plugin apis. --- @@ -28,10 +28,12 @@ All public APIs should be single, chainable methods, and return the collection a All methods should accept an optional options object, a string which targets a particular method, or null which initiates the default behavior: $("#myModal").modal() // initialized with defaults + $("#myModal").modal({ keyboard: false }) // initialized with now keyboard + $("#myModal").modal('show') // initializes and invokes show immediately afterqwe2 --- -### PLUGIN OPTIONS +### OPTIONS Options should be sparse and add universal value. We should pick the right defaults. @@ -51,7 +53,7 @@ examples: --- -### PLUGIN EVENTS +### EVENTS All events should have an infinitive and past participle form. The infinitive is fired just before an action takes place, the past participle on completion of the action. @@ -60,14 +62,30 @@ All events should have an infinitive and past participle form. The infinitive is --- +### CONSTRUCTORS + +Each plugin should expose it's raw constructor on a `Constructor` property -- accessed in the following way: + + + $.fn.popover.Constructor + +--- + +### DATA ACCESSOR + +Each plugin stores a copy of the invoked class on an object. This class instance can be accessed directly through jQuery's data api like this: + + $('[rel=popover]').data('popover') instanceof $.fn.popover.Constructor + +--- ### DATA ATTRIBUTES Data attributes should take the following form: - data-*(verb)* - defines main interaction -- data-target || href^=# - defined on controller element (if element interacts with an element other than self) -- data-*(noun)* - defines options for element invocation +- data-target || href^=# - defined on "control" element (if element controls an element other than self) +- data-*(noun)* - defines class instance options examples: diff --git a/js/bootstrap-alert.js b/js/bootstrap-alert.js index af15cbd7be..90961cdd39 100644 --- a/js/bootstrap-alert.js +++ b/js/bootstrap-alert.js @@ -35,18 +35,22 @@ constructor: Alert , close: function ( e ) { - var $element = $(this) + var $this = $(this) + , selector = $this.attr('data-target') || $this.attr('href') + , $parent = $(selector) - $element = $element.hasClass('alert-message') ? $element : $element.parent() e && e.preventDefault() - $element.removeClass('in') + + $parent.length || ($parent = $this.hasClass('alert-message') ? $this : $this.parent()) + + $parent.removeClass('in') function removeElement() { - $element.remove() + $parent.remove() } - $.support.transition && $element.hasClass('fade') ? - $element.on($.support.transition.end, removeElement) : + $.support.transition && $parent.hasClass('fade') ? + $parent.on($.support.transition.end, removeElement) : removeElement() } @@ -65,7 +69,7 @@ }) } - $.fn.alert.Alert = Alert + $.fn.alert.Constructor = Alert /* ALERT DATA-API diff --git a/js/bootstrap-button.js b/js/bootstrap-button.js index 508835a38f..10a85835e6 100644 --- a/js/bootstrap-button.js +++ b/js/bootstrap-button.js @@ -83,7 +83,7 @@ loadingText: 'loading...' } - $.fn.button.Button = Button + $.fn.button.Constructor = Button /* BUTTON DATA-API diff --git a/js/bootstrap-carousel.js b/js/bootstrap-carousel.js index e2b36884b5..ed4b8f3fac 100644 --- a/js/bootstrap-carousel.js +++ b/js/bootstrap-carousel.js @@ -46,6 +46,6 @@ }) } - $.fn.carousel.Carousel = Carousel + $.fn.carousel.Constructor = Carousel }( window.jQuery ) \ No newline at end of file diff --git a/js/bootstrap-collapse.js b/js/bootstrap-collapse.js index 8eefd8863a..313c0abcab 100644 --- a/js/bootstrap-collapse.js +++ b/js/bootstrap-collapse.js @@ -116,7 +116,7 @@ toggle: true } - $.fn.collapse.Collapse = Collapse + $.fn.collapse.Constructor = Collapse /* COLLAPSIBLE DATA-API diff --git a/js/bootstrap-dropdown.js b/js/bootstrap-dropdown.js index d2881b2762..15f4677b9d 100644 --- a/js/bootstrap-dropdown.js +++ b/js/bootstrap-dropdown.js @@ -35,11 +35,15 @@ constructor: Dropdown , toggle: function ( e ) { - var li = $(this).parent('li') - , isActive = li.hasClass('open') + var $this = $(this) + , selector = $this.attr('data-target') || $this.attr('href') + , $parent = $(selector) + + $parent.length || ($parent = $this.parent()) clearMenus() - !isActive && li.toggleClass('open') + + !$parent.hasClass('open') && $parent.toggleClass('open') return false } @@ -47,7 +51,7 @@ } function clearMenus() { - $(toggle).parent('li').removeClass('open') + $(toggle).parent().removeClass('open') } @@ -63,6 +67,8 @@ }) } + $.fn.dropdown.Constructor = Dropdown + /* APPLY TO STANDARD DROPDOWN ELEMENTS * =================================== */ diff --git a/js/bootstrap-modal.js b/js/bootstrap-modal.js index f2624ec1c1..98a62865b3 100644 --- a/js/bootstrap-modal.js +++ b/js/bootstrap-modal.js @@ -175,17 +175,16 @@ , options = typeof option == 'object' && option if (!data) $this.data('modal', (data = new Modal(this, options))) if (typeof option == 'string') data[option]() - else if (data.options.show) data.show() + else data.show() }) } $.fn.modal.defaults = { backdrop: true , keyboard: true - , show: true } - $.fn.modal.Modal = Modal + $.fn.modal.Constructor = Modal /* MODAL DATA-API @@ -194,10 +193,11 @@ $(function () { $('body').on('click.modal.data-api', '[data-toggle="modal"]', function ( e ) { var $this = $(this) - , target = $this.attr('data-target') || $this.attr('href') - , option = $(target).data('modal') ? 'toggle' : $this.data() + , $target = $($this.attr('data-target') || $this.attr('href')) + , option = $target.data('modal') ? 'toggle' : $.extend({}, $target.data(), $this.data()) + e.preventDefault() - $(target).modal(option) + $target.modal(option) }) }) diff --git a/js/bootstrap-popover.js b/js/bootstrap-popover.js index 53edfc8c9d..746699d372 100644 --- a/js/bootstrap-popover.js +++ b/js/bootstrap-popover.js @@ -29,7 +29,7 @@ /* NOTE: POPOVER EXTENDS BOOTSTRAP-TWIPSY.js ========================================= */ - Popover.prototype = $.extend({}, $.fn.twipsy.Twipsy.prototype, { + Popover.prototype = $.extend({}, $.fn.twipsy.Constructor.prototype, { constructor: Popover @@ -84,7 +84,7 @@ }) } - $.fn.popover.Popover = Popover + $.fn.popover.Constructor = Popover $.fn.popover.defaults = $.extend({} , $.fn.twipsy.defaults, { placement: 'right' diff --git a/js/bootstrap-scrollspy.js b/js/bootstrap-scrollspy.js index 041cfcb454..6201d4cefa 100644 --- a/js/bootstrap-scrollspy.js +++ b/js/bootstrap-scrollspy.js @@ -103,7 +103,7 @@ }) } - $.fn.scrollspy.ScrollSpy = ScrollSpy + $.fn.scrollspy.Constructor = ScrollSpy /* SCROLLSPY DATA-API diff --git a/js/bootstrap-tab.js b/js/bootstrap-tab.js index 2f147c59d8..c7632ded25 100644 --- a/js/bootstrap-tab.js +++ b/js/bootstrap-tab.js @@ -107,7 +107,7 @@ }) } - $.fn.tab.Tab = Tab + $.fn.tab.Constructor = Tab /* TAB DATA-API diff --git a/js/bootstrap-twipsy.js b/js/bootstrap-twipsy.js index ab744b7c5a..4868671bf3 100644 --- a/js/bootstrap-twipsy.js +++ b/js/bootstrap-twipsy.js @@ -247,7 +247,7 @@ }) } - $.fn.twipsy.Twipsy = Twipsy + $.fn.twipsy.Constructor = Twipsy $.fn.twipsy.defaults = { animate: true
Event