View Source BitstylesPhoenix (bitstyles_phoenix v2.4.0)

Documentation for BitstylesPhoenix.

Setup & Getting started

Check out the main README.

Usage

Use by either use BitstylesPhoenix or importing the components and helpers individually.

  use BitstylesPhoenix

  # or

  import BitstylesPhoenix.Helper.Button

Then use the components and helpers in your *.heex templates:

<.ui_badge>A nice badge</.ui_badge>
# => <span class="a-badge u-h6 u-font-medium a-badge--text">A nice badge</span>
ui_button("Save", type: "submit")
# => <button class="a-button" type="submit">Save</button>

Some components require additional JS to work as intended. Either you implement the JS yourself and use the ui components directly, or the Live or Alpine3 ones.

  use BitstylesPhoenix.Live    # import all `BitstylesPhoenix.Live` components
  use BitstylesPhoenix.Alpine3 # import all `BitstylesPhoenix.Alpine3` components

For the Alpine versions to work, alpine.js should be present on the page. The JS commands version will only work within connected LiveViews.

Checkout the components and helpers for examples and showcases.

Configuration

The library can be configured through mix configuration.

Bitstyles version

BitstylesPhoenix will generate classes 5.0.1 of bitstyles. You can set older versions with a configuration:

config :bitstyles_phoenix,
  bitstyles_version: "1.5.0"

Release candidate versions are currently not supported.

Translating error messages

Generated phoenix apps usually come with a helper for translating error messages using gettext. This helper can be used to translate error messages rendered with bitstyles_phoenix.

In order to do so you can configure the generated helper or write your own with the MFA configuration.

config :bitstyles_phoenix,
  translate_errors: {ExampleWeb.ErrorHelpers, :translate_error, []}

Icon file

In order for the bitstyles icons to properly render they can either be rendered inline in the document or served as an SVG file and configured with the phoenix static_path helpers. The configured icon file path can be either a string or a MF/MFA.

Example:

config :bitstyles_phoenix,
  icon_file: {MyappWeb.Endpoint, :static_path, ["/assets/images/icons.svg"]}

In order for the above example to work, one has to serve the bitstyles icon file under that static path. This can be done either via a webpack file-loader, postcss or simply by copying the files into the priv/static dir of your phoenix app.

Check out the demo project folder in the sources for an example configuration.

Trim e2e- classnames

Sometimes you need to set classes for testing, that are not needed or used in production. By default, all classes generated by bitstyles_phoenix are appended using BitstylesPhoenix.Helper.Classnames.classnames/1. This helper trims classes prefixed with e2e by default. This behaviour can be configured:

Disable trimming

config :bitstyles_phoenix,
  trim_e2e_classes: [enabled: false]

Use another prefix for trimming

config :bitstyles_phoenix,
  trim_e2e_classes: [enabled: true, prefix: "test-"]

Defining a required label

You can control how required labels are rendered. By default you will get this appended to your labels if the input is required:

  <span aria-hidden="true" class="u-fg-warning u-margin-xss-left">*</span>

You can override it by specifying your own component to render the required labels. The component will get the form and the field as assigns, as well as any optional parameters you pass in the MFA as @opts.

config :bitstyles_phoenix,
  required_label: {MyComponent, :my_required_label, []}

defmodule MyComponent do
  use Phoenix.Component

  def my_required_label(assigns) do
    ~H"<span>(required)</span>"
  end
end