# Create a reusable module

Source: https://zotonic.com/docs/1353/create-a-reusable-module

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

Language: en

Create apps_user/zotonic_mod_garden with the following files. This example adds a discoverable module without starting an extra process.

Create `apps_user/zotonic_mod_garden` with the following files. This example adds a discoverable module without starting an extra process.

`rebar.config`:

```erlang
{erl_opts, [debug_info]}.
```

`src/zotonic_mod_garden.app.src`:

```erlang
{application, zotonic_mod_garden, [
    {description, "Community garden features"},
    {vsn, "0.1.0"},
    {registered, []},
    {applications, [kernel, stdlib, zotonic_core]},
    {env, []},
    {modules, []}
]}.
```

`src/mod_garden.erl`:

```erlang
-module(mod_garden).
-mod_title("Garden").
-mod_description("Community garden features.").
-mod_prio(500).
```

Run `make` from the Zotonic workspace root. On the running development node, use `bin/zotonic update` to refresh discovery. Open module management in the site's admin and activate Garden.

Check that the module is active. Add the model from [Expose data through a model](/id/2960) for a first data lookup, and put templates in `priv/templates`. Keep installation hooks and observers in the main module; move domain logic into models or support modules.

Erlang applications, Zotonic modules, and sites
-----------------------------------------------

These terms describe different parts of the system.

::: {.aside}
Putting a package on the code path is different from activating its Zotonic module for a particular site. Use [Application startup and per-site module activation](/id/2926) to understand this distinction when a compiled feature is missing.
:::

An **Erlang application** is a package described by a `.app` file, normally generated from `src/<name>.app.src`. It can provide modules and an OTP application callback.

A **Zotonic module** is functionality that can be activated for a site. Its main Erlang module declares attributes such as `-mod_title` and `-mod_depends`.

A **site** is a named website with its own configuration and runtime context. Several sites share the same Erlang VM and loaded code, while module activation and site data are site-specific.

Upgrade a module's data schema
------------------------------

Version schema changes through the module's installation and upgrade mechanism. Inspect a module using `-mod_schema` and `manage_schema/2` before adding your own versioned step.

Make each step safe for the state it may encounter after a partial attempt. Separate database structure changes from long-running data conversion when a single startup transaction would be too costly.

Test a fresh install and an upgrade from the previously released schema. Keep a database backup for the upgrade test and verify application behavior after migration, not just the table definitions.

If version 1 installed the Garden fixture, change the declaration to `-mod_schema(2).` for the next release. Keep the fresh-install clause and add a `manage_schema({upgrade, 2}, Context)` clause for the version-1-to-2 change. Erlang function clauses are separated with semicolons. Do not return success for an upgrade you have not implemented.

The manager calls upgrades in sequence, within a database transaction per schema step, then applies any returned datamodel and records the version. A code reload alone is not an upgrade test: run the module activation/startup lifecycle on the test site. Use `manage_data/2` for a deliberate follow-up after schema work, or queue longer conversions. Compare fresh-install and upgraded data before release.

Dependencies, capabilities, and module priority
-----------------------------------------------

The main site or module can declare:

```erlang
-mod_depends([mod_base]).
-mod_prio(500).
```

Dependencies express requirements for activation. Modules can also declare provided capabilities with `-mod_provides`; depend on an established capability when your feature requires that service rather than one particular implementation.

Priority determines ordering when modules supply competing resources such as templates. Lower numerical priorities take precedence. Sites commonly use a low priority so their templates override generic module templates.

Do not use priority to hide a missing dependency or duplicate Erlang module name. Check which modules are active, inspect the selected template, and make one intentional override at a time.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/1353?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/1353?language=en>)
