thoughtbot / formulator

A form library for Phoenix

Formulator

Formulator is part of the thoughtbot Elixir family of projects.

This README follows master, which may not be the currently published version. Here are the docs for the latest published version of Formulator

Usage

Formulator is a library for Phoenix to give you:

• A label for your input, based on the attribute name
• An error label
• A class around the input if there is an error for the attribute. This allows you to easily style inputs that have errors.

You can replace the following:

  <%= label form, :name %>
  <%= text_input form, :name %>
  <%= error_tag form, :name %>

with this:

  <%= input form, :name %>

You also get the added benefit of having a class of has-error on the input when there is an error associated with the attribute.

By default, Formulator assumes that you want a standard text input but if you prefer, you can also specify the input type:

  <%= input form, :description, as: :textarea %>
  <%= input form, :count, as: :number %>
  <%= input form, :email_address, as: :email %>

See Formulator.input/3 for more examples.

Installation

Add formulator to your list of dependencies in mix.exs:

  def deps do
    [
      {:formulator, "~> 0.4.0"},
    ]
  end

  $ mix deps.get

Formulator needs to know what module to use for the translate_error/1 function. This is commonly defined by Phoenix either in web/views/error_helpers.ex or web/gettext.ex. Formulator can also be set to not validate by default; individual input options override the application config.

  # config/config.exs
  config :formulator,
    translate_error_module: YourAppName.ErrorHelpers,
    validate: false, # defaults to true
    validate_regex: false,  # defaults to true
    wrapper_class: "input-set"  # defaults to nil

You can import the package into all your views or individually as it makes sense:

  # web/web.ex
  def view do
    quote do
      ...
      import Formulator
      ...
    end
  end

Releases

To create a new release, use the bin/release script. You must provide the current version number and the new version number: bin/release 0.2 0.3.

If you need hex permissions, please ask someone in the thoughtbot #elixir slack channel.

This will create a new commit with the updated fields and publish to hex.

Please be sure to follow Semver when creating a new release

Contributing

See the CONTRIBUTING document. Thank you, contributors!

License

Formulator is Copyright (c) 2017 thoughtbot, inc. It is free software, and may be redistributed under the terms specified in the LICENSE file.

About

Formulator is maintained and funded by thoughtbot, inc. The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We love open source software, Elixir, and Phoenix. See our other Elixir projects, or hire our Elixir/Phoenix development team to design, develop, and grow your product.

formulator's Issues

Document the release process

1. How to release
2. How often we release

`field`?

Moving forward, to support other inputs such as radio_button or select, the logic for switching based on those in the input function is going to get pretty messy.

It seems like instead, we should break out multiple functions for those but the select and radio_button are already taken.

What do you all think about using field as the name for our inputs. We could go with field to replace input and you can still use field(form, :phone, as: :number) if you wanted to. We could then add select_field(form, :state, state_options) and others.

I'd love any thoughts you have @anellis @jsteiner

Create releases/tags when shipping a new version

Issue around translate_error/1

I tried to incorporate formulator into my app, but I got:

== Compilation error on file web/views/changeset_view.ex ==
** (CompileError) web/views/changeset_view.ex:5: function translate_error/1 imported from both Prodeal360.ErrorHelpers and Formulator, call is ambiguous
    (elixir) src/elixir_dispatch.erl:44: :elixir_dispatch.import_function/4
    (elixir) src/elixir_fn.erl:84: :elixir_fn.capture_import/4
    (stdlib) lists.erl:1353: :lists.mapfoldl/3
    (stdlib) lists.erl:1354: :lists.mapfoldl/3
    web/views/changeset_view.ex:4: (module)
    (stdlib) erl_eval.erl:670: :erl_eval.do_apply/6

I dropped the definition in my app, and got:

== Compilation error on file web/views/error_helpers.ex ==
** (CompileError) web/views/error_helpers.ex:13: undefined function translate_error/1
    (stdlib) lists.erl:1337: :lists.foreach/2
    (stdlib) erl_eval.erl:670: :erl_eval.do_apply/6
    (elixir) lib/kernel/parallel_compiler.ex:116: anonymous fn/4 in Kernel.ParallelCompiler.spawn_compilers/1

Why does this happen? Thank you!

bin/setup takes route of CI on local machine

So when running bin/setup on my local machine, I get:

maxhelmetag:formulator/ (master) $ bin/setup
Removing previous build artifacts
bin/setup: line 9: asdf: command not found

This is the path of, what I think is the CI setup, running on my local machine:

if [ -z "$CI" ]; then
  echo "Removing previous build artifacts"
  rm -rf deps _build
  asdf install
fi

I think if [ -z "$CI" ]; then should be if [ -n "$CI" ]; then because I want this path to run anytime $CI is defined (and in all other instances, I don't).

Or am I missing something?

Add a wrapping class around "input items"

More often than not I want a wrapping class around a label + input + error message.

This is useful for things like multi-column forms.

Maybe it's a plain div with a configurable class?

Upgrade Circle Infrastructure

Broken for @conn based forms

When you define a form with connection data (i.e. <%= form_for @conn, Formulator now fails as it expects a validations key in the source, but a connection does not have validations.

The failure happens on this line

Logo proposal

Hello! I am a graphic designer. I want to contribute to Formulator. Do you want me to design a logo for the formulator? If you have an idea, you can say me.

Add `bin/setup` and `bin/test_suite` scripts

Add select

I thought this wasn't really relevant but it's really frustrating now to have the styling/errors and such on the default select.

Configurable field order

Currently, it is only possible to output fields in order [label, input, error]. My project CSS required the label to be rendered after the input field i.e. [input, label, error].

I had to override the whole formulator module to overcome this:

  defp build_input_and_associated_tags(form, field, label_options, fun) do
    error = HtmlError.html_error(form, field)
    [
      fun.(error),
      build_label(form, field, label_options), # JA, swap label position
      error.html
    ]
    |> Enum.reject(&(is_nil(&1)))
  end

It would be great if order was configurable.

When compiling, Mix complains with warnings

==> formulator
Compiling 5 files (.ex)
warning: Phoenix.HTML.__using__/1 defined in application :phoenix_html is used by the current application but the current application does not depend on :phoenix_html. To fix this, you must do one of:

  1. If :phoenix_html is part of Erlang/Elixir, you must include it under :extra_applications inside "def application" in your mix.exs

  2. If :phoenix_html is a dependency, make sure it is listed under "def deps" in your mix.exs

  3. In case you don't want to add a requirement to :phoenix_html, you may optionally skip this warning by adding [xref: [exclude: [Phoenix.HTML]]] to your "def project" in mix.exs

Found at 3 locations:
  lib/formulator.ex:2: Formulator
  lib/formulator/html_builder.ex:2: Formulator.HtmlBuilder
  lib/formulator/input.ex:2: Formulator.Input
...
...
...
...

link to hexdocs