Skip to content

Commit 3c5b5bb

Browse files
cortex-tdcortex-td
committed
added xml block pages
1 parent b583b92 commit 3c5b5bb

File tree

7 files changed

+533
-72
lines changed

7 files changed

+533
-72
lines changed

‎.hugo_build.lock

Whitespace-only changes.

‎content/en/docs/Reference/Blocks/xml/convert-xml/convert-structure-to-xml-block.md

+236-70
Original file line numberDiff line numberDiff line change
@@ -12,50 +12,136 @@ description: "Converts a Structure To Xml."
1212

1313
## Description
1414

15-
Converts a [Structure][Structure Property] to [Xml][Json Property].
15+
Converts a [Structure][Structure Property] to [Xml][Xml Property].
16+
17+
This block will convert a [Structure][Structure Property] into [Xml][Xml Property], with each Key Value Pair being converted into a node with the node name being the Key and the data within the node being the Value.
18+
19+
If a Key Value Pair contains a Structure as its value, a node will be added to the value for each Key Value Pair with the inner node name being the Key and the data within the inner node being the Value.
1620

1721
## Examples
1822

1923
### Convert a Structure to Xml
2024

21-
This example will convert `TODO` to its Xml representation.
25+
This example will convert the [Structure][Structure Property] below to its [Xml][Xml Property] representation.
26+
27+
``` json
28+
{
29+
"topLevelNode": {
30+
"@attr" : "exampleAttribute",
31+
"id" : [
32+
"1",
33+
"2",
34+
"3"
35+
],
36+
"action" : "exampleAction",
37+
"#text" : "text without a node"
38+
}
39+
}
40+
```
2241

2342
#### Properties
2443

2544
| Property | Value | Notes |
2645
|--------------------|---------------------------|------------------------------------------|
27-
| [Structure][Structure Property] | `($)Structure`, with value `{TODO}` | `($)Structure` is a variable of type [Structure][] |
46+
| [Structure][Structure Property] | `($)Structure`, with value `{"topLevelNode": {"@attr" : "exampleAttribute", "id" : ["1","2","3"], "action" : "exampleAction", "#text" : "text without a node"}}` | `($)Structure` is a variable of type [Structure][] |
2847
| [Xml][Xml Property] | `($)Xml`, with no value | `($)Xml` is a variable that will be set to a [String][] value. |
2948

3049
#### Result
3150

32-
Converting `{TODO}` to Xml results in the variable `($)Xml` being updated to the following:
51+
Converting `{"topLevelNode": {"@attr" : "exampleAttribute", "id" : ["1","2","3"], "action" : "exampleAction", "#text" : "text without a node"}}` to Xml results in the variable `($)Xml` being updated to the following:
3352

