Core | Essentials | DAM (4.37)

# Icons and Icon Creation

The 4ALLPORTAL uses icons in multiple ways, e.g.:

  • module icons in the menu structure
  • action icons in the toolbox
  • icons for object references
  • icons to illustrate value options in a selection renderer


different icons in the GUI

  • Icons are stored per theme in the file system's styles folders (storage).
  • They can be of format 4APIcon, SVG, or PNG format (format).
  • Native 4APIcon files work with a redirect to a file of format SVG or PNG stored in the icon library (proxy).
  • The IconManager handles icons and redirects in the backend (IconManager).

Related documentation

# File Format and Syntax

The icons used in the 4ALLPORTAL can be of either format 4APIcon, SVG, or PNG. SVG files require extension .4apicon, PNG files .png.

The naming syntax of an icon depends on and displays its implementation context, e.g.:

  • Conditional operation: CO-{MODULE}-{CO-NAME} (e.g. CO-GLOBAL-CREATE.4apicon)
  • Field renderer: {MODULE}-{FIELDNAME} (e.g. FOLDER-TREE_ITEM_RENDERER-ISUPLOAD_FOLDER.4apicon)
  • Value option: V-{VALUE-OPTION-NAME}-{VALUE-OPTION-KEY} (e.g. V-LANGUAGE-EN_US.4apicon)
  • Dimension: D-{DIMENSION-NAME} (e.g. D-CHANNEL.4apicon)
  • Admin snap-in: A-{ADMIN-SNAP-IN-NAME} (e.g. A-LOGIN_ATTEMPT.4apicon)
  • Admin group: AG-{ADMIN-GROUP} (e.g. AG-DAM-CONFIGURATION.4apicon)
  • Admin subgroup: ASG-{ADMIN-SUBGROUP} (e.g. ASG-USERMANAGEMENT.4apicon)

Note that the prefixes are analogous to the label prefixes (more information).

4APIcon vs PNG vs SVG

If there are icons with the same file name but different extensions, they apply in the following order:

  • PNG before
  • 4APIcon before
  • SVG

PNG-based icons have priority over 4APIcons, because a customer may want to overwrite default icons and is more likely to do this with PNG files.

Please note:

Although the system supports storing SVG or PNG files in folder global/styles/{theme} directly (i.e. without creating a 4APIcon proxy), we highly recommend to store image files in the library and work with 4APIcon proxy files.

# 4APIcon Files and Icon Proxy

The 4ALLPORTAL supports so-called icon proxies. These are of type 4APIcon and follow a basic SVG structure. They are no actual image files, but redirect files that refer to an already existing icon from the icon library. Thus, multiple 4APIcons can refer to only one image file in the icon library.

4APIcon files are of format XML. They basically need an SVG tag and within a redirect tag which points to another icon name:

<svg>
  <redirect>icon_library/eye</redirect>
</svg>

Redirecting ensures that system-wide icons always looks the same. The referred to image can quickly be edited or replaced in its storage folder instead of editing it multiple times at its implementation places.

# Icon Storage and Themes

Icons are handled per theme. The standard 4ALLPORTAL comes with themes default and dark (more information about themes). As soon as an additional (custom) theme is configured, it must hold its own styles folders.

Icons are stored and retrieved from two cooperating styles folders:

  • Folder styles/{theme} contains the files of format .4apicon - which redirect to the actual images.
  • Subfolder styles/{theme}/icon_library is the icon library which contains the actual images in formats SVG or PNG.

# Global or Module-specific?

Icons are not module-specific. All icons (also module-specific ones) can be stored in the global folder, but may also be stored in a module's folder. Icons stored in a module's styles folders override a global icon for all modules, if it had the same filename.

Although module-specific icons are supported, we recommend keeping all icons in a global library to help keeping track.

# Example Folder Structure for Two Themes

If your system works with a custom and the 4ALLPORTAL standard theme default, the folder structure should look like this:

  • global/styles/default (for global .4apicon files)

  • global/styles/default/icon_library (for global referred to image files)

  • optional: modules/{module}/styles/default (for module-specific .4apicon files)

  • optional: modules/{module}/styles/default/icon_library (for module-specific referred to image files)

  • global/styles/my_custom_theme (for global .4apicon files)

  • global/styles/my_custom_them/icon_library (for global referred to image files)

  • optional: modules/{module}/styles/my_custom_them (for module-specific .4apicon files)

  • optional: modules/{module}/styles/my_custom_them/icon_library (for module-specific referred to image files)

Default Icons in a Custom Theme

You can create a custom theme but keep all icons from the default. In that case, you only need to create the new theme's folder next to the default folder. Its content is the theme file with the color information. All icons will automatically be retrieved from the default theme. You may replace individual icons, though, which will override the default.

# Request Logic and Fallback

When an icon available for the requested theme is accessed, it is found in the cache directly. E.g. an icon "create" from theme default is cached under default/create. If an icon (of any kind) is not found, there is a two-step fallback mechanism:

  1. If the requested theme is not default, the icon is searched for in the default theme.
  2. If the icon is not found in the default theme, icon "fallback.4apicon" is taken (the 4ALLPORTAL logo).

As soon as the actual icon is not available, the IconManager responds with a permanent redirect (302) to the respective icon.

Please note: If an icon is stored in a module's folder, and an icon with the same name is also stored globally, the module-specific icon will override the global icon.

# Icon Creation

If you want to implement a new icon in your system, you need to:

  1. Design a new icon, preferably of format SVG (design tips).
  2. Store it in the correct theme's library folder (global), or, in a module's folder if you wish to override an icon from the global folder.
    Please note: A module-specific icon will override a global icon in every case, also for other modules.
  3. Create a new 4APIcon proxy file (naming rules) with extension ".4apicon" in the corresponding parent folder.
  4. Implement you icon into your system (e.g. in an object renderer).

# Example


image "eye.svg" in its storage folder global/styles/default/icon_library

<svg>
  <redirect>icon_library/eye</redirect>
</svg>

4APIcon proxy "GLOBAL-CO-READ.4apicon" in folder global/styles/default

<action>
	<label>L-GLOBAL-CO-READ</label>
	<info>L-GLOBAL-CO-READ-INFO</info>
	<icon>GLOBAL-CO-READ</icon>
	<max_beans>1</max_beans>
	<views>
		<view visible="false">detail</view>
		<view visible="true">main</view>
		<view visible="true">subpanel</view>
	</views>
    <!-- more stuff -->

icon implemented in global action "read.xml"


icon "GLOBAL-CO-READ.4apicon" in the GUI

# Design and Creation of Custom Icons

If you want to create a custom icon, please consider the following tips to ensure a consistent style throughout the system:

  • Try to use the vectorized file format like .4apicon or .svg.
    Note that SVG attribute "viewBox" needs to be defined.
  • Try to build square-based icons.
  • Try to use paths only - no pixel based graphics (not even in .4apicon or .svg formats although this would work).
  • The size of the icon should be dividable by 2.
  • Do not use layers in your icons.
  • Do not use colors in your icons. Colors will automatically be applied by the current theme.

Design Guide and Resources

For a good result when creating a custom icon, please consider the following design principles of Google, Apple or Font Awesome when creating your icons:

Material Design (opens new window)

As an alternative, you can also search these publicly available resources for icons/icon sets, e.g. (external links):

← Implement and Customize the HTML Text Editor →

Request missing documentation