Template Groups

Template groups are preset properties for template and its options that work well together. In most cases at least one group will be a good fit for your Instant Answer.

We strongly recommend using a template group in your Instant Answer. Of course, if you cannot use an available template for your Instant Answer, definitely let us know. E-mail us at open@duckduckgo.com and we'll help you. We may find that a custom template is necessary, and we'll work with you to create an awesome one. (Who knows, your idea may inspire the next official template group!)

How Template Groups Work

Setting a template group automatically sets the item and detail templates for you. Some template groups also set an item_detail template and a few default options.

You can easily customize the appearance of the template group by overriding the default options in your Instant Answer front end code. The appearance will also be affected by which data is returned with each item.

Picking a Template Group

The best template group for your Instant Answer depends on what your Instant Answer is returning. Below are a few suggestions to help you narrow down your options.

A quick way to get a feel for the different template groups is to browse the Instant Answer directory. You can filter by the template group used on the right of the page.

My Instant Answer returns "things" where visuals are important

The Media template group works well when an image is a significant part of the display of an item, as might be a title and a rating. Also consider the Movies template group.

Examples that make a great fit for the Media or Movies template groups include:

If your Instant Answer results are themselves images or videos, consider the Images or Videos template groups.

My Instant Answer returns detailed "lookup" information

The Info template group is designed for Instant Answers that feature in-depth information about one item. It also provides an auxiliary section to display further detail in table or list format.

Examples include:

The List template group works well for lookups that don't need an image; this group is excellent for displaying attributes in just a list or table format. Take a look at the following example:

The Text and Icon template groups are simple templates for presenting text results. They both share the same item template, while the Icon group's detail template is better suited to displaying an icon image.

These results fit this format well:

My Instant Answer returns products with prices, ratings, and brands/authors/artists

The Products template group is great for items characterized by a price, brand, and rating. This is a good template group where images are important.

Examples of results that work well with the Products template group include:

My Instant Answer returns location-based results

The Places template group is perfect for results where location is an important aspect. This template group displays single and multiple items on a map.

Results that would make a good fit for the Places template group include:

My Instant Answer is amazingly unique and existing template groups won't meet my needs

We encourage you to think hard about using an existing template group. For example, many detail templates accept custom handlebars sub-templates. Additionally, many template features can be toggled.

If working within existing template groups feels too constraining, we're happy to help you figure out how your vision could be accomplished using existing templates. E-mail us at open@duckduckgo.com and we'll work with you to find the best way to express your idea.

In this context, the Base template group is a minimal container template that accepts totally custom markup. Because of this, the Base template group is a complete last-resort because of the amount of work up front, and difficult maintenance over time.

Please hold off from using the Base template group until you've contacted us. We hope to save you from ongoing, manual maintenance of your Instant Answer display. Additionally, knowing where our templates fall short helps us understand where we can improve our existing set of templates.


Template Groups Reference

This reference explains what each template group looks like, how it works, and what content works fits it best. Each template group is accompanied by live examples, layout diagrams, code links, and available features.

These are the currently available template groups:

A Note on Default Template Options

When no options are specified and no template group has been selected, the options are implicitly set as follows:

    options: {
        price: true,
        brand: true,
        priceAndBrand: true,
        rating: true,
        ratingText: true,
        moreAt: true,
        content: false
    }

Important Notes

  1. Before using these templates in your code, please familiarize yourself with the method for displaying your Instant Answer type (for example, Spice Display or Goodie Display). This will help understand the proper usage of both the templates block and the options block.

  2. For your desired template features to display correctly, each item's data must contain the corresponding properties. Generally these are set with the aid of a normalize function, if they do not already exist in your data object.

Understanding these is crucial to implementing templates properly and effectively.


Text Template Group

This template group is best used for results which are mostly text, where any images are icons or small logos. This template offers a title, description and footer.

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'text'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'text'
// does this for you!
templates: {
    item: 'text_item',
    detail: 'text_detail'
}

Default Templates Used

See the important notes for making this template display correctly.

Example Uses


Info Template Group

The info template group is designed for Instant Answers that feature in-depth information about one item. This includes an image, title, and a description or arbitrary content. It also provides an auxiliary section to display further detail in table or list format (to the right).

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'info'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'info'
// does this for you!
templates: {
    item: 'basic_image_item',
    detail: 'basic_info_detail',
    options: {
        moreAt: true,
        aux: false
    }
}

Default Templates Used

See the important notes for making this template display correctly.

Example Uses


