Differences

This shows you the differences between two versions of the page.

--- plugin:diagrams [2021-01-18 18:34] – Aleksandr
+++ plugin:diagrams [2024-01-06 00:29] (current) – Aleksandr
@@ Line 5: / Line 5: @@
 author     : Andreas Gohr, Anna Dabrowska
 email      : dokuwiki@cosmocode.de
-type       :
+type       : action, syntax
-lastupdate : 2021-01-18
+lastupdate : 2023-12-14
-compatible : Hogfather
+compatible : Jack Jackrum, !Igor
 depends    :
-conflicts  :
+conflicts  : anchor
 similar    : drawio, diagramsnet
 tags       : diagram
@@ Line 17: / Line 17: @@
 sourcerepo : https://github.com/cosmocode/dokuwiki-plugin-diagrams/
-screenshot_img :
+screenshot_img : https://i.imgur.com/8W31Onh.png
 ----
-[[https://www.cosmocode.de/en/open-source/dokuwiki-plugins/|{{ http://cosmocode.de/static/img/dokuwiki/dwplugins.png?recache|A CosmoCode Plugin}}]]
+[[https://www.cosmocode.de/en/open-source/dokuwiki-plugins/|{{ https://www.cosmocode.de/static/img/dokuwiki/dwplugins.png?recache|A CosmoCode Plugin}}]]
 ===== Installation =====
-Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.
+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
 ===== Usage =====
@@ Line 30: / Line 30: @@
 This plugin lets users create and edit diagrams in DokuWiki. In provides an integration with the online diagramming tool [[https://www.diagrams.net/|diagrams.net]], previously known as draw.io.
-The diagrams are internally saved as SVG images and treated as regular media files. That means storing older versions of files and applying [[:acl|ACL]] permissions for editors.
+==== Diagram Storage Modes ====
+The plugin provides two different ways to store the resulting diagrams:
+  - **mediafile mode** When using this mode, diagrams are saved as SVG images as regular media files. That means storing older versions of files and applying [[:acl|ACL]] permissions for editors happens on a per diagram basis. The same diagram can be used on many pages. This is enabled by default.
+  - **embed mode** When using this mode, the actual SVG code is embedded directly into a wiki page using the ''<diagram>'' syntax. Editing a diagram always edits the page it is embedded on (creating a new page version) and ACLs match that of the page.
+Which modes are available to your users is configured in the plugin's configuration settings.
+Please note that diagrams can not easily be transferred from one mode to the other.
 ==== Create a diagram ====
-Diagrams are created in the media manager, either the [[:fullscreen_mediamanager|fullscreen version]] or the [[:media_manager| media manager popup window]]. Just select the right namespace and click on the ''Create diagram'' link. Next, enter the file name for the diagram in the dialog that appears. Do not use any special characters here. You will be redirected to diagrams.net where you can create your diagram. Clicking on the ''Save'' button will take you back to your wiki.
+Creating a diagram differs depending on the used storage mode:
+  - **mediafile mode** Diagrams are created in the media manager, either the [[:fullscreen_mediamanager|fullscreen version]] or the [[:media_manager| media manager popup window]]. Just select the right namespace and click on the ''Create diagram'' link. Next, enter the file name for the diagram in the dialog that appears. Do not use any special characters here. You will be redirected to diagrams.net where you can create your diagram. Clicking on the ''Save'' button will take you back to your wiki.
+  - **embed mode** A new toolbar button allows you to insert a new diagram. Clicking the button will open the diagrams.net Editor and when saving the diagram is inserted at the current cursor position.
+==== Insert a diagram ====
+  - **mediafile mode** Diagrams are inserted using the standard [[wiki:syntax#media_files|Image syntax]]
+  - **embed_mode** Additional parameters for the toolbar button inserted ''<diagram>'' syntax can be used. Alignment can be picked via the ''left'', ''right'' and ''center'' keywords. Sizes can be given as ''//width//x//height//'' in pixels. Eg. ''%%<diagram center 300x200>%%''.
 ==== Edit a diagram ====
-Edit buttons are available in two places:
+Existing diagrams can always be edited from viewing a page that uses the diagram. The diagram will have a "Edit Diagram" button if the current user has the appropriate permissions to edit the diagram. This works for both storage modes.
-  * in the [[:fullscreen_mediamanager|fullscreen media manager]] in the ''View'' tab, which is displayed when an image is selected
-  * on a wiki page with an embedded diagram (only if the user has [[:acl|upload permissions]] for the given diagram file).
+Depending on the storage mode, edits can also happen elsewhere:
+  - **mediafile mode** In the [[:fullscreen_mediamanager|fullscreen media manager]] in the ''View'' tab, an "Edit Diagram" button will be displayed when a diagram image is selected
+  - **embed mode** When editing a page, the cursor can be positioned on the syntax of an embedded diagram, clicking the toolbar button will then edit this existing diagram instead of creating a new one
+==== Prosemirror Support ====
+This plugin support the [[plugin:prosemirror|Prosemirror WYSIWYG Plugin]] for both modes. New diagrams can be inserted via the toolbar. Diagrams are shown within the editor (interactive mechanisms like links are disabled in the editor) on click their properties can be changed and the diagram editor can be opened.
+==== PNG Caching ====
+The plugin works with SVGs by default. However SVGs created by diagrams.net use certain features (most notably multiline and formatted texts) that only work, when the SVG is displayed in a Webbrowser. This means that those features will be lost when exporting to PDF using the [[dw2pdf|dw2pdf Plugin]]. Please note that this is not true when using the browser's "Print to PDF" mechanism.
+To work around this, the Plugin can optionally save a PNG based cache file for each diagram on saving and use that cache file when exporting to PDF. Enable the ''pngcache'' option in the configuration of the plugin to enable it. Please note that only diagrams saved //after// enabling this option will have PNG cache file. You will need to resave your existing diagrams to make use of that feature.
+===== Comparison =====
+This plugin was inspired by a few other plugins that integrate diagrams.net/draw.io into DokuWiki. Below you can find a small feature comparison.
+^                            ^ **[[plugin:diagrams]]**\\ (this one)  ^ [[plugin:diagramsnet]]  ^ [[plugin:drawio]]                 ^
+^ Format                     | SVG (PNG optional for PDF Exports)    | PNG                     | PNG (SVG with additional Plugin)  |
+^ Storage                    | mediafile, embed                      | mediafile               | mediafile                         |
+^ Links in Diagrams          | ✅ yes                                   | ❌ no                      | ❌ no                                |
+^ Custom Diagrams Host       | ✅ yes                                   | ✅ yes                     | ✅ yes                               |
+^ Draft saving for Diagrams  | ❌ no                                    | ❌ no                      | ✅ yes                               |
+^ PDF Export                 | ✅ yes                                   | ✅ yes                     | ✅ yes                               |
+^ ODT Export                 | ❌ no                                    | ❌ no                      | ❌ no                                |