=== Web-Engine Graph ===
Contributors: web-engineer
Tags: graph, visualisation, content, site structure, knowledge graph
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.20754
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See your site's posts, pages, terms, users and menus as a graph of connected records, then filter it and lay it out to explore.

== Description ==

Web-Engine Graph draws your site's content as a graph. Each record is a node, and the lines between them are the connections WordPress already holds:

* Posts, pages and your site's own custom post types (published content only)
* Categories, tags and other public taxonomies, joined to the content that uses them
* Users, joined to the content they wrote and to their roles
* Navigation menus and their items, joined to the pages, posts and terms they link to
* Parent and child pages, and the same for any hierarchical post type

The graph opens on a new admin page, Graph, and is built from your own database each time the page is opened.

**Filters.** A stack of filters decides what is on screen. Each filter adds one record type to the graph, and can include or exclude records you pick. Turn on Related and a filter shows only the records of its type that connect to the records shown by the filters with Related off, such as the users who wrote a chosen set of posts. With no filters, everything is shown.

**Layouts.** The same records can be arranged in six ways:

* Manual: you place every record, and nothing moves unless you move it
* Series: the records of one type along a line, in date or alphabetical order, with related records in rows above and below
* Tree: records with parents and children, each parent above its children
* Grouped: one cluster per record type
* Hubs: each record of one type at the centre of the records that connect to it
* Columns: one column per filter, sorted to shorten the lines between neighbouring columns

