#### Getting Started Requirements: **NodeJS 6 LTS** and **npm 3** in your PATH. 1. Check the folder structure. An exported (compiled) **virtualcityMAP** must be in the _vcm_ path, relative to the root of your project ``` - . |- build/ |- src/ |- test/ |- vcm/ <- needs to be copied |- .babelrc |- package.json ``` 2. Install all the needed dependencies using `npm install` 3. To run the examples, execute `npm run examples` #### Reading the _docs_ Once you have the development server running, you will find the documentation of the **vcm** API at [http://localhost:8081/doc/index.html](http://localhost:8081/doc/index.html). Further reading: - [Vuejs](https://vuejs.org/) - [vue-router](https://router.vuejs.org/en/) - [vuex](https://vuex.vuejs.org/en/) - [openlayers](https://openlayers.org/en/latest/apidoc/index.html) - [Cesium](https://cesiumjs.org/Cesium/Build/Documentation/index.html) ### Writing your own plugin Using the examples as a basis, you can start writing your own plugins. Make sure to register your plugin by calling `vcs.ui.registerPlugin(options)`. To start writing your own plugin, simple use the `src/index.js` as an entry point for your own plugin. To stop running the examples, and run you own plugin, start the dev server with `npm start`. It is important to only write _a single plugin_ and only call _vcs.ui.registerPlugin_ **once**. Otherwise the build process will not properly run through and the configuration with the **virtualcityPUBLISHER** becomes impossible. Once you are satisfied with your plugin, you can build it using `npm run build`. This will create a zip-file containing your applications **bundled code** and **assets**. To add your plugin to the **virtualcityPUBLISHER**, unzip the contents of this file into the `root/public/plugins/` folder. The structur of the `public/plugins/` folder must look like this: ``` public/plugins |- myPlugin/ |- assets/ |- myPlugin.js |- config.json |- mySecondPlugin/ |- assets/ |- mySecondPlugin.js |- noAssetsPlugin/ |- noAssetsPlugin.js |- config.json ``` Your plugin can now be added to **virtualcityMAP**s. To ensure the usage of your plugin in a **virtualcityMAP** with a specific map version, set the `vcm` property in the `package.json`s _engine_ property. The `package.json` is shipped with your plugin, use it to define the current _version_ of your plugin, the author and supported **virtualcityMAP** version. To add your plugin to a deployed map, simply unzip the distribution into a folder `plugins/`. Add your plugin to a deployed map, by adding your plugin to the `config.json` under _ui.plugins_ and providing the name of your served plugin as the key (this is especially useful if you wish to pass configurations to your plugin): > This only works properly of you maintain the folder structure provided by the build script > and use the `plugins/` directory on your server. > If you use the virtualcityPUBLISHER to create your maps, this should not be an issue. ```json ..., "ui": { "plugins": { "myPlugin": { ... } } } ``` #### Adding static data to your plugin You may wish to add your own icons, images or other forms of static content. For this, use the `assets/` folder. You can then request your resource with `assets/yourResource`. The build script will automatically change this URLs to `plugins/myPlugin/assets/yourResource` for ease of deployment #### Adding configuration to your plugin Some plugins might need configuring. You can add your configuration to the vcm's `config.json` in the section _ui.plugins.myPlugin_ as shown above. To allow for a configuration of your plugin by the **virtualcityPUBLISHER**, you can specify the configurable parameters of your plugin in the `config.json` found in the root of your application. Add the keys and their default values to this JSON. ```json { "myKey": "defaultValue", "myNumeric": 123, "myBoolean": true, "myArray": [1, 2, 3] } ``` #### Testing your plugin Test are written for the `mocha` test framework, using `chai` for assertation and `sinon` for spies, stubs and mocks and `karma` as a test runner. To run the tests, run `npm test`. In the `test/` directory you will find a small example _spec_.