{"id":13807341,"url":"https://github.com/NorthwoodsSoftware/gojs-angular","last_synced_at":"2025-05-14T00:31:18.359Z","repository":{"id":38637299,"uuid":"228432582","full_name":"NorthwoodsSoftware/gojs-angular","owner":"NorthwoodsSoftware","description":"A set of Angular components to manage GoJS Diagrams, Palettes, and Overviews","archived":false,"fork":false,"pushed_at":"2025-01-30T20:29:30.000Z","size":851,"stargazers_count":61,"open_issues_count":13,"forks_count":16,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-01-30T21:27:24.115Z","etag":null,"topics":["angular","angular-components","diagram","gojs"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NorthwoodsSoftware.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-16T16:50:53.000Z","updated_at":"2025-01-30T20:29:33.000Z","dependencies_parsed_at":"2024-02-03T20:29:05.635Z","dependency_job_id":"0b13a8d7-27f4-4ec6-8455-1d03bc597450","html_url":"https://github.com/NorthwoodsSoftware/gojs-angular","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorthwoodsSoftware%2Fgojs-angular","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorthwoodsSoftware%2Fgojs-angular/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorthwoodsSoftware%2Fgojs-angular/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorthwoodsSoftware%2Fgojs-angular/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NorthwoodsSoftware","download_url":"https://codeload.github.com/NorthwoodsSoftware/gojs-angular/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254046285,"owners_count":22005567,"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":["angular","angular-components","diagram","gojs"],"created_at":"2024-08-04T01:01:24.378Z","updated_at":"2025-05-14T00:31:13.275Z","avatar_url":"https://github.com/NorthwoodsSoftware.png","language":"TypeScript","readme":"# gojs-angular\nVersion 2.0\n### By Northwoods Software for [GoJS 2.1](https://gojs.net)\n\nThis project provides Angular components for [GoJS](https://gojs.net/latest/index.html) Diagrams, Palettes, and Overviews to simplify usage of GoJS within an Angular application.\nThe implementation for these components is inside the projects/gojs-angular folder.\nSee the [gojs-angular-basic project](https://github.com/NorthwoodsSoftware/gojs-angular-basic) for example usage and the\n[Intro page on using GoJS with Angular](https://gojs.net/latest/intro/angular.html) for more information.\n\nVersion 2.0 expects immutability of all @Input properties to Diagram|Palette|Overview components, and removes `skipsPaletteUpdate` and `modelChange` properties from PaletteComponent. \n\n## Installation\n\ngojs-angular can be installed via NPM. This package has peer dependencies on GoJS and Angular, so make sure those are also installed or included on your page.\n\n### NPM\n\n```bash\nnpm install --save gojs-angular\n```\n\n## Making Changes\n\nIf you want to change how the GoJS / Angular components are implemented, you will need to edit the files in `projects/gojs-angular`, then, from the main directory, run\n\n```bash\nnpm run package\n```\n\nwhich will create a new package in the folder, dist/angular-gojs, for you to use. Currently, gojs-angular depends on TypeScript and [immer](https://github.com/immerjs/immer).\n\n## Usage\n\nThis package provides three components - DiagramComponent, PaletteComponent, and OverviewComponent - corresponding to the related GoJS classes.\n\n**Note**: As of version 2.0, `gojs-angular` assumes immutability of the `@Input` properties given to Diagram/Palette components. The [gojs-angular-basic repository](https://github.com/NorthwoodsSoftware/gojs-angular-basic) provides example usage of these components, as well as preserving state immutability (that project uses [immer](https://github.com/immerjs/immer) to maintain immutability, but you can use whatever you like best).\n\nBelow is an example of how you might pass properties to each of the components provided by `gojs-angular`. Here, for immutable data properties that may change, they are stored in an object called `state`. This is not required, but helps with organization.\n\n```html\n\u003cgojs-diagram\n  [initDiagram]='initDiagram'\n  [divClassName]='myDiagramDiv'\n  [nodeDataArray]='state.diagramNodeDataArray'\n  [linkDataArray]='state.diagramLinkDataArray'\n  [modelData]='state.diagramModelData'\n  (modelChange)='diagramModelChange($event)'\n  [skipsDiagramUpdate]='state.skipsDiagramUpdate'\n\u003e\u003c/gojs-diagram\u003e\n\n\u003cgojs-palette\n  [initPalette]='initPalette'\n  [divClassName]='myPaletteDiv'\n  [nodeDataArray]='state.paletteNodeData'\n\u003e\u003c/gojs-palette\u003e\n\n\u003cgojs-overview\n  [initOverview]='initOverview'\n  [divClassName]='myOverviewDiv'\n  [observedDiagram]='observedDiagram'\n\u003e\u003c/gojs-overview\u003e\n```\n\n### Component Properties\n\n#### initDiagram/initPalette/initOverview\nSpecifies a function that is reponsible for initializing and returning\na GoJS Diagram, Palette, or Overview. In the case of an Overview, this\nis an optional property and when not provided, an Overview with default\nproperties and centered content will be created.\n\n```js\nfunction initDiagram() {\n  const $ = go.GraphObject.make;\n\n  const diagram = $(go.Diagram,\n    {\n      'undoManager.isEnabled': true,\n      model: $(go.GraphLinksModel, {\n        linkKeyProperty: 'key'  // this should always be set when using a GraphLinksModel\n      })\n    });\n\n  diagram.nodeTemplate =\n    $(go.Node, 'Auto',  // the Shape will go around the TextBlock\n      $(go.Shape, 'RoundedRectangle', { strokeWidth: 0, fill: 'white' },\n        // Shape.fill is bound to Node.data.color\n        new go.Binding('fill', 'color')),\n      $(go.TextBlock,\n        { margin: 8 },  // some room around the text\n        // TextBlock.text is bound to Node.data.key\n        new go.Binding('text', 'key'))\n    );\n\n  return diagram;\n}\n```\n\n#### divClassName\nSpecifies the CSS classname to add to the rendered div.\nThis should usually specify a width/height.\n\n```css\n.myDiagramDiv {\n  width: 400px;\n  height: 400px;\n  border: 1px solid black;\n}\n```\n\n#### nodeDataArray (DiagramComponent and PaletteComponent only)\nSpecifies the array of nodes for the Diagram's model.\n\n```js\nnodeDataArray: [\n  { key: 'Alpha', color: 'lightblue' },\n  { key: 'Beta', color: 'orange' },\n  { key: 'Gamma', color: 'lightgreen' },\n  { key: 'Delta', color: 'pink' }\n]\n```\n\n#### Optional - linkDataArray (DiagramComponent and PaletteComponent only)\n\nSpecifies the array of links for the Diagram's model, only needed when using a [GraphLinksModel](https://gojs.net/latest/api/symbols/GraphLinksModel.html), not for Models or TreeModels. If are using this property, make sure to set the GraphLinksModel's linkKeyProperty in its corresponding initDiagram or initPalette function.\n\n```js\nlinkDataArray: [\n  { key: -1, from: 'Alpha', to: 'Beta' },\n  { key: -2, from: 'Alpha', to: 'Gamma' },\n  { key: -3, from: 'Beta', to: 'Beta' },\n  { key: -4, from: 'Gamma', to: 'Delta' },\n  { key: -5, from: 'Delta', to: 'Alpha' }\n]\n```\n\n#### Optional - modelData (DiagramComponent and PaletteComponent only)\nSpecifies a shared modelData object for the Diagram's model.\n\n#### skipsDiagramUpdate (DiagramComponent only)\nSpecifies whether the Diagram component should skip updating, often set to true when updating state from a GoJS model change. \n\nBecause GoJS Palettes are read-only by default, this property is not present in PaletteComponent.\n\n#### modelChange (DiagramComponent)\nSpecifies a function to be called when a GoJS transaction has completed.\nThis function will typically be responsible for updating app-level state. Remember, these state properties are assumed to be immutable. This example `modelChange`, is taken from the [gojs-angular-basic](https://github.com/NorthwoodsSoftware/gojs-angular-basic) project, which uses [immer](https://github.com/immerjs/immer)'s `produce` function to maintain immutability.\n\nIt is important that state updates made in this function include setting `skipsDiagramUpdate` to true, since the changes are known by GoJS.\n\nBecause GoJS Palettes are read-only by default, this property is not present on PaletteComponent. Although there won't be user-driven changes to a Palette's model due to the read-only nature of Palettes, changes to the nodeDataArray, linkDataArray, or shared modelData props described above allow for a Palette's model to be changed, if necessary.\n\n```js\n// When the diagram model changes, update app data to reflect those changes. Be sure to preserve immutability\n  public diagramModelChange = function(changes: go.IncrementalData) {\n    const appComp = this;\n    this.state = produce(this.state, draft =\u003e {\n      // set skipsDiagramUpdate: true since GoJS already has this update\n      draft.skipsDiagramUpdate = true;\n      draft.diagramNodeData = DataSyncService.syncNodeData(changes, draft.diagramNodeData, appComp.observedDiagram.model);\n      draft.diagramLinkData = DataSyncService.syncLinkData(changes, draft.diagramLinkData, appComp.observedDiagram.model);\n      draft.diagramModelData = DataSyncService.syncModelData(changes, draft.diagramModelData);\n    });\n  };\n```\n\nNotice the use of the three static functions of the `DataSyncService` (`syncNodeData`, `syncLinkData`, and `syncModelData`), which is included with this package to make syncing your app-level data with Diagram / Palette data simple. \n**Be aware**: If you have set your Diagram's [model.nodeKeyProperty](https://gojs.net/latest/api/symbols/Model.html#nodeKeyProperty) or [model.linkKeyProperty](https://gojs.net/latest/api/symbols/GraphLinksModel.html#linkKeyProperty) to anything other than 'key', you will need to pass your Diagram's model as a third parameter to `DataSyncService.syncNodeData` and `DataSyncService.syncLinkData`.\n\n#### observedDiagram (OverviewComponent only)\nSpecifies the [Diagram](https://gojs.net/latest/api/symbols/Diagram.html) which the Overview will observe.\n\n## Migrating to Version 2.0\nThis page assumes use of `gojs-angular` version 2.0, which requires immutable state, unlike version 1.0. It is recommended to use the 2.0 version. If you have a `gojs-angular` project using version 1.x and want to upgrade, reference this section for tips on migrating to version 2.\n\n#### Should I upgrade?\nIn general, yes.\n\nIf you have very simple node and link data, using the latest 1.x version might be okay. But new features and quality of life changes will be published on the 2.x branch moving forward.\n\nVersion 2.0 handles complex nested data much better than the previous version, due to its focus on immutable data. Additionally, it is a bit smaller in file size.\n\nOne may wish to hold off on upgrading if they have lots of operations mutating their `@Input` properties, and they do not want to take the time to rewrite those operations immutably. However, the guide below details one way one could do this. Our [gojs-angular-basic](https://github.com/NorthwoodsSoftware/gojs-angular-basic) sample also has demonstrations of immutably updating `@Input` properties to make such a rewrite easier.\n\n#### Upgrade gojs-angular Version\nUpdate your package.json to require `gojs-angular` version 2.0 or greater, then run `npm install`.\n\nIt is also recommended to upgrade to the lastest version of gojs.\n\n#### Immutability\nThe biggest change with 2.0 is you must enforce immutability of `@Input` properties to your Diagram and Palette components.\n\nSo, for instance, whenever an entry of `diagramNodeData` is updated, removed, or changed, you will need to generate a whole new Array for `DiagramComponent.diagramNodeData`. This can be done in many different ways with many different packages. A popular choice is [immer](https://github.com/immerjs/immer), which exposes a `produce` function that allows one to immutability manipulate their data on a `draft` variable. We will use that function here for demonstration purposes.\n###### The Version 1.0 Way\nIn `gojs-angular` version 1, if you wanted to add some node data to your `diagramNodeData` `@Input` property, you could do so by simply adding to the `diagramNodeData` Array, mutating it. Such as:\n```js\n// When the diagram model changes, update app data to reflect those changes\npublic addNode = function(nodeData: go.ObjectData) {\n  this.skipsDiagramUpdate = false; // sync changes with GoJS model\n  this.diagramNodeData.push(nodeData);\n}\n```\n###### The Version 2.0 Way\nIn `gojs-angular` version 2, that same `addNode` function must be changed so the `diagramNodeData` property is updated immutably (that is, replaced with an entirely new Array). Here is an example of doing that with immer's `produce` function.\n```js\n// When the diagram model changes, update app data to reflect those changes\npublic addNode = function(nodeData: go.ObjectData) {\n  this.state = produce(this.state, draft =\u003e {\n    var nodedata = { id: \"Zeta\", text: \"Zorro\", color: \"red\" };\n    draft.skipsDiagramUpdate = false;\n    draft.diagramNodeData.push(nodedata);\n  });\n}\n```\nNotice we are also using a massive `state` object to hold `gojs-angular` component properties. This makes these kinds of immutable operations (especially if you are using immer, or a package like it) straightforward (see how we were able to update both `skipsDiagramUpdate` and `diagramNodeData` on the same draft variable). \n\nTo see more samples of enforcing immutability with `gojs-angular`, see [gojs-angular-basic](https://github.com/NorthwoodsSoftware/gojs-angular-basic), particularly the modelChange property of the Diagram Component.\n\n#### Additional Considerations\nAdditionally, as of 2.0, PaletteComponent no longer supports `skipsPaletteUpdate` or `modelChange` properties. As GoJS Palettes are read-only by default, their models should not be changing based on user input. Instead, if you need to update their node/link/model data, update their `@Input` properties (immutably, of course).\n\n## License\n\nThis project is intended to be used alongside [GoJS](https://gojs.net/latest/index.html),\nand is covered by the GoJS \u003ca href=\"https://gojs.net/latest/license.html\"\u003esoftware license\u003c/a\u003e.\n\nCopyright 1998-2021 by Northwoods Software Corporation.","funding_links":[],"categories":["Framework Interoperability"],"sub_categories":["Wrappers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNorthwoodsSoftware%2Fgojs-angular","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNorthwoodsSoftware%2Fgojs-angular","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNorthwoodsSoftware%2Fgojs-angular/lists"}