Help:Diagrams: Difference between revisions

(One intermediate revision by the same user not shown)

Line 35:

== Showing a diagram on another page ==

Diagram pages are '''not''' transcluded with the usual double braces. Use ~~the <code>#display_diagram</code> parser function instead~~, naming the diagram page including its namespace:

Diagram pages are '''not''' transcluded with the usual double braces. Use [[Template:Diagram]], naming the diagram page including its namespace:

<pre>

</pre>

That renders the diagram inline wherever you put it, so an article can show a diagram that is maintained on its own page. Each section below gives the exact line for that format's example.

'''You do not have to type any of that.''' In the visual editor, diagrams can be added, repointed and opened for editing without touching wikitext — see [[#Using the visual editor|Using the visual editor]] below.

The older form <code><nowiki>{{#display_diagram:Mermaid:Meter capture chain}}</nowiki></code> still works and renders identically. Prefer the template: <code>#display_diagram</code> is a parser function, and the visual editor can edit a template's parameters but not a parser function's target, so bare calls can only be changed by editing the page source.

'''One limit to know about:''' a single page can contain '''at most one BPMN or Gantt''' diagram — the extension gives both of them the same internal element name, so a second one on the same page is refused with an error message. Mermaid, DOT and Drawio can be embedded as many times as you like.

== Using the visual editor ==

''Screenshots for this section have not been uploaded yet. Each caption below names the file to upload — for example <code>FlexDiagrams VE insert template.png</code> — so uploading under that exact name fills the slot with no further edit to this page.''

Everything here works in the ordinary visual editor. Nothing below requires editing wikitext.

=== Adding a diagram to a page ===

Put the cursor where the diagram should go, then '''Insert → Template'''. Type <code>Diagram</code> and choose it.

[[File:FlexDiagrams VE insert template.png|thumb|none|700px|The Insert → Template dialog with "Diagram" typed into the search box.]]

Fill in the '''Diagram page''' field with the diagram's full page name, ''including'' its namespace prefix — <code>Mermaid:</code>, <code>DOT:</code>, <code>Drawio:</code>, <code>BPMN:</code> or <code>Gantt:</code>. The field suggests existing pages as you type, so you rarely need to type the whole name.

[[File:FlexDiagrams VE diagram field.png|thumb|none|700px|The Diagram page field, suggesting existing diagram pages as you type.]]

Insert, and save the page as usual.

=== What a diagram looks like while editing ===

An embedded diagram does '''not''' appear as a picture in the visual editor. It shows as a single labelled line naming the diagram, like:

◈ Mermaid:RE FlowChart Overview — diagram, edit it on its own page

[[File:FlexDiagrams VE placeholder.png|thumb|none|700px|An embedded diagram as it appears while editing: one labelled line rather than the rendered picture.]]

That is deliberate. The visual editor cannot run the diagram renderer, so without it you would see the diagram's raw source — dozens of lines of flowchart code — sitting in the middle of the article. The line above is shown instead. Save or preview the page to see the diagram itself.

=== Editing the diagram ===

'''Double-click''' the line. The diagram's own editor opens '''in a new tab''', leaving your article edit untouched in the original tab. Edit the diagram, save it there, then return to your article.

=== Changing which diagram is shown ===

'''Single-click''' the line to select it. A small box appears with two choices:

* '''Edit "…" ↗''' — opens that diagram's editor in a new tab, the same as double-clicking.

* '''Change which diagram is shown''' — opens the template's settings so you can point this embed at a different diagram page.

[[File:FlexDiagrams VE context menu.png|thumb|none|700px|Selecting an embedded diagram: edit the diagram itself, or change which diagram the page shows.]]

Single-clicking also selects the diagram as a block, so <code>Backspace</code> removes the embed from the article — which deletes only the embed, never the diagram page itself.

=== If you edit the source instead ===

The visual editor is not required. In the source editor the same embed is one line:

<pre>

</pre>

Both editors produce exactly the same thing, and you can move between them freely.

== Mermaid ==

Line 65:

Line 122:

<pre>

</pre>

which renders as:

See [https://mermaid.js.org/intro/ the Mermaid documentation] for the full syntax. This wiki bundles '''Mermaid 11.17.2''', so the Mermaid 11 diagram types — architecture, packet, kanban, treemap and radar — all work. Diagram types added in Mermaid 12 will not render, and <code>layout: elk</code> is not available (it falls back to the default layout silently). The default look is <code>handDrawn</code>; override it per diagram with <code>%%{init: {'look': 'classic'}}%%</code>.

Line 99:

Line 156:

<pre>

</pre>

which renders as:

[[File:FlexDiagrams DOT editor.png|thumb|none|700px|The DOT editor: Graphviz source in the text box, with the rendered graph above it.]]

Line 117:

Line 174:

<pre>

</pre>

which renders as:

'''One thing to know:''' the Drawio editor is loaded from the external site <code>embed.diagrams.net</code> while you are editing. Your diagram is saved here on the wiki, not on their servers, and viewing a saved Drawio diagram does not contact them at all — but ''editing'' one needs that external site reachable from your browser. The other four formats are served entirely from this wiki.

Line 137:

Line 194:

<pre>

</pre>

which renders as:

That embed uses this page's one BPMN-or-Gantt slot; a second diagram of either type on the same page would be refused.

Line 157:

Line 214:

<pre>

</pre>

@@ Line 35: / Line 35: @@
 == Showing a diagram on another page ==
-Diagram pages are '''not''' transcluded with the usual double braces. Use the <code>#display_diagram</code> parser function instead, naming the diagram page including its namespace:
+Diagram pages are '''not''' transcluded with the usual double braces. Use [[Template:Diagram]], naming the diagram page including its namespace:
 <pre>
-{{#display_diagram:Mermaid:Meter capture chain}}
+{{Diagram|page=Mermaid:Meter capture chain}}
 </pre>
 That renders the diagram inline wherever you put it, so an article can show a diagram that is maintained on its own page. Each section below gives the exact line for that format's example.
+'''You do not have to type any of that.''' In the visual editor, diagrams can be added, repointed and opened for editing without touching wikitext — see [[#Using the visual editor|Using the visual editor]] below.
+The older form <code><nowiki>{{#display_diagram:Mermaid:Meter capture chain}}</nowiki></code> still works and renders identically. Prefer the template: <code>#display_diagram</code> is a parser function, and the visual editor can edit a template's parameters but not a parser function's target, so bare calls can only be changed by editing the page source.
 '''One limit to know about:''' a single page can contain '''at most one BPMN or Gantt''' diagram — the extension gives both of them the same internal element name, so a second one on the same page is refused with an error message. Mermaid, DOT and Drawio can be embedded as many times as you like.
+== Using the visual editor ==
+''Screenshots for this section have not been uploaded yet. Each caption below names the file to upload — for example <code>FlexDiagrams VE insert template.png</code> — so uploading under that exact name fills the slot with no further edit to this page.''
+Everything here works in the ordinary visual editor. Nothing below requires editing wikitext.
+=== Adding a diagram to a page ===
+Put the cursor where the diagram should go, then '''Insert → Template'''. Type <code>Diagram</code> and choose it.
+[[File:FlexDiagrams VE insert template.png|thumb|none|700px|The Insert → Template dialog with "Diagram" typed into the search box.]]
+Fill in the '''Diagram page''' field with the diagram's full page name, ''including'' its namespace prefix — <code>Mermaid:</code>, <code>DOT:</code>, <code>Drawio:</code>, <code>BPMN:</code> or <code>Gantt:</code>. The field suggests existing pages as you type, so you rarely need to type the whole name.
+[[File:FlexDiagrams VE diagram field.png|thumb|none|700px|The Diagram page field, suggesting existing diagram pages as you type.]]
+Insert, and save the page as usual.
+=== What a diagram looks like while editing ===
+An embedded diagram does '''not''' appear as a picture in the visual editor. It shows as a single labelled line naming the diagram, like:
+ ◈ Mermaid:RE FlowChart Overview — diagram, edit it on its own page
+[[File:FlexDiagrams VE placeholder.png|thumb|none|700px|An embedded diagram as it appears while editing: one labelled line rather than the rendered picture.]]
+That is deliberate. The visual editor cannot run the diagram renderer, so without it you would see the diagram's raw source — dozens of lines of flowchart code — sitting in the middle of the article. The line above is shown instead. Save or preview the page to see the diagram itself.
+=== Editing the diagram ===
+'''Double-click''' the line. The diagram's own editor opens '''in a new tab''', leaving your article edit untouched in the original tab. Edit the diagram, save it there, then return to your article.
+=== Changing which diagram is shown ===
+'''Single-click''' the line to select it. A small box appears with two choices:
+* '''Edit "…" ↗''' — opens that diagram's editor in a new tab, the same as double-clicking.
+* '''Change which diagram is shown''' — opens the template's settings so you can point this embed at a different diagram page.
+[[File:FlexDiagrams VE context menu.png|thumb|none|700px|Selecting an embedded diagram: edit the diagram itself, or change which diagram the page shows.]]
+Single-clicking also selects the diagram as a block, so <code>Backspace</code> removes the embed from the article — which deletes only the embed, never the diagram page itself.
+=== If you edit the source instead ===
+The visual editor is not required. In the source editor the same embed is one line:
+<pre>
+{{Diagram|page=Mermaid:RE FlowChart Overview}}
+</pre>
+Both editors produce exactly the same thing, and you can move between them freely.
 == Mermaid ==
@@ Line 65: / Line 122: @@
 <pre>
-{{#display_diagram:Mermaid:Example diagram}}
+{{Diagram|page=Mermaid:Example diagram}}
 </pre>
 which renders as:
-{{#display_diagram:Mermaid:Example diagram}}
+{{Diagram|page=Mermaid:Example diagram}}
 See [https://mermaid.js.org/intro/ the Mermaid documentation] for the full syntax. This wiki bundles '''Mermaid 11.17.2''', so the Mermaid 11 diagram types — architecture, packet, kanban, treemap and radar — all work. Diagram types added in Mermaid 12 will not render, and <code>layout: elk</code> is not available (it falls back to the default layout silently). The default look is <code>handDrawn</code>; override it per diagram with <code>%%{init: {'look': 'classic'}}%%</code>.
@@ Line 99: / Line 156: @@
 <pre>
-{{#display_diagram:DOT:Example diagram}}
+{{Diagram|page=DOT:Example diagram}}
 </pre>
 which renders as:
-{{#display_diagram:DOT:Example diagram}}
+{{Diagram|page=DOT:Example diagram}}
 [[File:FlexDiagrams DOT editor.png|thumb|none|700px|The DOT editor: Graphviz source in the text box, with the rendered graph above it.]]
@@ Line 117: / Line 174: @@
 <pre>
-{{#display_diagram:Drawio:Example diagram}}
+{{Diagram|page=Drawio:Example diagram}}
 </pre>
 which renders as:
-{{#display_diagram:Drawio:Example diagram}}
+{{Diagram|page=Drawio:Example diagram}}
 '''One thing to know:''' the Drawio editor is loaded from the external site <code>embed.diagrams.net</code> while you are editing. Your diagram is saved here on the wiki, not on their servers, and viewing a saved Drawio diagram does not contact them at all — but ''editing'' one needs that external site reachable from your browser. The other four formats are served entirely from this wiki.
@@ Line 137: / Line 194: @@
 <pre>
-{{#display_diagram:BPMN:Example diagram}}
+{{Diagram|page=BPMN:Example diagram}}
 </pre>
 which renders as:
-{{#display_diagram:BPMN:Example diagram}}
+{{Diagram|page=BPMN:Example diagram}}
 That embed uses this page's one BPMN-or-Gantt slot; a second diagram of either type on the same page would be refused.
@@ Line 157: / Line 214: @@
 <pre>
-{{#display_diagram:Gantt:Example diagram}}
+{{Diagram|page=Gantt:Example diagram}}
 </pre>