Support for

TCAPI: Choosing a template

John Valentine
by John Valentine 6 years ago

Approaches for selecting a template

The purpose of your website is to select a template and buy a PDF for your customer. Often your customer will not know which template they want, so your site will need to present some templates, to eventually reduce the selection to the one that the customer wants.

There are many approaches to achieving the objective of reducing your customer’s options to one.

  • Start with everything (possibly matching a user-initiated text search), and present filters to help narrow down the options.

  • Start with a few filters enabled,  to restrict your users to a subset of the total TemplateCloud library. Do this if:

    • Your site is ‘special interest’ or is dedicated to a business category, or you have a limited set of templates you want to sell (without the ability to remove those filters);

    • You want to inspire your users on a particular theme (where you make the filters available to switch back to the full collection).

  • Start with a suggestion of one template. Feature a design, or randomly choose from a small pool of designs, showing only one of them at a time. Your user then has the one template needed to (customise and) progress the order.

Getting a list of templates

TemplateCloud contains thousands of templates, tagged to enable their discovery. Each criterion (size, colour, industry type, number of pages, etc) is a tag type having several possible tags within that type.

If presented with an untargeted list of thousands of templates, it’s unlikely that your customer will find the template that they want, so you should ask TemplateCloud which tag types are available, and publish these tags as search options on your website, under tag type headings. It is conventional to add these as checkboxes alongside your search results.

You’ll probably want a page of initial search results, especially if you used a text search as a starting point. It’s also advisable to cache the results and present them to the client a page at a time.

Getting a list of tags

Call the template method, with filter_options=1, which returns the tags that are present in the templates that would be returned when filter_options=0. In other words, this gets a list of tags.

HTTP request

The response looks like this:

HTTP response (JSON)
     "colours" : [
            "colour" : "86200e",
            "name" : "Maroon"
        more colours ...
    "sizes" : [
            "name" : "US Business Card (2x3in)",
            "code" : "USABC",
            "count" : "572",
            "selected" : false,
            "area" : 7
        more sizes ...
    "tags" : [
            "title" : "Product Types",
            "types" : "PRODUCT",
            "tags" : [
                    "name" : "Appointment Cards",
                    "code" : "194",
                    "count" : "42",
                    "selected" : false
                more tags of type 'product'...
        more tag types...

You can parse this response into an array, and present the options on your pages.

When your customer ticks the filter options, you should initiate a refined search using an API call having filter_options=0 and the ticked tags encoded into parameters. Note that when a tag is specified, then it excludes all templates that do not have that tag within the tag type.

Including meta-information in your search results

To ask for extra information about the templates, you use the &include parameter to ask for a list of properties. e.g. here we want to know about sizes, colours, tags, tag groups, and images.

HTTP request

%2C is a comma, encoded as URL-compatible text.


Jump to contents page of

TemplateCloud API Guide


All content is (c) Grafenia Operations Limited, 2020 and may not be used, copied or distributed without permission.