34-
```json
35-
"TODO"
53+
``` xml
54+
@"<topLevelNode attr="exampleAttribute">
55+
<id>1</id>
56+
<id>2</id>
57+
<id>3</id>
58+
<action>exampleAction</action
59+
>text without a node
60+
</topLevelNode>"
3661
```
3762

38-
Explain how conversion works?
39-
4063
***
4164

42-
### TODO Different examples
65+
### Convert Nested Structure to Xml
66+
67+
This example will convert the [Structure][Structure Property] below to its [Xml][Xml Property] representation.
68+
69+
``` json
70+
{
71+
"topLevelNode": {
72+
"@attr" : "exampleAttribute",
73+
"id" : [
74+
"1",
75+
"2",
76+
"3"
77+
],
78+
"action" : "exampleAction",
79+
"#text" : "text without a node"
80+
}
81+
}
82+
```
83+
84+
#### Properties
85+
86+
| Property | Value | Notes |
87+
|--------------------|---------------------------|------------------------------------------|
88+
| [Structure][Structure Property] | `($)Structure`, with value `{ "topLevelNode": {"@attr" : "exampleAttribute", "id" : ["1", "2", "3"], "action" : "exampleAction", "#text" : "text without a node"}}` | `($)Structure` is a variable of type [Structure][] |
89+
| [Xml][Xml Property] | `($)Xml`, with no value | `($)Xml` is a variable that will be set to a [String][] value. |
90+
91+
#### Result
92+
93+
``` xml
94+
@"<topLevelNode attr="exampleAttribute">
95+
<id>1</id>
96+
<id>2</id>
97+
<id>3</id>
98+
<action>exampleAction</action>
99+
<innerNode>
100+
<nestedNode>nested node text</nestedNode>
101+
inner node text
102+
</innerNode>
103+
text without a node
104+
</topLevelNode>"
105+
```
106+
107+
***
43108

44-
TODO
109+
### Structure Node Example
110+
111+
This example will convert the [Structure][Structure Property] below to its [Xml][Xml Property] representation.
112+
113+
``` json
114+
{
115+
{
116+
"node1" : "1"
117+
},
118+
{
119+
"node2" : "2"
120+
},
121+
{
122+
"node3" : "3"
123+
}
124+
}
125+
```
45126

46127
#### Properties
47128

48129
| Property | Value | Notes |
49130
|--------------------|---------------------------|------------------------------------------|
50-
| [Structure][Structure Property] | `($)Structure`, with value `{TODO}` | `($)Structure` is a variable of type [Structure][] |
131+
| [Structure][Structure Property] | `($)Structure`, with value
132+
`{{ "node1" : "1"}, {"node2" : "2"}, {"node3" : "3"}}` | `($)Structure` is a variable of type [Structure][] |
51133
| [Xml][Xml Property] | `($)Xml`, with no value | `($)Xml` is a variable that will be set to a [String][] value. |
52134

53135
#### Result
54136

55-
TODO
137+
Converting `{{ "node1" : "1"}, {"node2" : "2"}, {"node3" : "3"}}` to [Xml][Xml Property] results in the variable `($)Xml` being updated to the following:
56138

57-
```json
58-
TODO
139+
``` xml
140+
@"<Cortex_DataTypes_Dictionaries_Structure>
141+
<node1>1</node1>
142+
<node2>2</node2>
143+
<node3>3</node3>
144+
</Cortex_DataTypes_Dictionaries_Structure>"
59145
```
60146

61147
***
@@ -66,8 +152,6 @@ TODO
66152

67153
The [Structure][Structure Property] to convert to [Xml][Xml Property].
68154

69-
TODO
70-
71155
| | |
72156
|--------------------|---------------------------|
73157
| Data Type | [Structure][] |
@@ -77,8 +161,6 @@ TODO
77161
### Xml
78162

79163
The [Xml][Xml Property] that has been converted from the [Structure][Structure Property].
80-
81-
TODO
82164

83165
| | |
84166
|--------------------|---------------------------|
@@ -92,16 +174,147 @@ The exceptions thrown by the block can be found below:
92174

93175
| Name | Description |
94176
|----------|----------|
95-
| [PropertyEmptyException][] | Thrown when [Structure][Structure Property] does not contain any items. |
96177
| [PropertyNullException][] | Thrown when [Structure][Structure Property] is `null`. |
178+
| [PropertyEmptyException][] | Thrown when [Structure][Structure Property] does not contain any items. |
97179
| [XmlSerializationException][] | Thrown when [Structure][Structure Property] has a key that is an empty string. |
180+
|| Thrown when the [Structure][Structure Property] includes an xml declaration key (e.g. ?xml) or a document type definition key (e.g. !DOCTYPE) that has an invalid attribute key. (e.g. Key: "@test", Value: "testValue"). |
181+
|| Thrown when the [Structure][Structure Property] includes an attribute key with a [Complex Type][] as a value. (e.g. Key: "@name", Value: new UserCredentials{...}). |
182+
|| Thrown when the [Structure][Structure Property] includes an xml declaration key (e.g. ?xml) with an attribute that has an invalid primitive value. (e.g. Key: "@version", Value: false). |
183+
|| Thrown when the [Structure][Structure Property] includes a document type definition key (e.g. !DOCTYPE) that has an attribute with an invalid primitive value. (e.g. Key: "@name", Value: 22). |
98184

