Component templates

Although components can be used directly within any liquid files in static/, often your component has a set structure that you would have to create and maintain at multiple locations in your theme. SALVO-TS supports defining a standard template for a component alongside its class, which you can then use elsewhere in this theme using a convenient preprocessor tag.

This has two benefits:

• When the component's HTML/liquid changes, you now only have a single place to update it.
• SALVO-TS will automatically validate that required props are passed into the template in Liquid.

tip

Compiler macros are available in component templates.

Creating component templates

Component templates are stored in a matching .liquid file, next to the component they apply to. The .ts and .liquid files for a component must use the same filename, except for the extensions.

MyComponent.ts

src/components/FooComponent.ts
ts
import { Component, Prop, Ref } from '@eastsideco/salvo-ts';
import { ThemeComponent } from '@/theme/ThemeComponent';
 
@Component
export class MyComponent extends ThemeComponent {
    @Prop name!: string;
}

src/components/FooComponent.ts
ts
import { Component, Prop, Ref } from '@eastsideco/salvo-ts';
import { ThemeComponent } from '@/theme/ThemeComponent';
 
@Component
export class MyComponent extends ThemeComponent {
    @Prop name!: string;
}

MyComponent.liquid

src/components/MyComponent.liquid
html
<my-component 
    name="{{ name|json|escape }}"
>
    Hello, <span>{{ name }}</span>
</my-component>

src/components/MyComponent.liquid
html
<my-component 
    name="{{ name|json|escape }}"
>
    Hello, <span>{{ name }}</span>
</my-component>

You can render a component in any liquid file using the {! component !} compiler macro.

static/layout/theme.liquid
js
{! component 'ComponentName', prop1: value, prop2: value, prop3: value !}

static/layout/theme.liquid
js
{! component 'ComponentName', prop1: value, prop2: value, prop3: value !}

Source liquid

static/snippets/example.liquid
html
<div>
    {! component 'MyComponent', name: "foobar" !}
</div>

static/snippets/example.liquid
html
<div>
    {! component 'MyComponent', name: "foobar" !}
</div>

Compiled liquid

dist/snippets/example.liquid
html
<div>
    {% render 'component_MyComponent', name: "foobar" %}
</div>

dist/snippets/example.liquid
html
<div>
    {% render 'component_MyComponent', name: "foobar" %}
</div>

HTML output

HTML
html
<div>
    <my-component 
        name="&quot;foobar&quot;"
    >
        Hello, <span>foobar</span>
    </my-component>
</div>

HTML
html
<div>
    <my-component 
        name="&quot;foobar&quot;"
    >
        Hello, <span>foobar</span>
    </my-component>
</div>

tip

Other compiler macros are also available.

Prop validation

If you don't include a required prop when rendering a component template, an error will be rendered on the page instead.

Source liquid

static/snippets/example.liquid
html
<div>
    <!-- Missing attribute for required 'name' prop: -->
    {! component 'MyComponent' !}
</div>

static/snippets/example.liquid
html
<div>
    <!-- Missing attribute for required 'name' prop: -->
    {! component 'MyComponent' !}
</div>

Compiled liquid

static/snippets/example.liquid
html
<div>
    <!-- Missing attribute for required 'name' prop: -->
    {% render 'component_MyComponent' %}
</div>

static/snippets/example.liquid
html
<div>
    <!-- Missing attribute for required 'name' prop: -->
    {% render 'component_MyComponent' %}
</div>

Output HTML

HTML
html
<div>
    <!-- Missing attribute for required 'name' prop: -->
    <div class="_SALVO_COMPONENT_ERROR">
        Required component prop 'name' not passed to MyComponent component template.
    </div>
</div>

HTML
html
<div>
    <!-- Missing attribute for required 'name' prop: -->
    <div class="_SALVO_COMPONENT_ERROR">
        Required component prop 'name' not passed to MyComponent component template.
    </div>
</div>

Optional props

Props are required by default, but you can make a prop optional by passing a default value to the prop definition (i.e. @Prop({ default: 'not found' }) foo: string;).