Zotonic Javascript
Developmentzotonic-javascriptZotonic Javascript is an Agent Skill for development published in the zotonic/zotonic repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when creating, refactoring, or reviewing Zotonic JavaScript, template JavaScript tags, wires, actions, Erlang event/2 browser handlers, Cotonic workers/models, MQTT client-server communication, authentication workers, and do_ widgets in Zotonic sites or modules.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/zotonic/zotonic/blob/HEAD/.agents/skills/zotonic-javascript/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/zotonic-javascript, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Zotonic JavaScript
First Pass
- Inspect nearby templates, JavaScript modules, workers, actions, and Erlang
event/2handlers before editing; preserve local patterns. - Prefer Zotonic declarative behavior (
{% wire %}, actions, Cotonic data attributes, workers, anddo_...widgets) over one-off DOM scripts. - Put reusable JavaScript under the module or site
priv/lib/jstree 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 includeminify,nocache,async, anddefer;{% 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.tplinstead 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, andformat="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 usuallymethod="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 theevent/2handler 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_mqttis enabled, for example{% wire type={mqtt topic="~site/public/hello"} action={growl text="hello"} %}. - Actions live under
src/actions/asaction_<module>_<name>.erl. They normally implementrender_action/4and 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 viazotonic.hrlorzotonic_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 withz_context:get_q/2,z_context:get_q_all/1, orz_context:get_q_validated/2.#postback_notify{message, trigger, target, data}is a notification-style event used by JavaScript postback handlers; seezotonic_notifications.hrland nearby moduleevent/2clauses for exact payloads.- Return the updated
Context. Usez_render:update/3,replace/3,insert_*,dialog/4,dialog_close/1,growl/2, andz_render:wire/2to queue browser responses.
Client Postback Notify
- Send a
#postback_notify{}from browser JavaScript withz_notify(message, params), defined inapps/zotonic_mod_wires/priv/lib/js/apps/zotonic-wired.js. - Without
z_delegate,z_notifysends to the server-sidepostback_notifyobserver chain via thenotifydelegate. Withz_delegate: 'mod_name', it callsmod_name:event(#postback_notify{}, Context). - Use
z_target_idfor the element that should receive possible updates andz_trigger_idfor the triggering element. Other params are available as request/query values inContext. z_notifyautomatically 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_notifysent byzotonic-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 underlocalStorage.postbackData. z_postback_data()merges these three stores and sends the result as a query parameter namedz_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 samez_postback_datavalue 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 withz_postback_data_get(Name). - Set tab-scoped state with
z_postback_data_set_session(Name, Value), which publishes tomodel/sessionStorage/post/postbackData/<Name>. - Set persistent state with
z_postback_data_set_local(Name, Value), which publishes tomodel/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, orz_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/2and 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.tplcreatescotonic.ready, pre-connectscotonic.bridgeSocketto themqtt_transportWebSocket with themqttsubprotocol, and buffers early click/submit data-attribute events._js_include.tplloadscotonic/cotonic.js,js/apps/zotonic-wired.js,js/apps/z.widgetmanager.js, and other base modules. Include_html_head.tpl/_html_head_admin.tpland_js_include.tplthrough the normal base template flow.controller_mqtt_transport.erlhandles MQTT over WebSocket and authenticated HTTP fallback/post traffic. Authentication can use thez.authcookie or MQTT username/password.- Add connection status HTML with
_bridge_warning.tplwhere the site wants to show “Connecting...” and a connection-test link. - MQTT topics are slash-separated and support
+and#wildcards. Serverz_mqttsupports QoS0,1, and2, and options such asretain; 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 underbridge/<client-id>/...route to the browser tree. - Server shorthand topics include
~clientfor the current client bridge and~userfor the current user topic. Core server topic roots includepublic,test,user,user/<id>, andbridge/<client-id>. - Server models are reachable through topics such as
bridge/origin/model/<model>/get/...,bridge/origin/model/<model>/post/..., andbridge/origin/model/<model>/delete/...; server-sidemod_mqttdispatches them throughz_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.readybefore 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, andcall(topic, payload, options)when a response topic is expected.
Server Publish Subscribe
- Use
z_mqttfor 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_mqttscans 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 usesself.subscribe,self.publish, andself.calland declaresprovides/dependsso startup can order services. - The service worker coordinates cross-tab/browser features. Zotonic uses topics such as
model/serviceWorker/post/broadcast/+channelandmodel/serviceWorker/event/broadcast/+channelfor 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 asmodel/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 (~clientorbridge/<client-id>/...). - Cotonic data attributes publish DOM events to topics:
data-onclick-topic,data-onsubmit-topic,data-oninput-topic, with matchingdata-on...-cancelattributes 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>, andmodel/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 asapps/zotonic_mod_wires/priv/lib/js/apps/zotonic-wired.js.
Authentication
zotonic.auth.worker.jsowns browser auth state. It checks, refreshes, logs on/off, resets, changes, and switches users by calling/zotonic-authand 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, andmodel/auth/event/ui-status. - The
z.authcookie is the browser auth cookie managed by server authentication token code and refreshed/reset via/zotonic-auth. Client code should go throughmodel/authtopics instead of editing this cookie directly. zotonic.auth-ui.worker.jsowns auth UI flows such as login views, reminders, verification messages, reset, change, and confirmation. It listens tomodel/auth-ui/post/...and calls server models viabridge/origin/model/authentication/....zotonic.oauth.worker.jscoordinates OAuth authorize/redirect flows, stores temporary OAuth data throughmodel/localStorage/model/sessionStorage, callsbridge/origin/model/oauth2_service/post/oauth-redirect, and publishes auth onetime-token or UI status topics as needed.
do Widgets
z.widgetmanager.jsinitializes classes starting withdo_. The classdo_clickablemaps to the jQuery widget/pluginclickable;do_dialogmaps toshow_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 widgetsdo_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, anddo_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, anddo_make_diff. - Before adding a new widget, run
rg "do_<name>|\$\.widget|\.defaults" apps/*/priv/lib/jsto avoid duplicating an existing core widget.