{"action":"created","comment":{"url":"https://api.github.com/repos/ScottLogic/d3fc/pulls/comments/52026549","id":52026549,"diff_hunk":"@@ -0,0 +1,188 @@\n+---\n+layout: component\n+namespace: Introduction\n+title: Building A Chart\n+externals:\n+  building-a-chart-complete-js: building-a-chart-complete.js\n+  building-a-chart-complete-html: building-a-chart-complete.html\n+  building-a-chart-complete-css: building-a-chart-complete.css\n+  creating-some-data-html: creating-some-data.html\n+  creating-some-data-js: creating-some-data.js\n+  rendering-a-series-html: rendering-a-series.html\n+  rendering-a-series-js: rendering-a-series.js\n+  cartesian-chart-html: cartesian-chart.html\n+  cartesian-chart-js: cartesian-chart.js\n+  cartesian-chart-extent-html: cartesian-chart-extent.html\n+  cartesian-chart-extent-js: cartesian-chart-extent.js\n+  tidy-chart-html: tidy-chart.html\n+  tidy-chart-js: tidy-chart.js\n+  adding-annotations-html: adding-annotations.html\n+  adding-annotations-js: adding-annotations.js\n+---\n+\n+This brief tutorial introduces the core concepts behind d3fc, via the process of building a chart. You'll find out why we created d3fc and what makes it different from the numerous other charting libraries out there!\n+\n+Here's the chart you're going to be building:\n+\n+<style>\n+{{{building-a-chart-complete-css}}}\n+</style>\n+\n+{{{ dynamic-include 'codepen' html=\"building-a-chart-complete-html\" js=\"building-a-chart-complete-js\"}}}\n+{{{ building-a-chart-complete-html }}}\n+\n+It's a pretty conventional 'sales dashboard' chart, in this case showing some fictional monthly sales data, with a couple of lines indicating targets.\n+\n+But before we start putting this chart together, let's look at charting libraries in a more general sense ...\n+\n+## Charting APIs\n+\n+Charts are complex UI components, they are designed to be highly flexible in order to support a wide range of different chart types, styles and configurations. However, this flexibility is most often presented as a complex API of hundreds of classes and thousands of methods. Searching for the correct configuration that will yield the result you are after is a challenge, and you are heavily reliant on the designer of the chart having considered your use-case to make that configuration possible.\n+\n+D3 offers a fresh perspective, offering a different way to create charts and visualisations. It is an expressive, yet low-level tool, that if wielded correctly, can be used to create practically any visual representation you like.\n+\n+There are a number of charting libraries built with D3, however these invariably hide the underlying power of D3 behind the same-old complex and confusing APIs.\n+\n+With d3fc our aim is to enhance D3 by providing a suite of powerful charting components that make it easy for you to assemble exactly the chart you want. These components 'speak the language' of D3, supporting selections and datajoins. Furthermore, using the decorate pattern, you can enhance and manipulate the way in which they are rendered.\n+\n+With d3fc components you can quickly assemble bespoke charts, without hiding the power of D3.\n+\n+## Creating the data\n+\n+Typically chart data will be supplied by some external source, in JSON or CSV format. For the purposes of this example we'll just generate some random data. d3fc has a number of `data` utilities, including components that help construct realistic ransom data. For this example we'll use the [random walk component](/components/data/walk.html) to generate 12 datapoints, mapping them to create datapoints with `sales` and `month` properties:\n+\n+```js\n+{{{creating-some-data-js}}}\n+```\n+\n+Here's the resulting data:\n+\n+{{{ dynamic-include 'codepen' html=\"creating-some-data-html\" js=\"creating-some-data-js\"}}}\n+{{{ creating-some-data-html }}}\n+{{{ dynamic-include 'javascript' js=\"creating-some-data-js\" }}}\n+\n+## Rendering the data\n+\n+The sales data is rendered as a bar chart. With D3 this typically involves rendering paths or rectangles and doing a bit of maths to locate each bar correctly, as illustrated in [Mike Bostock's excellent tutorial](http://bost.ocks.org/mike/bar/).\n+\n+d3fc has a [bar series component](/components/series/bar.html) (among others) that makes it much easier to render your data. To render the data, we create a bar series component and supply it with suitable D3 scales, configure the `xValue` and `yValue` accessors (which the component uses to extract the x and y values from the datapoints).\n+\n+The bar series is a regular D3 component, and is rendered via the `call` method on a D3 selection:\n+\n+```js\n+{{{ codeblock rendering-a-series-js }}}\n+```\n+\n+This renders as follows:\n+\n+{{{ dynamic-include 'codepen' html=\"rendering-a-series-html\" js=\"rendering-a-series-js\"}}}\n+{{{ rendering-a-series-html }}}\n+{{{ dynamic-include 'javascript' js=\"rendering-a-series-js\" }}}\n+\n+At this point you might like to read more about the [D3 component pattern](http://bost.ocks.org/mike/chart/) that we follow with d3fc.\n+\n+I'll forgive you if you are not too impressed with the above example. So far you've got a bar series, but no axes or labels, yet the example involves quite a bit of code.\n+\n+The reason for this is that the bar series component is relatively low-level component, it renders a series and nothing more. (It's actually not the lowest level of component, the bar series uses the d3fc bar SVG component). In order to quickly assemble a chart you need to make use of a more high-level component ... a chart.\n+\n+## Cartesian chart\n+\n+The cartesian chart component does a number of things, it measures its container in order to fill it, setting a suitable range on the scales that you supply (it's still your job to set the domain on each). The chart renders a pair of axes and, optionally, other cosmetic features such as chart and axis labels.\n+\n+You can render a series within the chart by setting it as the `plotArea`. The chart sets the x and y scales on the component you supply.\n+\n+Here's the complete example:\n+\n+```js\n+{{{ codeblock cartesian-chart-js }}}\n+```\n+\n+This renders a more complete chart:\n+\n+{{{ dynamic-include 'codepen' html=\"cartesian-chart-html\" js=\"cartesian-chart-js\"}}}\n+{{{ cartesian-chart-html }}}\n+\n+{{{ dynamic-include 'javascript' js=\"cartesian-chart-js\" }}}\n+\n+## Setting the axis domain","path":"site/src/components/introduction/building-a-chart.md","position":107,"original_position":107,"commit_id":"de68bbedcc068e3a213beaa2c542a7268a3a1d39","original_commit_id":"de68bbedcc068e3a213beaa2c542a7268a3a1d39","user":{"login":"jleft","id":2017615,"avatar_url":"https://avatars.githubusercontent.com/u/2017615?v=3","gravatar_id":"","url":"https://api.github.com/users/jleft","html_url":"https://github.com/jleft","followers_url":"https://api.github.com/users/jleft/followers","following_url":"https://api.github.com/users/jleft/following{/other_user}","gists_url":"https://api.github.com/users/jleft/gists{/gist_id}","starred_url":"https://api.github.com/users/jleft/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jleft/subscriptions","organizations_url":"https://api.github.com/users/jleft/orgs","repos_url":"https://api.github.com/users/jleft/repos","events_url":"https://api.github.com/users/jleft/events{/privacy}","received_events_url":"https://api.github.com/users/jleft/received_events","type":"User","site_admin":false},"body":"Just an idea and a bit nit-picky (sorry!) but this only covers the y-domain, this could be expanded to cover the x-domain too?\r\n\r\nEarlier, in the bar series and Cartesian chart sections, the x-domain is set like this:\r\n\r\n```js\r\ndata.map(function(d) { return d.month; })\r\n```\r\n\r\nThis could be changed to:\r\n\r\n\r\n```js\r\n['Jan', 'Feb', /* etc. */]\r\n```\r\n\r\nI quite like it when examples do this, as it's immediately obvious exactly what the values are and the focus can be on understanding how the components work and not what the data is.\r\n\r\nThen in this section it could explain how to be a bit more intelligent about it, using `data.map`?","created_at":"2016-02-05T15:12:03Z","updated_at":"2016-02-05T15:12:03Z","html_url":"https://github.com/ScottLogic/d3fc/pull/867#discussion_r52026549","pull_request_url":"https://api.github.com/repos/ScottLogic/d3fc/pulls/867","_links":{"self":{"href":"https://api.github.com/repos/ScottLogic/d3fc/pulls/comments/52026549"},"html":{"href":"https://github.com/ScottLogic/d3fc/pull/867#discussion_r52026549"},"pull_request":{"href":"https://api.github.com/repos/ScottLogic/d3fc/pulls/867"}}},"pull_request":{"url":"https://api.github.com/repos/ScottLogic/d3fc/pulls/867","id":58356760,"html_url":"https://github.com/ScottLogic/d3fc/pull/867","diff_url":"https://github.com/ScottLogic/d3fc/pull/867.diff","patch_url":"https://github.com/ScottLogic/d3fc/pull/867.patch","issue_url":"https://api.github.com/repos/ScottLogic/d3fc/issues/867","number":867,"state":"open","locked":false,"title":"Building a chart","user":{"login":"ColinEberhardt","id":1098110,"avatar_url":"https://avatars.githubusercontent.com/u/1098110?v=3","gravatar_id":"","url":"https://api.github.com/users/ColinEberhardt","html_url":"https://github.com/ColinEberhardt","followers_url":"https://api.github.com/users/ColinEberhardt/followers","following_url":"https://api.github.com/users/ColinEberhardt/following{/other_user}","gists_url":"https://api.github.com/users/ColinEberhardt/gists{/gist_id}","starred_url":"https://api.github.com/users/ColinEberhardt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ColinEberhardt/subscriptions","organizations_url":"https://api.github.com/users/ColinEberhardt/orgs","repos_url":"https://api.github.com/users/ColinEberhardt/repos","events_url":"https://api.github.com/users/ColinEberhardt/events{/privacy}","received_events_url":"https://api.github.com/users/ColinEberhardt/received_events","type":"User","site_admin":false},"body":"A much more in-depth tutorial on how to build a chart with d3fc","created_at":"2016-02-04T22:05:56Z","updated_at":"2016-02-05T15:12:03Z","closed_at":null,"merged_at":null,"merge_commit_sha":"09279b75f396957e8e252157ecfd2edbb07d3938","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/ScottLogic/d3fc/pulls/867/commits","review_comments_url":"https://api.github.com/repos/ScottLogic/d3fc/pulls/867/comments","review_comment_url":"https://api.github.com/repos/ScottLogic/d3fc/pulls/comments{/number}","comments_url":"https://api.github.com/repos/ScottLogic/d3fc/issues/867/comments","statuses_url":"https://api.github.com/repos/ScottLogic/d3fc/statuses/de68bbedcc068e3a213beaa2c542a7268a3a1d39","head":{"label":"ColinEberhardt:building-a-chart","ref":"building-a-chart","sha":"de68bbedcc068e3a213beaa2c542a7268a3a1d39","user":{"login":"ColinEberhardt","id":1098110,"avatar_url":"https://avatars.githubusercontent.com/u/1098110?v=3","gravatar_id":"","url":"https://api.github.com/users/ColinEberhardt","html_url":"https://github.com/ColinEberhardt","followers_url":"https://api.github.com/users/ColinEberhardt/followers","following_url":"https://api.github.com/users/ColinEberhardt/following{/other_user}","gists_url":"https://api.github.com/users/ColinEberhardt/gists{/gist_id}","starred_url":"https://api.github.com/users/ColinEberhardt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ColinEberhardt/subscriptions","organizations_url":"https://api.github.com/users/ColinEberhardt/orgs","repos_url":"https://api.github.com/users/ColinEberhardt/repos","events_url":"https://api.github.com/users/ColinEberhardt/events{/privacy}","received_events_url":"https://api.github.com/users/ColinEberhardt/received_events","type":"User","site_admin":false},"repo":{"id":26486000,"name":"d3-financial-components","full_name":"ColinEberhardt/d3-financial-components","owner":{"login":"ColinEberhardt","id":1098110,"avatar_url":"https://avatars.githubusercontent.com/u/1098110?v=3","gravatar_id":"","url":"https://api.github.com/users/ColinEberhardt","html_url":"https://github.com/ColinEberhardt","followers_url":"https://api.github.com/users/ColinEberhardt/followers","following_url":"https://api.github.com/users/ColinEberhardt/following{/other_user}","gists_url":"https://api.github.com/users/ColinEberhardt/gists{/gist_id}","starred_url":"https://api.github.com/users/ColinEberhardt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ColinEberhardt/subscriptions","organizations_url":"https://api.github.com/users/ColinEberhardt/orgs","repos_url":"https://api.github.com/users/ColinEberhardt/repos","events_url":"https://api.github.com/users/ColinEberhardt/events{/privacy}","received_events_url":"https://api.github.com/users/ColinEberhardt/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/ColinEberhardt/d3-financial-components","description":"A set of re-useable components for building financial charts with D3","fork":true,"url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components","forks_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/forks","keys_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/teams","hooks_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/hooks","issue_events_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/issues/events{/number}","events_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/events","assignees_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/assignees{/user}","branches_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/branches{/branch}","tags_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/tags","blobs_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/git/refs{/sha}","trees_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/statuses/{sha}","languages_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/languages","stargazers_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/stargazers","contributors_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/contributors","subscribers_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/subscribers","subscription_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/subscription","commits_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/commits{/sha}","git_commits_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/git/commits{/sha}","comments_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/comments{/number}","issue_comment_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/issues/comments{/number}","contents_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/contents/{+path}","compare_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/merges","archive_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/downloads","issues_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/issues{/number}","pulls_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/pulls{/number}","milestones_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/milestones{/number}","notifications_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/labels{/name}","releases_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/releases{/id}","deployments_url":"https://api.github.com/repos/ColinEberhardt/d3-financial-components/deployments","created_at":"2014-11-11T13:25:33Z","updated_at":"2016-01-13T16:28:04Z","pushed_at":"2016-02-05T13:50:56Z","git_url":"git://github.com/ColinEberhardt/d3-financial-components.git","ssh_url":"git@github.com:ColinEberhardt/d3-financial-components.git","clone_url":"https://github.com/ColinEberhardt/d3-financial-components.git","svn_url":"https://github.com/ColinEberhardt/d3-financial-components","homepage":"","size":5859,"stargazers_count":1,"watchers_count":1,"language":"JavaScript","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":2,"mirror_url":null,"open_issues_count":0,"forks":2,"open_issues":0,"watchers":1,"default_branch":"master"}},"base":{"label":"ScottLogic:master","ref":"master","sha":"1669fc7de71db1cf726db2b2e4880d2e85a6dd06","user":{"login":"ScottLogic","id":2046037,"avatar_url":"https://avatars.githubusercontent.com/u/2046037?v=3","gravatar_id":"","url":"https://api.github.com/users/ScottLogic","html_url":"https://github.com/ScottLogic","followers_url":"https://api.github.com/users/ScottLogic/followers","following_url":"https://api.github.com/users/ScottLogic/following{/other_user}","gists_url":"https://api.github.com/users/ScottLogic/gists{/gist_id}","starred_url":"https://api.github.com/users/ScottLogic/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ScottLogic/subscriptions","organizations_url":"https://api.github.com/users/ScottLogic/orgs","repos_url":"https://api.github.com/users/ScottLogic/repos","events_url":"https://api.github.com/users/ScottLogic/events{/privacy}","received_events_url":"https://api.github.com/users/ScottLogic/received_events","type":"Organization","site_admin":false},"repo":{"id":24850617,"name":"d3fc","full_name":"ScottLogic/d3fc","owner":{"login":"ScottLogic","id":2046037,"avatar_url":"https://avatars.githubusercontent.com/u/2046037?v=3","gravatar_id":"","url":"https://api.github.com/users/ScottLogic","html_url":"https://github.com/ScottLogic","followers_url":"https://api.github.com/users/ScottLogic/followers","following_url":"https://api.github.com/users/ScottLogic/following{/other_user}","gists_url":"https://api.github.com/users/ScottLogic/gists{/gist_id}","starred_url":"https://api.github.com/users/ScottLogic/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ScottLogic/subscriptions","organizations_url":"https://api.github.com/users/ScottLogic/orgs","repos_url":"https://api.github.com/users/ScottLogic/repos","events_url":"https://api.github.com/users/ScottLogic/events{/privacy}","received_events_url":"https://api.github.com/users/ScottLogic/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ScottLogic/d3fc","description":"A collection of components that make it easy to build interactive charts with D3","fork":false,"url":"https://api.github.com/repos/ScottLogic/d3fc","forks_url":"https://api.github.com/repos/ScottLogic/d3fc/forks","keys_url":"https://api.github.com/repos/ScottLogic/d3fc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ScottLogic/d3fc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ScottLogic/d3fc/teams","hooks_url":"https://api.github.com/repos/ScottLogic/d3fc/hooks","issue_events_url":"https://api.github.com/repos/ScottLogic/d3fc/issues/events{/number}","events_url":"https://api.github.com/repos/ScottLogic/d3fc/events","assignees_url":"https://api.github.com/repos/ScottLogic/d3fc/assignees{/user}","branches_url":"https://api.github.com/repos/ScottLogic/d3fc/branches{/branch}","tags_url":"https://api.github.com/repos/ScottLogic/d3fc/tags","blobs_url":"https://api.github.com/repos/ScottLogic/d3fc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ScottLogic/d3fc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ScottLogic/d3fc/git/refs{/sha}","trees_url":"https://api.github.com/repos/ScottLogic/d3fc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ScottLogic/d3fc/statuses/{sha}","languages_url":"https://api.github.com/repos/ScottLogic/d3fc/languages","stargazers_url":"https://api.github.com/repos/ScottLogic/d3fc/stargazers","contributors_url":"https://api.github.com/repos/ScottLogic/d3fc/contributors","subscribers_url":"https://api.github.com/repos/ScottLogic/d3fc/subscribers","subscription_url":"https://api.github.com/repos/ScottLogic/d3fc/subscription","commits_url":"https://api.github.com/repos/ScottLogic/d3fc/commits{/sha}","git_commits_url":"https://api.github.com/repos/ScottLogic/d3fc/git/commits{/sha}","comments_url":"https://api.github.com/repos/ScottLogic/d3fc/comments{/number}","issue_comment_url":"https://api.github.com/repos/ScottLogic/d3fc/issues/comments{/number}","contents_url":"https://api.github.com/repos/ScottLogic/d3fc/contents/{+path}","compare_url":"https://api.github.com/repos/ScottLogic/d3fc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ScottLogic/d3fc/merges","archive_url":"https://api.github.com/repos/ScottLogic/d3fc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ScottLogic/d3fc/downloads","issues_url":"https://api.github.com/repos/ScottLogic/d3fc/issues{/number}","pulls_url":"https://api.github.com/repos/ScottLogic/d3fc/pulls{/number}","milestones_url":"https://api.github.com/repos/ScottLogic/d3fc/milestones{/number}","notifications_url":"https://api.github.com/repos/ScottLogic/d3fc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ScottLogic/d3fc/labels{/name}","releases_url":"https://api.github.com/repos/ScottLogic/d3fc/releases{/id}","deployments_url":"https://api.github.com/repos/ScottLogic/d3fc/deployments","created_at":"2014-10-06T15:03:11Z","updated_at":"2016-02-04T18:07:10Z","pushed_at":"2016-02-05T13:50:13Z","git_url":"git://github.com/ScottLogic/d3fc.git","ssh_url":"git@github.com:ScottLogic/d3fc.git","clone_url":"https://github.com/ScottLogic/d3fc.git","svn_url":"https://github.com/ScottLogic/d3fc","homepage":"https://d3fc.io/","size":7325,"stargazers_count":219,"watchers_count":219,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":40,"mirror_url":null,"open_issues_count":65,"forks":40,"open_issues":65,"watchers":219,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/ScottLogic/d3fc/pulls/867"},"html":{"href":"https://github.com/ScottLogic/d3fc/pull/867"},"issue":{"href":"https://api.github.com/repos/ScottLogic/d3fc/issues/867"},"comments":{"href":"https://api.github.com/repos/ScottLogic/d3fc/issues/867/comments"},"review_comments":{"href":"https://api.github.com/repos/ScottLogic/d3fc/pulls/867/comments"},"review_comment":{"href":"https://api.github.com/repos/ScottLogic/d3fc/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/ScottLogic/d3fc/pulls/867/commits"},"statuses":{"href":"https://api.github.com/repos/ScottLogic/d3fc/statuses/de68bbedcc068e3a213beaa2c542a7268a3a1d39"}}}}