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

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. The reason is the following: 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.

For that to work, 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

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

Names for the default number operators (in the form of {internationalized_name, canonical_name}).

Supported operators are:

• "Equal to" - "equal_to"
• "Greater than" - "greater_than"
• "Less than" - "less_than"
• "Greater than or equal to" - "greater_than_or_equal_to"
• "Less than or equal to" - "less_than_or_equal_to"

Names for the default text operators (in the form of {internationalized_name, canonical_name}).

Supported operators are:

• "Contains" - "contains"
• "Equal to" - "equal_to"
• "Starts with" - "starts_with"
• "Ends with" - "ends_with"

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't been loaded.

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

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.

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.

It supports the following operators:

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

examples

Examples

TODO

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

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.

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.

It supports the following operators:

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

examples

Examples

TODO

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

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

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

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

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

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

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

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.

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.

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

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.

@spec forage_filter_form_for(
  Phoenix.HTML.FormData.t(),
  String.t(),
  Keyword.t(),
  (Phoenix.HTML.FormData.t() -> Phoenix.HTML.unsafe())
) :: Phoenix.HTML.safe()

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

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.

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.

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.

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.

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.

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

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.

Parameters:

• form (t:Phoenix.Html.Form.t/0)- the form
• field (atom)
• path (binary) - the URL from which to request the data

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

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) %>

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

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.

It supports the following operators:

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

examples

Examples

TODO

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

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

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.

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.

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

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

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

Print booleans (true and false) as font-awesome icones.

The CSS for FontAwesome 5 must be included in the webpage.

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

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

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

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

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.

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.

Parameters:

• form (t:Phoenix.Html.Form.t/0)- the form
• field (atom)
• path - the URL from which to request the data

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

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) %>

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

Parameters:

• form (t:Phoenix.Html.Form.t/0)- the form
• field (atom)
• path (binary) - the URL from which to request the data

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

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) %>

Filter for an enum of strings.

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

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

Parameters:

• form (t:Phoenix.Html.Form.t/0) - the form
• field (atom)

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"

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

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

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

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

A filter that works on text.

It supports the following operators:

• Contains
• Equal
• Starts with
• Ends with

examples

Examples

TODO

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

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.

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.

It supports the following operators:

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

examples

Examples

TODO

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

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.

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.

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.

Print booleans (true and false) as yes/no. Also prints nil as no.