99185
## Remarks
100186

101187
### Round-tripping
102188

103189
It should be possible to pass the Xml created by this block to the [Convert Xml To Structure][] block, and then pass the [Structure][Structure Property] created by the [Convert Xml To Structure][] block back to this block; this is called round-tripping.
104190

191+
### Attributes
192+
193+
If a node requires an attribute, the attribute is defined to a [Key Value Pair][] where the key is the attribute name with an `"@"` before it and the value is the attribute data, for example:
194+
195+
``` json
196+
{
197+
"node": {
198+
"@attribute": "Attribute Value",
199+
"innernode": "Inner Node Value"
200+
}
201+
}
202+
```
203+
204+
The [Xml][Xml Property] example above would be converted to the following [Structure][Structure Property] be converted to
205+
206+
``` xml
207+
@"<node attribute="Attribute Value">
208+
<innerNode>Inner Node Value</innerNode>
209+
</node>"
210+
```
211+
212+
### Primitive Values Within Attribute Keys
213+
214+
Attribute keys may only have [Primitive Values][], an [XmlSerializationException][] will be thrown if a [Complex Value][] is used as an attribute key.
215+
216+
### Key Restrictions
217+
218+
If provided, the xml declaration key (e.g. ?xml) can only accept following attributes: @version, @encoding and @standalone.
219+
220+
If provided, the document type definition key (e.g. !DOCTYPE) can only accept following attributes: @name, @public, @system and @internalSubset.
221+
222+
The keys `"$id"`, `"$ref"`, `"$type"` and `"$value"` are reserved words within the XMLConverter. Using them can cause odd behaviour as they are treated like attributes within the conversion.
223+
224+
The key `"values"` is also reserved, however it is treated as its own node within the conversion.
225+
226+
### Data Not Within a Node
227+
228+
If any data does not have any nodes and is within the same element as other data with nodes, the data is converted to a [Key Value Pair][] where the key is "#text" and the value is the node-less data.
229+
230+
If data does not require a node and is withiin the same element as other data with nodes, the nodeless data requires a [Key Value Pair][] where the
231+
232+
``` json
233+
{
234+
"node": {
235+
"innerNode": "Inner Node Value",
236+
"#text": "Node Value"
237+
}
238+
}
239+
```
240+
241+
The [Structure][Structure Property] example above would be converted to the following [Xml][Xml Property].
242+
243+
``` xml
244+
@"<node>
245+
<innerNode>
246+
Inner Node Value
247+
</innerNode>
248+
Node Value
249+
</node>"
250+
```
251+
252+
### Duplicate Nodes At The Same Level
253+
254+
If an multiple duplicate nodes are required at the same level, they are defined using a [Key Value Pair][] where the key is the duplicated node and the value is a list of each duplicate nodes data in order, for example:
255+
256+
``` json
257+
{
258+
"node": {
259+
"duplicateNode": ["First Duplicate Node", "Second Duplicate Node"],
260+
"distinctNode": "Distinct Node"
261+
}
262+
}
263+
```
264+
265+
The [Structure][Structure Property] example above would be converted to the following [Xml][Xml Property].
266+
267+
``` xml
268+
@"<node>
269+
<duplicateNode>
270+
First Duplicate Node
271+
</duplicateNode>
272+
273+
<duplicateNode>
274+
Second Duplicate Node
275+
</duplicateNode>
276+
277+
<distinctNode>
278+
Distinct Node
279+
</distinctNode>
280+
</node>"
281+
```
282+
283+
### Using Non-Alphanumeric Symbols Within Node Names
284+
285+
Any non-alphanumeric symbol (i.e. symbols that are not 0 to 9 or a to Z) will be converted to their respective Unicode values when used within a node name. For example, `"!"` and `"&"` are both non-alphanumeric symbols and would be converted to `"x0021"` and `"x0026"` respectively.
286+
287+
For more information on characters and their Unicode values please see [Character Sets][]
288+
289+
### Structure Node
290+
291+
If a root node is not defined, then the root node `""Cortex_DataTypes_Dictionaries_Structure""` will be added during the conversion to ensure that the resulting [Xml][Xml Property] is valid.
292+
293+
``` json
294+
{
295+
{
296+
"node1" : "1"
297+
},
298+
{
299+
"node2" : "2"
300+
},
301+
{
302+
"node3" : "3"
303+
}
304+
}
305+
```
306+
307+
The [Structure][Structure Property] example above would be converted to the following [Xml][Xml Property].
308+
309+
``` xml
310+
@"<Cortex_DataTypes_Dictionaries_Structure>
311+
<node1>1</node1>
312+
<node2>2</node2>
313+
<node3>3</node3>
314+
</Cortex_DataTypes_Dictionaries_Structure>"
315+
```
316+
317+
105318
[Structure Property]: {{< ref "#structure" >}}
106319
[Xml Property]: {{< ref "#xml" >}}
107320

