Image Placeholder

Processwire module for easy creation of placeholder images on the frontend. Uses TrueType fonts for the placeholder text (fe Sorry, no pic!).

Requirements

• PHP>=8.1
• ProcessWire>=3.0.181
• PHP GD library with FreeType support (needed for TrueTypeFonts)

Usage

My intention was to create "real" placeholder images for products, user images and others that will be displayed to real site users if an image is missing. I did not want to use too much different font families on a site. For this reason, I thought that it would be pretty cool to be able to use the same font for the text inside the placeholder image as used for the text of the site. This is possible with this module.

Another aspect was that a "real image" could be used without problems with CSS frameworks components, whenever an image is needed (but not present). I am thinking fe of the comment component of the UiKit framework. In the markup, you will need an image tag for the user image.

In general, you can use this module whenever a "real" image (page element with img tag) will be needed, but no image file is present at the moment.

Features

• 2 TTFs are shipped with this module by default (FjallaOne-Regular.ttf and Lobster-Regular.ttf).
• Allows upload and deletion of other fonts
• Allows scanning the complete site to find and use other TrueTypeFonts (fe used by templates or other modules)
• Preview of all fonts in the select font input field - you can see how the font looks like
• Global setting of various colors: background color, text color,..
• Supports adding of text shadow to the placeholder text
• Set global placeholder text (multi-language)
• Add an icon (FontAwesome 4.7 shipped with ProcessWire or a custom icon font) or an image (fe your logo) above, below, left or right of the text - or use the icon only
• Icon picker inside the module configuration: all icons of the selected icon font in a grid with search
• Upload of images (PNG, WebP, GIF) for the image icon, optionally colorized with the icon color
• Set global CSS class for the placeholder image tag
• Color picker for all color fields (color picker of the browser or FieldtypeColorPicker/FieldtypeColor, if installed)

Public methods to set/change properties manually

• setTextColor(string)
• setBackgroundColor(string|null)
• setWidth(int)
• setHeight(int)
• setFontFamily(string)
• setFontSize(int)
• setText(string|null)
• setCSSClass(string)
• setShadowColor(string|null)
• setXOffset(int)
• setYOffset(int)
• setAltText(string)
• setIcon(string|null)
• setIconSize(int)
• setIconColor(string|null)
• setIconPosition(string)
• setIconSpacing(int)
• setIconFont(string|null)
• setIconImage(string|Pageimage|null)
• setIconImageTint(bool)
• setIconType(string)

Use these methods below to set a value or to overwrite default values from the module configuration.

Other public methods: render(bool $tag = false), resetSettings(), getIconType(), getIconNames(), getIconList(), getIconFontFiles(), getTextFontFiles(), getIconImages() and the getters of the values above (fe getWidth(), getIcon()).

Please note: Values set with these methods are only valid for the next render() call. After rendering, all values will be reset to the global values of the module configuration, so they will not be taken over by the next placeholder image.

setText() method

With this method you can set or overwrite the global placeholder text or you can disable the output of any text. If you have a multilingual site please use translatable strings (fe _('My text')) as value. By default, there is no placeholder text set after you have installed the module.

setText(_('My placeholder text'))

If you want to disable the output of the text, use this method without a parameter inside the parenthesis.

setText()

In this case only the image without text inside will be rendered, independent if a global placeholder text was set in the backend or not.

setTextColor() method

Set a hexadecimal color for the text if you want to overwrite the default text color.

setTextColor('#990000')

setBackgroundColor() method

Set a hexadecimal color for the background if you want to add or overwrite the background.

setBackgroundColor('#000000')

If you want to remove the background color to get a transparent background, do not add a hexadecimal code inside the parenthesis.

setBackgroundColor()

setFontFamily() method

Set the name of the Font-Family that should be used. You can only use fonts that you will find inside the font family select inside the module configuration. If you enter a font family name that does not exist, an error message occurs.

setFontFamily('myFont') or setFontFamily('myFont.ttf').

It does not matter if you add the extension or not.

setWidth() method

Set the width of the image in px.

setWidth(600)

setHeight() method

Set the height of the image in px. If no height is set explicitly, the default height from the module configuration will be used.

setHeight(300)

setCSSClass() method

Set or overwrite the CSS class of the image tag.

