ForageWeb.ForageView behaviour (forage v0.6.0)

Helper functions for views that feature forage filters, pagination buttons or sort links.

Link to this section Summary

Functions

Imports functions from ForageWeb.ForageView and defines a number of functions specialized for the given resource.

Displays a resource as HTML. The resource must implement support the ForageWeb.Display protocol.

See docs for Phoenix.HTML.Form.checkbox/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.checkbox/3. A smaller version of the input widget.

See docs for Phoenix.HTML.Form.color_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.color_input/3. A smaller version of the input widget.

A filter that works on dates.

See docs for Phoenix.HTML.Form.date_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.date_input/3. A smaller version of the input widget.

See docs for Phoenix.HTML.Form.date_select/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.date_select/3. A smaller version of the input widget.

A filter that works on datetime objects.

See docs for Phoenix.HTML.Form.email_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.email_input/3. A smaller version of the input widget.

Renders validation errors inside a form group.

See docs for Phoenix.HTML.Form.file_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.file_input/3. A smaller version of the input widget.

A form widget that generates an HTTP query to return data filtered according to the filters in the form.

Form group with support for internationalization.

Renders validation errors inside a horizontal form group.

Horizontal form group with support for internationalization by taking in the application's error_helpers module.

See docs for Phoenix.HTML.Form.input_type/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.input_type/3. A smaller version of the input widget.

Widget to select multiple external resources using the Javascript Select2 widget.

See docs for Phoenix.HTML.Form.number_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.number_input/3. A smaller version of the input widget.

A filter that works on numbers.

A link to the next page of filter results. Returns the empty string if the next page doesn't exist.

A link to the previous page of filter results. Returns the empty string if the previous page doesn't exist.

An already styled "pagination widget" containing a link to the next page and to the previous page of filter results.

See docs for Phoenix.HTML.Form.range_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.range_input/3. A smaller version of the input widget.

See docs for Phoenix.HTML.Form.search_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.search_input/3. A smaller version of the input widget.

Widget to select multiple external resources using the Javascript Select2 widget.

Widget to select an external resource using the Javascript Select2 widget.

A link to sort a list of database rows by a certain key.

Widget to select multiple external resources using the Javascript Select2 widget.

A filter that works on text.

See docs for Phoenix.HTML.Form.text_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.text_input/3. A smaller version of the input widget.

See docs for Phoenix.HTML.Form.textarea/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.textarea/3. A smaller version of the input widget.

A filter that works on time.

See docs for Phoenix.HTML.Form.time_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.time_input/3. A smaller version of the input widget.

See docs for Phoenix.HTML.Form.time_select/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.time_select/3. A smaller version of the input widget.

See docs for Phoenix.HTML.Form.url_input/3. A larger version of the input widget.

See docs for Phoenix.HTML.Form.url_input/3. A smaller version of the input widget.

Callbacks

Specialized version of ForageWeb.ForageView.forage_form_check/6. that's meant to use the application's error helpers module for internationalization.

Specialized version of ForageWeb.ForageView.forage_form_group/6 that's meant to use the application's error helpers module for internationalization.

Specialized version of ForageWeb.ForageView.forage_horizontal_form_group/6. that's meant to use the application's error helpers module for internationalization.

Specialized version of ForageWeb.ForageView.forage_inline_form_check/6. that's meant to use the application's error helpers module for internationalization.

Link to this section Types

Specs

form_data() :: Phoenix.HTML.FormData.t()
Link to this type

form_field()

Specs

form_field() :: atom()

Specs

options() :: Keyword.t()

Specs

safe_html() :: Phoenix.HTML.Safe.t()

Link to this section Functions

Link to this macro

__using__(options)

(macro)

Imports functions from ForageWeb.ForageView and defines a number of functions specialized for the given resource.

Expects the following options:

  • :routes_module (required) - ...
  • :error_helpers_module (required) - ...
  • :prefix (required) - ...
  • :prefixes (optional) - ...

This macro defines a number of functions specialized to the parameters above. Some of those functions are indicated as callbacks for the ForageWeb.ForageView behaviour (because ForageView will always define them) and some of them are not because the function name may depend on the prefixes.

Questionable design decisions

Some design decisions are a little bit questionable and deserve a longer explanation.

