Templates

Table of Contents

Overview

MapSVG uses Handlebars templates.

Let's say you have the following DB Object in MapSVG:

{
  id: 1,
  title: "My city",
  description: "Lorem ipsum"
  location: {
      lat: 55.1234,
      lng: 66.1234,
      address: {formatted: "1 Main st., New York, USA"}
    }
}    

This is how you could use it in a DB Object Details view template:

<h2>{{title}}</h2>
<p>{{description}}</p>
<p><i>Address: {{location.address.formatted}}</i></p>

Which results in the following HTML code:

<h2>My city</h2>
<p>Lorem ipsum</p>
<p><i>Address: 1 Main st., New York, USA</i></p>

And this is how it looks when you open a Details View:


My city

Lorem ipsum

Address: 1 Main st., New York, USA


Syntax

#if/else

Handlebars support if/else conditions:

{{#if title}}
  {{title}}
{{else}}
  The title is empty!
{{/if}}    

Negative conditions:

{{#unless title}}
  The title is empty!
{{/unless}}    

Check if variable is equal or not equal to some value:

{{#ifeq title "Hello"}}
  The title is "Hello!
{{/ifeq}}
{{#ifnoteq title "Hello"}}
  The title is NOT "Hello!
{{/ifnoteq}}    

#each

Example: a Region have multiple attached DB Objects. You can show fields of attached objects individually by object index number:

{{objects.0.my_field}} <!-- "my_field" value of the  1st object --> 
{{objects.1.my_field}} <!-- "my_field" value of the  2nd object --> 
{{objects.1.title}}    <!-- "title" value of the  2nd object --> 

But also you can iterate over the list of DB Objects, attached to a Region:

{{#each objects}}
  Object's my_field: {{my_field}}
  Object's title: {{title}}
  Object's address: {{location.address.formatted}}
{{/each}}    

Iteration over a list of Regions, attached to a DB Object:

{{#each regions}}
  Region title: {{title}}
  Region status: {{status}}
{{/each}}    

#with

The with-helper allows you to change the evaluation context of template-part.

{{#with person}}
  {{firstname}} {{lastname}}
{{/with}}

when used with this context:

  person: {
    firstname: "Yehuda",
    lastname: "Katz",
  },
}

will result in:

Yehuda Katz

You can optionally provide an {{else}} section which will display only when the passed value is empty.

{{#with city}}
  {{city.name}} (not shown because there is no city)
{{else}}
  No city found
{{/with}}

#switch/case

Show content depending on the value of a field.

{{#switch status}}
  {{#case "1" break=true}} Status is "Available" {{/case}}
  {{#case "2" break=true}} Status is "Sold" {{/case}}
  {{#default}} Unknown status {{/default}}
{{/switch}}

Using different field types

Text, textarea

Example:

{{title}}, {{description}}

HTML

When you have a textarea field with HTML highlight mode, you have to use 3 curly braces {{{...}}} instead of 2 {{..}} around the field name in the template to render it as HTML. If you use 2 curly braces, the field will be rendered as a plain text.

{{{my_textarea_with_html}}}

Select, Radio, Status

These fields have 2 values for each option: number and text. Suppose that you have the following list of options in your select / radio / status fields:

Avaialble: 1
Sold: 2
Disabled: 3

Show number value of a select / radio / status field:

  {{my_field}}

Show text label of a select / radio / status field:

  {{my_field_text}}

Multiselect

Muliselect field contains an array of chosen options as label/value pairs.

Example:

{
    my_multiselect_field: [
      {label: "Option one", value: 1},
      {label: "Option two", value: 2}
    ]
}

Showing all chosen values of a multiselect field, comma-separated:

{{#each my_multiselect_field}}
 {{label}} - {{value}}{{#unless @last}}, {{/unless}}
{{/each}}    

Images

Images field always contain an array of images and each image comes in 3 different sizes: thumbnail, medium, full.

Example:

[
  {
    thumbnail: "/path/to/thumbnail/image.jpg", 
    medium: "/path/to/medium/image.jpg", 
    full: "/path/to/full/image.jpg"
  },
  {
    thumbnail: "/path/to/thumbnail/image2.jpg", 
    medium: "/path/to/medium/image2.jpg", 
    full: "/path/to/full/image2.jpg"
  }
]

This field contains only URLs of images, so if you want to show an image in a template, you should use <img src="..." /> HTML tag.

Show all images:

{{#each images}}
    <img src="{{thumbnail}}" />
    <img src="{{medium}}" />
    <img src="{{full}}" />
{{/each}}    

Show a single image by index number (0 is the first image, 1 is the second, etc.):

<img src="{{images.0.full}}" />

Post

Show rendered post content in an iframe:

{{post}}

Show post ID, URL, title, content:

{{post.id}}
{{post.url}}}
{{post.post_title}}
{{post.post_content}}

Show a link to post:

<a href="{{post.url}}">{{post.post_title}}</a>

If you use ACF plugin (Advanced Custom Fields), you can show your custom fields via .acf property:

{{post.acf.my_field_name}}
{{post.acf.my_another_field}}

How to show "repeater" ACF fields? Repeater field is an array, so you have to use the #each loop:

{{#each post.acf.my_repeater_field}}
  Sub-field 1: {{sub_field_1}}
  Sub-field 2: {{sub_field_2}}
{{/each}}

Location

Example of the Location field structure:

{
  location: {
    address: {
      formatted: "1 Main st., Houston, TX 10022, USA",
      locality: "Houston",
      state_short: "TX",
      state: "Texas",
      country_short: "US",
      country: "United States",
      zip: "10022"      
    }
    lat: 55.1234,
    lng: 66.1234
  }
}

Template:

{{location.address.formatted}}
{{location.address.city}}
{{location.address.zip}}

Showing distance to object

If you use the "Distance" filter, you can show distance to object from the address entered by user. Usually the following tag is used in the Directory item template but also you can use it in Popover or Details view.

{{distanceTo location}}

Or (it gives the same result):

{{distanceFrom location}}

"distanceTo" is a special template helper and "location" is the database field that stores lat/lon coordinates of an object. The distance is shown in miles or kilometers - depending on what is chosen for Menu > Filters > Edit fields > Distance filter > Units.

Using WordPress shortcodes

Show rendered shortcode content in an iframe:

{{shortcode '[my_shortcode id="1"]'}}

If your shortcode returns plain text that you want to insert as inline block (without iframe):

{{shortcode_inline '[my_shortcode id="1"]'}}

Show a shortcode stored in a custom text field:

{{shortcode shortcode_field_name}}

Pass MapSVG object parameters to a shortcode. Example: you can have a "Region Details view" with a contact form created with "Contact form 7" plugin, that has auto-filled "Region title" field. How to pass clicked Region {{title}} field to a contact form:

{{shortcode '[contact-form-7 id="1" region-title="{{title}}"]'}}

If you use Contact Form 7 plugin, you have to go to the form settings and define that the default value can be passed from a shortcode:

[text* region-title default:shortcode_attr]