Search documentation of phoenix_kit

# PhoenixKit.Emails.Templates (phoenix_kit v1.6.19)

View Source

Context module for managing email templates.

This module provides the business logic and database operations for email templates, including CRUD operations, template rendering, variable substitution, and usage tracking.

## Main Functions

- `list_templates/1` - List templates with filtering and pagination
- `get_template/1` - Get template by ID
- `get_template_by_name/1` - Get template by name
- `create_template/1` - Create a new template
- `update_template/2` - Update existing template
- `delete_template/1` - Delete template
- `render_template/2` - Render template with variables

## Examples

    # List all active templates
    Templates.list_templates(%{status: "active"})

    # Get template by name
    template = Templates.get_template_by_name("magic_link")

    # Render template with variables
    Templates.render_template(template, %{"user_name" => "John", "url" => "https://example.com"})

# Summary

## Functions

activate_template(template, user_id \\ nil)

Activates an email template by setting its status to "active".

archive_template(template, user_id \\ nil)

Archives an email template by setting its status to "archived".

clone_template(template, new_name, attrs \\ %{})

Clones an existing template with a new name.

count_templates(opts \\ %{})

Returns the count of templates matching the given filters.

create_template(attrs \\ %{})

Creates a new email template.

delete_template(template)

Deletes an email template.

get_active_template_by_name(name)

Gets an active template by name.

get_template(id)

Gets a template by ID.

get_template!(id)

Gets a template by ID, raising an exception if not found.

get_template_by_name(name)

Gets a template by name.

get_template_stats()

Gets template statistics for dashboard display.

list_templates(opts \\ %{})

Lists templates with optional filtering and pagination.

magic_link_html_template()

Returns the HTML template for magic link emails.

magic_link_text_template()

Returns the text template for magic link emails.

register_html_template()

Returns the HTML template for registration confirmation emails.

register_text_template()

Returns the text template for registration confirmation emails.

render_template(template, variables \\ %{})

Renders a template with the provided variables.

reset_password_html_template()

Returns the HTML template for password reset emails.

reset_password_text_template()

Returns the text template for password reset emails.

seed_system_templates()

Seeds the database with system email templates.

send_email(template_name, recipient, variables \\ %{}, opts \\ [])

Sends an email using a template.

test_email_html_template()

Returns the HTML template for test emails.

test_email_text_template()

Returns the text template for test emails.

track_usage(template)

Increments the usage count for a template and updates last_used_at.

update_email_html_template()

Returns the HTML template for email update confirmation emails.

update_email_text_template()

Returns the text template for email update confirmation emails.

update_template(template, attrs)

Updates an existing email template.

# Functions

# activate_template(template, user_id \\ nil)

Activates an email template by setting its status to "active".

## Examples

    iex> Templates.activate_template(template)
    {:ok, %Template{status: "active"}}

# archive_template(template, user_id \\ nil)

Archives an email template by setting its status to "archived".

## Examples

    iex> Templates.archive_template(template)
    {:ok, %Template{status: "archived"}}

# clone_template(template, new_name, attrs \\ %{})

Clones an existing template with a new name.

## Examples

    iex> Templates.clone_template(template, "new_welcome_email")
    {:ok, %Template{name: "new_welcome_email"}}

# count_templates(opts \\ %{})

Returns the count of templates matching the given filters.

# create_template(attrs \\ %{})

Creates a new email template.

## Examples

    iex> Templates.create_template(%{name: "welcome", subject: "Welcome!", ...})
    {:ok, %Template{}}

    iex> Templates.create_template(%{invalid: "data"})
    {:error, %Ecto.Changeset{}}

# delete_template(template)

Deletes an email template.

System templates (is_system: true) cannot be deleted.

## Examples

    iex> Templates.delete_template(template)
    {:ok, %Template{}}

    iex> Templates.delete_template(system_template)
    {:error, :system_template_protected}

# get_active_template_by_name(name)

Gets an active template by name.

Only returns templates with status "active".

## Examples

    iex> Templates.get_active_template_by_name("magic_link")
    %Template{}

# get_template(id)

Gets a template by ID.

Returns `nil` if the template does not exist.

## Examples

    iex> Templates.get_template(1)
    %Template{}

    iex> Templates.get_template(999)
    nil

# get_template!(id)

Gets a template by ID, raising an exception if not found.

## Examples

    iex> Templates.get_template!(1)
    %Template{}

    iex> Templates.get_template!(999)
    ** (Ecto.NoResultsError)