It might seem weird that we are defining so many functions so similar to the ones defined in Forage.ForageView itself. Forage uses Bootstrap4 templates and Forage widgets are based on the default Phoenix.HTML widgets. To deal with errors, Phoenix requires an ErrorHelpers module (defined by default by the phx.new generator), and Bootstrap requires the ability to inject the (translated) errors into the form group. This means that the ForageWeb.ForageView.forage_form_group/6 widget (and similar ones) need to be aware of the ErrorHelpers. This means that the user has to pass the ErrorHelpers module as an argument to all form groups, which would clutter the code for little benefit. By defining a ForageWeb.ForageView.forage_form_group/5 function which already incorporates the ErrorHelpers module, we can make for (slightly) cleaner code. By default, you should never have to use the

The way Bootstrap and Phoenix deal with internationalization requires an ErrorHelpers modules and the ability to inject the ForageWeb.ForageView.forage_form_group/6 function and should always use the ForageWeb.ForageView.forage_form_group/5 function instead (and similar ones)

TODO: complete this.

Examples

defmodule AppWeb.Backoffice.EmployeeView do
  use AppWeb, :view

  use ForageWeb.ForageView,
    routes_module: Routes,
    error_helpers_module: AppWeb.ErrorHelpers,
    prefix: :backoffice_employee,
    prefixes: [
      backoffice_department: MyApp.Backoffice.Department,
      backoffice_function: MyApp.Backoffice.Function,
      backoffice_benefit: MyApp.Backoffice.Benefit
    ]
end
Link to this function

forage_as_html(resource)

Displays a resource as HTML. The resource must implement support the ForageWeb.Display protocol.

This function works when the result is nil (it returns the empty string) and when the resource is an association that hasn«' been loaded.

Link to this function

forage_as_html_list(resources)

Link to this function

forage_as_text(resource)

Link to this function

