Build with SSR.
Continue in the browser.

The SSR to CSR model

A SiteMesh page has one authored HTML template and two stages of execution. The server resolves route data, conditions, loops, and text before returning HTML. The browser then activates the rendered controls and continues with the same initial object and list state.

Use server rendering for the first truthful view. Use browser behavior for user input and subsequent changes. A seeded model does not repeat its initial request when the browser starts.

Routes and page structure

Each configured WWW domain selects a WebRoot, so different domains can serve completely separate site folders or intentionally share the same one. Within that domain's root, HTML files become routes from their relative paths. Files beginning with an underscore are layouts or partials and do not become routes.

Page directives

Put directives at the top of the file, one per line. A layout places the route content where its expression appears.

@layout('_layout.html')
@title('Account')
@description('View and edit an account')

<sitemesh-view>
    <sitemesh-pane>
        <sitemesh-header>...</sitemesh-header>
        <sitemesh-body>...</sitemesh-body>
    </sitemesh-pane>
</sitemesh-view>

Root pages and fragments

An application root route uses exactly one <sitemesh-view> with one to three direct panes. A route loaded into an existing view with View.Navigate() is a fragment: return direct header, body, and optional footer elements without another view or pane wrapper.

Template rendering

Text and attributes

Double braces render encoded text. Use direct interpolation for an attribute containing text, or :attribute when the complete attribute value comes from a path.

<h1>{{ Account.AccountName }}</h1>
<a href="/account/{{ Account.AccountID }}">Open account</a>
<a :href="Account.AccountWebsite">Website</a>
<sitemesh-button :disabled="Account.AccountLocked">Save</sitemesh-button>

Conditions

Put if, else-if, and else on adjacent real elements. Paths are null-safe. Conditions support truthiness, negation, comparisons, length checks, and string containment.

<sitemesh-pill if="Account.AccountStatus == 'ACTIVE'">ACTIVE</sitemesh-pill>
<sitemesh-pill else-if="Account.AccountStatus == 'PAUSED'">PAUSED</sitemesh-pill>
<sitemesh-pill else muted>INACTIVE</sitemesh-pill>

<p if="Account.AccountPersonList.length == 0">No people assigned.</p>

Loops

Repeat a real element with for-each. The forms item in items and (item, index) in items are supported. Add if to the same element to filter rows during rendering.

<sitemesh-list-row for-each="(person, index) in PersonList"
                    :data-key="person.PersonID"
                    if="person.PersonActivity">
    <span>{{ index }}. {{ person.PersonName }}</span>
</sitemesh-list-row>

Filters

Append filters with | and chain them from left to right.

Objects: one record of state

Create an object in a top-level declaration when browser controls or conditions need to observe a record. The compiler uses the declaration variable as its binding name. Start with null when an OBJECT endpoint will supply the record, or use an object literal for local structural state.

<script>
    const Draft = SiteMesh.Object({
        Title: '',
        Notes: '',
        Published: false,
    });
</script>

Seed an object for SSR and CSR

Seed() loads during server rendering. The endpoint result is available to template expressions and becomes the browser object's initial state without another initial request.

<script>
    const Account = SiteMesh.Object(null)
        .Seed('/account/get', { AccountID: '{{ accountid }}' });
</script>

<h1>{{ Account.AccountName }}</h1>
<sitemesh-input name="Account.AccountName" label="Name:"></sitemesh-input>

Use SiteMesh.Object(null) for a null initial value. An OBJECT endpoint such as /account/get supplies its owning schema's IntelliSense and column metadata automatically. This does not create a blank record or filter its packet; the response is retained in full.

Render-only objects

Chain .Discard() when data is needed only for the current server render. The data remains available to interpolation, conditions, and loops while rendering, then its declaration and data are omitted from the browser response.

<script>
    const Summary = SiteMesh.Object(null)
        .Seed('/report/summary', { Range: 'MONTH' })
        .Discard();
</script>

<p>{{ Summary.Total | currency:'$' }}</p>

Do not reference a discarded model from browser functions. It exists only for the current server render.

Lists: SSR rows with browser ownership

