# Upgrade notes

Source: https://zotonic.com/docs/1455/upgrade-notes

URI: https://zotonic.com/id/1455

Language: en

Upgrade notes

::::::: {.section}
These notes list the most important changes between Zotonic versions. Please read these notes carefully when upgrading to a new major Zotonic version.

:::::: {.section}
Upgrading from 0.x to 1.0
-------------------------

Before upgrading to 1.0, be sure to check the upgrade notes for the latest 0.x version, especially if you are upgrading from before 0.12. See <a class="reference external" href="https://github.com/zotonic/zotonic/blob/0.x/doc/developer-guide/upgrading.rst">the upgrade notes on 0.x</a> for more information.

::::: {.section}
### Erlang/OTP

This is a historical migration guide from Zotonic 0.x. For current development use Erlang/OTP 28 and the current installation requirements; do not interpret old-version examples below as installation advice.

Zotonic modules are now separately published as packages to <a class="reference external" href="https://hex.pm">Hex.pm</a>, which allows you to build your own Zotonic distribution and to have each of your sites depend on the Zotonic modules (and other Erlang packages) it needs.

This was done by restructuring Zotonic into an <a class="reference external" href="https://www.rebar3.org/v3/docs/from-rebar-2x-to-rebar3#section-required-directory-structure">umbrella application</a>. The <code class="docutils literal notranslate"><span class="pre">src/</span></code> directory was moved to new <code class="docutils literal notranslate"><span class="pre">zotonic_core</span></code> app.

Before:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="p">-</span><span class="ni">include_lib</span><span class="p">(</span><span class="s">"zotonic.hrl"</span><span class="p">).</span>
</pre>
:::
::::

After:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="p">-</span><span class="ni">include_lib</span><span class="p">(</span><span class="s">"zotonic_core/include/zotonic.hrl"</span><span class="p">).</span>
</pre>
:::
::::

The HTTP and SMTP listeners were moved to a new <code class="docutils literal notranslate"><span class="pre">zotonic_listen_http</span></code> and <code class="docutils literal notranslate"><span class="pre">zotonic_listen_smtp</span></code> app respectively.

A <code class="docutils literal notranslate"><span class="pre">zotonic_launcher</span></code> app was introduced for starting Zotonic.

All built-in modules, the testsandbox and the status sites are now to be found in the <code class="docutils literal notranslate"><span class="pre">apps/</span></code> directory.
:::::

::: {.section}
### Docker

Only the <a class="reference external" href="https://hub.docker.com/r/zotonic/zotonic-dev/">zotonic/zotonic-dev</a> image is now available and automatically updated.

We have decided to drop the other Docker images as in practice everybody was creating their own production images anyway.

All files used by the Docker container are now placed in the <code class="file docutils literal notranslate"><span class="pre">docker-data</span></code> directory.

See for more information <a class="reference internal" href="/id/1411#guide-docker"><span class="std std-ref">Docker</span></a>.
:::

::::: {.section}
### Sites and modules are now OTP apps

Both sites and modules now follow the standard <a class="reference external" href="http://erlang.org/doc/design_principles/applications.html#id82228">OTP directory structure</a>, which means all Erlang files should reside in <code class="file docutils literal notranslate"><span class="pre">src/</span></code> and all other files (templates, dispatch rules etc.) in <code class="file docutils literal notranslate"><span class="pre">priv</span></code>/.

Before:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="n">yoursite</span><span class="o">/</span>
    <span class="n">models</span><span class="o">/</span>
        <span class="n">m_some_model</span><span class="p">.</span><span class="n">erl</span>
    <span class="n">templates</span><span class="o">/</span>
        <span class="n">some_template</span><span class="p">.</span><span class="n">tpl</span>
    <span class="n">yoursite</span><span class="p">.</span><span class="n">erl</span>
    <span class="n">config</span>
    <span class="p">...</span>
</pre>
:::
::::

After:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="n">yoursite</span><span class="o">/</span>
    <span class="n">priv</span><span class="o">/</span>
        <span class="n">zotonic_site</span><span class="p">.</span><span class="n">config</span>
        <span class="n">templates</span><span class="o">/</span><span class="n">some_template</span><span class="p">.</span><span class="n">tpl</span>
        <span class="p">...</span>
    <span class="n">src</span><span class="o">/</span>
        <span class="n">models</span><span class="o">/</span><span class="n">m_some_model</span><span class="p">.</span><span class="n">erl</span>
        <span class="n">yoursite</span><span class="p">.</span><span class="n">erl</span>
        <span class="n">yoursite</span><span class="p">.</span><span class="n">app</span><span class="p">.</span><span class="n">src</span>
        <span class="p">...</span>
    <span class="n">rebar</span><span class="p">.</span><span class="n">config</span>
</pre>
:::
::::

The <code class="docutils literal notranslate"><span class="pre">user_sites_dir</span></code> and <code class="docutils literal notranslate"><span class="pre">user_modules_dir</span></code> configurations have been removed. The default location for sites and modules is now the <code class="docutils literal notranslate"><span class="pre">apps_user</span></code> directory. With the <code class="docutils literal notranslate"><span class="pre">ZOTONIC_APPS</span></code> environment variable you can define an additional source directory outside the Zotonic umbrella <code class="docutils literal notranslate"><span class="pre">apps</span></code> directory.

To upgrade, move your <code class="docutils literal notranslate"><span class="pre">user/modules</span></code> and <code class="docutils literal notranslate"><span class="pre">user/sites</span></code> applications to the <code class="docutils literal notranslate"><span class="pre">apps_user</span></code> directory.

Also ensure that module directories are renamed, for example `mod_mymod` becomes:

<pre>zotonic_mod_mymod<br />    src/mod_mymod.erl<br />    src/zotonic_mod_mymod.app.src</pre>
:::::

::::: {.section}
Sites do not need to be renamed, though they *must* have the `priv/zotonic_site.config` file.

### Resources

All resources are now *maps* with *binary* keys. Use of the previous 0.x proplists is deprecated, the fetch routines will always return maps, the update routines will convert property lists to maps before updating.

The <code class="docutils literal notranslate"><span class="pre">name_to_id_check/2</span></code> functions were removed from <code class="docutils literal notranslate"><span class="pre">m_category</span></code>, <code class="docutils literal notranslate"><span class="pre">m_predicate</span></code> and <code class="docutils literal notranslate"><span class="pre">m_rsc</span></code>.

Before:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="nv">Id</span> <span class="o">=</span> <span class="nn">m_rsc</span><span class="p">:</span><span class="nf">name_to_id_check</span><span class="p">(</span><span class="nv">Value</span><span class="p">,</span> <span class="nv">Context</span><span class="p">).</span>
</pre>
:::
::::

After:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="p">{</span><span class="n">ok</span><span class="p">,</span> <span class="nv">Id</span><span class="p">}</span> <span class="o">=</span> <span class="nn">m_rsc</span><span class="p">:</span><span class="nf">name_to_id</span><span class="p">(</span><span class="nv">Value</span><span class="p">,</span> <span class="nv">Context</span><span class="p">).</span>
</pre>
:::
::::

Inserting or deleting an edge no longer modifies the last modified and modifier properties of the edge’s subject resource.

There are extra access controls on rsc properties. The <code class="docutils literal notranslate"><span class="pre">privacy</span></code> property controls what is visible for whom.

The function <code class="docutils literal notranslate"><span class="pre">m_rsc:get_visible/2</span></code> has been removed. The function <code class="docutils literal notranslate"><span class="pre">m_rsc:get/2</span></code> now checks on visibility of properties. To fetch all properties, either use <code class="docutils literal notranslate"><span class="pre">m_rsc:get_raw/2</span></code> or call <code class="docutils literal notranslate"><span class="pre">m_rsc:get/2</span></code> as a administrator level user.
:::::

::: {.section}
### Media

The medium record is now a *map* with *binary* keys. Use of the previous 0.x proplists is deprecated, the fetch routines will always return maps, the update routines will convert property lists to maps before updating.
:::

::: {.section}
### ACL