forage_checkbox(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.checkbox/3.

Link to this function

forage_checkbox_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.checkbox/3. A larger version of the input widget.

Link to this function

forage_checkbox_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.checkbox/3. A smaller version of the input widget.

Link to this function

forage_color_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.color_input/3.

Link to this function

forage_color_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.color_input/3. A larger version of the input widget.

Link to this function

forage_color_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.color_input/3. A smaller version of the input widget.

Link to this function

forage_date_filter(form, name, opts \\ [])

A filter that works on dates.

It supports the following operators:

  • Equal to
  • Greater than
  • Less than
  • Greater than or equal to
  • Less than or equal to

Examples

TODO

Link to this function

forage_date_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.date_input/3.

Link to this function

forage_date_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.date_input/3. A larger version of the input widget.

Link to this function

forage_date_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.date_input/3. A smaller version of the input widget.

Link to this function

forage_date_select(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.date_select/3.

Link to this function

forage_date_select_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.date_select/3. A larger version of the input widget.

Link to this function

forage_date_select_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.date_select/3. A smaller version of the input widget.

Link to this function

forage_datetime_filter(form, name, opts \\ [])

A filter that works on datetime objects.

It supports the following operators:

  • Equal to
  • Greater than
  • Less than
  • Greater than or equal to
  • Less than or equal to

Examples

TODO

Link to this function

forage_datetime_local_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.datetime_local_input/3.

Link to this function

forage_datetime_local_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.datetime_local_input/3. A larger version of the input widget.

Link to this function

forage_datetime_local_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.datetime_local_input/3. A smaller version of the input widget.

Link to this function

forage_datetime_select(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.datetime_select/3.

Link to this function

forage_datetime_select_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.datetime_select/3. A larger version of the input widget.

Link to this function

forage_datetime_select_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.datetime_select/3. A smaller version of the input widget.

Link to this function

forage_email_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.email_input/3.

Link to this function

forage_email_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.email_input/3. A larger version of the input widget.

Link to this function

forage_email_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.email_input/3. A smaller version of the input widget.

Link to this function

forage_error_tag(form, field, error_helpers)

Renders validation errors inside a form group.

By default, you should not have to use this function. The functions defined when you use ForageWeb.ForageView, ... in your view module already take care of rendering errors the right way.

Link to this function

forage_file_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.file_input/3.

Link to this function

forage_file_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.file_input/3. A larger version of the input widget.

Link to this function

forage_file_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.file_input/3. A smaller version of the input widget.

Link to this function

forage_filter_form_for(conn, action, options \\ [], fun)

Specs

A form widget that generates an HTTP query to return data filtered according to the filters in the form.

Link to this function

forage_form_check(form, field, label, error_helpers, opts, input_fun)

TODO

By default, you should not have to use this function. You should use ForageWeb.ForageView, ... in your view module and use the forage_form_check/5 function defined by that macro instead.

Link to this function

forage_form_group(form, field, label, error_helpers, opts, input_fun)

Form group with support for internationalization.

You shouldn't need to use this function directly. You can use the ForageWeb.ForageView.forage_horizontal_form_group/5 callback defined in your view module, which impoements a specialized version of this function using your application's error_helpers module.

Link to this function

forage_horizontal_error_tag(form, field, error_helpers, class)

Renders validation errors inside a horizontal form group.

By default, you should not have to use this function. The functions defined when you use ForageWeb.ForageView, ... in your view module already take care of rendering errors the right way.

Link to this function

forage_horizontal_form_group(form, field, label, error_helpers, opts, input_fun)

Horizontal form group with support for internationalization by taking in the application's error_helpers module.

You shouldn't need to use this function directly. You can use the ForageWeb.ForageView.forage_form_group/5 callback defined in your view module, which impoements a specialized version of this function using your application's error_helpers module.

Link to this function

forage_inline_form_check(form, field, label, error_helpers, opts, input_fun)

TODO

By default, you should not have to use this function. You should use ForageWeb.ForageView, ... in your view module and use the forage_inline_form_check/5 function defined by that macro instead.

Link to this function

forage_input_type(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.input_type/3.

Link to this function

forage_input_type_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.input_type/3. A larger version of the input widget.

Link to this function

forage_input_type_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.input_type/3. A smaller version of the input widget.

Link to this function

forage_multiple_select(form, field, path, opts)

Widget to select multiple external resources using the Javascript Select2 widget.

Parameters:

Options:

  • :foreign_key (optional) - The name of the foreign key (as a string or an atom). If this is not supplied it will default to "#{field}_id"

The path must be a URL that returns JSON according to what the Javascript Select2 expects.

Example

<%= forage_form_group(f, :benefits,
      dgettext("yupr_app", "Benefits"), [],
      fn form, field, opts ->
        forage_multiple_select(form, field, Routes.backoffice_benefit_path(@conn, :select), opts)
      end) %>
Link to this function

forage_number_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.number_input/3.

Link to this function

forage_number_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.number_input/3. A larger version of the input widget.

Link to this function

forage_number_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.number_input/3. A smaller version of the input widget.

Link to this function

forage_numeric_filter(form, name, opts \\ [])

A filter that works on numbers.

It supports the following operators:

  • Equal to
  • Greater than
  • Less than
  • Greater than or equal to
  • Less than or equal to

Examples

TODO

Link to this function

forage_pagination_widget(conn, resource, mod, fun, options)

An already styled "pagination widget" containing a link to the next page and to the previous page of filter results.

If either the previous page or the next page doesn't exist, the respective link will be empty.

TODO: find a way of internationalizing the text in this widget.

Link to this function

forage_password_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.password_input/3.

Link to this function

forage_password_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.password_input/3. A larger version of the input widget.

Link to this function

forage_password_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.password_input/3. A smaller version of the input widget.

Link to this function

forage_radio_button(form, field, value, opts \\ [])

See docs for Phoenix.HTML.Form.radio_button/3.

Link to this function

forage_radio_button_large(form, field, value, opts \\ [])

See docs for Phoenix.HTML.Form.radio_button/3. A larger version of the input widget.

Link to this function

forage_radio_button_small(form, field, value, opts \\ [])

See docs for Phoenix.HTML.Form.radio_button/3. A smaller version of the input widget.

Link to this function

forage_range_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.range_input/3.

Link to this function

forage_range_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.range_input/3. A larger version of the input widget.

Link to this function

forage_range_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.range_input/3. A smaller version of the input widget.

Link to this function

forage_search_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.search_input/3.

Link to this function

forage_search_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.search_input/3. A larger version of the input widget.

Link to this function

forage_search_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.search_input/3. A smaller version of the input widget.

Link to this function

forage_select(form, field, path, opts \\ [])

Widget to select multiple external resources using the Javascript Select2 widget.

Parameters:

Options:

  • :foreign_key (optional) - The name of the foreign key (as a string or an atom). If this is not supplied it will default to field_id

You'll probably want to use it inside a forage_form_group.

Examples

<%= forage_form_group(f, :function,
        dgettext("your_app", "Function"),
        fn form, field, opts ->
          forage_select(form, field, Routes.backoffice_function_path(@conn, :select), opts)
        end) %>
Link to this function

forage_select_filter(form, field, path, opts \\ [])

Widget to select an external resource using the Javascript Select2 widget.

Parameters:

Options:

  • :foreign_key (optionsl) - The name of the foreign key (as a string or an atom). If this is not supplied it will default to field_id

This filter (like all forage filters) will add the appropriate parameters to your HTTP query so that the Forage functions in the backend can create a properly paginated and filtered query.

Example

Filter a list of employees

<%= forage_horizontal_form_group(f, :department,
      dgettext("mandarin.backoffice", "Department"), [],
      fn form, field, opts ->
        forage_select_filter(form, field, Routes.backoffice_department_path(@conn, :select), opts)
      end) %>
Link to this function

forage_sort_link(conn, mod, fun, field, content, options \\ [])

A link to sort a list of database rows by a certain key.

Link to this function

forage_static_select(form, field, opts \\ [])

Widget to select multiple external resources using the Javascript Select2 widget.

Parameters:

Options:

  • :foreign_key (optional) - The name of the foreign key (as a string or an atom). If this is not supplied it will default to "#{field}_id"
Link to this function

forage_telephone_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.telephone_input/3.

Link to this function

forage_telephone_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.telephone_input/3. A larger version of the input widget.

Link to this function

forage_telephone_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.telephone_input/3. A smaller version of the input widget.

Link to this function

forage_text_filter(form, name, opts \\ [])

A filter that works on text.

It supports the following operators:

  • Contains
  • Equal
  • Starts with
  • Ends with

Examples

TODO

Link to this function

forage_text_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.text_input/3.

Link to this function

forage_text_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.text_input/3. A larger version of the input widget.

Link to this function

forage_text_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.text_input/3. A smaller version of the input widget.

Link to this function

forage_textarea(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.textarea/3.

Link to this function

forage_textarea_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.textarea/3. A larger version of the input widget.

Link to this function

forage_textarea_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.textarea/3. A smaller version of the input widget.

Link to this function

forage_time_filter(form, name, opts \\ [])

A filter that works on time.

It supports the following operators:

  • Equal to
  • Greater than
  • Less than
  • Greater than or equal to
  • Less than or equal to

Examples

TODO

Link to this function

forage_time_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.time_input/3.

Link to this function

forage_time_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.time_input/3. A larger version of the input widget.

Link to this function

forage_time_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.time_input/3. A smaller version of the input widget.

Link to this function

forage_time_select(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.time_select/3.

Link to this function

forage_time_select_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.time_select/3. A larger version of the input widget.

Link to this function

forage_time_select_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.time_select/3. A smaller version of the input widget.

Link to this function

forage_url_input(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.url_input/3.

Link to this function

forage_url_input_large(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.url_input/3. A larger version of the input widget.

Link to this function

forage_url_input_small(form, field, opts \\ [])

See docs for Phoenix.HTML.Form.url_input/3. A smaller version of the input widget.

Link to this section Callbacks

Link to this callback

forage_form_check(form_data, form_field, arg3, options, function)

Specs

forage_form_check(
  form_data(),
  form_field(),
  String.t(),
  options(),
  (form_data(), form_field(), options() -> safe_html())
) :: safe_html()

Specialized version of ForageWeb.ForageView.forage_form_check/6. that's meant to use the application's error helpers module for internationalization.

This callback is automatically implemented by use ForageWeb.ForageView, ...

Examples

TODO

Link to this callback

forage_form_group(form_data, form_field, arg3, options, function)

Specs

forage_form_group(
  form_data(),
  form_field(),
  String.t(),
  options(),
  (form_data(), form_field(), options() -> safe_html())
) :: safe_html()

Specialized version of ForageWeb.ForageView.forage_form_group/6 that's meant to use the application's error helpers module for internationalization.

This callback is automatically implemented by use ForageWeb.ForageView, ...

Examples

TODO

Link to this callback

forage_horizontal_form_group(form_data, form_field, arg3, options, function)

Specs

forage_horizontal_form_group(
  form_data(),
  form_field(),
  String.t(),
  options(),
  (form_data(), form_field(), options() -> safe_html())
) :: safe_html()

Specialized version of ForageWeb.ForageView.forage_horizontal_form_group/6. that's meant to use the application's error helpers module for internationalization.

This callback is automatically implemented by use ForageWeb.ForageView, ...

Examples

TODO

Link to this callback

forage_inline_form_check(form_data, form_field, arg3, options, function)

Specs

forage_inline_form_check(
  form_data(),
  form_field(),
  String.t(),
  options(),
  (form_data(), form_field(), options() -> safe_html())
) :: safe_html()

Specialized version of ForageWeb.ForageView.forage_inline_form_check/6. that's meant to use the application's error helpers module for internationalization.

This callback is automatically implemented by use ForageWeb.ForageView, ...

Examples

TODO