PhxComponentHelpers (phx_component_helpers v0.4.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 attributes from component assigns
  • set data attributes from component assigns
  • set phx_* attributes from component assigns
  • 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

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

Extends assigns with html_* data-attributes that can be interpolated within your component markup.

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.

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, class_attribute_name \\ :class, default_classes)

View Source

Extends 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.

Parameters

  • assigns - your component assigns
  • class_attribute_name - the class attribute you want to define, :class by default
  • default_classes - the css classed that will put by default

Example

assigns
|> extend_class("bg-blue-500 mt-8")
|> extend_class(:wrapper_class, "py-4 px-2 divide-y-8 divide-gray-200")

assigns now contains @html_class and @html_wrapper_class.

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

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

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

View Source

Extends assigns with html_* 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

Options

  • :required - raises if required attributes are absent from assigns
  • :json - when true, will JSON encode the assign value

Example

assigns
|> set_component_attributes([:id, :name, :label], required: [:id, :name])
|> set_component_attributes([:value], json: true)

assigns now contains @html_id, @html_name, @html_label and @html_value.

Link to this function

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

View Source

Extends assigns with html_* data-attributes that can be interpolated within your component markup.

Behaves exactly like set_component_attributes/3 excepted the output @html_attr assigns contain data-attributes markup.

Example

assigns
|> set_data_attributes([:key, :text], required: [:key])
|> set_data_attributes([:document], json: true)

assigns now contains @html_key, @html_text and @html_document.

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.

Example

assigns
|> set_phx_attributes(required: [:phx_submit], init: [:phx_change])

assigns now contains @html_phx_change and @html_phx_submit.

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

Example

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

assigns now contains @html_click and @html_x-bind:class.

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