Skip to content

Latest commit

 

History

History
199 lines (140 loc) · 4.87 KB

README.md

File metadata and controls

199 lines (140 loc) · 4.87 KB
Raw

PhoenixBootstrapForm

Format your application forms with Bootstrap 4 markup.

Hex.pm Build Status

Installation

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

def deps do
  [{:phoenix_bootstrap_form, "~> 0.1.0"}]
end

You may also alias this module in web.ex so it's shorter to type in templates.

alias PhoenixBootstrapForm, as: PBF

Usage

In order to change markup of form elements to bootstrap-style ones all you need is to prefix regular methods you aleady have with PhoenixBootstrapForm, or PBF if you created an alias. For example:

<%= form_for @changeset, "/", fn f -> %>
  <%= PBF.text_input f, :value %>
  <%= PBF.submit f %>
<% end %>

Becomes bootstrap-styled:

<form accept-charset="UTF-8" action="/" method="post">
  <div class="form-group row">
    <label class="col-form-label text-sm-right col-sm-2" for="record_value">
      Value
    </label>
    <div class="col-sm-10">
      <input class="form-control" id="record_value" name="record[value]" type="text">
    </div>
  </div>
  <div class="form-group row">
    <div class="col-sm-10 ml-auto">
      <button class="btn" type="submit">Submit</button>
    </div>
  </div>
</form>

This library generates horizonal form layout that collapses down on small screens.

You can always fall-back to default Phoenix.HTML.Form methods if bootstrapped ones are not good enough.

Currently this module supports following methods:

  • text_input
  • file_input
  • email_input
  • password_input
  • textarea
  • telephone_input
  • select
  • checkbox
  • checkboxes
  • radio_buttons
  • submit
  • static

For quick reference you can look at this template. You can mix phx.server inside demo folder to see this reference template rendered.

Labels

To set your own label you can do something like this:

<%= PBF.text_input f, :value, label: [text: "Custom"] %>

CSS Classes

To add your own css class to the input element / controls do this:

<%= PBF.text_input f, :value, input: [class: "custom"] %>

Help Text

You can add help text under the input. It could also be rendered template with links, tables, and whatever else.

<%= PBF.text_input f, :value, input: [help: "Help text"] %>

Prepending and Appending Inputs

<%= PBF.text_input f, :value, input: [prepend: "$", append: ".00"] %>

Radio Buttons

You don't need to do multiple calls to create list of radio buttons. One method will do them all:

<%= PBF.radio_buttons f, :value, ["red", "green"] %>

or with custom labels:

<%= PBF.radio_buttons f, :value, [{"R", "red"}, {"G", "green"}] %>

or rendered inline:

<%= PBF.radio_buttons f, :value, ["red", "green", "blue"], input: [inline: true] %>

Checkboxes

Very similar to multiple_select in functionality, you can render collection of checkboxes. Other options are the same as for radio_buttons

<%= PBF.checkboxes f, :value, ["red", "green", "blue"], selected: ["green"] %>

Submit Buttons

Besides simple PBF.submit f you can define custom label and content that goes next to the button. For example:

<% cancel = link "Cancel", to: "/", class: "btn btn-link" %>
<%= PBF.submit f, "Smash", class: "btn-primary", alternative: cancel %>

Static Elements

When you need to render a piece of content in the context of your form. For example:

<%= PBF.static f, "Current Avatar", avatar_image_tag %>

Form Errors

If changeset is invalid, form elements will have .is-invalid class added and .invalid-feedback container will be appended with an error message.

You can custom your error helper through:

config :phoenix_bootstrap_form, [
  translate_error: &MyApp.ErrorHelpers.translate_error/1
]

Custom Grid and Label Alignment

By default .col-sm-2 and .col-sm-10 used for label and control colums respectively. You can change that by passing label_col and control_col with form_for like this:

<% opts = [label_col: "col-sm-4", control_col: "col-sm-8", label_align: "text-sm-left"] %>
<%= form_for @changeset, "/", opts, fn f -> %>

If you need to change it application-wide just edit your config.exs and add:

config :phoenix_bootstrap_form,
  label_col_class: "col-sm-4",
  control_col_class: "col-sm-8",
  label_align_class: "text-sm-left",
  form_group_class: "form-group myclass"

Copyright 2017-2018, Oleg Khabarov