` should then be implemented as a CommonJS module that exports a constructor function. During client-side initialization, a new instance of your widget will be created for each rendered DOM element that the widget is bound to. A sample widget implementation is shown in the following JavaScript code:\n\n__src/pages/index/widget.js:__\n\n```javascript\nfunction Widget(config) {\n var rootEl = this.el; // this.el returns the root element that the widget is bound to\n var self = this;\n\n rootEl.addEventListener('click', function() {\n self.addText('You clicked on the root element!');\n });\n}\n\nWidget.prototype = {\n addText: function(text) {\n this.el.appendChild(document.createTextNode(text));\n }\n};\n\nmodule.exports = Widget;\n```\n\nIn order for everything to work on the client-side we need to include the code for the `raptor-widgets` module and the `./widget.js` module as part of the client bundle and we also need to use the custom `
` tag to let the client know which widgets rendered on the server need to be initialized on the client. To include the client-side dependencies will be using the [raptor-optimizer](https://github.com/raptorjs3/raptor-optimizer) module and the taglib that it provides. Our final page template is shown below:\n\n__src/pages/index/template.rhtml:__\n\n```html\n\n\n\n\n\n \n Widgets Demo\n \n\n\n \n \n
Click Me
\n \n\n \n \n\n\n```\n\nThe `optimizer.json` that includes the required client-side code is shown below:\n\n__src/pages/index/optimizer.json:__\n\n```javascript\n{\n \"dependencies\": [\n \"require raptor-widgets\",\n \"require ./widget\"\n ]\n}\n```\n\nIn the above example, the final HTML will be similar to the following:\n\n```html\n\n \n \n Widgets Demo\n \n \n \n
Click Me
\n \n \n \n \n\n```\n\n:arrow_forward: To try out and experiment with this code please see the documentation and source code for the [widgets-bind-behavior](https://github.com/raptorjs3/raptor-samples/tree/master/widgets-bind-behavior) sample app.\n\n## Referencing Widgets\n\nThe `raptor-widgets` taglib also provides support for allowing a widget to communicate directly with nested widgets. A nested widget can be assigned a widget ID (only needs to be unique within the scope of the containing widget) and the containing widget can then reference the nested widget by the assigned widget ID using the `this.widgets` collection.\n\nThe following HTML template fragment contains a widget that has three nested [sample-button](https://github.com/raptorjs3/raptor-sample-ui-components/tree/master/components/sample-button) widgets. Each nested [sample-button](https://github.com/raptorjs3/raptor-sample-ui-components/tree/master/components/sample-button) is assigned an ID (i.e. `primaryButton`, `successButton` and `dangerButton`).\n\n```html\n\n```\n\nThe containing widget can then refer to a particular nested widget as shown in the following sample JavaScript code:\n\n```javascript\nthis.widgets.dangerButton.on('click', function() {\n alert('You clicked on the danger button!');\n});\n```\n\n:arrow_forward: To try out and experiment with this code please see the documentation and source code for the [widgets-communication](https://github.com/raptorjs3/raptor-samples/tree/master/widgets-communication) sample app.\n\n## Referencing Widget DOM Elements\n\nDOM elements nested within a widget can be given unique IDs based on the containing widget's ID. These DOM elements can then be efficiently looked up by the containing widget using methods provided. The `w-el-id` custom attribute can be used to assign DOM element IDs to HTML elements that are prefixed with the widget's ID. For example, given the following HTML template fragment:\n\n```html\n\n```\n\nAssuming the unique ID assigned to the widget is `w123`, the following would be the HTML output:\n\n```html\n\n```\n\nFinally, to reference a widget's nested DOM element's the following code can be used in the containing widget:\n\n```javascript\nvar submitButton = this.getEl('submitButton'); // submitButton.id === 'w123-submitButton'\nvar cancelButton = this.getEl('cancelButton'); // cancelButton.id === 'w123-cancelButton'\n\nsubmitButton.style.border = '1px solid red';\n```\n\nThe object returned by `this.getEl()` will be a raw [HTML element](https://developer.mozilla.org/en-US/docs/Web/API/element). If you want a jQuery wrapped element you can do either of the following:\n\n\nOption 1) Use jQuery directly:\n\n```javascript\nvar $submitButton = $(this.getEl('submitButton'));\n```\n\nOption 2) Use the `this.$()` method:\n\n```javascript\nvar $submitButton = this.$('#submitButton');\n```\n\n## Rendering Widgets in the Browser\n\nTODO\n\n# API\n\n## Widget\n\n### Methods\n\n#### $(querySelector)\n\nThis is a convenience method for accessing a widget's DOM elements when jQuery is available. This mixin method serves as a proxy to jQuery to ease building queries based on widget element IDs.\n\nInternally, this jQuery proxy method will resolve widget element IDs to their actual DOM element ID by prefixing widget element IDs with the widget ID. For example, where this is a widget with an ID of `w123`:\n\n\n```javascript\nthis.$() ➡ $(\"#w123\")\nthis.$(\"#myEl\") ➡ $(\"#w123-myEl\")\n```\n\nThe usage of this mixin method is described below:\n\n__`$()`__\n\nConvenience usage to access the root widget DOM element wrapped as a jQuery object. All of the following are equivalent:\n\n```javascript\nthis.$()\n$(this.el)\n$(\"#\" + this.id)\n```\n\n__`$('#')`__\n\nConvenience usage to access a nested widget DOM element wrapped as a jQuery object. All of the following are equivalent:\n\n```javascript\nthis.$(\"#myEl)\n$(this.getEl(\"myEl\"))\n$(\"#\" + this.getElId(\"myEl\"))\n```\n\n__`$('')`__\n\nConvenience usage to query nested DOM elements scoped to the root widget DOM element. All of the following are equivalent:\n\n```javascript\nthis.$(\"ul > li\")\n$(\"ul > li\", this.el)\n$(\"#\" + this.id + \" ul > li\")\n```\n\n__`$('', '')`__\n\nConvenience usage to query nested DOM elements scoped to a nested widget DOM element. All of the following are equivalent:\n\n```javascript\nthis.$(\"li.color\", \"colorsUL\")\nthis.$(\"#colorsUL li.color\")\n$(\"li.color\", this.getEl(\"colorsUL\"))\n$(\"#\" + this.getElId(\"colorsUL\") + \" li.color\")\n```\n\n__`$('# ')`__\n\nConvenience usage to query nested DOM elements scoped to a nested widget DOM element. All of the following are equivalent:\n\n```javascript\nthis.$(\"#colorsUL li.color\")\nthis.$(\"li.color\", \"colorsUL\")\n$(\"li.color\", this.getEl(\"colorsUL\"))\n$(\"#\" + this.getElId(\"colorsUL\") + \" li.color\")\n```\n\n__`$(callbackFunction)`__\n\nConvenience usage to add a listener for the \"on DOM ready\" event and have the this object for the provided callback function be the current widget instance. All of the following are equivalent:\n\n```javascript\nthis.$(function() { /*...*/ });\n$(function() { /*...*/ }.bind(this)); // Using Function.prototype.bind\n$($.proxy(function() { /*...*/ }, this));\n```\n\n#### addEventListener(eventType, listener)\n\n#### appendTo(targetEl)\n\nMoves the widget's root DOM node from the current parent element to a new parent element. For example:\n\n```javascript\nthis.appendTo(document.body);\n```\n\n#### destroy()\n\nDestroys the widget by unsubscribing from all listeners made using the `subscribeTo` method and then detaching the widget's root element from the DOM. All nested widgets (discovered by querying the DOM) are also destroyed.\n\n#### detach()\n\nDetaches the widget's root element from the DOM by removing the node from its parent node.\n\n#### emit(eventType, arg1, arg2, ...)\n\nEmits an event. This method is inherited from EventEmitter (see [Node.js Events: EventsEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter)\n\n#### getEl(widgetElId)\n\nReturns a nested DOM element by prefixing the provided `widgetElId` with the widget's ID. For Raptor Templates, nested DOM elements should be assigned an ID using the `w-el-id` custom attribute. Returns `this.el` if no `widgetElId` is provided.\n\n#### getElId(widgetElId)\n\nSimilar to `getEl`, but only returns the String ID of the DOM element instead of the actual DOM element. \n\n#### insertAfter(targetEl)\n\n#### insertBefore(targetEl)\n\n#### isDestroyed()\n\n#### on(eventType, listener)\n\n#### prependTo(targetEl)\n\n#### ready(callback)\n\n#### replace(targetEl)\n\n#### replaceChildrenOf(targetEl)\n\n#### rerender(data, callback)\n\n#### subscribeTo(target)\n\n### Properties\n\n#### this.el\n\nThe root [HTML element](https://developer.mozilla.org/en-US/docs/Web/API/element) that the widget is bound to.\n\n#### this.id\n\nThe String ID of the root [HTML element](https://developer.mozilla.org/en-US/docs/Web/API/element) that the widget is bound to.\n\n#### this.widgets\n\nAn instance of `WidgetCollection` (see below) that holds references to all nested widgets with an assigned widget ID (e.g., but using the `w-id` custom attribute). For example:\n\n```javascript\nvar submitButton = this.widgets.submitButton;\n```\n\n## WidgetCollection\n\n### Methods\n\n#### forEach([id], callback)\n\n### Properties\n\n#### this.*","maintainers":[{"email":"austin.kell47@gmail.com","name":"austinkelleher"},{"email":"phillip.idem@gmail.com","name":"philidem"},{"email":"pnidem@gmail.com","name":"pnidem"}],"time":{"modified":"2022-07-13T15:06:36.736Z","created":"2014-02-26T23:39:58.420Z","0.2.0-beta":"2014-02-26T23:39:58.420Z","0.2.1-beta":"2014-03-04T00:08:40.603Z","0.2.2-beta":"2014-03-04T23:37:01.503Z","0.2.3-beta":"2014-03-04T23:40:53.616Z","0.2.4-beta":"2014-03-12T23:23:03.193Z","0.2.5-beta":"2014-03-13T23:43:20.724Z","0.2.6-beta":"2014-03-19T16:34:13.982Z","0.2.7-beta":"2014-03-26T21:07:30.868Z","0.2.8-beta":"2014-03-31T19:45:11.737Z","0.2.9-beta":"2014-04-14T20:38:51.124Z","0.2.10-beta":"2014-04-14T21:10:01.636Z","0.2.11-beta":"2014-04-30T04:24:19.012Z","0.2.12-beta":"2014-05-09T05:45:34.060Z","0.2.13-beta":"2014-05-16T01:12:31.837Z","0.2.14-beta":"2014-05-27T04:51:46.477Z","0.2.15-beta":"2014-06-05T17:01:18.833Z","0.2.16-beta":"2014-06-05T19:45:05.690Z","0.2.17-beta":"2014-06-06T19:16:55.769Z","0.2.18-beta":"2014-06-08T22:49:30.087Z","0.2.19-beta":"2014-06-09T13:50:46.713Z","0.2.20-beta":"2014-06-09T18:25:30.520Z","0.2.21-beta":"2014-06-10T21:56:02.656Z","0.2.22-beta":"2014-06-13T23:35:30.160Z","0.2.23-beta":"2014-06-18T20:05:11.852Z","0.2.24-beta":"2014-07-22T23:41:58.125Z","0.2.25-beta":"2014-07-28T21:50:25.169Z","0.2.26-beta":"2014-07-29T19:55:06.118Z","0.2.27-beta":"2014-07-31T20:15:46.401Z","0.2.28-beta":"2014-08-29T21:26:15.354Z","1.0.0-beta":"2014-09-04T18:27:16.259Z","1.0.1-beta":"2014-09-04T22:11:01.700Z","1.0.2-beta":"2014-09-18T05:00:00.155Z"},"homepage":"https://github.com/raptorjs3/raptor-widgets","repository":{"type":"git","url":"https://github.com/raptorjs3/raptor-widgets.git"},"author":{"name":"Patrick Steele-Idem","email":"pnidem@gmail.com"},"bugs":{"url":"https://github.com/raptorjs3/raptor-widgets/issues"},"license":"Apache License v2.0","readmeFilename":"README.md"}