Products Template Group

Best used to showcase products with an image, rating, review, brand and/or price. An optional buy sub-template can be used to provide a compelling call-to-action (i.e. button).

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'products'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'products'
// does this for you!
templates: {
    item: 'products_item',
    detail: 'products_detail',
    item_detail: 'products_item_detail',
    wrap_detail: 'base_detail',
    options: {
        rating: true,
        price: true,
        brand: true
    }
}

Using the Products template group also automatically makes the Product model available.

Default Templates Used

See the important notes for making this template display correctly.

Example Uses


Media Template Group

The media template group works well when an image is a significant part of the display of an item. Items can also have a title and a rating.

The item template is essentially a simplified version of the Products template group. It also uses the same detail template as the Products template group.

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'media'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'media'
// does this for you!
templates: {
    item: 'media_item',
    detail: 'basic_info_detail',
    item_detail: 'media_item_detail',
    options: {
        moreAt: true,
        aux: false
    }
}

Default Templates Used

See the important notes for making this template display correctly.

Example Uses


Icon Template Group

This template is similar to the text group, since it uses the same item template. However, the detail view is better suited to displaying an icon image.

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'icon'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'icon'
// does this for you!
templates: {
    item: 'text_item',
    detail: 'basic_icon_detail',
    item_detail: 'products_item_detail'
}

Default Templates Used

See the important notes for making this template display correctly.

Example Uses


Images Template Group

A template group for displaying image results. This group is ideal when the Instant Answer result is an image, and the image's attributes are important (such as its dimensions, source, and original file).

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'images'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'images'
// does this for you!
templates: {
    item: 'images_item',
    detail: 'images_detail'
}

Using the Images template group also automatically makes the Image model available.

Default Templates Used

Example Uses


Movies Template Group

An ideal template group for displaying movie results, but also great for other types of media such as books.

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'movies'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'movies'
// does this for you!
templates: {
    item: 'basic_image_item',
    detail: 'products_detail',
    item_detail: 'products_item_detail',
    wrap_detail: 'base_detail',
    options: {
        price: false,
        brand: false,
        rating: false,
        ratingText: true
    },
    variants: {
        tile: 'poster'
    },
    elClass: {
        tileBody: 'is-hidden'
    }
}

Default Templates Used

Example Uses


Videos Template Group

A template group for displaying online video results. This group is ideal when the Instant Answer result is a video, and can be viewed on the search results page.

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'videos'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'videos'
// does this for you!
templates: {
    item: 'videos_item',
    detail: 'videos_detail'
}

Setting the Videos template group also automatically makes the Video model available.

Default Templates Used

Example Uses


Places Template Group

This template group is ideal for displaying results where location is an important factor to the searcher. The Places template group makes it easy for searchers to view a map showing all results, or highlighting a particular item without leaving the search page.

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'places'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'places'
// does this for you!
templates: {
    item: 'places_item',
    detail: 'places_detail'
}

Using the Places template group also automatically makes the Place model available.

Default Templates Used

Alternative Templates

Specify these item templates to replace the default places_item template, while maintaining the unique 'flip' behavior of places_item.

Places Model and View

The Places template group works together with the Places model and Places view. The Places model and view enable special map functionality and behaviors that make Instant Answers using Places valuable and delightful.

The model and view are specified alongside the template group property in your Instant Answer display options.

To work correctly, the places model requires additional values passed that do not appear directly in the templates. Make sure that each item includes the attributes required by the places model. Generally these are set by your normalize function if they do not already exist in your api_result.

The available attributes for the Places Model are:

  • id string Unique identifier for the location
  • name string Name of the location
  • address string Display address of the location
  • city string
  • neighborhood string If neighborhood and city are both passed in, it will use neighborhood for the tile and fall back to the city when it's not there
  • image string Path to image thumbnail to be used for the location, will use default marker image if none is provided
  • polygonPoints array If the location represents a region, array of lat/lon coordinates that create the shaded outline in queries like 'Paris map'
  • lat number Latitude of the location
  • lon number Longitude of the location
  • rating number Number from [0-5], supports half's, i.e. 3.5
  • ratingImageURL string Optional, use custom rating image URL (i.e. Yelp)
  • reviews number Number of reviews
  • price number Integer from [0-4], will be converted to up to four $ symbols, for example $$$$
  • hours object Hash where three-char days are the keys and the values are a string of hours for that day, i.e.: { 'Mon': '8am - 5pm', 'Thu': '1pm - 5pm' }
  • phone string

