Facet Developer Docs

Facet is the template layer used by FaceFlow for dynamic rendering.

It gives technical users a controlled way to output values, compose reusable template fragments, work with loops and conditions, and build dynamic display logic inside PageFace.

What Facet Is Used For

• component templates
• variable templates
• dynamic list output
• shared content rendering
• contextual page output

Facet is not the whole FaceFlow system. It is the rendering language inside it. FaceFlow defines the objects and contracts. Facet defines how those objects render dynamic output safely.

Core Capabilities

Technical users typically rely on Facet for:

• escaped and raw output
• conditionals and loop blocks
• page-aware and query-aware rendering
• filter chains and formatting
• variable embedding
• safe template composition inside reusable objects

Facet vs FaceFlow

Keep this boundary clear:

• FaceFlow defines objects such as Pages, Components, Variables, Lists, Forms, and Reviews
• Facet defines how those objects render dynamic output

If a technical user is deciding what object to create, they are in FaceFlow design territory.

If they are deciding how an existing object should render fields, conditions, and loops, they are in Facet territory.

Where It Appears

Facet commonly appears in:

• Component HTML templates
• Variable templates
• List item templates
• smaller dynamic fragments that need runtime context

A simple example:

<section class="hero">
  <h1>{{ title }}</h1>

  {{#if summary}}
    <p>{{ summary }}</p>
  {{/if}}

  [[sales-contact-badge]]
</section>

This example shows the most common mental model:

• FaceFlow object provides the contract
• Facet provides the rendering logic

What Facet Should Not Do

Facet is powerful, but it should not become a replacement for good object modeling.

Do not use Facet to:

• hide weak content structure behind template tricks
• turn one template into a business workflow engine
• replace Lists with hand-written archive logic when the problem is really query-driven content
• simulate a large editable schema that should be a Component

How To Learn Facet

Use this reading path:

1. start with Template Syntax
2. continue to Reference
3. then return to the FaceFlow object that owns the template you are editing

That order works because syntax comes first, deeper patterns second, and object-specific application last.

Common Use Cases

Technical users typically reach for Facet when they need to:

• show optional fields cleanly
• loop through repeated content
• format page-aware values
• embed reusable Variables
• build archive and list templates without raw platform code

Common Mistakes

Technical users most often run into trouble when they:

• push too much logic into one template
• treat a repeated fragment like copied markup instead of a Variable
• use conditionals to compensate for an unclear field model
• build a dynamic archive in a Component when it should be a List
• forget that readability is part of template quality

Design Guidance

• keep templates readable
• keep business logic shallow
• prefer strong object modeling over clever template tricks
• use Variables for repeated fragments instead of copying markup
• use Lists when the problem is dynamic content selection, not just display

Decision Shortcut

Use Facet when the question sounds like:

• "how should this field render?"
• "should this section show only when data exists?"
• "how do I loop through these items?"
• "how do I reuse this small fragment?"

Do not stop at Facet when the question is really:

• "should this be a Component or a Variable?"
• "should this content be a List?"
• "does this belong in the Layout or on the Page?"

Related

• FaceFlow Components
• FaceFlow Variables
• FaceFlow Lists
• Template Syntax
• Reference