README.md

# Knowledge Space WordPress Plugin

Plugin for the WordPress CMS to display knowledge as structured data in a 3-dimensional graph. 
Nodes can provide useful information on their topic via several media components, including text, images, videos and references.

An example of the knowledge-space for the lecture "Algorithmen und Datenstrukturen 1" looks like this:
![example](docs/images/example_aud.png)

## Installation
Goto our [release page](https://gitlab.ibr.cs.tu-bs.de/alg/knowledge-space-wp-plugin/-/releases) and download the latest version of the "Plugin Zip Archive".

On your WordPress admin page, click on plugins and then click on the install-button on the top of the page.
Now click on the upload-plugin-button and select the downloaded plugin archive.
Go back to your plugin page and activate the knowledge-space plugin.
After installation, you should have access to the Knowledge-Space-Editor in the WordPress admin panel.

## Usage
The Knowledge-Space Plugin features a *frontend* which displays the 3d-graph and a *backend* which is only available through the admin panel and serves as an editor.
The user can define and manage multiple separate knowledge-spaces independently.

### Frontend
A knowledge space renderer can be included in any WordPress site or post by using the shortcode [knwoledge-space space="Your-space-name-here"].
This shortcode has a required parameter `space` to specify the name of the knowledge-space which should be rendered.

The shortcode also has a second optional parameter `mode` which can be set to `demo` if all click events should be disabled.

### Backend
TODO: Add editor description here.

# Development
The following section is only relevant for developers.

## Installation
If you already have a running WordPress installation on your computer you can skip to point three.

1. Install a webserver which supports PHP (e.g. apache) and a database (e.g. MySQL).
2. Download and setup [WordPress](https://wordpress.org/download/).
3. Clone the repository into the WP-directory wp-conntent/plugins.
4. Activate the plugin in WordPress in the admin control page.
5. Install dependencies with npm using ``npm ci``. (Warning: Do not install the packages using `npm install` as this will automatically use the newest version of every package!)

This project uses [Prettier](https://prettier.io/) and [Eslint](https://eslint.org/). 
Make sure to configure your IDE to use them automatically.

## Building
Building is done using [Webpack](https://webpack.js.org/).
The final plugin archive is bundled using [Gulp](https://gulpjs.com/).
The build process depends on the desired use case.
Building for development creates larger files which also include source maps to enable easier debugging.

### For Development
For development we recommend to use the NPM command ``npm run watch``.
This starts a webpack instance which automatically builds the project on every file change.
Building the project this way creates all source maps needed for debugging and omits some minification and optimization steps.
Files are stored in the ``build/debug`` folder.

### For Pre-Release Testing
To build with development settings without actually creating a WordPress plugin ZIP archive, run ``npm run build``.
This stores the files under ``build/release`` and produces the same output as when building for release, but omits bundling the plugin.
To use pre-relase builds instead of debug build with the development plugin installation, change the global variable `build` in the ``knowledge-space.php`` file from `debug` to `release`.

### For Release
To create a release-build which outputs a plugin archive, run `npm run distribute`.
This will create a ZIP archive which can be directly uploaded to the WordPress Plugin page.

A new official release is automatically build when pushing a new `git tag` to the `main` branch.
We recommend to use `npm version` to create new versions and tags, as it automatically increments the version number in the `package.json` correctly.
For example for a patch use `npm version patch`, for a minor feature `npm version minor` and for a major feature `npm version major`.
For more information see the official [docs](https://docs.npmjs.com/cli/v8/commands/npm-version).