# get_template_by_name(name)

Gets a template by name.

Returns `nil` if the template does not exist.

## Examples

    iex> Templates.get_template_by_name("magic_link")
    %Template{}

    iex> Templates.get_template_by_name("nonexistent")
    nil

# get_template_stats()

Gets template statistics for dashboard display.

Returns a map with various statistics about templates.

## Examples

    iex> Templates.get_template_stats()
    %{
      total_templates: 10,
      active_templates: 8,
      draft_templates: 1,
      archived_templates: 1,
      system_templates: 4,
      most_used: %Template{},
      categories: %{"system" => 4, "transactional" => 6}
    }

# list_templates(opts \\ %{})

Lists templates with optional filtering and pagination.

## Parameters

- `opts` - Keyword list with filtering options:
  - `:category` - Filter by category ("system", "marketing", "transactional")
  - `:status` - Filter by status ("active", "draft", "archived")
  - `:search` - Search in name, display_name, or description
  - `:is_system` - Filter by system templates (true/false)
  - `:limit` - Limit number of results
  - `:offset` - Offset for pagination
  - `:order_by` - Order by field (:name, :usage_count, :last_used_at, :inserted_at)
  - `:order_direction` - Order direction (:asc, :desc)

## Examples

    # List all templates
    Templates.list_templates()

    # List active marketing templates
    Templates.list_templates(%{category: "marketing", status: "active"})

    # Search templates
    Templates.list_templates(%{search: "welcome"})

    # Paginated results
    Templates.list_templates(%{limit: 10, offset: 20})

# magic_link_html_template()

Returns the HTML template for magic link emails.

# magic_link_text_template()

Returns the text template for magic link emails.

# register_html_template()

Returns the HTML template for registration confirmation emails.

# register_text_template()

Returns the text template for registration confirmation emails.

# render_template(template, variables \\ %{})

Renders a template with the provided variables.

Returns a map with `:subject`, `:html_body`, and `:text_body` keys containing the rendered content with variables substituted.

This function performs validation to ensure all template variables are properly substituted:

- Checks for missing required variables
- Warns if any unreplaced `{{variable}}` placeholders remain
- Logs information about unused variables

## Examples

    iex> Templates.render_template(template, %{"user_name" => "John"})
    %{
      subject: "Welcome John!",
      html_body: "<h1>Welcome John!</h1>",
      text_body: "Welcome John!"
    }

## Validation

If required variables are missing or templates contain unreplaced variables, warnings will be logged but the function will still return the rendered content. This allows for graceful degradation in production.

# reset_password_html_template()

Returns the HTML template for password reset emails.

# reset_password_text_template()

Returns the text template for password reset emails.

# seed_system_templates()

Seeds the database with system email templates.

This function creates the default system templates for authentication and core functionality.

## Examples

    iex> Templates.seed_system_templates()
    {:ok, [%Template{}, ...]}

# send_email(template_name, recipient, variables \\ %{}, opts \\ [])

Sends an email using a template.

This is a convenience wrapper around `PhoenixKit.Mailer.send_from_template/4` that provides a cleaner API for sending templated emails.

## Parameters

- `template_name` - Name of the template (e.g., "welcome_email")
- `recipient` - Email address or {name, email} tuple
- `variables` - Map of template variables
- `opts` - Additional options (see `PhoenixKit.Mailer.send_from_template/4`)

## Examples

    # Send welcome email
    Templates.send_email("welcome_email", user.email, %{
      "user_name" => user.name,
      "activation_url" => activation_url
    })

    # Send with tracking
    Templates.send_email(
      "order_confirmation",
      customer.email,
      %{"order_number" => order.number},
      user_id: customer.id,
      metadata: %{order_id: order.id}
    )

# test_email_html_template()

Returns the HTML template for test emails.

# test_email_text_template()

Returns the text template for test emails.

# track_usage(template)

Increments the usage count for a template and updates last_used_at.

This should be called whenever a template is used to send an email.

## Examples

    iex> Templates.track_usage(template)
    {:ok, %Template{usage_count: 1}}

# update_email_html_template()

Returns the HTML template for email update confirmation emails.

# update_email_text_template()

Returns the text template for email update confirmation emails.

# update_template(template, attrs)

Updates an existing email template.

## Examples

    iex> Templates.update_template(template, %{subject: "New Subject"})
    {:ok, %Template{}}

    iex> Templates.update_template(template, %{invalid: "data"})
    {:error, %Ecto.Changeset{}}