A list is declared as SiteMesh.List([]) and connects to a for-each row when its declaration variable matches the loop source. A LIST endpoint supplies its owning item schema automatically.

<sitemesh-list>
    <sitemesh-list-row for-each="account in AccountList"
                        :data-key="account.AccountID">
        <sitemesh-text>{{ account.AccountName }}</sitemesh-text>
    </sitemesh-list-row>
    <sitemesh-list-empty>NO ACCOUNTS</sitemesh-list-empty>
</sitemesh-list>

<script>
    const AccountList = SiteMesh.List([])
        .Seed('/account/list', { Limit: 50, Offset: 0 });
</script>

Seeded rows render on the server. The browser receives the same list and can later refresh, paginate, add, remove, or replace rows. A route-inferred schema supplies column metadata to controls bound through the loop alias, but does not filter returned rows. Keep custom projections on generic JSON endpoints and give them an explicit stable :data-key.

Search parameters and Watch

Use an earlier named object for reactive query parameters. .Watch() subscribes the list to that object and runs a debounced search when bound values change.

<sitemesh-input name="AccountParams.AccountName" label="Search:"></sitemesh-input>

<script>
    const AccountParams = SiteMesh.Object({
        AccountName: null,
        Limit: 50,
        Offset: 0,
    });

    const AccountList = SiteMesh.List([])
        .Seed('/account/list', AccountParams)
        .Watch();
</script>

Structural reactivity

Lists react to structural changes: push, pop, shift, unshift, splice, removal, replacement, refresh, and paging. Changing a property on an existing list item does not redraw its row. Replace the item or refresh the list when rendered row text must change.

The list element owns its loading and empty presentation. It shows loading rows only when loading starts without real rows, preserves current rows during refresh, and shows <sitemesh-list-empty> after a successful empty result.

Browser loads and updates

Use Load() when the browser should fetch data after the page is active. Loading replaces the model contents and retains the route for later Refresh().

<script>
    const Account = SiteMesh.Object(null)
        .Load('/account/get', { AccountID: SelectedAccountID });

    const ActivityList = SiteMesh.List([])
        .Load('/activity/list', { Limit: 25, Offset: 0 });
</script>

A top-level list declaration may chain .Load(), with an optional .Watch() when its parameters are an earlier named object. Later imperative calls such as await ActivityList.Load(route, params) return a promise and replace the existing list contents.

Objects and lists expose Loading. Bound list and object controls reflect pending requests automatically, so application code normally does not need to manage a second loading flag.

Bind controls to browser state

Set name="Object.Property" to connect a supported control to a named object. Use a model attribute or an ancestor data-model when several controls share the same model.

<div data-model="Article">
    <sitemesh-input name="ArticleTitle" label="Title:"></sitemesh-input>
    <sitemesh-textarea name="ArticleBody" label="Body:"></sitemesh-textarea>
    <sitemesh-toggle name="ArticlePublished" label="Published"></sitemesh-toggle>
</div>

<sitemesh-text name="Article.ArticleTitle"></sitemesh-text>

Controls expose PascalCase methods including Get(), Set(value), Enable(), and Disable(). Selects also expose Label() and Options().

Views and navigation

A view owns an application's local navigation stack. The first pane is the authored base surface. The second is the first navigation target. A third pane allows later destinations to remain beside the first destination on wider screens.

<sitemesh-view>
    <sitemesh-pane width="320px">
        <sitemesh-list>
            <sitemesh-list-row for-each="account in AccountList"
                                onclick="OpenAccount('{{ account.AccountID }}')">
                {{ account.AccountName }}
            </sitemesh-list-row>
            <sitemesh-list-empty>NO ACCOUNTS</sitemesh-list-empty>
        </sitemesh-list>
    </sitemesh-pane>
    <sitemesh-pane min-width="380px">
        <sitemesh-pane-empty>Select an account</sitemesh-pane-empty>
    </sitemesh-pane>
    <sitemesh-pane min-width="380px"></sitemesh-pane>
</sitemesh-view>

<script>
    function OpenAccount(AccountID_Value) {
        View.Navigate('/account/' + AccountID_Value);
    }
</script>

Destination fragments

A route opened by View.Navigate() returns unwrapped fragment content. It inherits the owning view and receives isolated model names, element lookups, and action handlers.

