can

<!DOCTYPE html>  <html lang="en"> <head> <meta charset="utf-8"> <title>CanJS - tag</title> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"> <link rel="stylesheet" type="text/css" href="./static/bundles/bit-docs-site/static.css"> <link rel="shortcut icon" sizes="16x16 24x24 32x32 48x48 64x64" href="/docs/images/canjs_favicon.ico"> <link rel="apple-touch-icon" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon-precomposed" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon" sizes="72x72" href="../docs/images/canjs_favicon_72x72.png"> <link rel="apple-touch-icon" sizes="114x114" href="../docs/images/canjs_favicon_114x114.png"> <link rel="apple-touch-icon" sizes="120x120" href="../docs/images/canjs_favicon_128x128.png"> <link rel="apple-touch-icon" sizes="144x144" href="../docs/images/canjs_favicon_144x144.png"> <link rel="apple-touch-icon" sizes="152x152" href="../docs/images/canjs_favicon_152x152.png"> <meta content="yes" name="apple-mobile-web-app-capable"> <meta name="apple-mobile-web-app-status-bar-style" content="white-translucent"> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-2302003-11', 'auto'); ga('send', 'pageview'); </script> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger"/> <label for="nav-trigger">Menu</label> <div id="everything"> <div id="left" class="column"> <div class="top-left"> <div class="brand"> <div class="logo"> <a href="../index.html" alt="CanJS"></a> <div class="dropdown project-dropdown"> <a href="https://donejs.com/">DoneJS</a> <a href="http://stealjs.com/">StealJS</a> <a href="http://jquerypp.com/">jQuery ++</a> <a href="https://funcunit.com/">FuncUnit</a> <a href="http://documentjs.com/">DocumentJS</a> </div> </div> <div class="version"> <div class="version-number"> 3.0.0 </div> <div class="dropdown version-dropdown"> <a href="https://v2.canjs.com">2.3.27</a> </div> </div> </div> <div class="search-bar"> <p>   </p> </div> </div> <div class="bottom-left"> <div class="social-side-container"> <ul class="social-side"> <li> <a class="header-mobile github" href="https://github.com/canjs/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/github.png">Github</a> </li> <li> <a class="header-mobile twitter" href="https://twitter.com/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/twitter.png">Twitter</a> </li> </ul> <ul class="social-side"> <li> <a class="header-mobile" href="https://gitter.im/canjs/canjs" target="_blank">Chat</a> </li> <li> <a class="header-mobile" href="http://forums.donejs.com/c/canjs" target="_blank">Forum</a> </li> </ul> </div> <ul> <li class=" "> <a class="page" href="guides.html" title="Welcome to CanJS! These guides are here to help you develop and improve your relationship with CanJS. After all, picking a JavaScript framework is a commitment. We want CanJS to be the framework you marry. This page helps you know how advance through the different stages of this relationship:"> Guides </a> </li> <li class=" "> <a class="page" href="can-core.html" title="The best, most hardened and generally useful libraries in CanJS."> Core </a> </li> <li class=" "> <a class="page" href="can-ecosystem.html" title="Useful libraries that extend or add important features to the core collection."> Ecosystem </a> </li> <li class=" parent expanded"> <a class="page" href="can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection."> Infrastructure </a> <ul> <li class=" "> <a class="module" href="can-construct.html" title="Provides a way to easily use the power of prototypal inheritance without worrying about hooking up all the particulars yourself. Use can-construct.extend to create an inheritable constructor function of your own."> can-construct </a> </li> <li class=" "> <a class="module" href="can-control.html" title="Create organized, memory-leak free, rapidly performing, stateful controls with declarative event binding. Use Control to create UI controls like tabs, grids, and context menus, and organize them into higher-order business rules with can.route. It can serve as both a traditional view and a traditional controller."> can-control </a> </li> <li class=" "> <a class="module" href="can-event.html" title="Add event functionality into your objects. The canEvent object provides a number of methods for handling events in objects. This functionality is best used by mixing the canEvent object into an object or prototype. However, event listeners can still be used even on objects that don't include canEvent. All methods provided by canEvent assume that they are mixed into an object -- this should be the object dispatching the events."> can-event </a> </li> <li class=" "> <a class="module" href="can-event/async/async.html" title="Makes the event system asynchronous. WARNING: This is experimental technology."> can-event/async/async </a> </li> <li class=" "> <a class="module" href="can-event/batch/batch.html" title="Adds task batching abilities to event dispatching."> can-event/batch/batch </a> </li> <li class=" "> <a class="module" href="can-observation.html" title="Provides a mechanism to notify when an observable has been read and a way to observe those reads called within a given function."> can-observation </a> </li> <li class=" "> <a class="module" href="can-simple-map.html" title="A performant live-bound map."> can-simple-map </a> </li> <li class=" "> <a class="page" href="can-util.html" title="A set of utilities."> can-util </a> </li> <li class=" parent expanded"> <a class="module" href="can-view-callbacks.html" title="Registered callbacks for behaviors"> can-view-callbacks </a> <ul> <li> <span>types</span> <ul> <li class=" "> <a class="typedef" href="can-view-callbacks.attrData.html" title="The data provided to can-view-callbacks.attr."> attrData </a> </li> <li class=" "> <a class="typedef" href="can-view-callbacks.tagData.html" title="The data passed to can-view-callbacks.tag."> tagData </a> </li> </ul> </li> <li> <span>methods</span> <ul> <li class=" "> <a class="function" href="can-view-callbacks.attr.html" title="Register custom behavior for an attribute."> attr </a> </li> <li class="current parent expanded"> <a class="function" href="can-view-callbacks.tag.html" title=""> tag </a> </li> </ul> </li> </ul> </li> <li class=" "> <a class="module" href="can-view-live.html" title="Setup live-binding between the DOM and a compute manually."> can-view-live </a> </li> <li class=" "> <a class="module" href="can-view-model.html" title="Gets the ViewModel of an element."> can-view-model </a> </li> <li class=" "> <a class="module" href="can-view-nodelist.html" title="Adds nesting of text nodes can.view.nodeLists are used to make sure "directly nested" live-binding sections update content correctly. Consider the following template: <div> {{#if items.length}} Items: {{#items}} <label></label> {{/items}} {{/if}} </div> The {{#if}} and {{#items}} seconds are "directly nested" because they share the same <div> parent element. If {{#items}} changes the DOM by adding more <labels>, {{#if}} needs to know about the <labels> to remove them if {{#if}} is re-rendered. {{#if}} would be re-rendered, for example, if all items were removed."> can-view-nodelist </a> </li> <li class=" "> <a class="module" href="can-view-parser.html" title="Parse HTML and mustache tokens."> can-view-parser </a> </li> <li class=" "> <a class="module" href="can-view-scope.html" title="Create a lookup node for keys."> can-view-scope </a> </li> <li class=" "> <a class="module" href="can-view-target.html" title=""> can-view-target </a> </li> </ul> </li> <li class=" "> <a class="page" href="can-legacy.html" title="Former libraries that we still accept patches for, but are not under active development."> Legacy </a> </li> </ul> </div> </div> <div id="right" class="column"> <div class="top-right"> <div class="top-right-top"> <ul class="top-right-bitovi"> <li class="dropdown"> <a href="http://bitovi.com" class="bitovi icon-bits">Bitovi</a> <ul class="dropdown-menu"> <li><a href="http://bitovi.com">Bitovi.com</a></li> <li><a href="http://bitovi.com/blog/">Blog</a></li> <li><a href="http://bitovi.com/consulting/">Consulting</a></li> <li><a href="http://bitovi.com/training/">Training</a></li> <li><a href="http://bitovi.com/open-source/">Open Source</a></li> </ul> </li> </ul> <div class="brand"> <div class="logo"> <a href="../index.html" alt="CanJS"></a> </div> </div> <ul class="top-right-links"> <li> <a href="https://gitter.im/canjs/canjs">Chat</a> </li> <li> <a href="http://forums.donejs.com/c/canjs">Forum</a> </li> <li> <a class="github-button nav-social" href="https://github.com/canjs/canjs" data-count-href="/canjs/canjs/stargazers" data-count-api="/repos/canjs/canjs#stargazers_count">Star</a> </li> <li> <a href="https://twitter.com/canjs" class="twitter-follow-button nav-social" data-show-count="true" data-show-screen-name="false">Follow @canjs</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> </li> </ul> </div> <div class="breadcrumb"> <li><a href="../index.html">CanJS</a></li> / <li><a href="can-infrastructure.html">Infrastructure</a></li> / <li><a href="can-view-callbacks.html">can-view-callbacks</a></li> / <li><a href="can-view-callbacks.tag.html">tag</a></li> <li class="breadcrumb-dropdown">/ <a> On this page</a> <ul class="on-this-page"></ul> </li> <div class="nav-toggle" title="Back to top"></div> </div> </div> <div class="bottom-right"> <article> <section class="title"> <div class="page-type"> <h1>tag</h1> <div>function</div> </div> <section class="description"> </section> </section> <section class="on-this-page-table"> </section> <section class="title-footer"> <ul class="title-links">  <li><a href="//github.com/canjs/can-view-callbacks/tree/v3.0.1/docs/tag.md">source</a></li>   </ul> </section> <div class="signature"> <h2 class="signature-title"> <code>callbacks.tag(tagName, tagHandler(el, tagData))</code> </h2> <p>Registers the <code>tagHandler</code> callback when <code>tagName</code> is found in a template.</p> <pre><code class="language-js">var $ = require("jquery"); require("jquery-datepicker"); var canViewCallbacks = require("can-view-callbacks"); canViewCallbacks.tag("date-picker", function(el, tagData){ $(el).datePicker(); }); </code></pre> <div class="parameters"> <h3 class="parameters-title">Parameters</h3> <ol> <li><b>tagName</b> <code>{String}</code>: <p>A lower-case, hypenated or colon-seperated html tag. Example: <code>"my-widget"</code> or <code>"my:widget"</code>. It is considered a best-practice to have a hypen or colon in all custom-tag names.</p> </li> <li><b>tagHandler</b> <code>{function(el, tagData)}</code>: <p>Adds custom behavior to <code>el</code>. If <code>tagHandler</code> returns data, it is used to render <code>tagData.subtemplate</code> and the result is inserted as the childNodes of <code>el</code>.</p> </li> </ol> </div> </div> <section class="body"> <h2>Use</h2> <p><code>canViewCallbacks.tag</code> is a low-level way to add custom behavior to custom elements. Often, you want to do this with <a href="can-component.html" title="Create a custom element that can be used to manage widgets or application logic.">can-component</a>. However, <a href="can-view-callbacks.tag.html" title="">callbacks.tag</a> is useful for when <a href="can-component.html" title="Create a custom element that can be used to manage widgets or application logic.">can-component</a> might be considered overkill. For example, the following creates a <a href="http://api.jqueryui.com/datepicker/">jQueryUI DatePicker</a> everytime a <code><jqui-datepicker></code> element is found:</p> <pre><code>callbacks.tag("jqui-datepicker", function(el, tagData){ $(el).datepicker() }) </code></pre> <p>The <code>tagHandler</code>'s <a href="can-view-callbacks.tagData.html" title="The data passed to can-view-callbacks.tag.">tagData</a> argument is an object that contains the stache <a href="can-view-scope.html" title="Create a lookup node for keys.">Scope</a> and helper <a href="can-view-scope.Options.html" title="">Options</a> where <code>el</code> is found and a <a href="can-stache.renderer.html" title="A function returned by can-stache that renders a template into an html documentFragment.">subtemplate</a> that renders the contents of the template within the custom tag.</p> <h2>Getting values from the template</h2> <p><code>tagData.scope</code> can be used to read data from the template. For example, if I wanted the value of <code>"format"</code> within the current template, it could be read like:</p> <pre><code>callbacks.tag("jqui-datepicker", function(el, tagData){ $(el).datepicker({format: tagData.scope.get("format")}) }) var template = mustache("<jqui-datepicker></jqui-datepicker>") template({format: "mm/dd/yy"}) </code></pre> <p><code>tagData.options</code> contains the helpers and partials provided to the template. A helper function might need to be called to get the current value of format like:</p> <pre><code>callbacks.tag("jqui-datepicker", function(el, tagData){ $(el).datepicker({format: tagData.options.get("helpers.format")()}) }) var template = mustache("<jqui-datepicker></jqui-datepicker>") template({},{format: function(){ return "mm/dd/yy" }}) </code></pre> <h2>Responding to changing data</h2> <p>Often, data passed to a template is observable. If you use <a href="can-view-callbacks.tag.html" title="">tag</a>, you must listen and respond to chagnes yourself. Consider if format is property on a <code>settings</code> [can.Map] like:</p> <pre><code>var settings = new Map({ format: "mm/dd/yy" }) </code></pre> <p>You want to update the datepicker if <code>format</code> changes. The easiest way to do this is to use <a href="can-view-scope.prototype.compute.html" title="">Scope's compute</a> method which returns a get-set compute that is tied to a key value:</p> <pre><code>callbacks.tag("jqui-datepicker", function(el, tagData){ var formatCompute = tagData.scope.compute("format"), changeHandler = function(ev, newVal){ $(el).datepicker("option","format", newVal}); } formatCompute.bind("change",changeHandler) changeHandler({}, formatCompute()); ... }) var template = mustache("<jqui-datepicker/>") template(settings) </code></pre> <p>If you listen on something outside the tag, it's a good practice to stop listening when the element is <a href="can-util/dom/events/removed/removed.html" title="This event fires when the bound element is detached or destroyed.">removed</a> from the page:</p> <pre><code>domEvents.addEventListener.call( el, "removed", function onremove(){ compute.off("change", showOrHide); formatCompute.unbind("change",changeHandler) }); </code></pre> <h2>Subtemplate</h2> <p>If content is found within a custom tag like:</p> <pre><code>var template = stache( "<my-form>\ <input value="{{first}}"/>\ <input value="{{last}}"/>\ </my-form>") </code></pre> <p>A separate template function is compiled and passed as <code>tagData.subtemplate</code>. That subtemplate can be rendered with custom data and options. For example:</p> <pre><code>callbacks.tag("my-form", function(el, tagData){ var frag = tagData.subtemplate({ first: "Justin" }, tagData.options) $(el).html( frag ) }) template({ last: "Meyer" }) </code></pre> <p>In this case, the sub-template will not get a value for <code>last</code>. To include the original data in the subtemplate's scope, <a href="can-view-scope.prototype.add.html" title="">add</a> to the old scope like:</p> <pre><code>callbacks.tag("my-form", function(el, tagData){ var frag = tagData.subtemplate( tagData.scope.add({ first: "Justin" }), tagData.options) $(el).html( frag ) }) template({ last: "Meyer" }) </code></pre> </section> <script type="text/javascript"> var docObject = {"src":{"path":"node_modules/can-view-callbacks/docs/tag.md"},"description":"\n","title":"tag","name":"can-view-callbacks.tag","type":"function","parent":"can-view-callbacks/methods","signatures":[{"code":"callbacks.tag(tagName, tagHandler(el, tagData))","description":"\n\nRegisters the `tagHandler` callback when `tagName` is found\nin a template.\n\n```js\nvar $ = require(\"jquery\");\nrequire(\"jquery-datepicker\");\nvar canViewCallbacks = require(\"can-view-callbacks\");\n\ncanViewCallbacks.tag(\"date-picker\", function(el, tagData){\n\t$(el).datePicker();\n});\n```\n","params":[{"types":[{"type":"String"}],"name":"tagName","description":"A lower-case, hypenated or colon-seperated html\ntag. Example: `\"my-widget\"` or `\"my:widget\"`. It is considered a best-practice to\nhave a hypen or colon in all custom-tag names.\n"},{"types":[{"type":"function","returns":{"types":[{"type":"can.view.Scope"}]},"params":[{"types":[{"type":"HTMLElement"}],"name":"el"},{"types":[{"type":"can.view.tagData"}],"name":"tagData"}]}],"name":"tagHandler","description":"\n\nAdds custom behavior to `el`. If `tagHandler` returns data, it is used to\nrender `tagData.subtemplate` and the result is inserted as the childNodes of `el`.\n"}],"release":"2.1"}],"_curParam":{"types":[{"type":"function","returns":{"types":[{"type":"can.view.Scope"}]},"params":[{"types":[{"type":"HTMLElement"}],"name":"el"},{"types":[{"type":"can.view.tagData"}],"name":"tagData"}]}],"name":"tagHandler","description":"\n\nAdds custom behavior to `el`. If `tagHandler` returns data, it is used to\nrender `tagData.subtemplate` and the result is inserted as the childNodes of `el`.\n"},"comment":" ","pathToRoot":".."}; </script> </article> <footer><p>CanJS is part of <a href="http://donejs.com" target="_blank">DoneJS</a>. Created and maintained by the core <a href="https://donejs.com/About.html#section=section_Team" target="_blank">DoneJS team</a> and <a href="http://bitovi.com" target="_blank">Bitovi</a>. <strong>Currently 3.0.0.</strong></p></footer> </div> </div> </div> <script> steal = { instantiated: { "bundles/bit-docs-site/static.css!$css" : null } }; </script> <script type='text/javascript' data-main="bit-docs-site/static" src="./static/node_modules/steal/steal.production.js"></script> <script async defer src="https://buttons.github.io/buttons.js"></script> </body> </html>