setCSSClass('my-image')

setFontSize() method

Set the fontsize of the placeholder text in px (without entering the px inside the parenthesis).

setFontSize(30)

setShadowColor() method

Set a hexadecimal color for the shadow color if you want to add a shadow to the text.

setShadowColor('#990000')

If you want to disable the shadow, do not add a hexadecimal code inside the parenthesis.

setShadowColor()

The shadow color and the offsets (setXOffset(), setYOffset()) are used for the icon too - for image icons the shadow is created from the shape of the image.

setXOffset() method

Set the offset for the x-coordinate of the text shadow. You can enter positive or negative values

setXOffset(3)

Offset on the x-axis is 3px in this case.

setYOffset() method

Set the offset for the y-coordinate of the text shadow. You can enter positive or negative values

setYOffset(-2)

Offset on the y-axis is -2px in this case.

setAltText() method

With this method you can change the alt attribute of the image tag.

setAltText('my custom alt text')

setIcon() method

Add an icon to the placeholder image. By default, the icons of FontAwesome 4.7 (shipped with ProcessWire) are used. You will find all FontAwesome 4.7 icons at fontawesome.com/v4/icons. Enter the name of the icon (with or without the prefix, fe "user" or "fa-user") or its unicode (fe "f007").

setIcon('user'), setIcon('fa-camera') or setIcon('f007')

If you want to remove the icon, use this method without a parameter inside the parenthesis.

setIcon()

If you want to display the icon only, remove the text with setText().

setIconSize() method

Set the size of the icon in px (without entering the px inside the parenthesis).

setIconSize(80)

setIconColor() method

Set a hexadecimal color for the icon. Without a value, the text color will be used. For image icons the color is only used if the image should be colorized (see setIconImageTint()).

setIconColor('#990000')

setIconPosition() method

Set the position of the icon relative to the text. Possible values are top (default), bottom, left and right.

setIconPosition('left')

setIconSpacing() method

Set the space between the icon and the text in px.

setIconSpacing(20)

setIconFont() method

Use another icon font than FontAwesome 4.7 (fe Bootstrap Icons, Material Icons, Remix Icon, Tabler Icons or FontAwesome 6). Enter the file name of the font. Please call this method before setIcon(), because the icon name will be checked against the selected icon font.

setIconFont('remixicon.ttf')->setIcon('camera-line')

Use this method without a parameter to switch back to FontAwesome 4.7. The default icon font can also be selected inside the module configuration.

setIconImage() method

Use an image as icon instead of an icon of an icon font (fe your logo). You can enter the path of the image (absolute or relative to the root of your site), its url or a ProcessWire image. Supported formats are PNG, WebP and GIF - formats that support transparency. JPG is not supported, because it cannot have a transparent background.

setIconImage('/site/templates/images/logo.png') or setIconImage($pages->get(1)->images->first())

The icon size (setIconSize()) is used for the longer side of the image, the aspect ratio is kept. To get a sharp result, the image should be at least as large as the icon size. The text shadow color and offsets are used for the shadow of the image too (created from the shape of the image).

Use this method without a parameter to remove the icon.

setIconImageTint() method

Colorize the image with the icon color. This is only useful for single-colored images with a transparent background (fe a black logo): all visible pixels get the icon color, the transparency is kept.

setIconImage('/site/templates/images/logo.png')->setIconImageTint()->setIconColor('#1f6fb5')

setIconType() method

Set the type of the icon: none (no icon), font (icon of an icon font) or image. Normally you do not need this method, because setIcon() switches to "font" and setIconImage() to "image". Both methods without a value switch to "none".

setIconType('none')

Icon type inside the module configuration

Select the icon type inside the module configuration first: "No icon", "Icon of an icon font" or "Image (fe logo)". Only the settings for the selected type are shown (without saving).

Icon picker

For the icon type "Icon of an icon font" you can click on "Show icons" below the icon field to see all icons of the selected icon font in a grid. Use the search field to filter the icons by name or unicode and click on an icon to select it. The search can be cleared with the x button or the Escape key. If you change the icon font, the grid will be updated immediately (without saving). Only icons that exist inside the font file are shown.

Images