mod\_acl\_adminonly was replaced by <a class="reference internal" href="/id/1752"><span class="std std-ref">mod_acl_user_groups</span></a>. To create users that have access to the admin, add them to the ‘Managers’ user group.

The <code class="docutils literal notranslate"><span class="pre">visible_for</span></code> property semantics and the the <code class="docutils literal notranslate"><span class="pre">acl_can_see</span></code> notification were removed. You can get similar functionality by adding users to user and collaboration groups. These are provided by mod\_acl\_user\_groups. The <code class="docutils literal notranslate"><span class="pre">visible_for</span></code> <code class="docutils literal notranslate"><span class="pre">rsc</span></code> table property has been kept for BC. So if you’re using mod\_acl\_adminonly, mod\_acl\_simple\_roles or a custom ACL module you can still rely on the property.

The <code class="docutils literal notranslate"><span class="pre">acl_rsc_update_check</span></code> notification was removed.
:::

::::: {.section}
### Authentication

All auth notifications values were converted to records.

Before:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="nf">observe_auth_logon</span><span class="p">(</span><span class="n">auth_logon</span><span class="p">,</span> <span class="nv">Context</span><span class="p">,</span> <span class="p">_</span><span class="nv">Context</span><span class="p">)</span> <span class="o">-&gt;</span>
</pre>
:::
::::

After:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="nf">observe_auth_logon</span><span class="p">(</span><span class="nl">#auth_logon</span><span class="p">{},</span> <span class="nv">Context</span><span class="p">,</span> <span class="p">_</span><span class="nv">Context</span><span class="p">)</span> <span class="o">-&gt;</span>
</pre>
:::
::::
:::::

::::: {.section}
### Configuration

Port configuration <a class="reference internal" href="/id/1481#guide-deployment-env"><span class="std std-ref">environment variables</span></a> were changed.

Before:

:::: {.highlight-bash .notranslate}
::: {.highlight}
<pre><span class="nv">ZOTONIC_PORT</span><span class="o">=</span><span class="m">80</span> <span class="nv">ZOTONIC_SSL_PORT</span><span class="o">=</span><span class="m">443</span> bin/zotonic start
</pre>
:::
::::

After:

:::: {.highlight-bash .notranslate}
::: {.highlight}
<pre><span class="nv">ZOTONIC_LISTEN_PORT</span><span class="o">=</span><span class="m">80</span> <span class="nv">ZOTONIC_SSL_LISTEN_PORT</span><span class="o">=</span><span class="m">443</span> bin/zotonic start
</pre>
:::
::::

Black/white-lists are now called block/allow-lists.

<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">proxy_whitelist</span></code> is now <code class="docutils literal notranslate"><span class="pre">proxy_allowlist</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">smtp_dnsbl</span></code> is now <code class="docutils literal notranslate"><span class="pre">smtp_dns_blocklist</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">smtp_dnswl</span></code> is now <code class="docutils literal notranslate"><span class="pre">smtp_dns_allowlist</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">ip_whitelist</span></code> is now <code class="docutils literal notranslate"><span class="pre">ip_allowlist</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">ip_whitelist_system_management</span></code> is now <code class="docutils literal notranslate"><span class="pre">ip_allowlist_system_management</span></code></li>
</ul>

If an IP is on DNS allowlist then <code class="docutils literal notranslate"><span class="pre">z_email_dnsbl:status/2</span></code> returns now <code class="docutils literal notranslate"><span class="pre">{ok,</span> <span class="pre">allowed}</span></code>.
:::::

::::: {.section}
### Errors

<code class="docutils literal notranslate"><span class="pre">m_edge</span></code>, <code class="docutils literal notranslate"><span class="pre">m_identity</span></code>, <code class="docutils literal notranslate"><span class="pre">m_rsc</span></code>, <code class="docutils literal notranslate"><span class="pre">m_rsc_import</span></code> and <code class="docutils literal notranslate"><span class="pre">m_rsc_update</span></code> no longer throw exceptions. Instead, they return an <code class="docutils literal notranslate"><span class="pre">{error,</span> <span class="pre">atom()}</span></code> tuple on failure.

Before:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="nn">m_edge</span><span class="p">:</span><span class="nf">insert</span><span class="p">(</span><span class="nv">Id</span><span class="p">,</span> <span class="n">this_predicate_does_not_exist</span><span class="p">,</span> <span class="nv">UserId</span><span class="p">,</span> <span class="nv">Context</span><span class="p">).</span>
<span class="c">%% crashes with an exception</span>
</pre>
:::
::::

After:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="nn">m_edge</span><span class="p">:</span><span class="nf">insert</span><span class="p">(</span><span class="nv">Id</span><span class="p">,</span> <span class="n">this_predicate_does_not_exist</span><span class="p">,</span> <span class="nv">UserId</span><span class="p">,</span> <span class="nv">Context</span><span class="p">).</span>
<span class="c">%% fails silently, so to make it crash:</span>

<span class="p">{</span><span class="n">ok</span><span class="p">,</span> <span class="p">_</span><span class="nv">EdgeId</span><span class="p">}</span> <span class="o">=</span> <span class="nn">m_edge</span><span class="p">:</span><span class="nf">insert</span><span class="p">(</span><span class="nv">Id</span><span class="p">,</span> <span class="n">this_predicate_does_not_exist</span><span class="p">,</span> <span class="nv">UserId</span><span class="p">,</span> <span class="nv">Context</span><span class="p">).</span>

<span class="c">%% alternatively:</span>
<span class="k">case</span> <span class="nn">m_edge</span><span class="p">:</span><span class="nf">insert</span><span class="p">(</span><span class="nv">Id</span><span class="p">,</span> <span class="n">this_predicate_does_not_exist</span><span class="p">,</span> <span class="nv">UserId</span><span class="p">,</span> <span class="nv">Context</span><span class="p">)</span> <span class="k">of</span>
    <span class="p">{</span><span class="n">ok</span><span class="p">,</span> <span class="p">_</span><span class="nv">EdgeId</span><span class="p">}</span> <span class="o">-&gt;</span>
        <span class="s">"Everything fine!"</span><span class="p">;</span>
    <span class="p">{</span><span class="n">error</span><span class="p">,</span> <span class="nv">Reason</span><span class="p">}</span> <span class="o">-&gt;</span>
        <span class="s">"Something went wrong!"</span>
<span class="k">end</span><span class="p">.</span>
</pre>
:::
::::
:::::

:::: {.section}
### Logging

::: {.aside .admonition .seealso}
<p class="first admonition-title">See also</p>

<p class="last"><a class="reference internal" href="/id/1580#cookbook-logstash"><span class="std std-ref">Logging to Logstash</span></a></p>
:::

The <code class="docutils literal notranslate"><span class="pre">lager</span></code> logger has been removed and replaced with the standard <a class="reference external" href="https://www.erlang.org/doc/apps/kernel/logger_chapter.html">erlang logger application</a>.

For this to work:

<ul class="simple">
<li>Add the logger configuration to the <code class="docutils literal notranslate"><span class="pre">erlang.config</span></code> file. See <a class="reference internal" href="/id/1640#dev-logging"><span class="std std-ref">Logging</span></a> for an example.</li>
<li>Remove the <code class="docutils literal notranslate"><span class="pre">lager</span></code> definition from the erlang.config file.</li>
</ul>
::::

::: {.section}
### Export

Modules mod\_atom and mod\_atom\_feed were removed. You can export data in a variety of formats using <a class="reference internal" href="/id/1720"><span class="std std-ref">mod_export</span></a>.
:::

::: {.section}
### JSON

Mochijson structures replaced with Erlang maps.

Use the Zotonic JSON wrapper through <code class="docutils literal notranslate"><span class="pre">z_json:encode/1</span></code> and <code class="docutils literal notranslate"><span class="pre">z_json:decode/1</span></code>.

<code class="docutils literal notranslate"><span class="pre">{trans,</span> <span class="pre">_}</span></code> tuples should now be unpacked by the client, before calling <code class="docutils literal notranslate"><span class="pre">z_json:encode/1</span></code> (previously <code class="docutils literal notranslate"><span class="pre">z_json:to_mochijson/2</span></code>).
:::

::: {.section}
### Removed or deprecated functions

Deprecated functions have been removed from <code class="docutils literal notranslate"><span class="pre">z_utils</span></code>. Use the <code class="docutils literal notranslate"><span class="pre">z_url</span></code> and <code class="docutils literal notranslate"><span class="pre">z_json</span></code> modules instead.

Deprecated function <code class="docutils literal notranslate"><span class="pre">z_utils:name_for_host/2</span></code> has been removed; use <code class="docutils literal notranslate"><span class="pre">z_utils:name_for_site/2</span></code> instead.

The <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">stream</span> <span class="pre">%}</span></code> tag was removed, use MQTT websocket instead

Removed older TinyMCE versions 3.5.0 and 4.2.4.

<code class="docutils literal notranslate"><span class="pre">z_utils:combine/2</span></code> is removed, use <code class="docutils literal notranslate"><span class="pre">lists:join/2</span></code> instead.

<code class="docutils literal notranslate"><span class="pre">z_utils:combine_defined/2</span></code> is renamed to <code class="docutils literal notranslate"><span class="pre">z_utils:join_defined/2</span></code>.
:::

::: {.section}
### Module schema and data initialization

The <cite>#datamodel.data</cite> field has been removed. The notifier <cite>#manage_data</cite> has also been removed.

Now the call to (the optional) <cite>manage_schema/2</cite> will be followed by a call to <cite>manage_data/2</cite>. Note that <cite>manage_data</cite> will be called if and only if you have a <cite>manage_schema/2</cite> function exported (and the <cite>-mod_schema(..)</cite> version changes or the module is installed).

The <cite>manage_schema/2</cite> function is called inside a transaction. The <cite>manage_data/2</cite> function is called after that transaction and also after all (optional) <cite>#datamodel</cite> changes are applied.
:::

::: {.section}
### Templates

The <code class="docutils literal notranslate"><span class="pre">use_absolute_url</span></code> argument of the <code class="docutils literal notranslate"><span class="pre">url</span></code>, <code class="docutils literal notranslate"><span class="pre">image</span></code> and <code class="docutils literal notranslate"><span class="pre">lib</span></code> tags was renamed to <code class="docutils literal notranslate"><span class="pre">absolute_url</span></code>.

Templates are now stored in <code class="file docutils literal notranslate"><span class="pre">yoursite/priv/templates/</span></code> instead of <code class="file docutils literal notranslate"><span class="pre">yoursite/templates/</span></code>.

The <code class="docutils literal notranslate"><span class="pre">maxage</span></code> caching argument was renamed to <code class="docutils literal notranslate"><span class="pre">max_age</span></code>.

The models have now extra ACL checks.

The <code class="docutils literal notranslate"><span class="pre">m.config</span></code>, <code class="docutils literal notranslate"><span class="pre">m.site</span></code> and <code class="docutils literal notranslate"><span class="pre">m.sysconfig</span></code> models are only accessible as administrator. Use the models *owning* the various settings to access the configurations.

Exception is that the hostname and site-title information is publicly accessible using <code class="docutils literal notranslate"><span class="pre">m.site</span></code>.

Examples:

<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">m.config.site.title.value</span></code> is now <code class="docutils literal notranslate"><span class="pre">m.site.title</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">m.config.mod_editor_tinymce.version.value</span></code> is now <code class="docutils literal notranslate"><span class="pre">m.editor_tinymce.version</span></code></li>
</ul>

Check the various models of the modules for the new lookups.

The <code class="docutils literal notranslate"><span class="pre">catinclude</span></code> for a resource with an unique name now looks for (assuming the unique name is <code class="docutils literal notranslate"><span class="pre">my_unique_name</span></code> and the template is <code class="docutils literal notranslate"><span class="pre">page.tpl</span></code>): <code class="docutils literal notranslate"><span class="pre">page.name.my_unique_name.tpl</span></code> and **not** anymore for <code class="docutils literal notranslate"><span class="pre">page.my_unique_name.tpl</span></code>. Rename your templates accordingly.

The category property <code class="docutils literal notranslate"><span class="pre">feature_show_address</span></code> property is now called <code class="docutils literal notranslate"><span class="pre">is_feature_show_address</span></code>. All feature properties should be called <code class="docutils literal notranslate"><span class="pre">is_feature_...</span></code> to obtain a proper boolean value after the category edit form is saved.
:::

::: {.section}
### Port, proxies and SSL certificates

SSL/https support has been completely refactored.

<ul class="simple">
<li>SSL self signed certificates have been moved into the core</li>
<li>New modules <a class="reference internal" href="/id/1753"><span class="std std-ref">mod_ssl_ca</span></a> and <a class="reference internal" href="/id/1754"><span class="std std-ref">mod_ssl_letsencrypt</span></a></li>
<li>Deleted module <code class="docutils literal notranslate"><span class="pre">mod_ssl</span></code></li>
<li>Port configuration has been changed, see <a class="reference internal" href="/id/1482#ref-port-ssl-configuration"><span class="std std-ref">Port configurations</span></a></li>
<li>If you have a <code class="docutils literal notranslate"><span class="pre">priv/ssl</span></code> directory in your site, rename it to <code class="docutils literal notranslate"><span class="pre">priv/security</span></code></li>
</ul>

For an overview of https support, see <a class="reference internal" href="/id/1755#https-support"><span class="std std-ref">HTTPS support</span></a>
:::

::: {.section}
### Erlang code, Controllers, Event handlers

If you made a site using custom controllers or request handling then you need to adapt your Erlang code. Zotonic is now using Cowboy under the hood for the http handling, previously this was MochiWeb.

The following changes are made:

<ul class="simple">
<li>Binaries for all request variables and arguments.</li>
<li>Events use binaries for strings in templates.</li>
<li>Cookies are binaries.</li>
<li>Request headers are binaries.</li>
<li>Controllers initialization callbacks are removed.</li>
<li>Controller callbacks have a single <em>Context</em> argument.</li>
<li>Custom websocket handlers are removed, implement your own using Cowboy.</li>
<li>The include file <code class="docutils literal notranslate"><span class="pre">include/controller_webmachine_helper.hrl</span></code> is removed (and not needed anymore).</li>
</ul>
:::

::: {.section}
### Binaries for request variables

If you request an argument with <code class="docutils literal notranslate"><span class="pre">z_context:get_q/2</span></code> and related functions then you might need to adapt some code. Requesting a query argument using an *atom* or *binary* will return a *binary*. Requesting with a *string* returns a string, this is for backwards compatibility. The function <code class="docutils literal notranslate"><span class="pre">get_q_all</span></code> will return all arguments as binaries.

In short:

<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">z_context:get_q(&lt;&lt;"arg"&gt;&gt;,</span> <span class="pre">Context)</span></code> returns <code class="docutils literal notranslate"><span class="pre">&lt;&lt;"value"&gt;&gt;</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">z_context:get_q(arg,</span> <span class="pre">Context)</span></code> returns <code class="docutils literal notranslate"><span class="pre">&lt;&lt;"value"&gt;&gt;</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">z_context:get_q("arg",</span> <span class="pre">Context)</span></code> returns <code class="docutils literal notranslate"><span class="pre">"value"</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">z_context:get_q_all(Context)</span></code> returns <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">{&lt;&lt;"arg"&gt;&gt;,&lt;&lt;"value"&gt;&gt;},</span> <span class="pre">...]</span></code></li>
</ul>

The binary name is the preferred way to request arguments.
:::

::: {.section}
### Events like submit, postback and postback\_notify

Strings in the <code class="docutils literal notranslate"><span class="pre">#submit{}</span></code>, <code class="docutils literal notranslate"><span class="pre">#postback{}</span></code> and <code class="docutils literal notranslate"><span class="pre">#postback_notify{}</span></code> events are now binaries. This is especially the case for the message, trigger, target, and form fields.

For example, replace <code class="docutils literal notranslate"><span class="pre">#submit{message="hello"}</span></code> with <code class="docutils literal notranslate"><span class="pre">#submit{message</span> <span class="pre">=</span> <span class="pre">&lt;&lt;"hello"&gt;&gt;}</span></code>. Watch the space between <code class="docutils literal notranslate"><span class="pre">=</span></code> and the <code class="docutils literal notranslate"><span class="pre">&lt;&lt;"..."&gt;&gt;</span></code>, without the space you will get a syntax error.
:::

::: {.section}
### Cookies

Use binaries for fetching and setting cookie names and values, don’t use strings.
:::

::: {.section}
### Request and response headers

All request and response headers now use binary names and values, do not use strings.

The request and response header names are normalized to lowercase names, so always use <code class="docutils literal notranslate"><span class="pre">&lt;&lt;"x-my-header"&gt;&gt;</span></code> and *never* <code class="docutils literal notranslate"><span class="pre">&lt;&lt;"X-My-Header"&gt;&gt;</span></code>.

The header values are passed as-is, and they are always binaries.
:::

::: {.section}
### Controllers

The controllers are simplified and will need some adaptations.

The following callbacks are removed:

<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">init</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">ping</span></code></li>
</ul>

Most resource callbacks now have a single *Context* argument; `process/4` receives method, accepted/provided content types and context. the *ReqData* argument has been removed. There is no need anymore for the <code class="docutils literal notranslate"><span class="pre">?WM_REQ</span></code> and <code class="docutils literal notranslate"><span class="pre">?WM_REPLY</span></code> macros, and they have been removed.

Other controller changes changes are:

<ul class="simple">
<li>Content types are now binaries in <cite>content_types_accepted</cite> and <cite>content_types_provided</cite></li>
<li>Character sets are now binaries in <cite>charsets_provided</cite></li>
<li>Methods are now binaries in <cite>allowed_methods</cite> and <cite>known_methods</cite></li>
<li>Encodings are now binaries in <cite>content_encodings_provided</cite></li>
<li>The return value of <cite>generate_etag</cite> must be a binary</li>
</ul>
:::

::: {.section}
### Search

Search argument <code class="docutils literal notranslate"><span class="pre">authoritative</span></code> was renamed to <code class="docutils literal notranslate"><span class="pre">is_authoritative</span></code>.

The <code class="docutils literal notranslate"><span class="pre">custompivot</span></code> has been removed. Pivot fields can now directly be addressed with <code class="docutils literal notranslate"><span class="pre">pivot.mypivotname.column</span></code>. Pivot tables are now joined automatically, removing the need for the <code class="docutils literal notranslate"><span class="pre">custompivot</span></code> search argument.
:::

::: {.section}
### Notifications

The <code class="docutils literal notranslate"><span class="pre">admin_menu</span></code> notifications is now a tuple: <code class="docutils literal notranslate"><span class="pre">#admin_menu{}</span></code>. Update the <code class="docutils literal notranslate"><span class="pre">observe_admin_menu</span></code> functions in sites and modules.
:::

::: {.section}
### Modules

Moved <code class="docutils literal notranslate"><span class="pre">mod_base_site</span></code> to <a class="reference external" href="https://github.com/zotonic/zotonic_mod_base_site">https://github.com/zotonic/zotonic_mod_base_site</a>
:::

::::: {.section}
### Menus

The storage format of the <cite>menu</cite> property is changed. Previously it was stored as a list of tuples:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="p">{</span><span class="mi">1234</span><span class="p">,</span> <span class="p">[</span> <span class="p">{</span><span class="mi">5678</span><span class="p">,</span> <span class="p">[</span> <span class="p">...</span> <span class="p">]},</span> <span class="p">...}</span>
</pre>
:::
::::

This doesn’t allow for conversion to JSON, so the structure has been changed to use records:

:::: {.highlight-erlang .notranslate}
::: {.highlight}
<pre><span class="nl">#rsc_tree</span><span class="p">{</span> <span class="n">id</span> <span class="o">=</span> <span class="p">...,</span>  <span class="n">tree</span> <span class="o">=</span> <span class="p">[</span> <span class="p">...</span> <span class="p">]}</span>
</pre>
:::
::::

Use the current export API for JSON serialization; do not depend on the historical jsxrecord implementation detail.
:::::
::::::
:::::::

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/1455?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/1455?language=en>)
