{"id":28033011,"url":"https://github.com/terriajs/plugin-sample","last_synced_at":"2025-08-10T16:09:19.862Z","repository":{"id":40471294,"uuid":"474782530","full_name":"TerriaJS/plugin-sample","owner":"TerriaJS","description":"A sample terriajs plugin that adds a mode for drawing 3d boxes","archived":false,"fork":false,"pushed_at":"2024-04-30T06:58:15.000Z","size":1127,"stargazers_count":1,"open_issues_count":7,"forks_count":3,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-11T09:08:20.486Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TerriaJS.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,"zenodo":null}},"created_at":"2022-03-27T23:13:22.000Z","updated_at":"2024-03-21T21:52:21.000Z","dependencies_parsed_at":"2025-05-11T09:08:21.600Z","dependency_job_id":"390f4707-a614-4946-b902-e08e25bc62da","html_url":"https://github.com/TerriaJS/plugin-sample","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/TerriaJS/plugin-sample","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TerriaJS%2Fplugin-sample","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TerriaJS%2Fplugin-sample/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TerriaJS%2Fplugin-sample/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TerriaJS%2Fplugin-sample/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TerriaJS","download_url":"https://codeload.github.com/TerriaJS/plugin-sample/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TerriaJS%2Fplugin-sample/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269748230,"owners_count":24469107,"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","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-05-11T09:07:57.688Z","updated_at":"2025-08-10T16:09:19.842Z","avatar_url":"https://github.com/TerriaJS.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TerriaJS sample plugin\n\nThis repository implements a sample TerriaJS plugin. The plugin implements a\ncustom tool for drawing an interactive 3D box on the map. It serves as an\nexample for setting up an loading an external plugin library that adds some new\nfunctionality to Terria without forking it.\n\nPlugins allow extending Terria in two ways:\n\n  - By adding support for new data formats or APIs through implementing new [catalog item ](https://docs.terria.io/guide/connecting-to-data/catalog-items/) types. \n  - and extending the UI in limited ways to create custom workflows.\n\nThis plugin code utilizes these additional peer dependencies from the TerriaJS\nlibrary and are pre-requisites for understanding the code:\n\n- [terriajs-plugin-api](https://github.com/terriajs/plugin-api) - for interfacing with the TerriaJS library.\n- [CesiumJS](https://github.com/cesiumgs/cesium/) - The 3D mapping library\n- [mobx](https://mobx.js.org/) - Reactive state management library\n- [ReactJS](https://react.dev/)\n- [styled-components](https://styled-components.com/)\n- [yarn](yarnpkg.com) - Package manager\n\n\nAdditional documentation for developing with terria is available at\n[https://docs.terria.io](https://docs.terria.io/). You can also reach us through our [discussion forum](https://github.com/TerriaJS/terriajs/discussions) if you require additional help.\n\n\nThis plugin repository is a work in progress and will be updated as the different\nAPIs evolve. Meanwhile expect breaking changes 👷\n\n### Current status\n- [x] Load external plugins in TerriaJS at build time\n- [x] Support for registering custom data types (aka catalog items)\n- [x] Initial, limited support for extending UI to add custom workflows\n- [ ] Testing\n- [ ] Linting\n\n# Adding the plugin to your terriamap\n\n### Clone terriamap\n```bash\ngit clone https://github.com/terriajs/terriamap\ncd terriamap\n```\n\n### Add this plugin as dependency in package.json\n```bash\nyarn add -W 'terriajs-plugin-sample'\n```\n\n### Add it to the plugin registry file `plugins.ts`\n```typescript\nconst plugins: any[] = [\n  import(\"terriajs-plugin-sample\")\n];\n...\nexport default plugins;\n```\n\nNote: The file `plugins.ts` is in the terriamap project root directory.\n\n### Now build your terriamap and start the server\n\n```\n# From the terriamap directory run\nyarn run gulp dev\n```\n\nOnce the server is running visit http://localhost:3001 to load the app. You should see a new plugin button added to the map toolbar on the right hand side. Opening the tool will prompt the user to draw a rectangle on the map, this will place a 3d box of the same dimension on the map. Screenshot of the plugin in action:\n\n![Sample plugin](sample-plugin.png \"Sample plugin\")\n\n# Plugin development workflow\n\nThis section assumes you have completed the steps for [adding the plugin to your terriamap](#adding-the-plugin-to-your-terriamap).\n\nDeveloping the plugin requires correctly setting up the yarn workspace. Your local directory structure should look something like:\n```\nterriamap/\n  packages/\n  ├── plugin-sample\n  └── terriajs\n```\n\nThe `terriajs` and  `plugin-sample` repositories must be checked out under `terriamap/packages/` folder\n\n\n### Checkout terriajs and sample-plugin into the packages folder\n\n```bash\ncd terriamap/\nmkdir -p packages\ngit clone https://github.com/terriajs/terriajs packages/terriajs\ngit clone https://github.com/terriajs/plugin-sample packages/plugin-sample\n```\n\n### Add the plugin package to the [yarn workspace](https://classic.yarnpkg.com/lang/en/docs/workspaces/) settings of your terriamap `package.json` file.\n\nEdit `package.json` for terriamap:\n\n```json\n  {\n  \"private\": true,\n  \"workspaces\": {\n    \"packages\": [\n      \"packages/terriajs\",\n      \"packages/cesium\",\n      \"packages/terriajs-server\"\n      \"packages/plugin-sample\" // \u003c-- plugin-sample added here\n    ],\n\n   ...\n   \n   \"dependencies\": {\n    \"terriajs-plugin-api\": \"0.0.1-alpha.16\",\n    \"terriajs-plugin-sample\": \"0.0.1-alpha.8\", // \u003c-- plugin-sample version should match the version in packages/plugin-sample/package.json\n```\n\n### Build terriamap \n\nFrom your `terriamap` folder run:\n\n```bash\nyarn install\n# Starts a terriamap dev server that watches for code changes and rebuilds the map\nyarn run gulp dev\n```\n\n### Build plugin-sample\n\n```bash\ncd terriamap/packages/plugin-sample\n# Start a plugin build process that watches for file changes\nyarn run watch\n```\n\nNote: you need to keep both the yarn commands running, then start making make changes to the plugin code, terriamap will automatically\nrebuild your changes. \n\nWatch for errors from the plugin build process. Note that the app page doesn't reload automatically when the code rebuilds, you\nhave to refresh the page to see your changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterriajs%2Fplugin-sample","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterriajs%2Fplugin-sample","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterriajs%2Fplugin-sample/lists"}