<sitemesh-header>
    <sitemesh-text h1 truncate pad>{{ Account.AccountName }}</sitemesh-text>
</sitemesh-header>
<sitemesh-body pad>
    <sitemesh-input name="Account.AccountName" label="Name:"></sitemesh-input>
</sitemesh-body>
<sitemesh-footer>
    <sitemesh-button onclick="SaveAccount()">Save</sitemesh-button>
</sitemesh-footer>

<script>
    const Account = SiteMesh.Object(null)
        .Seed('/account/get', { AccountID: '{{ accountid }}' });
</script>

Pass data forward with View.Navigate(route, { State: value }). Supply a separate Callback option when the destination should send a result back. Do not reach into another pane's models or elements.

Requests and actions

Use SiteMesh.Request(route, params) for commands and responses that are not model loads. Pass only the route and optional parameters.

<sitemesh-button onclick="SaveArticle()">Save</sitemesh-button>

<script>
    async function SaveArticle() {
        await SiteMesh.Request('/article/save', Article);
        await Article.Refresh();
        Toast.Show({ Message: 'Article saved', Timeout: 1500 });
    }
</script>

Use Load() to replace a model from a read route. Use SiteMesh.Request() for saves, deletes, downloads, and other actions. Await either operation before showing success or refreshing dependent data.

Local element access

Inside a navigated fragment, prefer View.Element('ElementID') so the lookup stays within that fragment. Root pages may use ordinary DOM lookup for globally unique elements.

<sitemesh-toast id="SavedToast" timeout="1500"></sitemesh-toast>

<script>
    function ShowSaved() {
        View.Element('SavedToast').Show('Saved');
    }
</script>

Complete working pattern

This master list renders its first result on the server, watches browser search state, and opens records inside the owning view.

<sitemesh-view>
    <sitemesh-pane width="340px">
        <sitemesh-header>
            <sitemesh-input name="PersonParams.PersonName" placeholder="Search people"></sitemesh-input>
        </sitemesh-header>
        <sitemesh-list>
            <sitemesh-list-row for-each="person in PersonList"
                                :data-key="person.PersonID"
                                onclick="View.Navigate('/person/{{ person.PersonID }}')">
                <sitemesh-text>{{ person.PersonName }}</sitemesh-text>
            </sitemesh-list-row>
            <sitemesh-list-empty>NO PEOPLE</sitemesh-list-empty>
        </sitemesh-list>
    </sitemesh-pane>
    <sitemesh-pane>
        <sitemesh-pane-empty>Select a person</sitemesh-pane-empty>
    </sitemesh-pane>
</sitemesh-view>

<script>
    const PersonParams = SiteMesh.Object({
        PersonName: null,
        Limit: 50,
        Offset: 0,
    });
    const PersonList = SiteMesh.List([])
        .Seed('/person/list', PersonParams)
        .Watch();
</script>

Pattern order

1. Declare query state before the list that consumes it.
2. Bind search controls to that named object.
3. Seed a list whose declaration name matches the loop source and render a stable keyed row.
4. Use the owning view for local navigation.
5. Use SiteMesh.Request() for commands, then refresh or replace affected state.

Public API reference

SiteMesh.Object

<script>
    const Filters = SiteMesh.Object({ Search: '' })
        .Cookie('account-filters');

    Filters.Autocomplete('Search', {
        search: async (text) => await SiteMesh.Request('/account/suggest', { Search: text }),
        label: (item) => item.AccountName,
    });

    function OnSearchChanged(next, previous) {
        console.log(next, previous);
    }
    Filters.Subscribe('Search', OnSearchChanged);
    // Later: Filters.Unsubscribe('Search', OnSearchChanged);
</script>

SiteMesh.List

View

Controls and feedback

Common mistakes

Authoring checklist

• Render the first useful state on the server whenever the data is available there.
• Use .Discard() only when browser code does not need the model after the current render.
• Use named objects and lists when controls or later actions need state.
• Keep model names, list source names, and loop sources exact.
• Give custom list rows stable identity.
• Use SiteMesh controls for reactive values and commands.
• Await requests, then refresh or replace affected state.