HTML

GOX allows you to return HTML using templates. The developer writes the marking directly into a GOX function and the compiler builds its internal representation.

The Pages they write the result as an HTML response. Actions and the WebSocket events they deliver it to JavaScript as nodes of the DOM.

There is no need to manually build, convert or receive an HTML type in Go.

Equivalence

The result received in JavaScript depends on the roots produced:

• A single elemental root produces HTMLElement.
• Several roots produce DocumentFragment.
• A mix of text and elements produces DocumentFragment.
• An empty result produces DocumentFragment.

Templates

A GOX function can return HTML directly using the template syntax:

func Card(name string) gox.Action {
    return <article class="card">
        <h2>{{name}}</h2>
    </article>
}

const [card, err] = await Actions.Card("George")

document.body.append(card)

JavaScript receives a HTMLElement because the temperate contains a single elemental root.

See Templates to know expressions, conditions, loops and content composition.

HTML in Pages

A Page uses a Template as a natural content of the response:

func GET() gox.Page {
    return <main>
        <h1>Hola, George</h1>
    </main>
}

GOX writes the result in the HTTP response body. The browser interprets it as an HTML document and not as the value returned by a JavaScript call.

A Page can combine reusable templates and components. Components to know how to declare and use that composition.

HTML in Actions

An Action can return a temperate to the client:

func Card() gox.Action {
    return <article>
        <h2>George</h2>
    </article>
}

const [card, err] = await Actions.Card()

console.log(card instanceof HTMLElement) // true
document.body.append(card)

The paragraph syntax is part of the GOX code. It should not be replaced by a manual conversion from a string.

HTML over WebSocket

WebSocket can send the client the result of a template:

socket.On("profile", func(name string) {
    profile := <article class="profile">
        <h2>{{name}}</h2>
    </article>

    socket.Emit("profile", profile)
})

socket.on("profile", profile => {
    document.body.append(profile)
})

The client receives HTMLElement or DocumentFragment according to the roots of the temperate.

This capacity describes the Go direction to JavaScript. communication/ does not present the elements of the DOM as arguments sent from JavaScript to Go.

Single and multiple roots

A single elemental root produces HTMLElement:

func Card() gox.Action {
    return <article>George</article>
}

Several roots produce DocumentFragment:

func Sections() gox.Action {
    return <>
        <h2>George</h2>
        <p>Administrator</p>
    </>
}

const [sections, err] = await Actions.Sections()

console.log(sections instanceof DocumentFragment) // true
container.replaceChildren(sections)

When a DocumentFragmentyour children pass to the document and the fragment is empty, following the normal behavior of the DOM.

Dynamic content

The expressions allow to insert values within the temperate:

func Profile(name string, active bool) gox.Action {
    return <article>
        <h2>{{name}}</h2>
        <:if condition={{active}}>
            <span>Active</span>
        </:if>
    </article>
}

Dynamic values use the temperate exhaust rules. Raw marking should only be used when its origin is reliable.

HTML controls

Form controls used as arguments are not transferred as HTML. GOX extracts its value according to the type of control:

• Text and textwork are sent as string.
• Number and range are sent as number.
• Checkbox and radio are sent as boolean.
• Date is sent as Date.
• File is sent as File or File[].

See Values to know the conversion of controls and Files for the file fields.

Errors

The delivery of HTML may fail when:

• The template makes a mistake during its rendering.
• The client cannot rebuild the result in an environment with DOM.
• The transport ends before the delivery is completed.

In Actions, the error is part of the result of the call. In WebSocket, it is communicated by the event error.

Best practices

• Build HTML using GOX Templates.
• It uses components to reuse presentation structures.
• It preserves raw content for reliable sources.
• Check if the result is HTMLElement or DocumentFragment when the amount of roots may vary.
• Insert the nodes using DOM APIs.
• Do not send a complete element when you only need the value of a control.
• Drive the errors before inserting the result.

See also

• Pages
• Return values of Actions
• WebSocket events
• Templates
• Components
• Values
• Files