Skip to content

Documenting Extension Points. Fixes #20. #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 8 commits into from
Closed

Documenting Extension Points. Fixes #20. #178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9606d2c
Autocomplete: Documenting _renderItem() extension point.
tjvantoll Sep 23, 2013
5c1fe18
Autocomplete: Clarify that menu items can be any element. Specifying …
tjvantoll Sep 24, 2013
009cb92
Autocomplete: _renderItem will always receive a <ul> element
tjvantoll Sep 24, 2013
256bbaa
Autocomplete: Document _renderMenu extension point.
tjvantoll Sep 24, 2013
7f90c49
Autocomplete: Document the _resizeMenu extension point.
tjvantoll Sep 25, 2013
9232d3e
Spinner: Document extension points.
tjvantoll Sep 26, 2013
38593a0
Dialog: Document _allowInteraction() extension point.
tjvantoll Sep 26, 2013
ce90a59
Menu: Document _closeOnDocumentClick() extension point.
tjvantoll Sep 26, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions entries/autocomplete.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,70 @@
<desc>Returns a <code>jQuery</code> object containing the menu element. Although the menu items are constantly created and destroyed, the menu element itself is created during initialization and is constantly reused.</desc>
</method>
</methods>
<extension-points>
<method name="_renderItem" return="jQuery">
<desc>
<p>Method that controls the creation of each option in the widget's menu. The method must create a new <code>&lt;li&gt;</code> element, append it to the menu, and return it.</p>
<p><em>Note: At this time the<code>&lt;ul&gt;</code> element created must contain an <code>&lt;a&gt;</code> element for compatibility with the <a href="/menu/">menu</a> widget. See the example below.</em></p>
</desc>
<argument name="ul" type="jQuery">
<desc>The <code>&lt;ul&gt;</code> element that the newly created <code>&lt;li&gt;</code> element must be appended to.</desc>
</argument>
<argument name="item" type="Object">
<property name="label" type="String">
<desc>The string to display for the item.</desc>
</property>
<property name="value" type="String">
<desc>The value to insert into the input when the item is selected.</desc>
</property>
</argument>
<example>
<desc>Add the item's value as a data attribute on the <code>&lt;li&gt;</code>.</desc>
<code><![CDATA[
_renderItem: function( ul, item ) {
return $( "<li>" )
.attr( "data-value", item.value )
.append( $( "<a>" ).text( item.label ) )
.appendTo( ul );
}
]]></code>
</example>
</method>
<method name="_renderMenu">
<desc>
Method that controls building the widget's menu. The method is passed an empty <code>&lt;ul&gt;</code> and an array of items that match the user typed term. Creation of the individual <code>&lt;li&gt;</code> elements should be delegated to <code>_renderItemData()</code>.
</desc>
<argument name="ul" type="jQuery">
<desc>An empty <code>&lt;ul&gt;</code> element to use as the widget's menu.</desc>
</argument>
<argument name="items" type="Array">
<desc>An Array of items that match the user typed term. Each item is an Object with <code>label</code> and <code>value</code> properties.</desc>
</argument>
<example>
<desc>Add a CSS class name to the odd menu items.</desc>
<code><![CDATA[
_renderMenu: function( ul, items ) {
var that = this;
$.each( items, function( index, item ) {
that._renderItemData( ul, item );
});
$( ul ).find( "li:odd" ).addClass( "odd" );
}
]]></code>
</example>
</method>
<method name="_resizeMenu">
<desc>Method responsible for sizing the menu before it is displayed. The menu element is available at <code>this.menu.element</code>.</desc>
<example>
<desc>Always display the menu as 500 pixels wide.</desc>
<code><![CDATA[
_resizeMenu: function() {
this.menu.element.outerWidth( 500 );
}
]]></code>
</example>
</method>
</extension-points>
<example>
<desc>A simple jQuery UI Autocomplete</desc>
<code><![CDATA[
Expand Down
16 changes: 16 additions & 0 deletions entries/dialog.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -345,6 +345,22 @@
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</methods>
<extension-points>
<method name="_allowInteraction" return="Boolean">
<desc>
Modal dialogs do not allow users to interact with elements behind the dialog. This can be problematic for elements that are not children of the dialog, but are absolutely positioned to appear as though they are. The <code>_allowInteraction()</code> method determines whether the user should be allowed to interact with a given target element; therefore, it can be used to whitelist elements that are not children of the dialog but you want users to be able to use.
</desc>
<argument name="event" type="Event"/>
<example>
<desc>Allow the Select2 plugin to be used within modal dialogs. The <a href="/jquery.widget/#method-_super"><code>_super()</code></a> call ensures elements within the dialog can still be interacted with.</desc>
<code><![CDATA[
_allowInteraction: function( event ) {
return !!$( event.target ).is( ".select2-input" ) || this._super( event );
}
]]></code>
</example>
</method>
</extension-points>
<example>
<desc>A simple jQuery UI Dialog</desc>
<code><![CDATA[
Expand Down
16 changes: 16 additions & 0 deletions entries/menu.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,22 @@
</method>
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</methods>
<extension-points>
<method name="_closeOnDocumentClick" return="Boolean">
<desc>
Method that determines whether clicks on the document should close any open menus. By default, menus are closed unless the click occurred a menu.
</desc>
<argument name="event" type="Event"/>
<example>
<desc>Never close menus on document click.</desc>
<code><![CDATA[
_closeOnDocumentClick: function( event ) {
return false;
}
]]></code>
</example>
</method>
</extension-points>
<events>
<event name="blur">
<desc>
Expand Down
34 changes: 34 additions & 0 deletions entries/spinner.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,40 @@
</method>
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</methods>
<extension-points>
<method name="_buttonHtml" return="String">
<desc>
Method that returns HTML to use for the spinner's increment and decrement buttons. Each button must be given a <code>ui-spinner-button</code> class name for the associated events to work.
</desc>
<example>
<desc>Use <code>&lt;button&gt;</code> elements for the increment and decrement buttons.</desc>
<code><![CDATA[
_buttonHtml: function() {
return "" +
"<button class='ui-spinner-button ui-spinner-up'>" +
"<span class='ui-icon " + this.options.icons.up + "'>&#9650;</span>" +
"</button>" +
"<button class='ui-spinner-button ui-spinner-down'>" +
"<span class='ui-icon " + this.options.icons.down + "'>&#9660;</span>" +
"</button>";
}
]]></code>
</example>
</method>
<method name="_uiSpinnerHtml" return="String">
<desc>
Method that determines the HTML to use to wrap the spinner's <code>&lt;input&gt;</code> element.
</desc>
<example>
<desc>Wrap the spinner with a <code>&lt;div&gt;</code> with no rounded corners.</desc>
<code><![CDATA[
_uiSpinnerHtml: function() {
return "<div class='ui-spinner ui-widget ui-widget-content'></div>";
}
]]></code>
</example>
</method>
</extension-points>
<events>
<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<event name="start">
Expand Down