#
View Source Spike (spike v0.4.0-rc.0)

This module contains top-level functions useful to validate, manipulate and inspect Spike forms.

To learn about how to create Spike forms, see `Spike.Form`.

# Link to this section Summary

## Functions

append(form, field, params)

Updates `embeds_many` association on the top-level Spike form, appending the new item at the end of the existing list.

append(form, ref, field, params)

Updates `embeds_many` association on given Spike form, appending the new item at the end of the existing list.

delete(form, ref)

Deletes a form from a Spike form by it's `ref`. Useful to remove items from `embeds_many` or `embeds_one`.

dirty_fields(form)

Given a Spike form, returns a map of fields that have been updated since the form form was created, or since the last time `Spike.make_pristine/1` was called.

errors(form)

Given a Spike form, returns a map of errors, where fields are refs of all forms that build the form, and each field is a list of errors.

has_errors?(form, ref, field)

Returns `true` if given form, identified by `ref` has error on given `field`.

has_errors?(form, ref, field, message)

Returns `true` if given form, identified by `ref` has specified error message on given `field`.

human_readable_errors(form)

Given a Spike form, returns a map of errors, where fields are Strings representing where in nested set of forms errors happened and values are errors.

make_dirty(form)

Given Spike form, marks all of it's fields as dirty, recursively.

make_pristine(form)

Given a dirty Spike form, makes it pristine, recursively.

set_private(form, field, value)

Allows you to update fields in a top-level Spike form that were marked as private.

set_private(form, ref, field, value)

Allows you to update fields in a Spike form that were marked as private.

update(form, params)

Updates a top level Spike form with given params. Marks updated fields as dirty.

update(form, ref, params)

Updates a Spike form, by finding a nested form by it's `ref` field, with given params. Marks updated fields as dirty.

valid?(form)

Returns true if given form has no errors.

# Link to this section Functions

Link to this function

# append(form, field, params)

View Source

Updates `embeds_many` association on the top-level Spike form, appending the new item at the end of the existing list.

    iex> form = Test.ComplexForm.new(%{company: %{name: "ACME Corp."}, partners: []})
    iex> form.partners
    []
    iex> form = Spike.append(form, :partners, %{name: "Hubert"})
    iex> form.partners |> Enum.map(& &1.name)
    ["Hubert"]
    iex> form = Spike.append(form, :partners, %{name: "Wojciech"})
    iex> form.partners |> Enum.map(& &1.name)
    ["Hubert", "Wojciech"]

Link to this function

# append(form, ref, field, params)

View Source

Updates `embeds_many` association on given Spike form, appending the new item at the end of the existing list.

    iex> form = Test.ComplexForm.new(%{company: %{name: "ACME Corp."}, partners: []})
    iex> form.partners
    []
    iex> form = Spike.append(form, form.ref, :partners, %{name: "Hubert"})
    iex> form.partners |> Enum.map(& &1.name)
    ["Hubert"]
    iex> form = Spike.append(form, form.ref, :partners, %{name: "Wojciech"})
    iex> form.partners |> Enum.map(& &1.name)
    ["Hubert", "Wojciech"]

Link to this function

# delete(form, ref)

View Source

Deletes a form from a Spike form by it's `ref`. Useful to remove items from `embeds_many` or `embeds_one`.

    iex> form = Test.ComplexForm.new(%{company: %{name: "ACME Corp."}, partners: [%{name: "John"}]})
    iex> form = Spike.delete(form, form.company.ref)
    iex> form = Spike.delete(form, form.partners |> hd() |> Map.get(:ref))
    iex> form.company
    nil
    iex> form.partners
    []

Link to this function

# dirty_fields(form)

View Source

Given a Spike form, returns a map of fields that have been updated since the form form was created, or since the last time `Spike.make_pristine/1` was called.

    iex> form = Test.SimpleForm.new(%{first_name: "Spike", last_name: "Spiegel"})
    iex> Spike.dirty_fields(form)
    %{}
    iex> form = Spike.update(form, form.ref, %{first_name: "Jet", last_name: "Black"})
    iex> Spike.dirty_fields(form)
    %{form.ref => [:first_name, :last_name]}
    iex> form = Spike.make_pristine(form)
    iex>  Spike.dirty_fields(form)
    %{}

Link to this function

# errors(form)

View Source

Given a Spike form, returns a map of errors, where fields are refs of all forms that build the form, and each field is a list of errors.

