PhxComponentHelpers (phx_component_helpers v1.0.0) View Source

PhxComponentHelpers are helper functions meant to be used within Phoenix LiveView live_components to make your components more configurable and extensible from your templates.

It provides following features:

  • set HTML or data attributes from component assigns
  • set phx-* attributes from component assigns
  • set attributes with any custom prefix such as @click or x-bind: from alpinejs
  • encode attributes as JSON from an Elixir structure assign
  • validate mandatory attributes
  • set and extend CSS classes from component assigns

Link to this section Summary

Functions

Set assigns with class attributes.

Forward and filter assigns to sub components. By default it doesn't forward anything unless you provide it with any combination of the options described below.

If assigns include form and field entries, this function will let you know if the given field is in error or not. Returns true or false.

Extends assigns with heex_* attributes that can be interpolated within your component markup.

Extends assigns with form related attributes.

Just a convenient method built on top of set_prefixed_attributes/3 for phx attributes. It will automatically detect any attribute prefixed by phx_ from input assigns. By default, the :into option of set_prefixed_attributes/3 is :phx_attributes

Extends assigns with prefixed attributes that can be interpolated within your component markup. It will automatically detect any attribute prefixed by any of the given prefixes from input assigns.

Validates that attributes are present in assigns. Raises an ArgumentError if any attribute is missing.

Link to this section Functions

Link to this function

extend_class(assigns, default_classes, opts \\ [])

View Source

Set assigns with class attributes.

The class attribute will take provided default_classes as a default value and will be extended, on a class-by-class basis, by your assigns.

This function will identify default classes to be replaced by assigns on a prefix basis:

  • "bg-gray-200" will be overwritten by "bg-blue-500" because they share the same "bg-" prefix
  • "hover:bg-gray-200" will be overwritten by "hover:bg-blue-500" because they share the same "hover:bg-" prefix
  • "m-1" would not be overwritten by "mt-1" because they don't share the same prefix ("m-" vs "mt-")

Parameters

  • assigns - your component assigns
  • default_classes - the default classes that will be overridden by your assigns. This parameter can be a binary or a single parameter function that receives all assigns and returns a binary

Options

  • :attribute - read & write css classes from & into this key

Example

assigns
|> extend_class("bg-blue-500 mt-8")
|> extend_class("py-4 px-2 divide-y-8 divide-gray-200", attribute: :wrapper_class)
|> extend_class(fn assigns ->
    default = "p-2 m-4 text-sm "
    if assigns[:active], do: default <> "bg-indigo-500", else: default <> "bg-gray-200"
   end)

assigns now contains @heex_class and @heex_wrapper_class.

If your input assigns were %{class: "mt-2", wrapper_class: "divide-none"} then:

  • @heex_class would contain "bg-blue-500 mt-2"
  • @heex_wrapper_class would contain "py-4 px-2 divide-none"
Link to this function

forward_assigns(assigns, opts)

View Source

Forward and filter assigns to sub components. By default it doesn't forward anything unless you provide it with any combination of the options described below.

Parameters

  • assigns - your component assigns

Options

  • prefix - will only forward assigns prefixed by the given prefix. Forwarded assign key will no longer have the prefix
  • take- is a list of key (without prefix) that will be picked from assigns to be forwarded
  • merge- takes a map that will be merged as-is to the output assigns

If both options are given at the same time, the resulting assigns will be the union of the two.

Example

Following will forward an assign map containing %{button_id: 42, button_label: "label", phx_click: "save"} as %{id: 42, label: "label", phx_click: "save"}

forward_assigns(assigns, prefix: :button, take: [:phx_click])

If assigns include form and field entries, this function will let you know if the given field is in error or not. Returns true or false.

Parameters

  • assigns - your component assigns, which should have form and field keys.
Link to this function

set_attributes(assigns, attributes, opts \\ [])

View Source

Extends assigns with heex_* attributes that can be interpolated within your component markup.

Parameters

  • assigns - your component assigns
  • attributes - a list of attributes (atoms) that will be fetched from assigns. Attributes can either be single atoms or tuples in the form {:atom, default} to provide default values.

Options

  • :required - raises if required attributes are absent from assigns
  • :json - when true, will JSON encode the assign value
  • :data - when true, HTML attributes are prefixed with data-
  • :into - merges all assigns in a single one that can be interpolated at once

Example

assigns
|> set_attributes(
    [:id, :name, label: "default label"],
    required: [:id, :name],
    into: :attributes
  )
|> set_attributes([:value], json: true)

assigns now contains :

  • @heex_id, @heex_name, @heex_label and @heex_value.
  • @heex_attributes which holds the values if :id, :name and :label.
Link to this function

set_form_attributes(assigns)

View Source

Extends assigns with form related attributes.

If assigns contain :form and :field keys then it will set :id, :name, :for, :value, and :errors from received Phoenix.HTML.Form.

Parameters

  • assigns - your component assigns

Example

assigns
|> set_form_attributes()
Link to this function

set_phx_attributes(assigns, opts \\ [])

View Source

Just a convenient method built on top of set_prefixed_attributes/3 for phx attributes. It will automatically detect any attribute prefixed by phx_ from input assigns. By default, the :into option of set_prefixed_attributes/3 is :phx_attributes

Example

assigns
|> set_phx_attributes(required: [:"phx-submit"], init: [:"phx-change"])

assigns now contains @heex_phx_change, @heex_phx_submit and @heex_phx_attributes.

Link to this function

set_prefixed_attributes(assigns, prefixes, opts \\ [])

View Source

Extends assigns with prefixed attributes that can be interpolated within your component markup. It will automatically detect any attribute prefixed by any of the given prefixes from input assigns.

Can be used for intance to easily map alpinejs html attributes.

Parameters

  • assigns - your component assigns
  • prefixes - a list of prefix as binaries

Options

  • :init - a list of attributes that will be initialized if absent from assigns
  • :required - raises if required attributes are absent from assigns
  • :into - merges all assigns in a single one that can be interpolated at once

Example

assigns
|> set_prefixed_attributes(
    ["@click", "x-bind:"],
    required: ["x-bind:class"],
    into: :alpine_attributes
  )

assigns now contains @heex_click, @heex_x-bind:class and @heex_alpine_attributes.

Link to this function

validate_required_attributes(assigns, required)

View Source

Validates that attributes are present in assigns. Raises an ArgumentError if any attribute is missing.

Example

assigns
|> validate_required_attributes([:id, :label])