zotonic-javascript

Zotonic JavaScript

First Pass

• Inspect nearby templates, JavaScript modules, workers, actions, and Erlang event/2 handlers before editing; preserve local patterns.
• Prefer Zotonic declarative behavior ({% wire %}, actions, Cotonic data attributes, workers, and do_... widgets) over one-off DOM scripts.
• Put reusable JavaScript under the module or site priv/lib/js tree and include it with {% lib %} from the relevant include template.
• Use plain JavaScript and small functional helpers; keep jQuery usage only where existing Zotonic widgets/actions require it.
• For source documentation, Erlang actions, scomps, models, and modules should have -moduledoc; use those docs as the local source of truth.

Template JavaScript

• Include JavaScript libraries with {% lib "js/file.js" %} or multi-file {% lib %} blocks. Options include minify, nocache, async, and defer; {% lib ... minify %} can force minification.
• Add module/site JS includes through local include templates such as _js_include.tpl, _admin_js_include.tpl, _html_head.tpl, or _html_body.tpl instead of duplicating script tags in pages.
• Put page-specific inline JavaScript inside {% javascript %}...{% endjavascript %}. It runs after jQuery is initialized; for dynamic content it runs after the DOM update that inserted the template.
• Ensure the base template has exactly one {% script %}, normally near the end of <body>. It emits collected JavaScript from {% javascript %}, {% wire %}, actions, and related scomps.
• Do not put generated JavaScript after {% script %} in a page; it will not be included in that page render.
• {% script nostartup %} omits startup code, and format="html" | "escapejs" | "js" controls output format. Use these only when the caller expects a nonstandard script output.
• Direct <script> tags must carry the CSP nonce: <script nonce="{{ m.req.csp_nonce }}">. Prefer {% javascript %} or {% lib %} when possible because they fit Zotonic's collection/minification flow.

Wires And Actions

• Use {% wire %} to bind browser events to actions and optional server postbacks. The default event is click.

{% wire id="show" action={show target="message"} %}
<button id="show" type="button">{_ Show _}</button>

• Use type="submit" to wire form submission. The target form should have an id and usually method="post" action="postback".

{% wire id="edit-form" type="submit" postback={save id=id} delegate=`mod_example` %}
<form id="edit-form" method="post" action="postback">
    ...
</form>

• A click wire with postback=... sends a #postback{} to the delegate. A submit wire sends a #submit{}.
• Use delegate=`mod_example` when the event/2 handler is not in the controller or current module.
• Use repeated action={...} arguments for client-side effects before/after a postback; keep user-visible text translated.
• Named wires can be triggered from JavaScript with z_event("name"): {% wire name="refresh-list" action={update target="list" template="_list.tpl"} %}.
• MQTT wires can subscribe client actions to topics when mod_mqtt is enabled, for example {% wire type={mqtt topic="~site/public/hello"} action={growl text="hello"} %}.
• Actions live under src/actions/ as action_<module>_<name>.erl. They normally implement render_action/4 and should document arguments, generated JavaScript, postbacks, and security assumptions in -moduledoc.

Erlang Event Handlers

• Browser wire events are received by event/2; include the relevant records via zotonic.hrl or zotonic_wired.hrl.
• #postback{message, trigger, target} is sent for normal postbacks from clicks and explicit postback actions.
• #submit{message, form, target} is sent for wired form submits; access fields with z_context:get_q/2, z_context:get_q_all/1, or z_context:get_q_validated/2.
• #postback_notify{message, trigger, target, data} is a notification-style event used by JavaScript postback handlers; see zotonic_notifications.hrl and nearby module event/2 clauses for exact payloads.
• Return the updated Context. Use z_render:update/3, replace/3, insert_*, dialog/4, dialog_close/1, growl/2, and z_render:wire/2 to queue browser responses.

Client Postback Notify