Below are examples of the objects passed to the data property in your Instant Answer display options (in this case, Spice.add()). These might be directly found in your api_result or created by defining a normalize function.

Spice.add({
    id: 'landmarks',
    name: 'Landmarks',
    model: 'Place',
    view: 'Map',
    templates: {
        group: 'places'
    },
    meta: {
        sourceName: 'Wikipedia',
        sourceUrl: 'https://wikipedia.org'
    },
    data: [
        {
            id: 'uniqueid-1',
            name: 'Empire State Building',
            url: 'https://en.wikipedia.org/wiki/Empire_State_Building',
            image: 'https://upload.wikimedia.org/...480px-Empire_State_Building_by_David_Shankbone.jpg',
            rating: '3.5',
            address: '350 Fifth Ave',
            neighborhood: 'Midtown',
            city: 'New York City',
            price: 3,
            lat: 40.7484324,
            lon: -73.98566413,
            hours: {
                Thu: '8am - 5pm'
            }
        }
    ]
});

Example of rendering multiple locations as tiles with an expandable map:

Spice.add({
    id: 'landmarks',
    name: 'Landmarks',
    model: 'Place',
    view: 'Places',
    templates: {
        group: 'places'
    },
    meta: {
        type: 'Landmarks',
        sourceName: 'Wikipedia',
        sourceUrl: 'https://wikipedia.org'
    },
    data: [
            {
                id: 'uniqueid-1',
                name: 'Empire State Building',
                url: 'https://en.wikipedia.org/wiki/Empire_State_Building',
                image: 'https://upload.wikimedia.org/...480px-Empire_State_Building_by_David_Shankbone.jpg',
                rating: '3.5',
                address: '350 Fifth Ave',
                neighborhood: 'Midtown',
                city: 'New York City',
                price: 3,
                lat: 40.7484324,
                lon: -73.98566413,
                hours: {
                    Thu: '8am - 5pm'
                }
            },
            {
                id: 'uniqueid-2',
                name: 'Central Park',
                url: 'https://en.wikipedia.org/wiki/Central_Park',
                image: 'https://upload.wikimedia.org/...240px-Southwest_corner_of_Central_Park%2C_looking_east%2C_NYC.jpg',
                rating: 5,
                address: '86th Street, Traverse Road',
                neighborhood: 'Midtown',
                city: 'New York City',
                lat: "40.78257765",
                lon: "-73.9654435614027",
                phone: '867-5309',
                reviews: 327,
                polygonPoints: [
                    ["-73.9812971", "40.7685782"],
                    ["-73.9812422", "40.7686381"],
                    ["-73.9808211", "40.7692536"],
                    ...
                    ["-73.9810729", "40.7683834"],
                    ["-73.9811234", "40.7684477"],
                    ["-73.9811992", "40.7685112"],
                    ["-73.9812971", "40.7685782"]
                ]
            }
        ]
});

Example use of the 'places' template group


List Template Group

The List template group was designed for displaying in-depth attributes of one item. These attributes can be displayed as either a bulleted list of properties, or a table of key-value pairs.

Multiple items are displayed using the same text_item template used by Text and Icon template groups. As a result, this template group is mainly useful for Instant Answers designed to return a single item with detailed properties.

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'list'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'list'
// does this for you!
templates: {
    item: 'text_item',
    detail: 'list_detail'
}

Default Templates Used

See the important notes for making this template display correctly.

Example use of the list template group


Base Template Group

This is the most rudimentary template group. It provides a minimal container template that accepts totally custom markup.

Using this template group requires a large amount of work up front, and difficult maintenance over time. As a result, this template should be a last resort.

It's important to note that the community cannot accept submissions using the Base template unless they've received prior permission (by discussing with community leaders or staff on Slack or email). If you feel that other template groups do not meet your needs, definitely talk to us. We'll work with you to find the best way to express your idea and avoid ongoing, manual maintenance for your Instant Answer.

Usage

Using this template requires that that you set the group property of the templates block like so:

templates: {
    group: 'base'
}

When you specify this template group, it is equivalent to setting the properties of the templates block as follows:

// setting the template group to: 'base'
// does this for you!
templates: {
    item: 'base_item',
    detail: 'base_detail',
    options: {
        price: false,
        brand: false,
        rating: false,
        ratingText: false,
        rowHighlight: false,
        keySpacing: false,
        moreAt: false
    }
}

Default Templates Used

See the important notes for making this template display correctly.

Example Uses

results matching ""

    No results matching ""