Returns empty map in case the form is valid.

    iex> form = Test.SimpleForm.new(%{})
    iex> Spike.errors(form)[form.ref]
    %{accepts_conditions: [acceptance: "must be accepted"], first_name: [presence: "must be present"]}
    iex> form = Spike.update(form, form.ref, %{first_name: "Spike", last_name: "Spiegel", accepts_conditions: "1"})
    iex> Spike.errors(form)
    %{}
    iex> form = Test.ComplexForm.new(%{company: %{}, partners: []})
    iex> Spike.errors(form)
    %{form.company.ref => %{name: [presence: "must be present"]}, form.ref => %{accepts_conditions: [acceptance: "must be accepted"]}}

Link to this function

# has_errors?(form, ref, field)

View Source

Returns `true` if given form, identified by `ref` has error on given `field`.

    iex> form = Test.SimpleForm.new(%{first_name: "Jet", accepts_conditions: "0"})
    iex> Spike.has_errors?(form, form.ref, :first_name)
    false
    iex> Spike.has_errors?(form, form.ref, :accepts_conditions)
    true

Link to this function

# has_errors?(form, ref, field, message)

View Source

Returns `true` if given form, identified by `ref` has specified error message on given `field`.

    iex> form = Test.SimpleForm.new(%{first_name: "Jet", accepts_conditions: "0"})
    iex> Spike.has_errors?(form, form.ref, :accepts_conditions, "must be accepted")
    true
    iex> Spike.has_errors?(form, form.ref, :accepts_conditions, "is invalid")
    false

Link to this function

# human_readable_errors(form)

View Source

Given a Spike form, returns a map of errors, where fields are Strings representing where in nested set of forms errors happened and values are errors.

Returns empty map in case the form is valid.

    iex> form = Test.ComplexForm.new(%{company: %{}, partners: [%{}]})
    iex> Spike.human_readable_errors(form)
    %{"accepts_conditions" => ["must be accepted"], "company.name" => ["must be present"]}

Link to this function

# make_dirty(form)

View Source

Given Spike form, marks all of it's fields as dirty, recursively.

    iex> form = Test.ComplexForm.new(%{company: %{}, partners: [%{}]})
    iex> form = Spike.make_dirty(form)
    iex> Spike.dirty_fields(form)
    %{
       form.ref => [:accepts_conditions, :company, :partners],
       form.company.ref => [:country, :name],
       hd(form.partners).ref => [:name]
     }

Link to this function

# make_pristine(form)

View Source

Given a dirty Spike form, makes it pristine, recursively.

    iex> form = Test.ComplexForm.new(%{company: %{}, partners: [%{}]})
    iex> form = Spike.make_dirty(form)
    iex> form = Spike.make_pristine(form)
    iex> Spike.dirty_fields(form)
    %{}

Link to this function

# set_private(form, field, value)

View Source

Allows you to update fields in a top-level Spike form that were marked as private.

    iex> form = Test.PrivateForm.new(%{private_field: "foo"}, allow_private_fields: true)
    iex> form = Spike.update(form, %{private_field: "bar"})
    iex> form.private_field
    "foo"
    iex> form = Spike.set_private(form, :private_field, "bar")
    iex> form.private_field
    "bar"

Link to this function

# set_private(form, ref, field, value)

View Source

Allows you to update fields in a Spike form that were marked as private.

    iex> form = Test.PrivateForm.new(%{private_field: "foo"}, allow_private_fields: true)
    iex> form = Spike.update(form, form.ref, %{private_field: "bar"})
    iex> form.private_field
    "foo"
    iex> form = Spike.set_private(form, form.ref, :private_field, "bar")
    iex> form.private_field
    "bar"

Link to this function

# update(form, params)

View Source

Updates a top level Spike form with given params. Marks updated fields as dirty.

    iex> form = Test.SimpleForm.new(%{})
    iex> form = Spike.update(form, %{first_name: "Spike", last_name: "Spiegel", accepts_conditions: "1"})
    iex> Spike.errors(form)
    %{}

Link to this function

# update(form, ref, params)

View Source

Updates a Spike form, by finding a nested form by it's `ref` field, with given params. Marks updated fields as dirty.

    iex> form = Test.ComplexForm.new(%{company: %{name: "ACME Corp."}, partners: [%{}]})
    iex> form.company.name
    "ACME Corp."
    iex> form = Spike.update(form, form.company.ref, %{name: "Amazon"})
    iex> form.company.name
    "Amazon"
    iex> Spike.dirty_fields(form)
    %{form.company.ref => [:name], form.ref => [:company]}

Link to this function

# valid?(form)

View Source

Returns true if given form has no errors.

    iex> form = Test.SimpleForm.new(%{})
    iex> Spike.valid?(form)
    false
    iex> form = Spike.update(form, form.ref, %{first_name: "Spike", last_name: "Spiegel", accepts_conditions: "1"})
    iex> Spike.valid?(form)
    true