Skip to content

Setting up your templates

How templates work

Templates are based on HTML with custom attributes added to the tags that tell carimbo how to fill in the data that is passed with each request.

After your template is set up a call the following call to your template will generate the below image:

https://app.carimbo.dev/public/crowdfundnow/campaign/rendered.png
    ?title=CosmoCube: The Ultimate Interstellar Home Aquarium
    &progress=60%
    &duration=Ends on Aug. 5, 2023
    &thumbnail=https://static.crowdfundnow.imaginary/image1.png
    &url=https://crowdfundnow.imaginary/cosmo-cube
(url parameters are not encoded here for legibility)

CrowdFundNow Sample Image

This allows you to create dynamic social cars (a.k.a. open graph images) without any API calls or rendering on your end.

Writing regular HTML to create your layout

Let's look at a simpler exampel to get started. Imagine we want to achieve the following preview image that simply shows somebody's name infront of a pink background:

Sample Template

To achieve this we can use the following HTML: 

<html>
  <head>
    <style>
      body {
        background-color: pink;
        margin: 0px;
      }
      h1 {
        color: white;
        text-shadow: 4px 2px 60px red;
        font-size: 60px;
        position: absolute;
        margin: 0;
        top: 50vh;
        left: 50vw;
        transform: translateX(-50%) translateY(-50%);
      }
    </style>
  </head>
  <body>
    <h1>Jeff</h1>
  </body>
</html>

It's standard HTML and there's nothing we need to change about it for it now.

Making your HTML dynamic

In its current state the HTML will always say "Jeff". To make it dynamic, we need to tell carimbo which elements to change.

This is done by adding the carimbo-id tag to an HTML element. The value of this attribute is used as the query parameter to change the content of the tag.

We need to make these changes to the <h1> tag of our template to be able to change the name:

<h1 carimbo-id="name">Jeff</h1>

carimbo will now show this field in the editor and the preview URL at the bottom of the page. If we save the template, we can now generate images like this:

https://app.carimbo.dev/example/example/rendered.png?name=Jerry

Sample Template

Modifying what attribute of the element to change

By default, caribo will update the innerHTML property of any element. If we want to change other aspects of the element, we can specify what to modify using the carimbo-target attribute.

The target can be set to one of the following values:

carimbo-target Effect
src Changes the src attribute of the element.
width / height Changes the width or height in the element's css styles.
color Changes the color of the element's css styles (text color).
bg-color Changes the background-color of the element's css styles.
any other value / no value Changes the inner HTML of the element.

Note

It is currently not possible to change multiple properties of the same element. You can, however, use the same carimbo-id to modify multiple elements. If you really need modify to multiple properties of one element you can wrap it in other elements like this: 

<span carimbo-id="name-color" carimbo-target="color">
    <span carimbo-id="name">Name</span>
</span>