{"id":19185707,"url":"https://github.com/fusioncharts/fusioncharts-smartlabel","last_synced_at":"2025-05-08T01:15:46.363Z","repository":{"id":46300088,"uuid":"77454663","full_name":"fusioncharts/fusioncharts-smartlabel","owner":"fusioncharts","description":"SmartLabel component of FusionCharts","archived":false,"fork":false,"pushed_at":"2024-10-08T11:44:23.000Z","size":1047,"stargazers_count":14,"open_issues_count":4,"forks_count":12,"subscribers_count":19,"default_branch":"develop","last_synced_at":"2025-05-08T01:15:40.805Z","etag":null,"topics":["canvas","fusioncharts","labels","smartlabel","svg","text"],"latest_commit_sha":null,"homepage":"https://fusioncharts.github.io/fusioncharts-smartlabel","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fusioncharts.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.MD","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-27T12:41:35.000Z","updated_at":"2025-03-25T10:32:57.000Z","dependencies_parsed_at":"2022-09-19T09:00:40.229Z","dependency_job_id":null,"html_url":"https://github.com/fusioncharts/fusioncharts-smartlabel","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusioncharts%2Ffusioncharts-smartlabel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusioncharts%2Ffusioncharts-smartlabel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusioncharts%2Ffusioncharts-smartlabel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusioncharts%2Ffusioncharts-smartlabel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fusioncharts","download_url":"https://codeload.github.com/fusioncharts/fusioncharts-smartlabel/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252978809,"owners_count":21834920,"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":["canvas","fusioncharts","labels","smartlabel","svg","text"],"created_at":"2024-11-09T11:11:38.558Z","updated_at":"2025-05-08T01:15:46.331Z","avatar_url":"https://github.com/fusioncharts.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SmartLabel [![Build Status](https://travis-ci.org/fusioncharts/fusioncharts-smartlabel.svg?branch=develop)](https://travis-ci.org/fusioncharts/fusioncharts-smartlabel) [![Coverage Status](https://coveralls.io/repos/github/fusioncharts/fusioncharts-smartlabel/badge.svg?branch=develop)](https://coveralls.io/github/fusioncharts/fusioncharts-smartlabel?branch=develop)\n\nSmartLabel is a component which can be used to measure and restrict text in svg / canvas where the layout engine does not automatically takes care of the text behaviours.\n\n\n## Concept\n\nLive demo: [fusioncharts.github.io/fusioncharts-smartlabel](http://fusioncharts.github.io/fusioncharts-smartlabel/)\n\nTo build the examples locally, run:\n\n```javascript\nnpm install\nnpm start\n```\n\nThen open [`localhost:8000`](http://localhost:8000) in a browser.\n\n\n## Installation\n\nThe easiest way to use fusioncharts-smartlabel is to install it from NPM and include it in your own build process (using [Browserify](http://browserify.org), [Webpack](http://webpack.github.io/), etc).\n\nYou can also use the standalone build by including `dist/fusioncharts-smartlabel.js`\n\n```javascript\nnpm install fusioncharts-smartlabel --save\n```\n\n\n## API\n\n__Please see the concept above before proceeding__\n\n\nSmartLabel is immensely useful when text needs to be drawn in SVG or Canvas. Since SVG / Canvas does not manage text, it is necessary to have pre procressing on the text before getting it rendered.\n\nSmartLabel provides out of the box features to\n- If a bound box is provided it wraps / truncates the text\n- Calculate the metrics (height and width) of text for any style\n- Add ellipses if the text is truncated\n- Wraps a label in the bound box\n\n\nTo Create a new instance\n```javascript\nimport SmartLabel from 'fusioncharts-smartlabel'\n/*\n * Create new instance of SmartLabel.\n *\n * SmartLabel controls the lifetime of the execution space where the text's metrics will be calculated.\n * This takes a string for a given style and returns the height, width.\n * If a bound box is defined it wraps the text and returns the wrapped height and width.\n * It allows to append ellipsis at the end if the text is truncated.\n *\n * @param {String | HTMLElement} container - The id or the instance of the container where the intermediate dom\n *                              elements are to be attached. If not passed, it appends in body.\n *\n * @param {Boolean} useEllipses - This decides if a ellipses to be appended if the text is truncated.\n * @param {Object} options - Control options\n *                          {\n *                              maxCacheLimit: No of letter to be cached. Default: 500.\n *                          }\n * @constructor\n */\nvar sl =  new SmartLabel(container, useEllipses, options)\n```\n\nTo apply style before calculating text metrics\n```javascript\n/*\n * Sets the style based on which the text's metrics to be calculated.\n *\n * @param {Object} style - The style object which affects the text size\n *                      {\n *                          fontSize / 'font-size' : MUST BE FOLLOWED BY PX (10px, 11px)\n *                          fontFamily / 'font-family'\n *                          fontWeight / 'font-weight'\n *                          fontStyle / 'font-style'\n *                      }\n *\n * @return {SmartLabel} - Current instance of SmartLabel\n */\nsl.setStyle(style);\n```\n\nDecide whether the text would have trailing ellipses if truncated\n```javascript\n/*\n * Decides whether ellipses to be shown if the node is truncated\n *\n * @param {Boolean} useEllipses - decides if a ellipses to be appended if the text is truncated. Default: false\n *\n * @return {SmartLabel} - Current instance of SmartLabel\n */\nsl.useEllipsesOnOverflow(useEllipses);\n```\n\nTo get the text bounded by a bound box\n```javascript\n/*\n * Get wrapped or truncated text if a bound box is defined around it. The result text would be separated by \u003cbr/\u003e\n * if wrapped\n *\n * @param {String} text - the subject text\n * @param {Number} maxWidth - width in px of the the bound box\n * @param {Number} maxHeight - height in px of the the bound box\n * @param {Boolean} noWrap - whether the text not to be wrapped. Default false i.e. by default wrapping is enabled.\n *\n * @return {Object} - The metrics of the text bounded by the box\n *                  {\n *                      height : height of the wrapped text\n *                      width : width of the wrapped text\n *                      isTruncated : whether the text is truncated\n *                      maxHeight : Maximum height given\n *                      maxWidth : Maximum width given\n *                      oriText : Original text sent\n *                      oriTextHeight : Original text height\n *                      oriTextWidth : Original text width\n *                      text : SMART TEXT\n *                  }\n */\nsmartlabel = sl.getSmartText(text, maxWidth, maxHeight, noWrap);\n```\n\nTo get the lines for a truncated text\n```javascript\n/*\n * getSmartText returns the text separated by \u003cbr/\u003e whenever a break is necessary. This is to recgonize one\n * generalized format independent of the implementation (html5 based solution, canvas based solution, svg based solution).\n * This method converts the output of getSmartText().text to array of lines if the text is wrapped. It sets a named property\n * `lines` on the object passed as parameter.\n *\n * @param {Object} smartlabel - the object returned by getSmartText based on which line arr which to be formed.\n *\n * @return {Object} - The same object which was passed in the arguments. Also a named property `lines` is set.\n */\n smartlabel = sl.getSmartText(text, maxWidth, maxHeight, noWrap);\n generalizedSmartlabel = SmartLabel.textToLines(smartlabel);\n```\n\nTo get the size of a given text\n```javascript\n/*\n * Get the height and width of a text.\n *\n * @param {String} text - Text whose metrics to be measured\n * @param {Boolean} Optional detailedCalculationFlag - this flag if set it calculates per letter position\n *                          information and returns it. Ideally you dont need it unless you want to post process the\n *                          string. And its an EXPENSIVE OPERATION.\n *\n * @return {Object} - If detailedCalculationFlag is set to true the returned object would be\n *                  {``\n *                      height: height of the text\n *                      width: width of the text\n *                      detailObj: detail calculation of letters in the format {lettername: width}\n *                  }\n *                  If detailedCalculationFlag is set to false the returned object wont have the detailObj prop.\n */\nsize = sl.getSize(text, detailedCalculationFlag);\n```\n\nTo dispose the components\n```javascript\n/*\n * Dispose the container and object allocated by the smartlabel\n */\nsl.dispose();\n```\n\n## Usage\n\nA visualization library requires to restrict a text in a bound box to eliminate over lapping. The use case of the application of SmartLabel is huge, however we are taking a small subset of the universal set.\n\nFor a typical column chart the labels in X axis conveys category information. It's important to display the labels properly in the visualization. But there are many parameters which affect the label placement.\nIf the chart is displayed in a space which is large enough to accommodate all the labels, then it is desired to place all the labels in one line\n![labels in one line](example/img/mode-orig.png \"labels in one line\")\n\nIf the space is not enough to place all the labels side by side, it's required to wrap or truncate it.\n![labels wrapped](example/img/mode-1.png \"labels wrapped\")\n\nIt's some time desired to skip the labels as well if the category is continuous (Like month of the years)\n![label skipped](example/img/mode-2.png \"label skipped\")\n\nAll this can be eaisly done using SmartLabel.\n\nFollowing is the example of how a text is constrained by a bound box.\n```javascript\n// Set the vertical alignment on already created text node\ntext\n\t.attr('dy', \".35em\");\n\n// Let smartlabel know ellipses is required if the text is truncated.\n// Get the text restricted by a bound box which has 100px width and 200px height\nsmarttext = this.smartlabel\n\t.useEllipsesOnOverflow(true)\n\t.getSmartText('Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididun', 100, 200);\n\n// Get all the lines in an array. SmartLabel injects \u003cbr/\u003e whereever a wrap is required, this conversion is necessary.\nnormalizedSL = SmartLabel.textToLines(smarttext);\n\n// Create tspan. For more than one line create more than one tspan\ntspan = text\n\t.selectAll('tspan')\n\t.data(smarttext.lines);\n\n// Perform data joining operations of d3 on the tspans\ntspan\n\t.enter()\n\t\t.append('tspan')\n\t.merge(tspan)\n\t\t.attr(\"dy\", normalizedSL.oriTextHeight)\n\t\t.attr(\"x\", 0)\n\t\t.text(d =\u003e d);\n\n```\n\n## License\n\n__MIT__\n\nCopyright (c) 2016 FusionCharts, Inc.  \u0026lt;support@fusioncharts.com\u0026gt;.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffusioncharts%2Ffusioncharts-smartlabel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffusioncharts%2Ffusioncharts-smartlabel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffusioncharts%2Ffusioncharts-smartlabel/lists"}