For the icon type "Image (fe logo)" you can upload new images (PNG, WebP or GIF), select the default image by click on its thumbnail and delete uploaded images. An uploaded image can be selected after saving the module configuration. The images are stored inside site/assets/files/JkImagePlaceholder/images/.

Other icon fonts

1. Upload the TrueTypeFont (.ttf) of the icon font inside the module configuration (or put it anywhere inside your project and press "Update font files").
2. Upload the CSS file of the icon font too (fe remixicon.css for remixicon.ttf) - then you can use the names of the icons. For Google Material Icons you can upload the .codepoints file instead. Without such a file, you have to use the unicode of the icons (fe setIcon('eb31')).
3. Select the icon font inside the module configuration or use setIconFont().

The same icon (camera) from different icon fonts: FontAwesome 4.7, Remix Icon, Tabler Icons and FontAwesome 6

The CSS file will be found automatically if it has the same name as the font or if it references the font file and is stored inside the folder of the font, the parent folder or a "css" folder next to them (fe FontAwesome 6: webfonts/fa-solid-900.ttf and css/all.css).

Icon fonts are detected automatically and will not be listed as text fonts: FontAwesome and Entypo by their name, all other icon fonts by their characters (most of the characters of icon fonts are stored inside the Unicode Private Use Area).

Please note: Only TrueTypeFonts (.ttf) are supported. Some icon fonts are only available as .woff/.woff2 (fe FontAwesome 7, Bootstrap Icons) - use an older version with a .ttf file or convert the font.

Examples for usage in templates

Usage with default values from the module configuration

echo $modules->JkImagePlaceholder->render();

or

echo $modules->JkImagePlaceholder->render(true);

The first code outputs the image src value as base64 string. In this case you have to write the image tag by yourself. The second one with boolean true as parameter renders the complete image tag.

Usage with all parameters set individually (global values will be overwritten)

echo $modules->JkImagePlaceholder
->setFontSize(30)
->setWidth(800)
->setHeight(400)
->setCSSClass('placeholder-class')
->setBackgroundColor('#dddddd')
->setTextColor('#000000')
->setText('My placeholder text')
->setFontFamily('pacifico.ttf')
->setShadowColor('#666666')
->setXOffset(-1)
->setYOffset(1)
->setIcon('camera')
->setIconSize(60)
->setIconColor('#990000')
->setIconPosition('left')
->setIconSpacing(15)
->render(true);

Placeholder with your logo

echo $modules->JkImagePlaceholder
->setIconImage($pages->get(1)->images->first())
->setIconSize(120)
->setText('No picture available')
->render(true);

Placeholder with an icon only (fe for user images)

echo $modules->JkImagePlaceholder
->setWidth(300)
->setHeight(300)
->setText()
->setIcon('user')
->setIconSize(150)
->render(true);

Input field for colors

The color fields inside the module configuration use the color picker of the browser (HTML5 color input) with an editable hexadecimal code next to it. For the optional colors (background, text shadow and icon color) a checkbox "No color" is shown, because a color picker always contains a color.

If FieldtypeColorPicker or FieldtypeColor is installed, its input field will be used instead (FieldtypeColorPicker, if both are installed).

Preview of font family

The font family selection field provides a preview of all fonts, so it will be much easier for you to decide which font you want to use.

Unit tests (for developers)

The module contains unit tests (PHPUnit). They test the logic of the module without a ProcessWire installation: a small replacement of the ProcessWire API is used (tests/Stubs/ProcessWire.php) and the test site is installed inside a subdirectory, so ProcessWire installations inside a subdirectory are tested too.

Requirements: PHP >= 8.1 with the GD library (FreeType support) and Composer.

composer install
vendor/bin/phpunit

The fixtures (small test icon fonts, CSS files and images) were created with tests/Fixtures/generate-fixtures.py (Python 3 with fontTools and Pillow), so the tests do not depend on third-party fonts. The tests run automatically on GitHub for PHP 8.1 to 8.4 (.github/workflows/tests.yml).

The development files (tests, phpunit.xml, composer.json, .github) are not part of the downloaded module (see .gitattributes).

Multi-language

This module includes the German translation file (languages/de.csv).

If you have installed the RockLanguage module, the translations will be synced automatically from the folder RockLanguage/DE (see CHANGELOG).