calcinator v1.5.0 Calcinator.ChangesetView

Attempts to show Ecto changeset errors in JSON:API compliant fashion.

Summary

Functions

Returns a map of attributes to be serialized

The id to be used in the resource object

return links about this resource

Adds meta data to the individual resource being serialized

A special callback that can be used to preload related data

A callback that should return a map of relationship structs

The type to be used in the resource object

Functions

attributes(data, conn)

Returns a map of attributes to be serialized.

The default implementation returns all the data’s fields except id, type, and __struct__.

A typical non-DSL implementation looks like:

defmodule UserSerializer do
  def attributes(user, conn) do
    Map.take(user, [:email, :name])
  end
end

UserSerializer.attributes(user, conn)
# %{email: "...", name: "..."}

If using the JaSerializer.DSL the default implementation is based on the JaSerializer.DSL.attributes/1 macro. Eg:

defmodule UserSerializer do
  attributes [:email, :name, :is_admin]
end

UserSerializer.attributes(user, conn)
# %{email: "...", name: "...", is_admin: "..."}

Overriding this callback can be a good way to customize attribute behaviour based on the context (conn) with super.

defmodule UserSerializer do
  attributes [:email, :name, :is_admin]

  def attributes(user, %{assigns: %{current_user: %{is_admin: true}}}) do
    super(user, conn)
  end

  def attributes(user, conn) do
    super(user, conn)
    |> Map.take([:email, :name])
  end
end

UserSerializer.attributes(user, conn)
# %{email: "...", name: "..."}

Callback implementation for JaSerializer.Serializer.attributes/2.

format(data)
format(data, conn)
format(data, conn, opts)
id(data, c)

The id to be used in the resource object.

http://jsonapi.org/format/#document-resource-objects

Default implementation attempts to get the :id field from the struct.

To override simply define the id function:

def id(struct, _conn), do: struct.slug

Callback implementation for JaSerializer.Serializer.id/2.

links(data, conn)

return links about this resource

Callback implementation for JaSerializer.Serializer.links/2.

meta(struct, conn)

Adds meta data to the individual resource being serialized.

NOTE: To add meta data to the top level object pass the meta: option into YourSerializer.format/3.

A nil return value results in no meta key being added to the serializer. A map return value will be formated with JaSerializer.Formatter.format/1.

The default implementation returns nil.

Callback implementation for JaSerializer.Serializer.meta/2.

preload(data, conn, include_opts)

A special callback that can be used to preload related data.

Unlike the other callbacks, this callback is ONLY executed on the top level data being serialized. Also unlike any other callback when serializing a list of data (eg: from an index action) it recieves the entire list, not each individual post. When serializing a single record (eg, show, create, update) a single record is received.

The primary use case of the callback is to preload all the relationships you need. For example:

@default_includes [:category, comments: :author]
def preload(record_or_records, _conn, []) do
  MyApp.Repo.preload(record_or_records, @default_includes)
end
def preload(record_or_records, _conn, include_opts) do
  MyApp.Repo.preload(record_or_records, include_opts)
end

Callback implementation for JaSerializer.Serializer.preload/3.

relationships(struct, conn)

A callback that should return a map of relationship structs.

Example:

def relationships(article, _conn) do
  %{
    comments: %HasMany{
      serializer:  MyApp.CommentView,
      include:     true,
      data:        article.comments,
    },
    author: %HasOne{
      serializer:  MyApp.AuthorView,
      include:     true,
      data:        article.author,
    }
  }
end

See JaSerializer.Relationship.HasMany for details on fields.

When using the DSL this is defined for you based on the has_many and has_one macros.

Callback implementation for JaSerializer.Serializer.relationships/2.

render(binary, data)
type()
type(data, conn)

The type to be used in the resource object.

http://jsonapi.org/format/#document-resource-objects

Default implementation attempts to infer the type from the serializer module’s name. For example:

MyApp.UserView becomes "user"
MyApp.V1.Serializers.Post becomes "post"
MyApp.V1.CommentsSerializer becomes "comments"

To override simply define the type function:

def type(_post,_conn), do: "category"

Callback implementation for JaSerializer.Serializer.type/2.