{"id":20455064,"url":"https://github.com/jumpingrivers/ard-js","last_synced_at":"2025-07-14T19:38:06.262Z","repository":{"id":46319406,"uuid":"514249321","full_name":"jumpingrivers/ard-js","owner":"jumpingrivers","description":"Admissions / Retentions dashboard js repo","archived":false,"fork":false,"pushed_at":"2022-09-01T15:58:31.000Z","size":1217,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-01-15T23:25:29.184Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/jumpingrivers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-15T11:45:03.000Z","updated_at":"2022-07-19T09:30:34.000Z","dependencies_parsed_at":"2023-01-17T17:30:28.067Z","dependency_job_id":null,"html_url":"https://github.com/jumpingrivers/ard-js","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jumpingrivers%2Fard-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jumpingrivers%2Fard-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jumpingrivers%2Fard-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jumpingrivers%2Fard-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jumpingrivers","download_url":"https://codeload.github.com/jumpingrivers/ard-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242005820,"owners_count":20056434,"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-15T11:17:50.538Z","updated_at":"2025-03-05T10:19:13.857Z","avatar_url":"https://github.com/jumpingrivers.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# utviz.js\n\n## Developing this repo\n\n1. Clone the repo.\n2. Run `npm ci` to install all the requisite node modules. You'll probably want to do this everytime you pull in changes.\n3. Run `npm run prepare`. This is required for the pre-commit tests to work, but you should only have to do this once.\n\nAfter the above you can:\n* Build the scripts using `npm run build`.\n* Build scripts and view examples on local server using `npm run start`.\n* Run linting using `npm run lint` (or `npm run lint:fix`).\n* Run tests using `npm run test`.\n\n## Including utviz.js in a page\n\nutviz.js depends on [Handlebars](https://handlebarsjs.com/) (tested on version 4.7.x) which must be included before utviz.js.\n\nFor development you'll probably want to include unminified versions of both:\n\n``` html\n  \u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.7.7/handlebars.js\"\u003e\u003c/script\u003e\n  \u003cscript src=\"scripts/utviz.js\"\u003e\u003c/script\u003e\n```\n\nFor production use the minfied versions to reduce the bundle size:\n\n``` html\n  \u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.7.7/handlebars.min.js\"\u003e\u003c/script\u003e\n  \u003cscript src=\"scripts/utviz.min.js\"\u003e\u003c/script\u003e\n```\n\nBoth options add a `utviz` object (and a `Handlebars` object) to the `window` object.\n\n## `utviz.createSankey([data, [steps]])`\n\nCreates and returns a new `sankey` object instance. The `data` and `steps` arguments are optional here but must be supplied at some point before `.render()` can actually render anything. See the `.data()` and `.steps()` methods below for more details.\n\nAll methods except `.render()` act as both getters and setters. That means that if they are called without an argument then the current stored value associated with the method is returned. If they are called with an argument then that argument is assigned as the stored value for that method and the instance is returned to allow for method chaining.\n\n\n### sankey.viz\n\nThe instance's only read-only property, holding the actualy Sankey visualisation, including dropdowns and reset button. Append it to a container element and it will fill it:\n\n``` js\ndocument.querySelector('#my-sankey-container')\n  .appendChild(sankey.viz);\n```\n\n### sankey.altClickHandler([value])\n\nIf supplied, `value` must be a function or `null`. If it is a function the function will be called whenever the user alt-clicks a node in the Sankey diagram and is passed the click event and the node's data as arguments while the `this` variable will correspond to the Sankey instance. If `value` is null then any previously-set alt-click handler will be removed.\n\n### sankey.aspect([value])\n\nIf supplied, `value` should be a finite number greater than 0. This value sets the aspect ratio (width / height) of the Sankey (not including the dropdown menus and the reset button).\n\n### sankey.color([value])\n\nIf supplied, `value` should be a string representing a color. This color is used to color all nodes that don't have an associated color override. Links emanating from these nodes will also be a translucent version of this color.\n\n### sankey.colorOverrides([value])\n\nIf supplied, `value` should be an array of objects. Each object specifies some form of color override. To have any effect it must have a \"color\" property and at least one of a \"name\" property and a \"group\" property. The \"name\" property corresponds to the name or label of a node while the group property corresponds to the name associated with the column in the Sankey. This means the groups are derived from the keys in the supplied `data` while the names are the values associated with these keys. An override assigned to a node through a \"name\" property trumps an override assigned through a \"group\" property. An override assigned through a \"name\" and a \"group\" property in the same object will trump both of these.\n\n### sankey.data([value])\n\nIf supplied, `value` must be an array of objects. Each object should represent a single entry, e.g. a single student. These data values, alongside the `steps` are then used to construct the Sankey chart.\n\n### sankey.hoverColor([value])\n\nIf supplied, `value` should be a string representing a color. This color is used to highlight a node on hover. It is also used, in a translucent form, to highlight a link on hover.\n\n### sankey.linkPopupTemplate([value])\n\nIf supplied, `value` should be a string representing a [Handlebars HTML template](https://handlebarsjs.com/guide/#simple-expressions) that will be used to construct a popup when hovering over a link. Alongside regular HTML constructs, the template can reference the following properties:\n* {{sourceName}} the name of the source node of the link.\n* {{targetName}} the name of the target node of the link.\n* {{count}} the count of the link.\n* {{totalCount}} the total count for the whole Sankey diagram.\n* {{percentageOfSourceCount}} the (rounded) percentage value of all counts from the source node that go through this link.\n* {{percentageOfTargetCount}} the (rounded) percentage value of all counts to the target node that go through this link.\n\n### sankey.nodePopupTemplate([value])\n\nIf supplied, `value` should be a string representing a [Handlebars HTML template](https://handlebarsjs.com/guide/#simple-expressions) that will be used to construct a popup when hovering over a node. Alongside regular HTML constructs, the template can reference the following properties:\n* {{name}} the name of the node.\n* {{count}} the count of the node.\n* {{totalCount}} the total count for the whole Sankey diagram.\n\n### sankey.render()\n\nUpdates the viz based on the latest set of stored properties and returns the Sankey instance. The `data` and `steps` must have been defined prior to this method call for anything interesting to happen.\n\n### sankey.steps([value])\n\nIf supplied, `steps` should be an array. The elements of the array can be either strings or arrays of strings. Each outer element of the `steps` array represents a vertical column of nodes, going from left to right. The strings should match keys in the `data`. If a given step is an array, then each element represents a drill-down stage for that column in the Sankey diagram, starting from the first element. For example, an array of `[[\"a\", \"b\"], \"c\", \"d\"]` will create a Sankey with three steps or columns which initially shows data corresponding to the properties for the keys \"a\", \"c\", and \"d\" in the `data`. Clicking on any node in the first column will drill-down to show the data for the \"b\" key, filtered on a particular value for the \"a\" property.\n\n## `utviz.createSunburst([data, [steps]])`\n\nCreates and returns a new `sunburst` object instance. The `data` and `steps` arguments are optional here but must be supplied at some point before `.render()` can actually render anything. See the `.data()` and `.steps()` methods below for more details.\n\nAll methods except `.render()` act as both getters and setters. That means that if they are called without an argument then the current stored value associated with the method is returned. If they are called with an argument then that argument is assigned as the stored value for that method and the instance is returned to allow for method chaining.\n\n\n### sunburst.viz\n\nThe instance's only read-only property, holding the actualy sunburst visualisation, including reset button. Append it to a container element and it will fill it:\n\n``` js\ndocument.querySelector('#my-sunburst-container')\n  .appendChild(sunburst.viz);\n```\n\n### sunburst.altClickHandler([value])\n\nIf supplied, `value` must be a function or `null`. If it is a function the function will be called whenever the user alt-clicks a ring section in the sunburst diagram and is passed the click event, the ring-section's data and an array describing the path to that ring section as arguments while the `this` variable will correspond to the sunburst instance. If `value` is null then any previously-set alt-click handler will be removed.\n\n### sunburst.colorOverrides([value])\n\nIf supplied, `value` should be an array of objects. Each object specifies some form of color override. To have any effect it must have a \"color\" property and at least one of a \"name\" property and a \"group\" property. The \"name\" property corresponds to the name or label for ring sections while the group property corresponds to the name associated with a whole ring. This means the groups are derived from the keys in the supplied `data` while the names are the values associated with these keys. An override assigned to a ring-section through a \"name\" property trumps an override assigned through a \"group\" property. An override assigned through a \"name\" and a \"group\" property in the same object will trump both of these.\n\n### sunburst.data([value])\n\nIf supplied, `value` must be an array of objects. Each object should represent a single entry, e.g. a single student. These data values, alongside the `steps` are then used to construct the sunburst chart.\n\n### sunburst.mouseoutHandler([value])\n\nIf supplied, `value` must be a function or `null`. If it is a function the function will be called whenever the user moves their mouse out of a ring section in the sunburst diagram and is passed the mouseout event, the ring-section's data and an array describing the path to that ring section as arguments while the `this` variable will correspond to the sunburst instance. If `value` is null then any previously-set alt-click handler will be removed.\n\n### sunburst.mouseoverHandler([value])\n\nIf supplied, `value` must be a function or `null`. If it is a function the function will be called whenever the user moves their mouse into a ring section in the sunburst diagram and is passed the mouseover event, the ring-section's data and an array describing the path to that ring section as arguments while the `this` variable will correspond to the sunburst instance. If `value` is null then any previously-set alt-click handler will be removed.\n\n### sunburst.palette([value])\n\nIf supplied, `value` should be an array of strings where each string represents a color. These colors are used to color all the sections of the inner ring in order from largest to smallest. The colors of other ring-sections are then derived from the corresponding innermost ring color. Color-overrides are applied _after_ this assignment process.\n\n### sunburst.render()\n\nUpdates the viz based on the latest set of stored properties and returns the sunburst instance. The `data` and `steps` must have been defined prior to this method call for anything interesting to happen.\n\n### sunburst.steps([value])\n\nIf supplied, `steps` should be an array. The elements of the array should be strings. Each element of the `steps` array represents a ring, going from inside to outside. The strings should match keys in the `data`.\n\n## `utviz.version`\n\nA property whose value is the current semantic version (format: _digits.digits.digits_) of utviz.js.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjumpingrivers%2Fard-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjumpingrivers%2Fard-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjumpingrivers%2Fard-js/lists"}