Gentics CMS-OSS Documentation

Chapters

1. Overview

2. Standard behavior

3. Configuration

   • Sanitize characters list

   • Allowing other characters

   • Setting the standard replacement character

4. Examples

   • Replacing with special characters

   • Replacing a character that is allowed by default

   • Using hyphens instead of underscores

1 Overview

Gentics CMS will use the sanitize_character array from the .yml files in /cms/conf to transform special characters from filenames of pages, images and files and folder paths. This configuration is also used with the Aloha Editor headerids plugin to generate header ids from text contents.

The purpose of this feature is to transform special characters to characters that are allowed in a filename in a meaningful way.

For example: the character “è” is used in many languages, so it makes sense to replace it with “e” in the filename, because it would be lost otherwise. The default settings for sanitizing characters are:

		'é' => 'e',
		'è' => 'e',
		'ë' => 'e',
		'ê' => 'e',
		'à' => 'a',
		'ä' => 'ae',
		'â' => 'a',
		'Ä' => 'Ae',
		'ù' => 'u',
		'ü' => 'ue',
		'û' => 'u',
		'Ü' => 'Ue',
		'ö' => 'oe',
		'ô' => 'o',
		'Ö' => 'Oe',
		'ï' => 'i',
		'î' => 'i',
		'ß' => 'ss'

This will transform strings as follows:

	"äöï 23.jpg" => "aeoei_23.jpg"
	"ia 23$%.html" => "ia_23__.html"

2 Standard behavior

If the configuration is not changed, the standard behavior of sanitizing filenames and paths will be the following

1. Replace all characters listed in the map above by their specific replacement.
2. Replace all characters, that are not allowed with the standard replacement character (see Setting the standard replacement character). By default all alphanumeric characters, including “_”, and all of “.-()[]{}$/” are allowed and will not be replaced.

Further Rules:

• All leading and trailing whitespace will be removed
• If the name is empty, then the resulting filename will begin with “1”
• If the name starts with a dot “.” then the sanitizing will put a “1” before the dot. (This is because certain apache installations would interpret the filename as a hidden file, if it starts with a dot.)

3 Configuration

3.1 Sanitize characters list

You can redefined the pre-defined set of replacements or just add new ones in “node.conf” file like this:

sanitize_character:
  "ï": "i"
  "ä": "ae"

3.2 Allowing other characters

You can specifically allow other characters, so that they will not be replaced.

sanitize_allowed_characters:
  # allow , and µ in filenames
  - ","
  - "µ"

3.3 Setting the standard replacement character

All characters that are not allowed in filenames are replaced with an underscore by default. You can however redefine the standard replacement character like this:

sanitize_replacement_character: "-";

4 Examples

4.1 Replacing with special characters

You can also use the sanitize characters list together with the list of allowed characters like this:

sanitize_character:
  "(c)":  "©"
sanitize_allowed_characters:
  - "©"

This would do

	"(c) 2014 Gentics.jpg" => "©_2014_Gentics.jpg"

4.2 Replacing a character that is allowed by default

If you want to replace e.g. ( and ) with the default replacement character, you need to list them in the sanitize characters.

sanitize_character:
  "(": "_"
  ")": "_"

4.3 Using hyphens instead of underscores

If you want to use hyphens (-) instead of underscores (_), you need to do the following:

sanitize_character:
  " ": "-" # replace space with - instead of _
  "_": "-" # replace _ with -
sanitize_replacement_character: "-" # replace not allowed characters with -