Data Models

Hash Model

Hash models are probably the most common model you'll use in FM-Classic. Like TemplateScalarModel, TemplateHashModel defines only one method:

public TemplateModel get(java.lang.String key)
                  throws TemplateModelException;

FM-Classic uses this method to return a value for a given key name. This method is equivalent to the get() method in the Java 2 java.util.Map interface.

If the specified key does not exist in the hash, the results are implementation dependant. Some models may throw a TemplateModelException, others might return null, still others might return a default value. All are considered to be valid in FM-Classic.

Similarly, if the get() method is passed a null value, which can happen when a hash is indexed by another FM-Classic variable, the results are undefined. The implementing class may be expected to throw a TemplateModelException, or otherwise gracefully deal with the null value.

Hash models are powerful because humans tend to recognise things in terms of names rather than numbers. Hash models can return other models. A hash model can contain other hash models, and so on (as we saw in the introduction).

Writeable Hash

Writeable hash models are created by implementing the TemplateWriteableHashModel. This extends TemplateHashModel and adds the following method:

public void put(String key, TemplateModel model)
                  throws TemplateModelException;

This method should set or replace any existing named key with the given TemplateModel value. Handling of null or other special keys should be consistent with the get() method.

Key Names

Key names can start with a letter or an underscore ("_") character. The rest of the key name can contain letters, numbers or underscores. If you're tempted to use other characters in your key name, try to avoid them, or make sure you always use the Dynamic Key Name operator (the [] operator).