Skip to main content

How can we help?

Search

Shared Object Types

Updated: Andrew Tat Edited:

Overview

Some object types appear consistently across multiple parts of the Localist data model. Rather than re-documenting them inside every parent object, they are collected here. This article covers:

  • Tag and TagList — Classification labels used by Events, Places, Groups, Departments, and Users

  • Photo — Image objects used by Events, Places, Groups, Departments, and Users

  • Custom Field and Custom Fields Collection — Configurable extra fields available on Events, Places, and Groups/Departments

Each of these objects is accessed in the same way regardless of the parent. The surrounding context (event, place, group, etc.) determines which list or value is returned.

Tags and Tag Lists

Tags, filters, and keywords share a single classification system underneath. The same Tag and TagList structures are used by Events, Places, Groups, Departments, and Users. The surrounding context determines which list of tags is returned.

The Tag Object

A Tag represents a single classification label.

Variable Type Description
name String Tag name
id Integer Tag unique identifier
event_search_url String Link to search events by this tag
place_search_url String Link to search places by this tag
group_search_url String Link to search groups by this tag
department_search_url String Link to search departments by this tag
week_calendar_url String Link to a week calendar filtered by this tag

The TagList Object

A TagList is a dynamic collection of Tags grouped by context (filter category). Access tags either by listing all contexts or by indexing into a specific context name.

Variable Type Description
context_names Array of String All available context names for this TagList
[context_name] Array of Tag Tags belonging to a specific context

Liquid example — iterating all contexts on an event:

{% for context in event.types.context_names %}
  <h4>{{ context }}</h4>
  {% for tag in event.types[context] %}
    <span class="tag">{{ tag.name }}</span>
  {% endfor %}
{% endfor %}

Liquid example — same pattern on a place:

{% for tag in place.types %}
  <span class="tag">{{ tag.name }}</span>
{% endfor %}

The Photo Object

Photos appear on Events, Places, Groups, Departments, and Users. The Photo object provides URLs for many pre-defined sizes; each size has a base variant and a 2x variant for hidpi displays.

Recommendation: Prefer the {% photo_for %} tag (Article 6) over reading these URLs directly. It handles 2x logic automatically and produces correctly-sized <img> markup.

Size Pattern

For any size name, three accessors are available on the Photo object:

  • photo.name — URL for the base size

  • photo.name_2x — URL for the 2x (hidpi) variant

  • photo.name_supports_2x — Boolean; true when the uploaded image is large enough for the 2x variant to be genuinely hidpi

Example:

Accessor Returns
photo.featured 940×557 variant
photo.featured_2x 1880×1114 variant (same crop area)
photo.featured_supports_2x true when the original is ≥ 1880×1114

In Liquid:

<img src="{{ event.photo.featured }}"
     srcset="{{ event.photo.featured_2x }} 2x"
     alt="{{ event.photo.caption }}" />

Sizes ending with # are center-cropped to the nearest defined crop area; > sizes preserve aspect ratio.

Current Sizes

Name Dimensions Cropping
cover 1440 wide Preserves aspect ratio
huge 750×750 max Preserves aspect ratio, longest edge scaled to 750
hero 690×480 Center-cropped
spotlight 700×300 Center-cropped
featured 940×557 Center-cropped
card 478×310 Center-cropped
icon_large 110×110 Center-cropped
icon_tiny 36×36 Center-cropped

All current dimensions are visible on the View All Sizes page in the Photo Library.

Legacy Sizes

These sizes remain available for existing templates. Prefer the current sizes above for new work.

Name Dimensions
big_300 300×225
square_300 300×300
big_square 200×200
big 200×150
medium 80×80
small 50×50
tiny 20×20

Metadata

Variable Type Description
caption String Photo caption
type String Photo type/classification
dom_id String HTML DOM ID
created_at DateTime When the photo was uploaded

Associations

Variable Type Description
user User The user who uploaded the photo
group Group/Department Associated group, when applicable
event_instance Event Associated event, when applicable

Custom Fields

Custom Fields are configurable extra fields that platform admins can define for Events, Places, and Groups/Departments. There are two related concepts:

  • Custom Field (the definition) — A configured field with a label, type, options, and visibility rules. Definitions are exposed via site.public_event_custom_fields and site.public_user_custom_fields.

  • Custom Fields Collection (the values) — A dynamic key/value map of the values on a parent object, accessed via parent.custom_fields.<key>.

Each definition has an Internal ID (its key) configured in admin. That key is how templates read and write the field’s value on parent objects.

The Custom Field Object

Variable Type Description
name String Internal name of the field
id Integer Unique identifier for the field definition
key String Machine-readable Internal ID used to access the field value (e.g., custom_fields.my_field_key)
label String Human-readable label displayed to users
field_type String Type of field (text, textarea, dropdown, checkbox, etc.)
required Boolean Whether the field must be filled in
public_form Boolean Whether the field appears on public event submission forms
visible_to_public Boolean Whether the field value is visible to non-owners
position Integer Display order of the field in the form
html Boolean Whether HTML content is allowed in the field value

The Custom Fields Collection

The Custom Fields collection is a dynamic accessor on Events, Places, and Groups/Departments. Read individual field values by their key:

{% if event.custom_fields.department %}
  <p>Department: {{ event.custom_fields.department }}</p>
{% endif %}

{% if place.custom_fields.capacity %}
  <p>Capacity: {{ place.custom_fields.capacity }}</p>
{% endif %}

For rendering custom fields on forms (event submission, etc.), see Article 9 (Forms and User Management).

Related Articles

This article is part of a 9-part series on Localist developer theming:

  1. Introduction to Localist Developer Theming

  2. Site Configuration and Global Objects

  3. Events, Instances, and Related Objects

  4. Places, Groups, Departments, and Channels

  5. Shared Object Types

  6. Custom Liquid Tags Reference

  7. Custom Liquid Filters Reference

  8. Template Variable Reference

  9. Forms and User Management

Related articles