**Who can use it.** The Graph page is open to Editors and Administrators (any user who can edit other people's posts). Connecting the site to the cloud needs an Administrator.

**Saving.** You can explore, filter and arrange the graph without an account, and every feature works without saving. To save a graph and reopen it later, an Administrator connects the site to a Web-Engine cloud account. Connecting is optional and registration is free. Registering includes agreeing that saved graphs may appear in the cloud's public gallery, as set out on the registration page. Saved graphs belong to the site rather than to one WordPress user.

**Privacy.** The graph view itself makes no call to any outside service. The plugin contacts the Web-Engine cloud only to connect the site and, once connected, to save, list or reopen saved graphs, to open My account, and to say goodbye when the plugin is deleted. It adds no analytics or tracking. The External services section below lists exactly what is sent and when.

The plugin adds nothing to your site's public pages.

== Installation ==

1. In your WordPress admin, go to Plugins > Add New Plugin and search for "Web-Engine Graph", or upload the plugin's zip file from that screen.
2. Click Install Now, then Activate.
3. Open Graph in the admin menu. Your site's graph is drawn straight away.
4. Optional, to save graphs: as an Administrator, click Register on the Graph page. A Web-Engine cloud page opens in a new tab; sign in or register there and approve the connection. The tab closes itself, and a Save button appears on the Graph page.

== Frequently Asked Questions ==

= Do I need an account? =

No. The graph, the filters and the layouts all work without one. An account is needed only to save a graph and reopen it later. Registration is free.

= Is the plugin free? =

Yes. Everything in the plugin is free, with or without a cloud account. The Web-Engine cloud offers optional paid features of its own; the plugin does not need them.

= Can I use it without connecting to the cloud? =

Yes. Without a connection the graph is drawn from your site's database and nothing is sent anywhere. Your changes last until you leave the page; the page warns you before you leave with unsaved changes.

= What is sent to the cloud? =

Nothing, until an Administrator connects the site. After that, the site contacts the cloud only when someone saves, lists or reopens saved graphs, or opens My account, and when the plugin is deleted. A save contains the records that were on screen at the time: each one's title or name, type, link, WordPress ID and publication date, and the connections between them. For users, that is their display name, the link to their author page and their roles. It never contains post content, email addresses or passwords. The External services section has the full list. Saved graphs may be shown in the cloud's public gallery, as agreed when registering.

= Who can see the graph? =

In WordPress, users who can edit other people's posts: Editors and Administrators by default. The page reads every published post, term, user and menu on the site, so it is not offered to Authors, Contributors or Subscribers.

= How do I disconnect or remove my data? =

Deleting the plugin from the Plugins screen removes the options it stored in WordPress. If no other Web-Engine plugin (such as Web-Engine Sentry) is installed, it also tells the cloud the site is leaving, the cloud revokes the site's access, and the site's connection details are deleted. If another Web-Engine plugin is installed, the connection is left for that plugin to use.

Deleting the plugin does not ask the cloud to delete graphs you have saved. To have them deleted, contact support@web-engineer.co.uk.

= Does it work on multisite? =

Yes. Each site in a network has its own graph, built from that site's content, and its own cloud connection. Deleting the plugin removes its data from every site in the network.

= Is anything tracked? =

No. The plugin contains no analytics or tracking code and loads no scripts, fonts or images from other servers: all its JavaScript is bundled with the plugin.

= Is there a limit on how much is drawn? =

By default the graph reads up to 500 posts of each post type, 200 terms of each taxonomy and 500 users, so that a large site still produces a graph a browser can draw. Developers can change these limits with the `we360cloud_graph_max_records` filter.

== Screenshots ==

1. The graph of a site in the Manual layout, with posts, pages, terms and users joined by their connections.
2. The filter stack, choosing which record types are shown and which records are included or excluded.
3. The Layout window, with a site's pages arranged as a Tree.
4. The list of saved graphs, ready to reopen.

== External services ==

This plugin can connect to the Web-Engine cloud (https://www.we360.cloud), a service operated by Web Engine Limited, to save graphs and reopen them later. The connection is optional. Drawing, filtering and arranging the graph uses only your site's own database and makes no call to the cloud.

The site talks to the cloud only in the circumstances below. Every request after connecting carries the site's access token.

* Connecting: when an Administrator clicks Register, their browser opens a page on www.we360.cloud carrying the Administrator's email address, their name (first and last name, or display name if those are empty), the site's domain, the address to return to on the site, and a one-time security code. Once they approve, the site exchanges a code for an access token with the cloud directly, sending the site's domain.
* Checking the connection: when a graph is saved, and when the cloud refuses a request, the site asks the cloud for the connection's status. No site content is sent.
* Saving a graph: the site sends the graph's name, its filters, its layout positions, its colours and display settings, and a snapshot of the records on screen with the connections between them. Each record carries its title or name, type, link, WordPress ID and, for content, its publication date. User records carry the display name, the author page link and roles. The save also records the site's domain and the plugin's version. Post content, excerpts, email addresses and passwords are not sent. A large save is sent in several parts.
* Public gallery: registering with the cloud includes agreeing that saved graphs may be shown in its public gallery. A graph in the gallery shows only what was visible when it was saved, such as record titles, and no links.
* Listing and reopening saved graphs: the site asks the cloud for the list of saved graphs, the saves within one, and the filters, layout and colours of the save being opened. The records themselves are read from your site again, not from the save.
* Opening My account: the site sends its domain to the cloud and receives a sign-in link for the cloud's dashboard.
* Uninstalling: when the plugin is deleted and no other Web-Engine plugin is installed, the site sends its domain to the cloud so the cloud can revoke its access token.

The plugin sends nothing else. It contains no analytics or tracking, loads no assets from a content delivery network, and bundles all of its JavaScript.

Web-Engine cloud terms of service: https://www.we360.cloud/terms-of-service
Web-Engine cloud privacy policy: https://www.we360.cloud/privacy-policy

== Source code ==

The admin page's JavaScript, `dist/buttercup-wordpress.js`, is compiled and minified. Its human-readable source ships with the plugin:

* `src/`: the admin page, written in TypeScript and React
* `buttercup/`: the graph engine, in TypeScript

The bundle is built from `src/index.ts` with `@wordpress/scripts` (webpack), TypeScript and Tailwind CSS. React, ReactDOM and `@wordpress/i18n` are taken from WordPress rather than bundled. The licences of the bundled third-party code are listed in `dist/buttercup-wordpress.js.LICENSE.txt`.

The PHP in `lib/` is not compiled.

== Changelog ==

= 1.0 =
* First release.
* Draws a site's posts, pages, custom post types, terms, users, roles and menus as a graph of connected records.
* Filter stack with include, exclude and related filters.
* Six layouts: Manual, Series, Tree, Grouped, Hubs and Columns.
* Optional saving to a Web-Engine cloud account, with a history of saves for each graph.
