# How to customize the metadata icon-list on the rich tile

# What is the metadata icon-list?

The metadata icon-list displays metadata as icons on the rich tile of an object. This is especially useful if you want to see key information straightaway without opening an object in the detail view. A tooltip gives you further information.
Which metadata will be displayed on your rich tile is entirely customizable and not limited. It may look something like this:

The metadata icon-list is part of the product standard of the 4APP "Essentials" (4allportal-essentials) from version 3.7 onward.
It is primarily used in the files module, but can be configured for any other module, too.

# How does the metadata icon-list work?

All contents of the metadata icon-list get their information from a corresponding metadata field. For each metadata you want to display here, the corresponding field value will be converted into an icon key. If an icon key is empty, the icon will not be displayed.

The most common way to configure is by simply using a valueOption. ValueOptions and their icons can be used in any presentation of the metadata, including this.

There are some cases in which this way will not fit your needs, e.g. if an icon depends on a boolean field or if you want to show it although the value of the corresponding field is null. In these cases, you can also change the ValueOptionKey or make a custom icon mapping.

In our example above, we configured the following:

excavator: shown if "construction site" is set in the field "buzzwords"
camera: shown if the field "photographer" is filled (one color per name)
globe: shown if the boolean field "share to Typo3" is set to "true"
toolbox: shown if the field "producttyp" is "tools"

# Example: How to configure the metadata icon-list

The metadata icon-list is easy to implement via a layout change. The property of the component RichTileItemRenderer is named metaDataIcons. It accepts an array of strings or complex definitions.

In the following example you find all possible ways to configure a metadata icon. Look further down for detailed information.

Go to custom/modules/file/layouts/main and change the file "default" like this:

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

  <!-- your other changes -->

  <change xpath="//actor[@id='mainSearchTileFactory']/parameter/entry[@key='itemRendererProperties']" type="add">
    <entry class="array" key="metaDataIcons">

      <value>my_first_field</value>

      <value class="map">
        <entry key="fieldName">my_second_field</entry>
        <entry key="valueOptionKey">my_value_option_key</entry>
      </value>

      <value class="map">
        <entry key="fieldName">my_third_field</entry>
        <entry key="iconMapping" class="map">
          <entry key="">MY-NULL_OR_EMPTY_TEXT-ICON</entry>
          <entry key="false">MY-ICON_FOR_BOOLEAN_OR_TEXT-FALSE</entry>
          <entry key="true">MY-ICON_FOR_BOOLEAN_OR_TEXT-TRUE</entry>
          <entry key="42">MY-ICON_FOR_NUMBER_OR_TEXT-42</entry>
          <entry key="myStringValue">MY-STRING_VALUE_ICON</entry>
        </entry>
       </value>
 
    </entry>
  </change>

</changes>

If you want only certain roles to see the metadata icon-list on the rich tile, create an extra layout-file for this role, e.g. "ro_admin.4aplayout".

# Option 1: Use a valueOption

The simple way to configure a metadata icon is to just use an already configured valueOption:

<value>my_first_field</value>

It is the same as:

<value class="map">
  <entry key="fieldName">my_first_field</entry>
</value>

Make sure to maintain your valueOptions and check for appropriate icons (_ICON) and information (_INFO), for these will be used as icon and tooltip in the metadata icon-list.

# Option 2: Change the valueOptionKey

By default, the valueOptionKey is given by the corresponding field configuration. If you need another valueOptionKey or if there is none configured, you can customize it like this:

 <value class="map">
   <entry key="fieldName">my_second_field</entry>
   <entry key="valueOptionKey">my_value_option_key</entry>
 </value>

Use this option for strings.

# Option 3: Custom icon mapping

Sometimes the valueOption does not fit your needs. For number, boolean or null values, you cannot use a valueOption without getting problems. So the following configuration will map exactly one value to exactly one icon key. All not mentioned values will result in no icon.

Note: Any configured valueOption will be ignored in this case.

 <value class="map">
        <entry key="fieldName">my_third_field</entry>
        <entry key="iconMapping" class="map">
          <entry key="">MY-NULL_OR_EMPTY_TEXT-ICON</entry>
          <entry key="false">MY-ICON_FOR_BOOLEAN_OR_TEXT-FALSE</entry>
          <entry key="true">MY-ICON_FOR_BOOLEAN_OR_TEXT-TRUE</entry>
          <entry key="42">MY-ICON_FOR_NUMBER_OR_TEXT-42</entry>
          <entry key="myStringValue">MY-STRING_VALUE_ICON</entry>
        </entry>
  </value>

The key of each entry is the string representation of your field value, and the content is the resulting icon key. If you don't want to display any icon for certain values, just don't mention them, because only mentioned values will result in an icon.

Your field value will be converted to its string representation, so that true becomes simply <entry key="true" ... (same for false), null becomes an empty string <entry key="" ... and number values like 42.1337 result in <entry key="42.1337" ....

Note: It is not recommended to use types like arrays or dates because their behavior is not defined.

# ShowEmpty: Leave space for empty values

The same metadata icon may appear in different positions on the rich tile, depending on how many other icons are defined and active for an object. This is because icons are not fixed and show in the first free position.
So it may be confusing for a user that an icon with necessary information is sometimes in the fifth position, sometimes in the second and sometimes in the first.

In this example, the globe (which tells that an object is on the website) appears in different positions, because not all configured metadata icons apply for the second object.

If you need a good overview and fixed positions for your icons (especially if the icons you use look quite alike), you can use the option showEmpty. This option will leave a blank space for an icon, even if the resulting icon key is empty:

 <value class="map">
   <entry key="fieldName">my_second_field</entry>
   <entry key="showEmpty" class="boolean">true</entry>
   <entry key="iconMapping" class="map">
    <entry key="">ICON_NAME-FOR-NULL_VALUES</entry>
   </entry>
 </value>

Now, all configured icons have their fixed position. Two placeholders block the first two positions for the icons "excavator" and "camera" until the value may change. The globe shows always on position three now.

For each new icon you want to use in your metadata icon-list, make sure to create one in your styles folder.

← SendMailAction Aggregations →