new-diagram-jison.md

8.7 KB225 lines

1	> Warning
2	>
3	> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
4	>
5	> ## Please edit the corresponding file in [/packages/mermaid/src/docs/community/new-diagram-jison.md](../../packages/mermaid/src/docs/community/new-diagram-jison.md).
6
7	# Adding a New Diagram/Chart (Deprecated) 📊
8
9	> Warning
10	> JISON grammars are deprecated in mermaid. Please use Langium instead. See [New Diagram](./new-diagram.md) for more information.
11	>
12	> New diagrams with JISON grammars will not be accepted.
13
14	### Step 1: Grammar & Parsing
15
16	#### Grammar
17
18	This would be to define a JISON grammar for the new diagram type. That should start with a way to identify that the text in the mermaid tag is a diagram of that type. Create a new folder under diagrams for your new diagram type and a parser folder in it. This leads us to step 2.
19
20	For instance:
21
22	- the flowchart starts with the keyword _graph_
23	- the sequence diagram starts with the keyword _sequenceDiagram_
24
25	#### Store data found during parsing
26
27	There are some jison specific sub steps here where the parser stores the data encountered when parsing the diagram, this data is later used by the renderer. You can during the parsing call an object provided to the parser by the user of the parser. This object can be called during parsing for storing data.
28
29	```jison
30	statement
31	: 'participant' actor { $$='actor'; }
32	\| signal { $$='signal'; }
33	\| note_statement { $$='note'; }
34	\| 'title' message { yy.setTitle($2); }
35	;
36	```
37
38	In the extract of the grammar above, it is defined that a call to the setTitle method in the data object will be done when parsing and the title keyword is encountered.
39
40	> Note
41	> Make sure that the `parseError` function for the parser is defined and calling `mermaid.parseError`. This way a common way of detecting parse errors is provided for the end-user.
42
43	For more info look at the example diagram type:
44
45	The `yy` object has the following function:
46
47	```javascript
48	exports.parseError = function (err, hash) {
49	mermaid.parseError(err, hash);
50	};
51	```
52
53	when parsing the `yy` object is initialized as per below:
54
55	```javascript
56	const parser = exampleParser.parser;
57	parser.yy = db;
58	```
59
60	### Step 2: Rendering
61
62	Write a renderer that given the data found during parsing renders the diagram. To look at an example look at sequenceRenderer.js rather than the flowchart renderer as this is a more generic example.
63
64	Place the renderer in the diagram folder.
65
66	### Step 3: Detection of the new diagram type
67
68	The second thing to do is to add the capability to detect the new diagram to type to the detectType in `diagram-api/detectType.ts`. The detection should return a key for the new diagram type.
69	[This key will be used to as the aria roledescription](#aria-roledescription), so it should be a word that clearly describes the diagram type.
70	For example, if your new diagram uses a UML deployment diagram, a good key would be "UMLDeploymentDiagram" because assistive technologies such as a screen reader
71	would voice that as "U-M-L Deployment diagram." Another good key would be "deploymentDiagram" because that would be voiced as "Deployment Diagram." A bad key would be "deployment" because that would not sufficiently describe the diagram.
72
73	Note that the diagram type key does not have to be the same as the diagram keyword chosen for the [grammar](#grammar), but it is helpful if they are the same.
74
75	### Step 4: The final piece - triggering the rendering
76
77	At this point when mermaid is trying to render the diagram, it will detect it as being of the new type but there will be no match when trying to render the diagram. To fix this add a new case in the switch statement in main.js:init this should match the diagram type returned from step #2. The code in this new case statement should call the renderer for the diagram type with the data found by the parser as an argument.
78
79	## Usage of the parser as a separate module
80
81	### Setup
82
83	```javascript
84	const graph = require('./graphDb');
85	const flow = require('./parser/flow');
86	flow.parser.yy = graph;
87	```
88
89	### Parsing
90
91	```javascript
92	flow.parser.parse(text);
93	```
94
95	### Data extraction
96
97	```javascript
98	graph.getDirection();
99	graph.getVertices();
100	graph.getEdges();
101	```
102
103	The parser is also exposed in the mermaid api by calling:
104
105	```javascript
106	const parser = mermaid.getParser();
107	```
108
109	Note that the parse needs a graph object to store the data as per:
110
111	```javascript
112	flow.parser.yy = graph;
113	```
114
115	Look at `graphDb.js` for more details on that object.
116
117	## Layout
118
119	If you are using a dagre based layout, please use flowchart-v2 as a template and by doing that you will be using dagre-wrapper instead of dagreD3 which we are migrating away from.
120
121	### Common parts of a diagram
122
123	There are a few features that are common between the different types of diagrams. We try to standardize the diagrams that work as similar as possible for the end user. The commonalities are:
124
125	- Directives, a way of modifying the diagram configuration from within the diagram code.
126	- Accessibility, a way for an author to provide additional information like titles and descriptions to people accessing a text with diagrams using a screen reader.
127	- Themes, there is a common way to modify the styling of diagrams in Mermaid.
128	- Comments should follow mermaid standards
129
130	Here are some pointers on how to handle these different areas.
131
132	## Accessibility
133
134	Mermaid automatically adds the following accessibility information for the diagram SVG HTML element:
135
136	- aria-roledescription
137	- accessible title
138	- accessible description
139
140	### aria-roledescription
141
142	The aria-roledescription is automatically set to [the diagram type](#step-3--detection-of-the-new-diagram-type) and inserted into the SVG element.
143
144	See [the definition of aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) in [the Accessible Rich Internet Applications W3 standard.](https://www.w3.org/WAI/standards-guidelines/aria/)
145
146	### accessible title and description
147
148	The syntax for accessible titles and descriptions is described in [the Accessibility documentation section.](../config/accessibility.md)
149
150	As a design goal, the jison syntax should be similar between the diagrams.
151
152	```jison
153
154	* lexical grammar */
155	%lex
156	%x acc_title
157	%x acc_descr
158	%x acc_descr_multiline
159
160	%%
161	accTitle\s":"\s { this.begin("acc_title");return 'acc_title'; }
162	<acc_title>(?!\n\|;\|#)[^\n] { this.popState(); return "acc_title_value"; }
163	accDescr\s":"\s { this.begin("acc_descr");return 'acc_descr'; }
164	<acc_descr>(?!\n\|;\|#)[^\n] { this.popState(); return "acc_descr_value"; }
165	accDescr\s"{"\s { this.begin("acc_descr_multiline");}
166	<acc_descr_multiline>[\}] { this.popState(); }
167	<acc_descr_multiline>[^\}]* return "acc_descr_multiline_value";
168
169	statement
170	: acc_title acc_title_value { $$=$2.trim();yy.setTitle($$); }
171	\| acc_descr acc_descr_value { $$=$2.trim();yy.setAccDescription($$); }
172	\| acc_descr_multiline_value { $$=$1.trim();yy.setAccDescription($$); }
173
174	```
175
176	The functions for setting title and description are provided by a common module. This is the import from flowDb.js:
177
178	```
179	import {
180	setAccTitle,
181	getAccTitle,
182	getAccDescription,
183	setAccDescription,
184	clear as commonClear,
185	} from '../../commonDb';
186	```
187
188	The accessibility title and description are inserted into the SVG element in the `render` function in mermaidAPI.
189
190	## Theming
191
192	Mermaid supports themes and has an integrated theming engine. You can read more about how the themes can be used [in the docs](../config/theming.md).
193
194	When adding themes to a diagram it comes down to a few important locations in the code.
195
196	The entry point for the styling engine is in src/styles.js. The getStyles function will be called by Mermaid when the styles are being applied to the diagram.
197
198	This function will in turn call a function _your diagram should provide_ returning the css for the new diagram. The diagram specific, also which is commonly also called getStyles and located in the folder for your diagram under src/diagrams and should be named styles.js. The getStyles function will be called with the theme options as an argument like in the following example:
199
200	```js
201	const getStyles = (options) =>
202	`
203	.line {
204	stroke-width: 1;
205	stroke: ${options.lineColor};
206	stroke-dasharray: 2;
207	}
208	// ...
209	`;
210	```
211
212	Note that you need to provide your function to the main getStyles by adding it into the themes object in src/styles.js like in the xyzDiagram in the provided example:
213
214	```js
215	const themes = {
216	flowchart,
217	'flowchart-v2': flowchart,
218	sequence,
219	xyzDiagram,
220	//...
221	};
222	```
223
224	The actual options and values for the colors are defined in src/theme/theme-\[xyz].js. If you provide the options your diagram needs in the existing theme files then the theming will work smoothly without hiccups.
225