• Send a #postback_notify{} from browser JavaScript with z_notify(message, params), defined in apps/zotonic_mod_wires/priv/lib/js/apps/zotonic-wired.js.
• Without z_delegate, z_notify sends to the server-side postback_notify observer chain via the notify delegate. With z_delegate: 'mod_name', it calls mod_name:event(#postback_notify{}, Context).
• Use z_target_id for the element that should receive possible updates and z_trigger_id for the triggering element. Other params are available as request/query values in Context.
• z_notify automatically sends the current CSP nonce and any stored postback data.

z_notify("update", {
    z_delegate: "mod_admin",
    z_target_id: targetId,
    z_trigger_id: triggerId,
    id: resourceId
});

event(#postback_notify{message = <<"update">>, target = TargetId}, Context) ->
    Id = z_context:get_q(<<"id">>, Context),
    Html = z_template:render("_rsc_item.tpl", [{id, Id}], Context),
    z_render:update(TargetId, Html, Context).

Postback Client State

• Zotonic wires can attach client-side state to every postback, submit, and postback_notify sent by zotonic-wired.js.
• Page-scoped state is stored as JSON in the <body data-wired-postback="..."> attribute.
• Tab-scoped state is stored under sessionStorage.postbackData; persistent browser/site state is stored under localStorage.postbackData.
• z_postback_data() merges these three stores and sends the result as a query parameter named z_postback_data.
• Merge precedence is body attribute over sessionStorage over localStorage. Use page-scoped state for current-page UI state, sessionStorage for per-tab state, and localStorage only for state that should survive reloads and new tabs.
• z_notify(...) adds this data to #postback_notify{data = #{ q := ... }}. Normal postback and submit events add the same z_postback_data value to the #postback_event{data = #{ q := ... }} payload before it becomes #postback{} or #submit{}.
• On the server, read it with z_context:get_q(<<"z_postback_data">>, Context) and validate it like any other client-provided value.

case z_context:get_q(<<"z_postback_data">>, Context) of
    #{ <<"z_edit_language">> := Lang } ->
        handle_language(Lang, Context);
    _ ->
        Context
end.

• Set page-scoped state from client JavaScript with z_postback_data_set(Name, Value). Read it with z_postback_data_get(Name).
• Set tab-scoped state with z_postback_data_set_session(Name, Value), which publishes to model/sessionStorage/post/postbackData/<Name>.
• Set persistent state with z_postback_data_set_local(Name, Value), which publishes to model/localStorage/post/postbackData/<Name>.
• Delete a key from all three stores with z_postback_data_delete(Name).

z_postback_data_set("z_edit_language", "nl");
z_postback_data_set_session("wizard_step", 3);
z_postback_data_set_local("preferred_panel", "advanced");
z_postback_data_delete("wizard_step");

• Set initial page-scoped state from a template by rendering the JSON-encoded map on <body data-wired-postback="...">; escape it as an HTML attribute.
• Set or change state from a server response by emitting JavaScript with a {script} action, {% javascript %} in rendered HTML, or z_render:add_script/2. Escape any values placed into generated JavaScript.
• From Erlang code running in a page/client context, persistent client stores can also be updated by publishing to the current client bridge:

z_mqtt:publish(
    [<<"~client">>, <<"model">>, <<"sessionStorage">>, <<"post">>, <<"postbackData">>, <<"wizard_step">>],
    3,
    Context),
z_mqtt:publish(
    [<<"~client">>, <<"model">>, <<"localStorage">>, <<"post">>, <<"postbackData">>, <<"preferred_panel">>],
    <<"advanced">>,
    Context).

-spec event(#submit{} | #postback{}, z:context()) -> z:context().
event(#submit{message = {save, Args}, form = FormId}, Context0) ->
    Title = z_context:get_q(<<"title">>, Context0),
    Context = save_title(Args, Title, Context0),
    z_render:growl(?__("Saved.", Context), z_render:update(FormId, <<>>, Context));
event(#postback{message = refresh, target = TargetId}, Context) ->
    Html = z_template:render("_list.tpl", [], Context),
    z_render:update(TargetId, Html, Context).

Security

• Always use a nonce on direct script tags: nonce="{{ m.req.csp_nonce }}".
• Treat query arguments, form fields, postback payload data, MQTT payloads, and Cotonic data attribute values as untrusted. Validate in event/2 and server model callbacks.
• Do not interpolate untrusted template values directly into JavaScript. Use JSON/JS escaping filters appropriate to the local code, and prefer passing structured data via data attributes or MQTT payloads.
• Signed postbacks protect the postback command, not arbitrary form/query data. Validate ids through m_rsc, ACL checks, or model functions before modifying state.
• Client-side MQTT topics are subject to bridge/server authorization, but handlers must still validate payload shape, ids, and permissions.

Client Server Communication

• Zotonic uses Cotonic in the browser and MQTT-style messaging between browser and server.
• _html_head_cotonic.tpl creates cotonic.ready, pre-connects cotonic.bridgeSocket to the mqtt_transport WebSocket with the mqtt subprotocol, and buffers early click/submit data-attribute events.
• _js_include.tpl loads cotonic/cotonic.js, js/apps/zotonic-wired.js, js/apps/z.widgetmanager.js, and other base modules. Include _html_head.tpl/_html_head_admin.tpl and _js_include.tpl through the normal base template flow.
• controller_mqtt_transport.erl handles MQTT over WebSocket and authenticated HTTP fallback/post traffic. Authentication can use the z.auth cookie or MQTT username/password.
• Add connection status HTML with _bridge_warning.tpl where the site wants to show “Connecting...” and a connection-test link.
• MQTT topics are slash-separated and support + and # wildcards. Server z_mqtt supports QoS 0, 1, and 2, and options such as retain; most browser communication uses QoS 0 unless a call explicitly asks otherwise.
• Do not assume exactly-once delivery for JavaScript relay traffic. The browser/server bridge queues while reconnecting, and the server page process buffers until the browser connects, but persistent semantics depend on the server topic, retain flag, and QoS path being used.
• There are two topic trees: the browser's local Cotonic broker and Zotonic's server broker. bridge/origin/... on the client publishes/calls the server origin tree. Server topics under bridge/<client-id>/... route to the browser tree.
• Server shorthand topics include ~client for the current client bridge and ~user for the current user topic. Core server topic roots include public, test, user, user/<id>, and bridge/<client-id>.
• Server models are reachable through topics such as bridge/origin/model/<model>/get/..., bridge/origin/model/<model>/post/..., and bridge/origin/model/<model>/delete/...; server-side mod_mqtt dispatches them through z_model:callback/5.
• Client-routing topics on the server are the bridge/... topics; use them for page-specific browser communication, not for durable global state.

Client Publish Subscribe

• Wait for cotonic.ready before browser code depends on Cotonic startup.

cotonic.ready.then(() => {
    const sub = cotonic.broker.subscribe("bridge/origin/test/#", (msg, bindings, options) => {
        console.log(msg, bindings, options);
    });

    cotonic.broker.publish("bridge/origin/test/hello", { text: "Hello" });

    cotonic.broker.call(
        "bridge/origin/model/template/get/render/_item.tpl",
        { vars: { id: 123 } },
        { qos: 1 }
    ).then((html) => cotonic.broker.publish("model/ui/replace/item", html));
});

• Use cotonic.broker.publish(topic, payload, options) for fire-and-forget messages, subscribe(filter, callback, options) for subscriptions, and call(topic, payload, options) when a response topic is expected.

Server Publish Subscribe

• Use z_mqtt for Erlang-side MQTT. Prefer binary topic segments or the helper mapping functions when topic parts are dynamic.

z_mqtt:subscribe([<<"my">>, <<"topic">>, '#'], Context),
z_mqtt:publish([<<"my">>, <<"topic">>], #{status => ok}, #{qos => 1, retain => true}, Context).

• A subscribed Erlang process receives {mqtt_msg, Msg} when using process subscriptions.
• Modules can export quoted mqtt: callback functions. mod_mqtt scans active modules and subscribes these with a sudo context.

-export(['mqtt:test/#'/2]).

'mqtt:test/#'(#{payload := Payload, topic := Topic}, Context) ->
    handle_test_message(Topic, Payload, Context).

Cotonic

• Cotonic is the browser-side runtime for isolated workers, models, topic routing, and interactive DOM updates. See cotonic.org for the upstream concepts and use local Zotonic sources for Zotonic-specific topics.
• Workers are spawned by Cotonic (cotonic.spawn, cotonic.spawn_named, or Zotonic template worker tags). Worker code uses self.subscribe, self.publish, and self.call and declares provides/depends so startup can order services.
• The service worker coordinates cross-tab/browser features. Zotonic uses topics such as model/serviceWorker/post/broadcast/+channel and model/serviceWorker/event/broadcast/+channel for browser-window synchronization, including auth state sync.
• Common client models include model/localStorage, model/sessionStorage, model/sessionId, model/document, model/location, model/window, model/ui, model/serviceWorker, model/lifecycle, model/autofocus, model/dedup, model/auth, model/auth-ui, model/oauth, model/loadmore, and module-specific models such as model/fileuploader.
• Use local/client models directly from JavaScript (model/localStorage/get/key) and server models via the origin bridge (bridge/origin/model/rsc/get/...). Server code can target client models by publishing to the current client bridge (~client or bridge/<client-id>/...).
• Cotonic data attributes publish DOM events to topics: data-onclick-topic, data-onsubmit-topic, data-oninput-topic, with matching data-on...-cancel attributes for cancellation behavior.
• Add data-cotonic-pathname-search="{% cotonic_pathname_search %}" to <body> in normal pages so Cotonic location/UI logic has the routed pathname/search value.
• The interactive DOM is updated by publishing to UI topics such as model/ui/insert/<key>, model/ui/update/<key>, model/ui/replace/<key>, model/ui/delete/<key>, and model/ui/render-template/<key>. Listen for DOM update events when follow-up initialization is needed.
• Check Zotonic Cotonic workers and models under apps/*/priv/lib/js/**/*.worker.js, apps/*/priv/lib/js/models/*.js, and base files such as apps/zotonic_mod_wires/priv/lib/js/apps/zotonic-wired.js.

Authentication

• zotonic.auth.worker.js owns browser auth state. It checks, refreshes, logs on/off, resets, changes, and switches users by calling /zotonic-auth and publishing auth model events.
• Important auth topics include model/auth/post/check, model/auth/post/logon, model/auth/post/logoff, model/auth/post/refresh, model/auth/post/form/logon, model/auth/post/onetime-token, model/auth/event/auth, model/auth/event/auth-user-id, model/auth/event/auth-error, and model/auth/event/ui-status.
• The z.auth cookie is the browser auth cookie managed by server authentication token code and refreshed/reset via /zotonic-auth. Client code should go through model/auth topics instead of editing this cookie directly.
• zotonic.auth-ui.worker.js owns auth UI flows such as login views, reminders, verification messages, reset, change, and confirmation. It listens to model/auth-ui/post/... and calls server models via bridge/origin/model/authentication/....
• zotonic.oauth.worker.js coordinates OAuth authorize/redirect flows, stores temporary OAuth data through model/localStorage/model/sessionStorage, calls bridge/origin/model/oauth2_service/post/oauth-redirect, and publishes auth onetime-token or UI status topics as needed.

do Widgets

• z.widgetmanager.js initializes classes starting with do_. The class do_clickable maps to the jQuery widget/plugin clickable; do_dialog maps to show_dialog.
• Widget options are read from metadata/data attributes such as data-adminwidget='{"minifiedOnInit": true}', merged with widget defaults, and passed to the plugin.
• Run widgets by adding the class and including the widget JavaScript through {% lib %}. The widget manager initializes existing DOM on page startup and new nodes after IncrementalDOM/Cotonic updates.

{% lib "js/modules/z.clickable.js" %}
<div class="do_clickable" data-clickable='{"url":"/example"}'>...</div>

• Define widgets as normal jQuery UI/Zotonic widgets in priv/lib/js/modules/ and set defaults on the widget, for example $.ui.clickable.defaults = {...}.
• Core Zotonic widgets under apps/ include base widgets do_clickable, do_smiley, do_feedback, do_timesince, do_tooltip, do_inputoverlay, do_autocomplete, do_zeditor, do_datepicker, do_formdirty, do_popupwindow, do_filepreview, do_forminit, and do_dialog.
• Additional core module widgets include do_live (mod_mqtt), do_adminwidget (mod_admin), do_menuedit/do_trash/Superfish menu behavior (mod_menu), do_cookie_consent, do_survey_test_feedback, do_gaq_track, and do_make_diff.
• Before adding a new widget, run rg "do_<name>|\$\.widget|\.defaults" apps/*/priv/lib/js to avoid duplicating an existing core widget.