{"action":"created","comment":{"url":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/comments/22853018","id":22853018,"diff_hunk":"@@ -0,0 +1,588 @@\n+# delite - creating custom components\n+\n+## delite background\n+`delite` is a new JavaScript library born out of the [Dojo Toolkit Dijit framework](http://dojotoolkit.org/reference-guide/1.10/dijit).\n+This isn't a replacement per se but a repository to be used as the core building blocks for leveraging current and future standards\n+in HTML, CSS & JavaScript to build reusable Web Components.\n+\n+It can be used on its own but more likely used with other projects either from the [ibm-js repositories](https://github.com/ibm-js)\n+or other repositories.\n+\n+More information can be found on the [delite website](http://ibm-js.github.io/delite/) explaining the standards this library aims to conform to.\n+\n+## Tutorial details\n+In this tutorial you'll learn how to create your own custom elements, learn how to register them, learn how to use templates\n+and learn how to theme them. It's a beginner tutorial so we won't be delving too deep into what `delite` provides (yet!!!).\n+\n+\n+## Getting started\n+To quickly get started, we're using [https://github.com/ibm-js/generator-delite-element](https://github.com/ibm-js/generator-delite-element)\n+to install the required dependencies and create a basic scaffold.\n+\n+Install the `generator-delite-element` globally (or update it if necessary).\n+\n+    npm install -g generator-delite-element\n+\n+##Templates\n+`delite` provides first class support for templates. We wouldn't expect to programmatically create DOM nodes & this is where\n+`delite` comes into it's own; out of the box `delite` supports templating using a built in implementation of [Handlebars](http://handlebarsjs.com/).\n+\n+Note there are some limitations using the `delite/handlebars!` plugin for templating, namely it doesn't support iterators or conditionals.\n+However in many cases this isn't a limiting factor. Support for this will be explained in a later more advanced tutorial when we discuss\n+[Liaison](https://github.com/ibm-js/liaison). The handlebars template implementation `delite` uses is primarily focused on performance.\n+\n+Let's try create a 'real life' widget, for example a blogging widget.\n+\n+### create the scaffold\n+We'll create a new `delite` custom element using Yeoman.\n+\n+From the command line create a new directory somewhere (named `blogging-package`) and change directory to it using the commands:\n+\n+    mkdir -p blogging-package\n+    cd blogging-package\n+\n+Run Yeoman to create our scaffold.\n+\n+    yo delite-element\n+\n+You'll be prompted to enter the widget package name and the name of the custom widget element. Set the following choices shown in brackets below.\n+\n+    ? What is the name of your delite widget element package? (blogging-package)\n+    ? What do you want to call your delite widget element (must contain a dash)? (blog-post)\n+    ? Would you like your delite element to be built on a template? (Y)\n+    ? Would you like your delite element to providing theming capabilities? (N)\n+    ? Will your delite element require string internationalization? (N)\n+    ? Will your delite element require pointer management? (N)\n+    ? Do you want to use build version of delite package (instead of source version)? (N)\n+\n+### What's been generated\n+Yeoman created the following (as shown in the console output):\n+\n+- `./BlogPost.js` - __this is our widget module__\n+- `./BlogPost/css/BlogPost.css` - __this is our widget css__\n+- `./BlogPost/BlogPost.html` - __this is our widget template__\n+- `./samples/BlogPost.html` - __this is a sample how to use our new widget__\n+\n+You can view the sample generated HTML `./samples/BlogPost.html` in a browser to see what's been created.\n+\n+\n+## Creating a custom element\n+Viewing the `./samples/BlogPost.html` example HTML we can see we've (partly) created the custom element declaratively in markup via:\n+```html\n+<blog-post id=\"element\" value=\"The Title\"></blog-post>\n+```\n+For those who used the Dojo Toolkit Dijit framework previously, an important conceptual difference in `delite` is that the widget is the DOM node.\n+Dijit widgets instead had a property which referenced the DOM node.\n+\n+For example if you open your browser developer tools and in the console enter `myvar = document.getElementById('element')` and then explore\n+the properties on that variable `myvar`, you'll see it's just a regular HTML element;\n+if you're more inquisitive you might be able to see there are extra properties/methods on this element which is what the `delite` framework is providing.\n+\n+###Registering\n+\n+The `<blog-post>` element doesn't constitute a custom element on its own; it first needs to go through a registration process which is achieved using\n+the `delite/register` module. This is analogous to the HTML specification for registering custom elements\n+i.e. `document.registerElement('blog-post');`\n+\n+If we look at the custom element module `./BlogPost.js` we see that we register the custom element tag via the `return register(....)` method:\n+\n+```js\n+\n+define([\n+\t\"delite/register\",\n+\t\"delite/Widget\",\n+\t\"delite/handlebars!./BlogPost/BlogPost.html\",\n+    \"requirejs-dplugins/css!./BlogPost/css/BlogPost.css\"\n+], function (register, Widget, template) {\n+\treturn register(\"blog-post\", [HTMLElement, Widget], {\n+\t\tbaseClass: \"blog-post\",\n+\t\tvalue: \"\",\n+\t\ttemplate: template\n+\t});\n+});\n+\n+```\n+\n+\n+This is an important concept which sometimes isn't clear at a first glance. You can add any non-standard tag to an HTML page and the browser HTML parser\n+will not complain; this is because these elements will be defined as a native\n+[`HTMLUnknownElement`](http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#htmlunknownelement).\n+To create a custom element it must be **upgraded** first; this is what `delite/register` does. `delite/register` supports browsers who natively\n+support `document.registerElement` and those who don't.\n+\n+The registration process above using `delite/register`, creates a custom element by registering the tag name `\"blog-post\"` as the first\n+argument and then inheriting (prototyping) the `HTMLElement` native element (as well as the `\"delite/Widget\"` module).\n+\n+Elements which inherit from `HTMLElement`\n+using [valid custom element names](http://www.w3.org/TR/2013/WD-custom-elements-20130514/#dfn-custom-element-name) are custom elements.\n+The most basic requirement for the tag name is it **MUST** contain a dash **(-)**.\n+\n+In case there's any confusion, the module name created `BlogPost` bears no relation to the custom element name i.e. `blog-post`, the module `BlogPost`\n+registers the custom element tag name `blog-post`.\n+\n+###Declarative creation of custom elements\n+If we view the generated sample `./samples/BlogPost.html`, we see the following JavaScript:\n+\n+```js\n+require([\"delite/register\", \"blogging-package/BlogPost\"], function (register) {\n+    register.parse();\n+});\n+```\n+\n+Declarative widgets (those created via markup in the page) need to be parsed in order to kick off the lifecycle of creating the widget.","path":"beginner.md","position":132,"original_position":132,"commit_id":"9e4044d55b84365764180a0173a02ab7ce4f8e2d","original_commit_id":"9e4044d55b84365764180a0173a02ab7ce4f8e2d","user":{"login":"cjolif","id":623171,"avatar_url":"https://avatars.githubusercontent.com/u/623171?v=3","gravatar_id":"","url":"https://api.github.com/users/cjolif","html_url":"https://github.com/cjolif","followers_url":"https://api.github.com/users/cjolif/followers","following_url":"https://api.github.com/users/cjolif/following{/other_user}","gists_url":"https://api.github.com/users/cjolif/gists{/gist_id}","starred_url":"https://api.github.com/users/cjolif/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cjolif/subscriptions","organizations_url":"https://api.github.com/users/cjolif/orgs","repos_url":"https://api.github.com/users/cjolif/repos","events_url":"https://api.github.com/users/cjolif/events{/privacy}","received_events_url":"https://api.github.com/users/cjolif/received_events","type":"User","site_admin":false},"body":"widget instances? (i.e. the widget themselves are not declarative or programatic just their instanciation?)","created_at":"2015-01-13T10:14:03Z","updated_at":"2015-01-13T10:14:03Z","html_url":"https://github.com/ibm-js/delite-tutorial/pull/1#discussion_r22853018","pull_request_url":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/1","_links":{"self":{"href":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/comments/22853018"},"html":{"href":"https://github.com/ibm-js/delite-tutorial/pull/1#discussion_r22853018"},"pull_request":{"href":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/1"}}},"pull_request":{"url":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/1","id":26671014,"html_url":"https://github.com/ibm-js/delite-tutorial/pull/1","diff_url":"https://github.com/ibm-js/delite-tutorial/pull/1.diff","patch_url":"https://github.com/ibm-js/delite-tutorial/pull/1.patch","issue_url":"https://api.github.com/repos/ibm-js/delite-tutorial/issues/1","number":1,"state":"open","locked":false,"title":"Initial commit","user":{"login":"lbod","id":733371,"avatar_url":"https://avatars.githubusercontent.com/u/733371?v=3","gravatar_id":"","url":"https://api.github.com/users/lbod","html_url":"https://github.com/lbod","followers_url":"https://api.github.com/users/lbod/followers","following_url":"https://api.github.com/users/lbod/following{/other_user}","gists_url":"https://api.github.com/users/lbod/gists{/gist_id}","starred_url":"https://api.github.com/users/lbod/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lbod/subscriptions","organizations_url":"https://api.github.com/users/lbod/orgs","repos_url":"https://api.github.com/users/lbod/repos","events_url":"https://api.github.com/users/lbod/events{/privacy}","received_events_url":"https://api.github.com/users/lbod/received_events","type":"User","site_admin":false},"body":"I couldn't rebase to a repo that wasn't already forked (this being a new repo that existed before mines)\r\n\r\nIt appears you can't do this so I copy/pasted https://github.com/lbod/delite-tutorial-old to this fork.","created_at":"2014-12-30T02:05:33Z","updated_at":"2015-01-13T10:14:03Z","closed_at":null,"merged_at":null,"merge_commit_sha":"64856519b426c89dfc343191bdcefc13fd4589d0","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/1/commits","review_comments_url":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/1/comments","review_comment_url":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/comments/{number}","comments_url":"https://api.github.com/repos/ibm-js/delite-tutorial/issues/1/comments","statuses_url":"https://api.github.com/repos/ibm-js/delite-tutorial/statuses/9e4044d55b84365764180a0173a02ab7ce4f8e2d","head":{"label":"lbod:master","ref":"master","sha":"9e4044d55b84365764180a0173a02ab7ce4f8e2d","user":{"login":"lbod","id":733371,"avatar_url":"https://avatars.githubusercontent.com/u/733371?v=3","gravatar_id":"","url":"https://api.github.com/users/lbod","html_url":"https://github.com/lbod","followers_url":"https://api.github.com/users/lbod/followers","following_url":"https://api.github.com/users/lbod/following{/other_user}","gists_url":"https://api.github.com/users/lbod/gists{/gist_id}","starred_url":"https://api.github.com/users/lbod/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lbod/subscriptions","organizations_url":"https://api.github.com/users/lbod/orgs","repos_url":"https://api.github.com/users/lbod/repos","events_url":"https://api.github.com/users/lbod/events{/privacy}","received_events_url":"https://api.github.com/users/lbod/received_events","type":"User","site_admin":false},"repo":{"id":28612965,"name":"delite-tutorial","full_name":"lbod/delite-tutorial","owner":{"login":"lbod","id":733371,"avatar_url":"https://avatars.githubusercontent.com/u/733371?v=3","gravatar_id":"","url":"https://api.github.com/users/lbod","html_url":"https://github.com/lbod","followers_url":"https://api.github.com/users/lbod/followers","following_url":"https://api.github.com/users/lbod/following{/other_user}","gists_url":"https://api.github.com/users/lbod/gists{/gist_id}","starred_url":"https://api.github.com/users/lbod/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lbod/subscriptions","organizations_url":"https://api.github.com/users/lbod/orgs","repos_url":"https://api.github.com/users/lbod/repos","events_url":"https://api.github.com/users/lbod/events{/privacy}","received_events_url":"https://api.github.com/users/lbod/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/lbod/delite-tutorial","description":"Tutorial for delite","fork":true,"url":"https://api.github.com/repos/lbod/delite-tutorial","forks_url":"https://api.github.com/repos/lbod/delite-tutorial/forks","keys_url":"https://api.github.com/repos/lbod/delite-tutorial/keys{/key_id}","collaborators_url":"https://api.github.com/repos/lbod/delite-tutorial/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/lbod/delite-tutorial/teams","hooks_url":"https://api.github.com/repos/lbod/delite-tutorial/hooks","issue_events_url":"https://api.github.com/repos/lbod/delite-tutorial/issues/events{/number}","events_url":"https://api.github.com/repos/lbod/delite-tutorial/events","assignees_url":"https://api.github.com/repos/lbod/delite-tutorial/assignees{/user}","branches_url":"https://api.github.com/repos/lbod/delite-tutorial/branches{/branch}","tags_url":"https://api.github.com/repos/lbod/delite-tutorial/tags","blobs_url":"https://api.github.com/repos/lbod/delite-tutorial/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/lbod/delite-tutorial/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/lbod/delite-tutorial/git/refs{/sha}","trees_url":"https://api.github.com/repos/lbod/delite-tutorial/git/trees{/sha}","statuses_url":"https://api.github.com/repos/lbod/delite-tutorial/statuses/{sha}","languages_url":"https://api.github.com/repos/lbod/delite-tutorial/languages","stargazers_url":"https://api.github.com/repos/lbod/delite-tutorial/stargazers","contributors_url":"https://api.github.com/repos/lbod/delite-tutorial/contributors","subscribers_url":"https://api.github.com/repos/lbod/delite-tutorial/subscribers","subscription_url":"https://api.github.com/repos/lbod/delite-tutorial/subscription","commits_url":"https://api.github.com/repos/lbod/delite-tutorial/commits{/sha}","git_commits_url":"https://api.github.com/repos/lbod/delite-tutorial/git/commits{/sha}","comments_url":"https://api.github.com/repos/lbod/delite-tutorial/comments{/number}","issue_comment_url":"https://api.github.com/repos/lbod/delite-tutorial/issues/comments/{number}","contents_url":"https://api.github.com/repos/lbod/delite-tutorial/contents/{+path}","compare_url":"https://api.github.com/repos/lbod/delite-tutorial/compare/{base}...{head}","merges_url":"https://api.github.com/repos/lbod/delite-tutorial/merges","archive_url":"https://api.github.com/repos/lbod/delite-tutorial/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/lbod/delite-tutorial/downloads","issues_url":"https://api.github.com/repos/lbod/delite-tutorial/issues{/number}","pulls_url":"https://api.github.com/repos/lbod/delite-tutorial/pulls{/number}","milestones_url":"https://api.github.com/repos/lbod/delite-tutorial/milestones{/number}","notifications_url":"https://api.github.com/repos/lbod/delite-tutorial/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/lbod/delite-tutorial/labels{/name}","releases_url":"https://api.github.com/repos/lbod/delite-tutorial/releases{/id}","created_at":"2014-12-30T01:28:47Z","updated_at":"2014-12-26T21:49:40Z","pushed_at":"2015-01-12T23:35:50Z","git_url":"git://github.com/lbod/delite-tutorial.git","ssh_url":"git@github.com:lbod/delite-tutorial.git","clone_url":"https://github.com/lbod/delite-tutorial.git","svn_url":"https://github.com/lbod/delite-tutorial","homepage":null,"size":765,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"ibm-js:master","ref":"master","sha":"0855ae53a023e99673030cbd43991f64f69be869","user":{"login":"ibm-js","id":3503805,"avatar_url":"https://avatars.githubusercontent.com/u/3503805?v=3","gravatar_id":"","url":"https://api.github.com/users/ibm-js","html_url":"https://github.com/ibm-js","followers_url":"https://api.github.com/users/ibm-js/followers","following_url":"https://api.github.com/users/ibm-js/following{/other_user}","gists_url":"https://api.github.com/users/ibm-js/gists{/gist_id}","starred_url":"https://api.github.com/users/ibm-js/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ibm-js/subscriptions","organizations_url":"https://api.github.com/users/ibm-js/orgs","repos_url":"https://api.github.com/users/ibm-js/repos","events_url":"https://api.github.com/users/ibm-js/events{/privacy}","received_events_url":"https://api.github.com/users/ibm-js/received_events","type":"Organization","site_admin":false},"repo":{"id":28522030,"name":"delite-tutorial","full_name":"ibm-js/delite-tutorial","owner":{"login":"ibm-js","id":3503805,"avatar_url":"https://avatars.githubusercontent.com/u/3503805?v=3","gravatar_id":"","url":"https://api.github.com/users/ibm-js","html_url":"https://github.com/ibm-js","followers_url":"https://api.github.com/users/ibm-js/followers","following_url":"https://api.github.com/users/ibm-js/following{/other_user}","gists_url":"https://api.github.com/users/ibm-js/gists{/gist_id}","starred_url":"https://api.github.com/users/ibm-js/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ibm-js/subscriptions","organizations_url":"https://api.github.com/users/ibm-js/orgs","repos_url":"https://api.github.com/users/ibm-js/repos","events_url":"https://api.github.com/users/ibm-js/events{/privacy}","received_events_url":"https://api.github.com/users/ibm-js/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ibm-js/delite-tutorial","description":"Tutorial for delite","fork":false,"url":"https://api.github.com/repos/ibm-js/delite-tutorial","forks_url":"https://api.github.com/repos/ibm-js/delite-tutorial/forks","keys_url":"https://api.github.com/repos/ibm-js/delite-tutorial/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ibm-js/delite-tutorial/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ibm-js/delite-tutorial/teams","hooks_url":"https://api.github.com/repos/ibm-js/delite-tutorial/hooks","issue_events_url":"https://api.github.com/repos/ibm-js/delite-tutorial/issues/events{/number}","events_url":"https://api.github.com/repos/ibm-js/delite-tutorial/events","assignees_url":"https://api.github.com/repos/ibm-js/delite-tutorial/assignees{/user}","branches_url":"https://api.github.com/repos/ibm-js/delite-tutorial/branches{/branch}","tags_url":"https://api.github.com/repos/ibm-js/delite-tutorial/tags","blobs_url":"https://api.github.com/repos/ibm-js/delite-tutorial/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ibm-js/delite-tutorial/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ibm-js/delite-tutorial/git/refs{/sha}","trees_url":"https://api.github.com/repos/ibm-js/delite-tutorial/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ibm-js/delite-tutorial/statuses/{sha}","languages_url":"https://api.github.com/repos/ibm-js/delite-tutorial/languages","stargazers_url":"https://api.github.com/repos/ibm-js/delite-tutorial/stargazers","contributors_url":"https://api.github.com/repos/ibm-js/delite-tutorial/contributors","subscribers_url":"https://api.github.com/repos/ibm-js/delite-tutorial/subscribers","subscription_url":"https://api.github.com/repos/ibm-js/delite-tutorial/subscription","commits_url":"https://api.github.com/repos/ibm-js/delite-tutorial/commits{/sha}","git_commits_url":"https://api.github.com/repos/ibm-js/delite-tutorial/git/commits{/sha}","comments_url":"https://api.github.com/repos/ibm-js/delite-tutorial/comments{/number}","issue_comment_url":"https://api.github.com/repos/ibm-js/delite-tutorial/issues/comments/{number}","contents_url":"https://api.github.com/repos/ibm-js/delite-tutorial/contents/{+path}","compare_url":"https://api.github.com/repos/ibm-js/delite-tutorial/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ibm-js/delite-tutorial/merges","archive_url":"https://api.github.com/repos/ibm-js/delite-tutorial/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ibm-js/delite-tutorial/downloads","issues_url":"https://api.github.com/repos/ibm-js/delite-tutorial/issues{/number}","pulls_url":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls{/number}","milestones_url":"https://api.github.com/repos/ibm-js/delite-tutorial/milestones{/number}","notifications_url":"https://api.github.com/repos/ibm-js/delite-tutorial/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ibm-js/delite-tutorial/labels{/name}","releases_url":"https://api.github.com/repos/ibm-js/delite-tutorial/releases{/id}","created_at":"2014-12-26T21:49:40Z","updated_at":"2014-12-26T21:49:40Z","pushed_at":"2014-12-26T21:49:40Z","git_url":"git://github.com/ibm-js/delite-tutorial.git","ssh_url":"git@github.com:ibm-js/delite-tutorial.git","clone_url":"https://github.com/ibm-js/delite-tutorial.git","svn_url":"https://github.com/ibm-js/delite-tutorial","homepage":null,"size":154,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":1,"forks":1,"open_issues":1,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/1"},"html":{"href":"https://github.com/ibm-js/delite-tutorial/pull/1"},"issue":{"href":"https://api.github.com/repos/ibm-js/delite-tutorial/issues/1"},"comments":{"href":"https://api.github.com/repos/ibm-js/delite-tutorial/issues/1/comments"},"review_comments":{"href":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/1/comments"},"review_comment":{"href":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/ibm-js/delite-tutorial/pulls/1/commits"},"statuses":{"href":"https://api.github.com/repos/ibm-js/delite-tutorial/statuses/9e4044d55b84365764180a0173a02ab7ce4f8e2d"}}}}