Plugin for the WordPress CMS to display knowledge as structured data in a 3-dimensional graph.
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:
## 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.
...
...
@@ -16,22 +18,62 @@ 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 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 [knowledge-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.
The backend gives you access to an editor that looks like this:
### Managing spaces
On the top left, you can select your desired space to work on. Currently the space called "space" is selected and thereby also shown below in a 2D view.
Next to the currently selected space, you can find the "Space manager". This button opens a pop-up, that allows you to create, duplicate, rename and delete spaces. A space name has to be unique and certain special characters are automatically replaced.
### Editor graph
The graph view gives you a 2D overview of the graph you are working on.
Use simple drag-n-drop to move around and the mouse wheel to zoom in and out.
You can select the nodes you want to edit with a simple Click. Holding down Shift, you can drag-n-drop a selection area, to easily select multiple nodes at once.
Holding Control and left-clicking on the background, creates new nodes, whereas simply right-clicking a node (or link) will delete the element.
Having at least one node select, and then holding down Control while performing a Click on another node, connects them with a link.
All possible interactions are listed in the "Help"-section of the sidebar.
### Sidebar
On the top of the sidebar, you have basic history management. Most importantly, use the "Save" button to save your changes in the database, so that they will be rendered in the frontend. Otherwise, your changes wont be saved and will be lost when closing the tab.
The dropdown list shows you your edit history, so you can easily jump to any savepoint you want, while the "Undo" and "Redo" buttons simply move one step back/forth in your edit history.
Below that, you find 3 tabs.
The "Edit"-tab allows you to edit all relevant properties of one, or multiple selected nodes. When having multiple nodes selected, it might not allow you to edit all properties. All changes are immediately reflected in the graph view. Make sure to use absolute URLs for the images. The icon image is rendered in the graph view over the node, while the banner is rendered in the infon-bar in the frontend.
The "Types"-tab helps you manage all types available in this space. Use the "Add type" button to create a type called "Unnamed". Use the dropdown menu to select the desired type to edit. Below, you can edit the name of the type and the color, with the color being split into its 3 color-components Red, Green and Blue. Clicking "Select nodes" will select all nodes that use the selected type, and "Delete" simply deletes the type. Nodes that use the deleted type, will get another type from the list. You always need to have at least one type.
The "Help"-tab gives you a few settings and lists all available interactions with the graph. Having "Node labels" checked means that labels of nodes are rendered in the graph view. The option "Connecct nodes when dragged" enables a special link-creation interaction. When enabled, nodes that are dragged close enough to each other, will automatically create a link to be connected.
# Development
The following section is only relevant for developers.
## Overview
This project is written in [Typescript](https://www.typescriptlang.org/) which is basically just typed JavaScript.
We use [React](https://reactjs.org/) to have a project wide default on component handling, data flow and data handling.
...
...
@@ -41,54 +83,60 @@ With React 18.+ new components should be implemented as functional components, i
For rendering, we use the `ForceGraph3D`-component of the [React Force Graph](https://github.com/vasturiano/react-force-graph) package, which is based on [THREE.js](https://threejs.org/).
## 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. Download and install [NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). We use NPM to manage dependencies.
4. Clone the repository directly into the WordPress-plugin-directory which is located at ``/wordpress-path/wp-conntent/plugins``.
4. Clone the repository directly into the WordPress-plugin-directory which is located at `/wordpress-path/wp-conntent/plugins`.
5. Cd into the directory and install the dependencies using `npm ci`. (Warning: Do not install the packages using `npm install` as this might select new package versions and will overwrite `package-lock.json`!)
6. Navigate to the plugin page using the WordPress admin panel and activate the plugin.
This project uses [Prettier](https://prettier.io/) and [Eslint](https://eslint.org/).
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``.
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.
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`.
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).
For more information see the official [docs](https://docs.npmjs.com/cli/v8/commands/npm-version).
## Project Structure
The plugin code will be loaded by WordPress. The content is defined in the main plugin file ``knowledge-space.php`` (also see [WordPress plugin basics](https://developer.wordpress.org/plugins/plugin-basics/)).
TypeScript code between frontend (`src/display`) and backend (`src/editor`) is separated.
The plugin code will be loaded by WordPress. The content is defined in the main plugin file `knowledge-space.php` (also see [WordPress plugin basics](https://developer.wordpress.org/plugins/plugin-basics/)).
TypeScript code between frontend (`src/display`) and backend (`src/editor`) is separated.
Common data structures or components can be found in `src/common`.
## Dependencies
Besides the [React](https://reactjs.org/) and [React Force Graph](https://github.com/vasturiano/react-force-graph) packages, we use a few additional libraries to support rendering:
1.[KaTeX](https://katex.org/) to render LaTeX formulas.
2.[Three-Fatline](https://github.com/vasturiano/three-fatline) to consistently display lines with thickness.
3.[Three-Spritetext](https://github.com/vasturiano/three-spritetext) to easily convert text into 3d sprites.