@@ -112,57 +325,10 @@ It should be possible to pass the Xml created by this block to the [Convert Xml
112325
[PropertyNullException]: {{< url "Cortex.Reference.Exceptions.Common.Property.PropertyNullException.MainDoc" >}}
113326
[XmlSerializationException]: {{< url "JsonDotNet.XmlSerializationException" >}}
114327

115-
116-
117328
[Structure]: {{< url "Cortex.Reference.DataTypes.MostCommon.Structure" >}}
118329
[String]: {{< url "Cortex.Reference.DataTypes.MostCommon.String" >}}
119330

120-
121-
/// If there are multiple items in the specified structure, a root node is automatically added to make it valid xml (added root node: "Cortex_FlowEngine_Core_Types_Structure")
122-
123-
/// If a node requires an attribute, use a key value pair where the key is the attribute name with an "@" before it and the value is the attribute data.
124-
125-
/// If data does not require nodes and is within the same element as data that does require nodes, use a key value pair where the key is "#text" and the value is the node-less data.
126-
127-
/// If multiple of the same nodes are required are within the same element, use a key value pair where the key is the node and the value is a list with the nodes data.
128-
129-
/// If the specified structure includes an ampersand symbol in a node's name, the xml will return with "_x0026_" in place of the ampersand symbol.
130-
131-
/// If the specified structure includes an ampersand symbol in a node's data, the xml will return with "&amp;" in place of the ampersand symbol.
132-
133-
134-
/// </remarks>
135-
136-
/// <example>
137-
/// structure: {
138-
/// "msg&amp;": {
139-
/// "@attr" : "exampleAttribute"
140-
/// "id" :
141-
/// [
142-
/// "1",
143-
/// "2",
144-
/// "3"
145-
/// ],
146-
/// "action" : "stop&amp;"
147-
/// "#text" : "hello"
148-
/// }
149-
/// }
150-
///
151-
/// xml: "<msg_x0026_ attr="exampleAttribute"><id>1</id><id>2</id><id>3</id><action>stop&amp;</action>hello</msg_x0026_>"
152-
/// </example>
153-
/// <example>
154-
/// structure: {
155-
/// {
156-
/// "id" : "1"
157-
/// },
158-
/// {
159-
/// "id2" : "2"
160-
/// },
161-
/// {
162-
/// "id3" : "3"
163-
/// }
164-
/// }
165-
///
166-
/// xml: "<Cortex_FlowEngine_Core_Types_Structure><id>1</id><id2>2</id2><id3>3</id3></Cortex_FlowEngine_Core_Types_Structure>"
167-
/// </example>
168-
void ConvertStructureToXml(Structure structure, out string xml);
331+
[Character Sets]: {{< url "W3.CharacterSets" >}}
332+
[Complex Type]: {{}}
333+
[Primitive Type]: {{}}
334+
[Key Value Pair]: {{}}

0 commit comments

Comments
 (0)