{"id":21496927,"url":"https://github.com/financial-times/g-chartframe","last_synced_at":"2025-07-15T19:32:54.102Z","repository":{"id":4862737,"uuid":"47627855","full_name":"Financial-Times/g-chartframe","owner":"Financial-Times","description":"FT styled frames for D3 graphics","archived":false,"fork":false,"pushed_at":"2023-07-09T10:14:24.000Z","size":1480,"stargazers_count":3,"open_issues_count":19,"forks_count":3,"subscribers_count":29,"default_branch":"main","last_synced_at":"2024-11-22T03:11:30.969Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://ft-interactive.github.io/g-chartframe/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Financial-Times.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2015-12-08T14:39:59.000Z","updated_at":"2024-11-20T09:18:11.000Z","dependencies_parsed_at":"2023-07-05T18:02:24.298Z","dependency_job_id":null,"html_url":"https://github.com/Financial-Times/g-chartframe","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Financial-Times%2Fg-chartframe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Financial-Times%2Fg-chartframe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Financial-Times%2Fg-chartframe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Financial-Times%2Fg-chartframe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Financial-Times","download_url":"https://codeload.github.com/Financial-Times/g-chartframe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226065219,"owners_count":17568174,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-23T16:19:42.691Z","updated_at":"2024-11-23T16:19:43.366Z","avatar_url":"https://github.com/Financial-Times.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# g-chartframe\n\nFor making the boring but necessary stuff on D3 charts in as painless a fashion as possible.\n\n## Installation\n\nIf you use NPM, `npm install g-chartframe`. Otherwise, download the [latest release](https://github.com/ft-interactive/g-chartframe/releases/latest). Or you could include it stright in your page via unpkg (or equiv) https://unpkg.com/g-chartframe@0.3.0/build/g-chartframe.js\n\n## Use\n\nPreconfigured frames...\n\n```js\nconst webframe = gChartframe.webFrame();\nwebframe.title('A simple chart')\n\t.subtitle('showing some interesting things')\n\t.source('source: FT research|FT Graphic Tom Pearson');\n\nd3.select('.web-chart-container svg')\n\t.call(webframe);\n\nwebframe.plot()\n\t...add your visualisation code here...\n\n```\n\nConfigure your own frame...\n\n```js\nconst myFrame = gChartframe\n  .frame()\n  .width(350)\n  .height(350)\n  .margin({ top: 20, left: 20, bottom: 20, right: 20 })\n  .title(\"My totally custom title\")\n  .subtitle(\"hello hello hello\");\n\nd3.select(\".custom-chart-container\")\n  .append(\"svg\")\n  .call(myFrame);\n```\n\nYou may also set frame properties en-masse via the `attrs` function. Though note: if you're relying on setting units you should do so before calling `attrs` as you can't guarantee in which order the setters will be called.\n\n```js\nmyFrame.attrs({\n  title: \"A different title\",\n  subtitle: \"A different subtitle\",\n  width: 600,\n  ...etc\n});\n```\n\n## API Reference\n\n![reference image indicating whcih properties refer to which bits of the chart frame](https://raw.githubusercontent.com/ft-interactive/g-chartframe/main/markup-frame.png)\n\n\u003ca id=\"frame-factory\" href=\"#frame-factory\"\u003e#\u003c/a\u003e**frame(_[configuration]_)**\n\nMake a new chart frame drawer:\n\n```js\nconst myFrame = gChartframe.frame();\n```\n\n_configuration_ is an optional parameter which sets the initial properties of the frame via the setter functions as defined below.\n\ne.g.\n\n```js\nconst config = {\n  title: \"The fastest cars in the world\",\n  subtitle: \"acceleration m/s\u003csup\u003e2\u003c/sup\u003e\",\n  source: \"Guiness book of records\"\n};\n\nconst myFrame = gChartframe.frame(config);\n```\n\nMost of the time you won't want to use this though but instead use one of the pre configured chartframe factories...\n\n```js\nconst myFrame = gChartframe.webFrame(config);\n```\n\nor...\n\n```js\nconst myFrame = gChartframe.printFrame(config);\n```\n\nor...\n\n```js\nconst myFrame = gChartframe.socialFrame(config);\n```\n\nor...\n\n```js\nconst myFrame = gChartframe.videoFrame(config);\n```\n\nthese provide appropriate positioning, size and fonts for the specified use within the FT (web, print, social media or video)\n\n\u003ca id=\"frame-attrs\" href=\"#frame-attrs\"\u003e#\u003c/a\u003eframe.**attrs(_object_)**\n\nA convenience setter: Set as many values as you choose by passing a big object to the frame (see above).\n\n\u003ca id=\"frame-autoposition\" href=\"#frame-attrs\"\u003e#\u003c/a\u003eframe.**autoPosition(_boolean_)**\n\nThis get the frame to try and automatically comput its top margin. _Not really reccomended though it it used by the pre-packaged webframes_.\n\n\u003ca id=\"frame-backgroundColor\" href=\"#frame-backgroundColor\"\u003e#\u003c/a\u003eframe.**backgroundColor(_string_)**\n\nSet the background color of the frame. For the single argument you can use the same css color naming schemes that you use in HTML, whether that's color names (that is red), rgb values (that is rgb(255,0,0)), hex values, rgba values, etc. If no argument is specified returns the current value.\n\n```js\nmyFrame.backgroundColor(\"#00FF00\");\n```\n\n\u003ca id=\"frame-containerClass\" href=\"#frame-containerClass\"\u003e#\u003c/a\u003eframe.**containerClass(_string_)**\n\nSet the class assigned to the containing SVG element. This allows you to select the frame later and to define CSS styles pertaining only to its contents. If no argument is specified returns the current value.\n\n```js\nmyFrame.containerClass(\"special-frame\");\n```\n\nwould allow you to target the frames contents in your CSS like this...\n\n```css\n.special-frame line {\n  stroke-width: 2;\n  stroke: #00ff00;\n  stroke-opacity: 0.5;\n  fill: none;\n}\n```\n\n\u003ca id=\"frame-dimension\" href=\"#frame-dimension\"\u003e#\u003c/a\u003eframe.**dimension()**\n\nThis returns an object with the `height` and `width` of the suggested plot area. This is useful for determining the range of scales.\nIf no argument is specified returns the current value.\n\n```js\nconst dimension = myFrame.dimension(); // e.g. { width: 200 ,height: 550,}\nconst horizontalScale = d3.linearScale().range([0, dimension.width]);\n\nconst verticalScale = d.lineaScale().range([dimension.height, 0]);\n```\n\n\u003ca id=\"frame-height\" href=\"#frame-height\"\u003e#\u003c/a\u003eframe.**height(_number_)**\n\nSet the height for the frames container (typically be an SVG).\nIf no argument is specified returns the current value.\n\n\u003ca id=\"frame-margin\" href=\"#frame-margin\"\u003e#\u003c/a\u003eframe.**margin(_[{[top:number], [left:number], [bottom:number], [right:number],}]_)**\n\nSet the margins for the frame follwing the \u003ca href=\"https://bl.ocks.org/mbostock/3019563\"\u003eD3 margin convention\u003c/a\u003e.\nIf no argument is specified returns the current value.\n\n\u003ca id=\"frame-plot\" href=\"#frame-plot\"\u003e#\u003c/a\u003eframe.**plot()**\n\nThis returns a d3 selection of the frames plot group. This is where the graphical elements of the chart can be appended.\n\n```js\nconst plot = myFrame.plot();\n\nplot.selectAll('rect')\n\t.data(theData)\n\t.enter()\n\t.append('rect')\n\t...\n\n```\n\n\u003ca id=\"frame-source\" href=\"#frame-source\"\u003e#\u003c/a\u003eframe.**source(_[string]_)**\n\nA string describes the source of the graphic's data, line breaks can be added with the `|` character. The property can also be used to add notes, credits etc. If no argument is specified returns the current value.\n\n```js\nmyFrame.source(\"Source:FT Research|Graphic: Pam Ampersand\");\n```\n\n\u003ca id=\"frame-sourceLineHeight\" href=\"#frame-sourceLineHeight\"\u003e#\u003c/a\u003eframe.**sourceLineHeight(_[number]_)**\n\nSet the line height for the graphic's source text. If no argument is specified returns the current value.\n\n\u003ca id=\"frame-sourceStyle\" href=\"#frame-sourceStyle\"\u003e#\u003c/a\u003eframe.**sourceStyle(_[{attribute:value}]_)**\n\nSet the appearnce of the graphic's source text. A series of attributes are added to the text element with the specified values. If no argument is specified returns the current value.\n\n```js\nmyFrame.sourceStyle({\n\t'font-family':'Sans-serif, Helvetica',\n\t'fill':'#00FF00';\n\t...\n});\n```\n\nwill result in a text element that looks like...\n\n```\n\u003ctext class=\"chart-source\"\u003e\u003ctspan y=\"477\" x=\"4\" font-family=\"Sans-serif, Helvetica\" fill=\"#00FF00\"\u003eSource text\u003c/tspan\u003e\u003c/text\u003e\n```\n\n\u003ca id=\"frame-sourceX\" href=\"#frame-sourceX\"\u003e#\u003c/a\u003eframe.**sourceX(_[number]_)**\n\nSet the X translation of the graphic's source text. If no argument is specified returns the current value.\n\n\u003ca id=\"frame-sourceY\" href=\"#frame-sourceY\"\u003e#\u003c/a\u003eframe.**sourceY(_[number]_)**\n\nSet the Y translation of the graphic's source text. If no argument is specified returns the current value.\n\n\u003ca id=\"frame-subtitle\" href=\"#frame-subtitle\"\u003e#\u003c/a\u003eframe.**subtitle(_[string]_)** similar to \u003ca href=\"#frame-source\"\u003e_source_\u003c/a\u003e\n\n\u003ca id=\"frame-subtitleLineHeight\" href=\"#frame-subtitleLineHeight\"\u003e#\u003c/a\u003eframe.**subtitleLineHeight(_[number]_)** similar to \u003ca href=\"#frame-sourceLineHeight\"\u003e_sourceLineHeight_\u003c/a\u003e\n\n\u003ca id=\"frame-subtitleStyle\" href=\"#frame-subtitleStyle\"\u003e#\u003c/a\u003eframe.**subtitleStyle(_[{attribute:value}]_)** similar to \u003ca href=\"#frame-sourceStyle\"\u003e_sourceStyle_\u003c/a\u003e\n\n\u003ca id=\"frame-subtitleX\" href=\"#frame-subtitleX\"\u003e#\u003c/a\u003eframe.**subtitleX(_[number]_)** similar to \u003ca href=\"#frame-sourceLineX\"\u003e_sourceX_\u003c/a\u003e\n\n\u003ca id=\"frame-subtitleY\" href=\"#frame-subtitleY\"\u003e#\u003c/a\u003eframe.**subtitleY(_[number]_)** similar to \u003ca href=\"#frame-sourceY\"\u003e_sourceY_\u003c/a\u003e\n\n\u003ca id=\"frame-title\" href=\"#frame-title\"\u003e#\u003c/a\u003eframe.**title(_[string]_)** similar to \u003ca href=\"#frame-source\"\u003e_source_\u003c/a\u003e\n\n\u003ca id=\"frame-titleStyle\" href=\"#frame-titleStyle\"\u003e#\u003c/a\u003eframe.**titleStyle(_[number]_)** similar to \u003ca href=\"#frame-sourceStyle\"\u003e_sourceStyle_\u003c/a\u003e\n\n\u003ca id=\"frame-titleLineHeight\" href=\"#frame-titleLineHeight\"\u003e#\u003c/a\u003eframe.**titleLineHeight(_[number]_)** similar to \u003ca href=\"#frame-sourceLineHeight\"\u003e_sourceLineHeight_\u003c/a\u003e\n\n\u003ca id=\"frame-titleX\" href=\"#frame-titleX\"\u003e#\u003c/a\u003eframe.**titleX(_[number]_)** similar to \u003ca href=\"#frame-sourceLineX\"\u003e_sourceX_\u003c/a\u003e\n\n\u003ca id=\"frame-titleY\" href=\"#frame-titleY\"\u003e#\u003c/a\u003eframe.**titleY(_[number]_)** similar to \u003ca href=\"#frame-sourceY\"\u003e_sourceY_\u003c/a\u003e\n\n\u003ca id=\"frame-units\" href=\"#frame-units\"\u003e#\u003c/a\u003eframe.**units(_[string]_)**\n\nSet the units in which the Height and Width are set. At the moment the only useful argument is 'mm' which allows you to specify height and width in mm -- useful for print. If no argument is specified returns the current value.\n\n\u003ca id=\"frame-watermark\" href=\"#frame-watermark\"\u003e#\u003c/a\u003eframe.**watermark(_[svgnodes]_)**\n\nThe user can supply arbitrary SVG markup as a string. THis will be used as the watermark for the graphic. If no argument is specified returns the current value.\n\n\u003ca id=\"frame-watermarkLocation\" href=\"#frame-watermarkLocation\"\u003e#\u003c/a\u003eframe.**watermarkLocation(_[href]_)**\n\nThe user can set a URL for a watermark SVG to be used.\n\n\u003ca id=\"frame-width\" href=\"#frame-width\"\u003e#\u003c/a\u003eframe.**width(_[number]_)**\n\nSet the height for the frames container (typically be an SVG).\nIf no argument is specified returns the current value.\n\n👉 _Note_: If the chart frame is being called on an SVG element the width, height and title functions will re-write those properties of the parent SVG. If you don't want this to happen you can avoid it by calling the function on a group element instead.\n\n--\n\n# Licence\n\nThis software is published by the Financial Times under the [MIT licence](https://opensource.org/licenses/MIT).\n\nPlease note the MIT licence only covers the software, and does not cover any FT content or branding incorporated into the software or made available using the software. FT content is copyright © The Financial Times Limited, and FT and 'Financial Times' are trademarks of The Financial Times Limited, all rights reserved. For more information about republishing FT content, please contact our [republishing department](https://ft.com/republishing).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinancial-times%2Fg-chartframe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffinancial-times%2Fg-chartframe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinancial-times%2Fg-chartframe/lists"}