Creating a custom template

The Simple Social Images plugin comes with a wide variety of different templates for your to choose from. However, if you need something more custom, you can create your own template.

In this article we look at how to create your own custom template to use with the Simple Social Images plugin.

The template file

All templates in Simple Social images consist of 1 file. This file should include:

Template markup – this is the HTML structure of your template
CSS – these are the style rules that control how your HTML markup looks
Merge tags – these are special strings which get replaced with the actual data from the post e.g. the post title.

Template file location

To allow your custom template to show in the list of templates to choose from, you should place your template file inside your active theme in the following folder structure:

ssi/templates/{template-name}.html

Once your template is placed in that location, visit the plugin settings page and you should see your template at the bottom of the template selection dropdown. To use your custom template, choose this from the dropdown and save the settings page.

Once you do this, you will notice that some settings disappear when the page loads. The settings removed are the display settings such as colours, fronts, and sizes which you can control in your templates CSS.

Template markup

The beauty about using Simple Social Images is that templates are made from HTML and CSS. This means you can use whatever markup you want in your template.

CSS

You should include your CSS above your template markup in <style> tags.

Template wrapper

Your outer template wrapper will be a div with a class of ssi-template--{template-name}, where {template-name} is the filename of your template.

For example, if your custom template file is my-template.html, your wrapper class will be ssi-template--my-template.

Size units

We recommend using relative sizes in your CSS.

We’ve created a custom property for you to use (--ssi-template--unit) that allows for units relative to the template width.

Each ‘unit’ is 1% of the rendered width of the template.

For example:

.ssi-template__title {
  font-size: calc(10 * var(--ssi-template--unit));
}

The above code sets the font size to 10% of the template width.

This means that no matter how large or small the template is rendered the font size will correct.

Why not use relative viewport units?

Sometimes, we need to render the template at less than 100% viewport width (e.g. in the template previews).

Using vw units would break the template.

Merge tags

Merge tags are the special strings that get replaced with the real data from a post. The merge tags are all added in square brackets.

The following merge tags are available.

[ssi:image_url] – this merge tag is replaced with an image. If you post has a featured image, this image is used, otherwise it will fall back to a random background image added on the plugin settings page.
[ssi:logo_url] – this is replaced with the logo image added on the plugin settings page
[ssi:author_avatar_url] – is replaced with the URL of the authors avatar image.
[post:post_title] – this merge tag is replaced with the title of the post
[post:post_author] – this is replaced with the post authors display name
[post:post_date] – replaced with the post published date and is output in the format selected in the WordPress general settings screen.
[tax:tax_name] – this will be replaced with a list of the terms for the given taxonomy. For post categories you would use this – [tax:category]
[meta:meta_key] – this is replaced with the value of the meta key provided. For example, if you have a meta key of person_name the following merge tag would output its value – [meta:person_name]
[siteinfo:name] – replaced with the name of the website as set in Settings > General in the WordPress admin.
[siteinfo:description] – replaced with the description of the website as set in Settings > General in the WordPress admin.
[siteinfo:url] – is replaced with the site URL.

Example custom template

<style>
    .ssi-template--custom-template {
        --custom--logo--height: calc(6 * var(--ssi-template--unit));
        position: relative;
    }

    .custom-template__title {
        font-size: calc(6 * var(--ssi-template--unit));
        line-height: 1;
    }

    .custom-template__logo {
        height: var(--custom--logo--height);
        position: absolute;
        z-index: 1;
        top: calc(3 * var(--ssi-template--unit));
        left: calc(3 * var(--ssi-template--unit));
    }

    .custom-template__image {
        position: absolute;
        top: 0;
        bottom: 0;
        left: 0;
        right: 0;
        object-fit: cover;
        width: 100%;
    }

    .custom-template__title {
        position: absolute;
        bottom: 0;
        left: 0;
        margin: calc(3 * var(--ssi-template--unit));
        padding: .25em;
        color: black;
        background-color: white; 
    }

    .custom-template__author {
        position: absolute;
        top: calc(var(--custom--logo--height) + (3 * var(--ssi-template--unit)));
        right: 0;
        margin: calc(3 * var(--ssi-template--unit));
        padding: .25em;
        color: black;
        background-color: white; 
    }

    .custom-template__avatar {
        height: var(--custom--logo--height);
        position: absolute;
        z-index: 1;
        top: calc(3 * var(--ssi-template--unit));
        right: calc(3 * var(--ssi-template--unit));
    }
</style>

<img class="custom-template__logo" src="[ssi:logo_url]" >

<img class="custom-template__image" src="[ssi:image_url]" >

<div class="custom-template__title">[post:post_title]</div>

<img class="custom-template__avatar" src="[ssi:author_avatar_url]" >

<span class="custom-template__author">Written by [post:post_author] on [post:post_date]</span>