Using <snippets>

While including files as shown in the previous section is fairly powerful, it become most useful when used in combination with <snippets>. Snippets are really smaller sections which you can insert at another point in the file. An example illustrates this best:

<document>
	<snippets>
		<snippet id="note">
			<frame>
				<text>
		This will be inserted at two places in the GUI
				</text>
			</frame>
		</snippet>
	</snippets>
	<dialog label="test">
		<column>
			<insert snippet="note"/>
			[...]
			<insert snippet="note"/>
		</column>
	</dialog>
</document>
	

Hence, you define the snippet at one place at the top of the XML file, and then you <insert> it at any place(s) you wish.

While this example is not too useful in itself, think about combining this with an <include>d .xml file. Note that you can also place snippets for the .rkh file in the same file. You would simply <include> the file there as well, and <insert> the relevant snippet:

<!-- This is a file called "common_snippets.xml" -->
<document>
	<snippet id="common_options">
		<spinbox id="something" [...]/>
		[...]
	</snippet>
	<snippet id="common_note">
		<text>An important note for this type of plugin</text>
	</snippet>

	<snippet id="common_help">
		<setting id="something">This does something</setting>
		[...]
	</snippet>
</document>
	

<!-- This is the .xml file of the plugin -->
<document>
	<snippets>
		<!-- Import the common snippets -->
		<include file="common_snippets.xml"/>
	</snippets>

	<dialog label="test2">
		<insert snippet="common_note"/>
		<spinbox id="something_plugin_specific" [...] />
		<insert snippet="common_options"/>
	</dialog>
</document>
	

Similar to inclusion in JS, the reverse approach is often even more useful:

<!-- This is a file called "common_layout.xml" -->
<document>
	<column>
		<insert snippet="note">
		[...]
		<insert snippet="plugin_parameters">
	</column>
	[...]
</document>
	

<!-- This is the .xml file of the plugin -->
<document>
	<snippets>
		<snippet id="note">
			<text>The note used for this specific plugin</text>
		</snippet>

		<snippet id="plugin_parameters">
			<frame label="Parameters specific to this plugin">
				[...]
			</frame>
		</snippet>
	</snippets>

	<dialog label="test3">
		<include file="common_layout.xml"/>
	</dialog>
</document>
	

Finally, it is also possible to <insert> snippets into other snippets, provided that: a) there is only one level of nesting, and b) the <snippets> section is placed at the top of the file (before a nested snippet is inserted); this is because <insert> statements are resolved from top to bottom.