Custom UI XML Syntax Rules

Before you start working with Custom UI XML, you need to learn basic background information. The syntax rules of Custom UI XML are very simple and logical. The rules are easy to learn, and easy to use.

The XML Prolog

This line is called the XML prolog:

<?xml version="1.0" encoding="UTF-8"?>

The XML prolog is optional. If it exists, it must come first in the document.

To avoid errors, you should specify the encoding used, or save your XML files as UTF-8.

UTF-8 is the default character encoding for XML documents.

Custom UI XML Must Have a Root Element

The root element of Custom UI XML documents:

<customUI>

Custom UI XML Elements Must Have a Closing Tag

XML consists of data between opening and closing tags, such as <ribbon>, there must be a closing tag, </ribbon>:

<customUI>
	<ribbon>
		<tabs>
			<tab>
				<!-- your ribbon controls here -->
			</tab>
		</tabs>
	</ribbon>
</customUI>

in some cases, within self-closing tags, for example:

<group idMso="GroupClipboard" />

Custom UI XML Tags are Case Sensitive

Custom UI XML all tags, be they elements or attributes, are case sensitive. The tag <Group> is different from the tag <group>.

Opening and closing tags must be written with the same case:

<group id="customGroup"
       label="Custom Group">
	<button id="customButton"
	        label="Custom Button"
	        imageMso="HappyFace"
	        size="large"
	        onAction="Callback"/>
</group>

Custom UI XML Elements Must be Properly Nested

The nesting of child elements within a parent is precise. Every start tag must be matched with its own end tag, whether it is closed within the same tag (via "/>") or by a separate tag later.

<customUI>
	<ribbon>
		<tabs>
			<tab>
				<!-- your ribbon controls here -->
			</tab>
		</tabs>
	</ribbon>
</customUI>

Custom UI XML Attribute Values Must Always be Quoted

Attribute values must be enclosed in single or double quotation marks (it doesn’t matter which).

<button id="customButton"
        label="Custom Button"
        imageMso="HappyFace"
        size="large"
        onAction="Callback"/>

Custom UI XML Entity References

Some characters have a special meaning in XML.

If you place a character like "<" inside an XML element, it will generate an error because the parser interprets it as the start of a new element.

This will generate an XML error:

<button description="<This is a description."/>

To avoid this error, replace the "<" character with an entity reference:

<button description="&lt;This is a description."/>

There are 5 pre-defined entity references in XML:

Only < and & are strictly illegal in XML, but it is a good habit to replace > with > as well.

Custom UI XML Comments

To include a comment, just enter your comments between <!-- and -->, and the program ignores the line when it runs.

<!--This is a comment -->

An XML comment cannot contain "--", and "-" cannot be the last character.

<!-- This is an invalid -- comment -->

White-space is Preserved in Custom UI XML

XML does not truncate multiple white-spaces:

<customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
	<ribbon startFromScratch="true">
		<tabs>
			<tab id="CustomTab"
			     label="My Tab">
				<group id="Group1"
				       label="Group 1">
					<menu id="MyMenu"
					      label="My Menu"
					      itemSize="large">
						<button id="MyButton1"
						        label="Button"
						        imageMso="HappyFace"
						        description="This           is a description."/>
					</menu>
				</group>
			</tab>
		</tabs>
	</ribbon>
</customUI>

Custom UI XML Ignores Hard Returns and Tabs

Unlike VBA, you can include hard returns and tabs in the XML without affecting the code. Therefore, we highly recommend that you divide the code into easy-to-read-and-interpret blocks. Space really isn’t an issue, so it makes sense to use the whitespace to make it easy to read, interpret, and edit.

<group
    id="mygrp"
    label="My First Group">
        
    <button
        id="mybtn1"
        imageMso="Italic"
        label="Large size button"
        size="large"
        onAction="mybtn1_Click"/>
        
    <button
        id="mybtn2"
        imageMso="Bold"
        label="Normal size button"
        size="normal"
        onAction="mybtn2_Click"/>
        
</group>

XML Stores New Line as LF

Windows applications store a new line as: carriage return and line feed (CR+LF).

Unix and Mac OSX use LF.

Old Mac systems use CR.

XML stores a new line as LF.

Well Formed Custom UI XML

XML documents that conform to the syntax rules above are said to be "Well Formed" XML documents.

Show Add-in User Interface Errors

Before you do any work with Ribbon customization, you should enable the display of RibbonX errors. Access the Excel Options dialog box (File > Options) and click the Advanced tab. Scroll down to the General section, and select Show Add-in User Interface Errors.

When this setting is enabled, RibbonX errors (if any) are displayed when the workbook opens, which is helpful for debugging.