Presents various tools for development.<\/p>\n
After the development module is enabled a menu item System > Development is added in the admin.<\/p>\n
On the development page it is possible to set debugging options, trace template compilation, and test dispatch rules.<\/p>\n\n
The settings column contains these development options:<\/p>\n
Show paths to included template files.<\/strong> Add comments to generated templates\nshowing the exact file included at each point.<\/p><\/li> Show defined blocks.<\/strong> Add comments marking the start and end of each\n Always hide the floating template trace button.<\/strong> Hide the button in every\nenvironment. This takes precedence over the option to show it on production\nand acceptance sites.<\/p><\/li> Allow to show the floating template trace button on production and acceptance\nsites.<\/strong> Make the button available outside development and test environments.\nIt is still shown only to users with permission to use Download CSS and JavaScript as separate files.<\/strong> Generate separate Live reload of changed CSS files. Reload page on change of templates or\nJavaScript.<\/strong> Update styles in the browser when CSS changes, and reload the\npage when a template or JavaScript file changes. Enabling this checkbox also\nenables downloading CSS and JavaScript as separate files. The development\ntools' own pages do not automatically reload on template or JavaScript changes.<\/p><\/li> Disable caching by the Trace all database queries for the current session.<\/strong> Enable database query\ntracing for requests in your session. This checkbox requires\n Enable API to recompile and build Zotonic.<\/strong> Enable the development APIs,\nincluding Show server log in the browser console.<\/strong> Start forwarding server logs to\nthe current browser tab's developer console. Stopping it stops console logging\nfor all connected logging tabs on the site. This option requires The second settings column configures opening templates in a source editor.\nThis is either done by running a command to open a file, or by opening a\nbrowser URL. The editor can be chosen explicitly or detected automatically.<\/p>\n The local editor choice is stored in Containers only launch through browser URLs. Configure a browser editor preset\nor custom URL and map the container source root to the host checkout root.\nSublime and Vim URLs need an installed host-side protocol handler.<\/p>\n In the Erlang shell use A trusted zotonic configuration Set the zotonic configuration These settings belong to the global For example, a node configuration fragment can contain:<\/p>\n The executable can be a name on PATH or an absolute path. Executable paths and\narguments accept strings or UTF-8 binaries. Each list element is one argument;\npaths with spaces do not need embedded shell quotes. Choose the local editor in Admin > Development to save Browser URL presets, custom URLs and source-root mappings are stored separately\nin the browser for the site. They are not node configuration settings. In Docker,\nmap the source path inside the container to the corresponding checkout on the\nhost and install any required URL handler on that host. Shell helpers cannot\nopen the browser on the user's machine and return The template language server provides editor support for Supported features include:<\/p>\n Category includes list candidate templates: selecting the effective template\nrequires a resource\/category context. Formatting, rename and workspace\nreferences are not currently supported.<\/p>\n Completion after a model name follows literal Static descriptions are cached by the loaded module checksum and refreshed after\ncode reload. Models with dynamic paths or returned maps can supplement inferred\npaths with a This describes Compile and start Zotonic, and enable This launcher requires Python 3 on the editor host. It probes the local node\nfirst, then checks running Docker containers and infers source path mappings\nfrom bind mounts. Multiple matching containers require an explicit\n Semantic lookups use the selected site when one is configured. Otherwise,\nfilters, models and delegates are resolved across running development sites.\nTemplate references first use sites containing the current file; if no target\nis found, other running development sites are tried. Matching source locations\nand template priority orders are accepted without selecting a site. Conflicting\ntargets still require an explicit choice. Completion combines suggestions from\ncandidate sites, and syntax diagnostics do not require a site selection.<\/p>\n The VS Code client is in\n Use Zotonic: Select Site<\/strong> or the status-bar item to save a site choice in the\nworkspace. Zotonic: Restart Language Server<\/strong> reconnects after a node restart.\nThe extension runs only in trusted workspaces.<\/p>\n For Sublime Text, install the LSP<\/strong> package and copy the supplied\n{% block %} ... {% endblock %}<\/code> in generated templates.<\/p><\/li>mod_development<\/code>, and\nnot on the development tools' own pages. In development and test it is\navailable by default unless explicitly hidden.<\/p><\/li><link><\/code>\nand <script><\/code> tags for the files in a {% lib %}<\/code> tag. This makes debugging\neasier, but increases the number of requests needed to load a page.<\/p><\/li>{% cache %}<\/code> tag.<\/strong> Bypass template cache blocks\nwhile checking changes. This does not disable other caches, such as browser\ncaching or application data caches.<\/p><\/li>mod_server_storage<\/code>. Turn it off after investigating.<\/p><\/li>\/api\/model\/development\/get\/recompile<\/code> for compilation and\n\/api\/model\/development\/get\/flush<\/code> for flushing caches. These APIs do not\nrequire authentication when enabled; use this option only on trusted\ndevelopment installations.<\/p><\/li>mod_logging<\/code> and permission\nto receive client logs. In development, the checkbox is replaced by a notice:\nadmin pages show these logs automatically, and site pages can opt in with the\nenvironment-development<\/code> class on their <html><\/code> element.<\/p><\/li><\/ul>\nOpen source file in editor<\/h2>\n
config.d\/zotonic-editor.config<\/code> under the\nnode configuration directory and shared by development sites and shell helpers.\nBrowser URL preferences and host-path mappings remain browser\/site-specific.\nChoosing automatic detection clears the explicit machine choice. Detection\nuses trusted node configuration, ZOTONIC_EDITOR\/VISUAL\/EDITOR, inherited editor\nsessions, file associations, running editors and installed launchers, in that\norder. Ambiguous detection requires a choice. Local browser-triggered launches\nrequire the development environment and the mod_development permission.<\/p>\nz:edit(mod_foobar)<\/code>, z:edit(mod_foobar, function_name)<\/code>,\nz:edit(StackTrace)<\/code> or z:edit(<<"path\/to\/template.tpl">>, 42)<\/code>. Library and\ntemplate names are resolved across running sites; ambiguous names require a\nfull path.<\/p>\ndevelopment_editor<\/code> can contain an executable and\nargument list, for example:<\/p>\n{"code", ["--reuse-window", "--goto", "{file}:{line}:{column}"]}\n<\/code><\/pre>\ndevelopment_editor_browser_only<\/code> to true to\nforce browser launches on a remote host or a container that cannot be detected\nautomatically.<\/p>\nNode configuration<\/h3>\n
zotonic<\/code> configuration,\n(so not to a site's configuration or the module configuration):<\/p>\nSetting<\/th> Default<\/th> Purpose<\/th><\/tr><\/thead> development_editor<\/code><\/td>undefined<\/code><\/td>Trusted {Executable, Args}<\/code> command. When set, takes precedence over editor environment variables during automatic detection.<\/td><\/tr>development_editor_id<\/code><\/td><<"auto">><\/code><\/td>Saved candidate ID. An explicit ID overrides automatic selection; an unavailable choice is reported instead of silently falling back.<\/td><\/tr> development_editor_browser_only<\/code><\/td>false<\/code><\/td>Disables local discovery and launching, including shell helpers. Containers enforce this behavior regardless of the setting.<\/td><\/tr><\/tbody><\/table>\n [{zotonic, [\n {development_editor, {"code", ["--reuse-window", "--goto", "{file}:{line}:{column}"]}}\n]}].\n<\/code><\/pre>\n{file}<\/code>, {line}<\/code> and\n{column}<\/code> are replaced within arguments, with positions starting at 1. When no\nargument contains {file}<\/code>, the filename is appended. Commands are executed\nwithout a shell: shell variables, pipelines and command substitutions are not\nexpanded. Terminal editors need a supported remote client or session.<\/p>\ndevelopment_editor_id<\/code>\nin config.d\/zotonic-editor.config<\/code>. The choice applies immediately and is loaded\nagain on restart. Automatic detection saves <<"auto">><\/code>; it does not remove a\ncustom development_editor<\/code> command. Avoid defining the saved ID in multiple\nconfiguration files. Use z_config_files:config_dir()<\/code> in the Erlang shell to\nfind the node configuration directory; deployments can override it with\nZOTONIC_CONFIG_DIR<\/code>. The generated file stores only the candidate ID.<\/p>\n{error, browser_only}<\/code>.<\/p>\nLanguage server (LSP) integration<\/h2>\n
.tpl<\/code> files using a\nrunning site's module and template indexes. It complements an Erlang language\nserver; it does not provide language services for .erl<\/code> files.<\/p>\nextends<\/code> and overrules<\/code>,\nincluding the next template in module priority order and symlinked sources.<\/li>event\/2<\/code> handler.<\/li>Model path completion<\/h3>\n
m_get\/3<\/code> path patterns and simple\nliteral alternatives in guards. Bracket expressions such as m.rsc[id].title<\/code>\nare treated as arguments without evaluating them. Suggestions also include common\nand computed resource properties, request keys from m_req<\/code>, declared module\nconfiguration keys, and system keys from z_config<\/code>. Configuration values are\nnever fetched. Predicate names are suggested only with an explicitly selected site.<\/p>\nmodel_paths<\/code> attribute. Use binary keys and any<\/code> for an argument:<\/p>\n-model_paths([\n #{path => [<<"result">>, any, <<"title">>],\n description => <<"Title of the selected result.">>}\n]).\n<\/code><\/pre>\nm.example.result[id].title<\/code>. Metadata describes names and optional\nplain-text documentation only; the language server never calls m_get\/3<\/code> to\nprobe a path. Arbitrary helper calls, runtime map fields and resource-specific\ncustom properties are not inferred. Missing debug information falls back to the\navailable source file; paths without either source are omitted.<\/p>\nStart and select a site<\/h3>\n
mod_development<\/code> on the desired site.\nConfigure the editor to start this stdio command:<\/p>\n\/absolute\/path\/to\/zotonic\/bin\/zotonic-lsp\n<\/code><\/pre>\n--container NAME<\/code>. Discovery runs only at startup; the launcher replaces\nitself with the selected process and adds no ongoing proxy. Use\nbin\/zotonic lsp<\/code> directly to skip discovery and connect to the local node.<\/p>\nEditor setup<\/h3>\n
apps\/zotonic_mod_development\/priv\/editors\/vscode<\/code>. Run npm ci<\/code> there and load\nit with VS Code's --extensionDevelopmentPath<\/code> option, or package and install\nit as a VSIX. Configure automatic runtime selection with:<\/p>\n{\n "zotonic.command": "\/absolute\/path\/to\/zotonic\/bin\/zotonic-lsp",\n "zotonic.args": [],\n "zotonic.site": "mysite"\n}\n<\/code><\/pre>\napps\/zotonic_mod_development\/priv\/editors\/sublime\/Zotonic.sublime-syntax<\/code> into Packages\/User<\/code>. Configure the\nserver with command<\/code> set to ["\/absolute\/path\/to\/zotonic\/bin\/zotonic-lsp"]<\/code>,\nselector<\/code> set to text.html.zotonic<\/code>, and the desired site in\ninitialization_options.site<\/code> and settings.zotonic.site<\/code>. An example server\nconfiguration is included beside the syntax file.<\/p>\n