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:

Installation

Goto our release page 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 [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

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 which is basically just typed JavaScript.

We use React to have a project wide default on component handling, data flow and data handling. React also provides the beautiful JSX extension, letting us integrate HTML directly into the source files. With React 18.+ new components should be implemented as functional components, if there are no specific reasons to do otherwise.

For rendering, we use the ForceGraph3D-component of the React Force Graph package, which is based on THREE.js.

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.
3. Download and install 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.
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 and Eslint. Make sure to configure your IDE to use them automatically.

Building

Building is done using Webpack. The final plugin archive is bundled using Gulp. 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.

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).

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 and React Force Graph packages, we use a few additional libraries to support rendering:

1. KaTeX to render LaTeX formulas.
2. Three-Fatline to consistently display lines with thickness.
3. Three-Spritetext to easily convert text into 3d sprites.