The final, and topmost, layer of an OpenGraph image template in SocialMagick is for (optional) text.
If you do not want any text at all, set the Overlay Text option to No. Do note that this cannot be overridden in categories, content items, and menu items. It completely disables text overlays with this template.
The Template does not allow you to select a source for the text. This is always set at the category, content item, or menu item level. The template only tells SocialMagick whether and how to render overlay text. It does not tell it what to text to render. This is quite different than the Extra Image tab which defines both the source, and the rendering options.
The Font For Text lets you select a TrueType (.ttf) font file to use for rendering the text. SocialMagick comes with two font files for the Open Sans Bold and Open Sans Bold Italic typefaces. If you would like to use different fonts, upload the corresponding TrueType font files into the plugins/system/socialmagick/fonts directory of your site. Kindly note that you are solely responsible for adhering to the license of the font you are using. Some fonts may be free for use on the web, but not for use in images – even if automatically generated ones. The Open Sans font is a thoroughly Open Source font, without any restrictions.
The Font Size (in points) lets you select how big the text will be. We are using points, not pixel, sizes because they are the most common font size metric in text and graphics processing software. If you want to work out the font size in pixels, it's 1.33 pixels to a point and 0.75 points to a pixel. We recommend font sizes between 40 to 70 points as your image will be scaled down 2–3 times when displayed. Text smaller than that would be unreadable in many practical use cases.
There are 72 points to an inch. Graphics are rendered by browsers at an average density of 96 pixels per inch. Therefore one point is 1.33 pixels. Conversely, that's 0.75 points per pixel. A 16 pixel text size (the default used by most browsers) is 12pt.
The Text Colour and Opacity control the colour (fill) of the text. You may want to use an Opacity lower than 100 –therefore, semi-transparent text– for artistic effect. This works best with large font sizes rendered over a large area of the image.
Sometimes it may be hard to make out the text against a background that's either busy, or a similar luminosity to the text. This is a long-understood problem; it affected movie and television subtitles, too! The solution is to have a contrasting contour surrounding and following the letter shapes to better isolate them from the background. This is called a stroke. You can use the Text Stroke Colour and Text Stroke Width to select the colour of the stroke, and how wide it will be in pixels. If you do not want a text stroke set the Text Stroke Width to 0. Please note that if you set an Opacity less than 100 for the text colour, the text stroke will also have the same opacity. This is intentional. The text is rendered with the stroke, and the opacity is applied to the whole overlay text including the stroke.
SocialMagick renders text inside a text box. The size (width and height) of this text box is given in the Maximum Text Height (px) and Maximum Text Width (px) options.
The positioning of the text box on the horizontal and vertical axis can either be centered, or positioned exactly as a number of pixels measured from the edge of the image.
Enabling Centre text vertically? (default) will position the text box on the vertical axis so that its centre point is halfway between the top and bottom edge of the image. Use the Nudge Vertically from Centre (px) option to move the text box vertically towards the bottom (positive numbers) or the top (negative numbers) of the image.
Disabling Centre text vertically? will position the text box on the vertical axis so that its top edge coincides with the image's top edge. Use the Pixels from the Top option to move the text box towards the bottom of the image.
Enabling Centre text horizontally? (default) will position the text box on the horizontal axis so that its centre point is halfway between the left and right edge of the image. Use the Nudge Horizontally from Centre (px) option to move the text box horizontally towards the right (positive numbers) or the left (negative numbers) of the image.
Disabling Centre text horizontally? will position the text box on the horizontal axis so that its left edge coincides with the image's left edge. Use the Pixels from the Left option to move the text box towards the right of the image.
SocialMagick uses a text rendering concept which is a lot like how a browser would render text in a block container with the CSS style overflow: hidden; text-overflow: ellipsis;.
Here's how it works. The text is broken down into word-like pieces by finding spaces (ASCII 32) in the text. These word-like pieces are distributed into "lines" so that each line contains as many (but at least one!) word-like pieces keeping its length under the Maximum Text Width. Then, the algorithm tries to see how many of these "lines" fit fully within the Maximum Text Height and throws away the rest. If not all word-like pieces were used, it will try to add ellipsis (…) after the last word-like piece of the last line it will render. If that makes the line exceed the Maximum Text Width it will delete the last word-like piece of the last line, replacing it with ellipsis.
The following edge cases cannot be handled:
If your vertical or horizontal height are small enough that not even one word-like part can be rendered fully within the allocated text space, no text will be rendered. This is a deliberate choice. In any other case, you'd end up with clipped, unreadable text.
Some languages, especially Asian ones, do not use spaces (ASCII 32) to separate words. Therefore, the entire text may end up being considered one long word-like piece. Likewise, if your words are separated by punctuation other than regular spaces –such as dashes, underscores, points, etc– these will be considered a single word-like piece (e.g. do-not-disturb is considered one word-like piece). This may result in your entire text being considered as a few very long word-like pieces which exceed the Maximum Text Width and are clipped as a result. Moreover, if you have more than one of these pieces you may end up in a situation where the only text rendered is the ellipsis or (for small enough text box sizes and big enough font sizes) seemingly nothing at all.
Quotes, parentheses, braces, and other punctuation are consider as part of a word-like piece. This may result in rendered text such as He said: “enough… which is grammatically incorrect. Do note that browsers rendering text with hidden overflow also suffer from the same problem. In fact, there is no good way to automatically handle this use case without rewriting the text.
In most cases, the default behaviour is fine. If you hit the aforementioned edge cases it is best to override the rendered text at the content or menu item level with something that reads and displays well.