Help:Diagrams: Difference between revisions

(3 intermediate revisions by the same user not shown)

Line 46:

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.

'''Highlighting one node for one page:''' Mermaid diagrams take an optional <code>style</code> parameter that restyles part of the diagram on that page only — see [[#Highlighting part of a diagram on one page|Highlighting part of a diagram on one page]].

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

Line 174:

Line 176:

so makes that diagram ignore the site-wide theme '''completely''', including any later change

to it — so prefer leaving it alone unless one diagram genuinely needs to differ.

=== Highlighting part of a diagram on one page ===

An article sometimes needs to point at '''one step''' of a shared diagram without changing the diagram itself. Add a <code>style</code> parameter to [[Template:Diagram]]: its contents are added to the end of the diagram '''for this embed only'''. The diagram page, and every other page that shows it, stay exactly as they are.

<pre>

{{Diagram|page=Mermaid:RE Microscope Workflow|style=style MW_Memory_File stroke-width:8px}}

</pre>

{{Diagram|page=Mermaid:RE Microscope Workflow|style=style MW_Memory_File stroke-width:8px}}

Compare it with the unmodified [[Mermaid:RE Microscope Workflow]]: only the ''IC Data'' circle has changed. In the visual editor, the same thing is the '''Extra style (Mermaid only)''' field of the template.

* '''Use the node's id, not its label.''' Above, the id is <code>MW_Memory_File</code>; its label is ''IC Data''. Open the diagram page to find the ids.

* '''Several statements go on one line, separated by <code>;</code>''', e.g. <code>style=style MW_Memory_File stroke-width:8px; style MW_Sample-Preparation fill:#ffd</code>

* Any Mermaid flowchart statement works, not only <code>style</code> — e.g. <code>classDef hot fill:#ffd; class MW_Memory_File,MW_Sample-Preparation hot</code> to highlight several nodes the same way.

* '''A misspelled id is not reported.''' Mermaid does not complain — it draws an extra, empty node with that name. If a stray box appears, check the spelling.

* '''Mermaid only.''' On a DOT, Drawio, BPMN or Gantt page the parameter shows an error instead of the diagram.

* Editing the diagram page still updates this embed by itself, with no purge.

=== Building one diagram from several pages ===

A large flowchart can be split up so that '''each part is its own diagram page''' —

with its own editor, preview and history — while an overview page assembles them

into a '''single diagram''' at render time. Edit a part and every overview that uses it

updates by itself, with no purge.

Here are two small parts. [[Mermaid:Example part one]]:

<pre>

flowchart LR

EX1_Start([Start]) --> EX1_Capture[/Capture signal/]

EX1_Capture --> EX1_Decode[Decode frames]

</pre>

and [[Mermaid:Example part two]]:

<pre>

flowchart LR

EX2_Analyse[Analyse payload] --> EX2_Report[[Write it up]]

EX2_Report --> EX2_End([End])

</pre>

Put them together on any ordinary page with <code><composediagram></code>. Each part

gets an <code>id</code>, a <code>title</code> (the heading shown on its box) and the

<code>page</code> to read. Edges joining the parts go '''between the tags''':

<pre>

<composediagram direction="TD"

id1="EX_Capture" title1="Capture" page1="Mermaid:Example part one"

id2="EX_Analysis" title2="Analysis" page2="Mermaid:Example part two">

EX_Capture --> EX_Analysis

</composediagram>

</pre>

which renders as:

<composediagram direction="TD"

id1="EX_Capture" title1="Capture" page1="Mermaid:Example part one"

id2="EX_Analysis" title2="Analysis" page2="Mermaid:Example part two">

EX_Capture --> EX_Analysis

</composediagram>

A worked example with five parts is at [[User:Hash/Sandbox]].

==== Choosing how deep to draw ====

Add <code>level</code> to draw every part at a given depth, or <code>level''N''</code> to set part ''N'' on its own (it overrides <code>level</code>):

{| class="wikitable"

! Level !! What each part shows

|-

| <code>1</code> || One block with the part's title

|-

| <code>2</code> || The part's own nodes; any subgraphs inside it are drawn as titled blocks

|-

| <code>3</code>, <code>4</code>, … || One more layer of subgraphs opened at each step

|}

<pre>

</pre>

With no level at all, every part is drawn in full, exactly as before. Setting a part to <code>all</code> (e.g. <code>level5="all"</code>) also means full depth, which is useful when <code>level</code> sets a lower default.

* '''Empty subgraphs are placeholders''' — <code>subgraph FW_Advanced [Advanced Techniques]; end</code> — and simply stay blocks at any level until someone fills them in. No error.

* '''Edges into hidden nodes are redrawn to the block''' that now stands for them, keeping their labels, so the overview's edges can point at nodes deep inside a part and still make sense when that part is collapsed.

* Contents must be written '''inline''' in the part page; a subgraph cannot pull in another page.

Examples of each are at [[User:Hash/Sandbox#Depth levels]].

==== What you need to get right ====

# '''Each part must be a valid diagram on its own''', starting with <code>flowchart ...</code>. That header is removed when composing (it is not legal inside a subgraph) but its direction is kept, so a part laid out <code>LR</code> still runs left-to-right inside the overview.

# '''Node ids must be unique across every part.''' This is the one that bites. Give each part its own prefix — <code>EX1_</code>, <code>EX2_</code>, <code>FI_</code>, <code>ME_</code>. If two parts both declare <code>Start</code>, '''Mermaid does not report an error''': it silently merges the two boxes, keeping the position of the first and the label of the last, so one part quietly starts displaying another part's text. The tag checks for this before rendering and, if it finds a clash, shows an error naming the id and both pages instead of drawing a misleading diagram.

# '''Edges that join two parts belong in the overview''', between the tags — a part cannot refer to ids it does not contain.

# '''Do not put a <code>config:</code> or <code>%%{init}%%</code> block in a part.''' It is stripped when composing, and on the part's own page it would override the site-wide theme (see [[#How diagrams are styled]]).

# '''The subgraph <code>id</code> you choose shares the same namespace as the node ids''', so it must not collide with a node in any part either.

If a part has a syntax error, the '''overview''' is what shows the error. The composed

source carries <code>%% ___ begin <Page> ___</code> markers, so the line number in the

error message can be traced back to the part that caused it.

[[File:FlexDiagrams Mermaid editor.png|thumb|none|700px|The Mermaid editor: type the diagram source in the text box and the preview above it redraws as you type.]]

Line 276:

Line 384:

* [[Help:Uploading files]] — for photographs, scans and CAD files

* [https://www.mediawiki.org/wiki/Extension:Flex_Diagrams Extension:Flex Diagrams] — the extension providing this

[[Category:Help]]

@@ Line 46: / Line 46: @@
 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.
+'''Highlighting one node for one page:''' Mermaid diagrams take an optional <code>style</code> parameter that restyles part of the diagram on that page only &mdash; see [[#Highlighting part of a diagram on one page|Highlighting part of a diagram on one page]].
 '''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.
@@ Line 174: / Line 176: @@
 so makes that diagram ignore the site-wide theme '''completely''', including any later change
 to it &mdash; so prefer leaving it alone unless one diagram genuinely needs to differ.
+=== Highlighting part of a diagram on one page ===
+An article sometimes needs to point at '''one step''' of a shared diagram without changing the diagram itself. Add a <code>style</code> parameter to [[Template:Diagram]]: its contents are added to the end of the diagram '''for this embed only'''. The diagram page, and every other page that shows it, stay exactly as they are.
+<pre>
+{{Diagram|page=Mermaid:RE Microscope Workflow|style=style MW_Memory_File stroke-width:8px}}
+</pre>
+{{Diagram|page=Mermaid:RE Microscope Workflow|style=style MW_Memory_File stroke-width:8px}}
+Compare it with the unmodified [[Mermaid:RE Microscope Workflow]]: only the ''IC Data'' circle has changed. In the visual editor, the same thing is the '''Extra style (Mermaid only)''' field of the template.
+* '''Use the node's id, not its label.''' Above, the id is <code>MW_Memory_File</code>; its label is ''IC Data''. Open the diagram page to find the ids.
+* '''Several statements go on one line, separated by <code>;</code>''', e.g. <code>style=style MW_Memory_File stroke-width:8px; style MW_Sample-Preparation fill:#ffd</code>
+* Any Mermaid flowchart statement works, not only <code>style</code> &mdash; e.g. <code>classDef hot fill:#ffd; class MW_Memory_File,MW_Sample-Preparation hot</code> to highlight several nodes the same way.
+* '''A misspelled id is not reported.''' Mermaid does not complain &mdash; it draws an extra, empty node with that name. If a stray box appears, check the spelling.
+* '''Mermaid only.''' On a DOT, Drawio, BPMN or Gantt page the parameter shows an error instead of the diagram.
+* Editing the diagram page still updates this embed by itself, with no purge.
+=== Building one diagram from several pages ===
+A large flowchart can be split up so that '''each part is its own diagram page''' &mdash;
+with its own editor, preview and history &mdash; while an overview page assembles them
+into a '''single diagram''' at render time. Edit a part and every overview that uses it
+updates by itself, with no purge.
+Here are two small parts. [[Mermaid:Example part one]]:
+<pre>
+flowchart LR
+  EX1_Start([Start]) --> EX1_Capture[/Capture signal/]
+  EX1_Capture --> EX1_Decode[Decode frames]
+</pre>
+{{Diagram|page=Mermaid:Example part one}}
+and [[Mermaid:Example part two]]:
+<pre>
+flowchart LR
+  EX2_Analyse[Analyse payload] --> EX2_Report[[Write it up]]
+  EX2_Report --> EX2_End([End])
+</pre>
+{{Diagram|page=Mermaid:Example part two}}
+Put them together on any ordinary page with <code>&lt;composediagram&gt;</code>. Each part
+gets an <code>id</code>, a <code>title</code> (the heading shown on its box) and the
+<code>page</code> to read. Edges joining the parts go '''between the tags''':
+<pre>
+&lt;composediagram direction="TD"
+ id1="EX_Capture"  title1="Capture"  page1="Mermaid:Example part one"
+ id2="EX_Analysis" title2="Analysis" page2="Mermaid:Example part two"&gt;
+EX_Capture --> EX_Analysis
+&lt;/composediagram&gt;
+</pre>
+which renders as:
+<composediagram direction="TD"
+ id1="EX_Capture"  title1="Capture"  page1="Mermaid:Example part one"
+ id2="EX_Analysis" title2="Analysis" page2="Mermaid:Example part two">
+EX_Capture --> EX_Analysis
+</composediagram>
+A worked example with five parts is at [[User:Hash/Sandbox]].
+==== Choosing how deep to draw ====
+Add <code>level</code> to draw every part at a given depth, or <code>level''N''</code> to set part ''N'' on its own (it overrides <code>level</code>):
+{| class="wikitable"
+! Level !! What each part shows
+|-
+| <code>1</code> || One block with the part's title
+|-
+| <code>2</code> || The part's own nodes; any subgraphs inside it are drawn as titled blocks
+|-
+| <code>3</code>, <code>4</code>, &hellip; || One more layer of subgraphs opened at each step
+|}
+<pre>
+&lt;composediagram direction="TD" level="1" level5="3" ...&gt;
+</pre>
+With no level at all, every part is drawn in full, exactly as before. Setting a part to <code>all</code> (e.g. <code>level5="all"</code>) also means full depth, which is useful when <code>level</code> sets a lower default.
+* '''Empty subgraphs are placeholders''' &mdash; <code>subgraph FW_Advanced [Advanced Techniques]; end</code> &mdash; and simply stay blocks at any level until someone fills them in. No error.
+* '''Edges into hidden nodes are redrawn to the block''' that now stands for them, keeping their labels, so the overview's edges can point at nodes deep inside a part and still make sense when that part is collapsed.
+* Contents must be written '''inline''' in the part page; a subgraph cannot pull in another page.
+Examples of each are at [[User:Hash/Sandbox#Depth levels]].
+==== What you need to get right ====
+# '''Each part must be a valid diagram on its own''', starting with <code>flowchart ...</code>. That header is removed when composing (it is not legal inside a subgraph) but its direction is kept, so a part laid out <code>LR</code> still runs left-to-right inside the overview.
+# '''Node ids must be unique across every part.''' This is the one that bites. Give each part its own prefix &mdash; <code>EX1_</code>, <code>EX2_</code>, <code>FI_</code>, <code>ME_</code>. If two parts both declare <code>Start</code>, '''Mermaid does not report an error''': it silently merges the two boxes, keeping the position of the first and the label of the last, so one part quietly starts displaying another part's text. The tag checks for this before rendering and, if it finds a clash, shows an error naming the id and both pages instead of drawing a misleading diagram.
+# '''Edges that join two parts belong in the overview''', between the tags &mdash; a part cannot refer to ids it does not contain.
+# '''Do not put a <code>config:</code> or <code>%%{init}%%</code> block in a part.''' It is stripped when composing, and on the part's own page it would override the site-wide theme (see [[#How diagrams are styled]]).
+# '''The subgraph <code>id</code> you choose shares the same namespace as the node ids''', so it must not collide with a node in any part either.
+If a part has a syntax error, the '''overview''' is what shows the error. The composed
+source carries <code>%% ___ begin <Page> ___</code> markers, so the line number in the
+error message can be traced back to the part that caused it.
 [[File:FlexDiagrams Mermaid editor.png|thumb|none|700px|The Mermaid editor: type the diagram source in the text box and the preview above it redraws as you type.]]
@@ Line 276: / Line 384: @@
 * [[Help:Uploading files]] — for photographs, scans and CAD files
 * [https://www.mediawiki.org/wiki/Extension:Flex_Diagrams Extension:Flex Diagrams] — the extension providing this
+[[Category:Help]]