Skip to main content

Templates

With templates you can create custom views that show your DB Objects, or Regions.

Temlates are HTML code with Handlebars tags.

Overview​

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]