Proposal: new common method element

Proposal: new common method element

<div>Scott G and I came up with an idea yesterday, to solve a common problem.</div><div>
</div><div><b>Problem</b></div><div>
</div>Many jQuery UI plugins wrap the element on which the .pluginname() init is called, or provide a different element altogether. Some plugins do this always, such as Dialog:<div>
</div><div>  <p id="dialog">jQuery UI Dialog</div><div>after $('#dialog').dialog() becomes</div><div>  <div class="ui-dialog">[...]<p id="dialog" class="ui-dialog-content">jQuery UI Dialog[ ... ]</div></div>
<div>
</div><div>Other plugins do it sometimes. Resizable doesn't wrap a div:</div><div>
</div><div>  <div id="resizable">jQuery UI Resizable</div></div><div>after $('#resizable').resizable() becomes</div>
<div>  <div id="resizable" class="ui-resizable">jQuery UI Resizable [ ... handles ... ]</div></div><div>
</div><div>but wraps iframes and imgs, among others:</div><div>
</div><div>  <iframe></iframe> or <img></div>
<div>after $('iframe, img').resizable() become</div><div>  <div class="ui-resizable"><iframe></iframe> [ ... handles ... ] </div></div><div>  <div class="ui-resizable"><img> [ ... handles ... ] </div></div>
<div>
</div><div>as those elements can't contain the resize handles, so they need a wrapper. But if a wrapper isn't needed, it isn't created.</div><div>
</div><div>In the case of datepicker called on an input, the element created is not a wrapper, but some external div.</div>
<div>
</div><div>In all these cases it can be useful to get access to that generated element from the original element and plugin instance. For people to hide the dialog titlebar, for example, one recommendation is:</div>
<div>
</div><div>jQuery 1.2.6:</div><div>$('#dialog').parents('.ui-dialog:first').find('ui-dialog-titlebar').hide();</div><div>jQuery 1.3:</div><div>$('#dialog').closest('.ui-dialog').find('ui-dialog-titlebar').hide();</div>
<div>
</div><div>This got a little better with 1.3, especially as you have to worry about nested plugins when using .parents(). Not applicable here as dialogs are never nested. But this doesn't address outside elements, like that created by datepicker.</div>
<div>
</div><div><b>Proposal</b></div><div>
</div><div>Create a new common method for all jQuery UI plugins called 'element'. This will always return the associated element with the ui-pluginname class, whether original or generated, so you could do</div>
<div>
</div><div>$('#msg').dialog('element').find('ui-dialog-titlebar').hide();</div><div>
</div><div>$('div').resizable('element').animate({ width: '500px' });</div><div>
</div><div>$('img').resizable('element').height(300);</div><div>
</div><div>$('input.date').datepicker('element').show('slow');</div><div>
</div><div>We currently use this.element internally in the jQuery UI widget factory and all widget internal implementations to mean the original element on which .pluginname() init was called. So as to avoid confusion, this.element will be deprecated in favor of this.elem. As these (method element and this.element) will never conflict, just be a source of confusion, there's no rush to remove the deprecated this.element. Maybe at 2.0.</div>
<div>
</div><div>Thoughts?</div><div>
</div><div>- Richard</div><div>
</div>