Structuring the custom-assetinfo.xml file of Elvis 5

The custom-assetinfo.xml file is used for changing the settings of default metadata fields and for creating custom metadata fields.

Over time this file can get very complex and potentially confusing.

To keep the file readable for yourself, your customers or your colleagues who work on the installation, you can structure the file in various ways, depending on your needs and personal preferences.

Below are some guidelines that you might find useful.

View the content in an XML editor

The first tip is more to do with readability than with the structure of the file itself.

When modifying the custom-assetinfo.xml file for a running cluster, the changes need to be made in the Admin pages of Elvis Server. (See Changing the Elvis 5 Server configuration for a running cluster.)

The configuration page displays the content of the file as plain text without any syntax coloration.

Best practice is to copy the content to your favorite text editor such as TextWrangler or Notepad++ so that you can easily read and edit the configuration settings. When finished editing, paste the content back into the Elvis page.

Figure: The difference between viewing the custom-assetinfo.xml file in the Elvis 5 configuration page (top) and viewing the same code of the file in TextWrangler (bottom).

Use comments

Adding comments is an essential way of keeping track of how an option works, how it should be used and why it was implemented.

Be as complete as possible so that even when reading it a year from now it is still clear and comprehensible.

To increase the readability, write full sentences and try not to use abbreviations.

One downside of using large sections of comments is that they can obscure small sections of code, especially single lines of code.

You might want to first define all the code for a particular section and place the comments below it or place all comments at the bottom of the file.

Clearly divide each section

The custom-assetinfo.xml file consists of 3 sections:

1. Group definitions
2. Custom field definitions
3. Definitions for extending default fields

To separate each section you can use clear dividers, for example by using (multiple) lines of (multiple) special characters, and text written in capitals.

<assetsInfoExt>

<!--
============================================================================
#
#
#
# FIELD GROUPS
#
#
#
============================================================================
-->
		
	<fieldGroups>
		<fieldGroup name="CompanyData" />
		<fieldGroup name="Collections" />
		<fieldGroup name="PDFs" />
	</fieldGroups>
		

When definitions for settings become very long (such as extensions for default metadata fields), you could divide each group they are part ofo:

<fieldExtensions>

	<!-- 
		*********************************
		***   Field Group:   SYSTEM   *** 
		*********************************
	-->
	<fieldExt name="metadataComplete" group="System">
		<data editable="false">
			<predefinedValues onlyFromList="true">
				<value flagIcon="label_broken.png">false</value>
				<value flagIcon="label.png">true</value>
			</predefinedValues>
		</data>
		<userInterface flagPosition="20" />
	</fieldExt>


	<!-- 
		*************************************
		***   Field Group:   ENTERPRISE   *** 
		*************************************
	-->
	<fieldExt name="sceUsed" group="Enterprise">
		<data editable="false">
			<predefinedValues onlyFromList="true">
				<value flagIcon="woodwing.png">true</value>
				<value flagIcon="">false</value>
			</predefinedValues>
		</data>
		<userInterface flagPosition="60" />
	</fieldExt>
	   
</fieldExtensions>

Store examples in a separate file

Examples are a great way to learn about features that you have never used before but once you are familiar with them these examples can get in the way and reduce readability of the file.

One way of dealing with this is to store all examples in a separate file and to make sure to clearly name this file as such.

Example: custom-assetinfo-EXAMPLES.xml or custom-assetinfo-ARCHIVE.xml

Then, use the custom-assetinfo.xml file for storing only the configuration that is used in production.