bulma_x

• BulmaX
  • Requirements
  • Installation
    • Example of integration with Rails & Importmap
  • Getting started
    • Using BulmaX components
    • Components may contains slots
    • Create your own components
  • Problems ?
  • Contributing
  • Licence
  • Authors

BulmaX

Generate Bulma CSS components using the power of Phlex.

BulmaX is a Phlex component library that provides a set of components styled with Bulma CSS. It allows you to create responsive and modern web applications using the Bulma framework while leveraging the power of Phlex for building reusable components.

Features

BulmaX is based on Phlex which is its only dependency.

BulmaX's ambition is to expose a DSL as simple as possible and the team will focus on keeping it that way.

We decided to make BulmaX's components deferred by default which makes sure component's markup is rendered in a consistent order.

Non-features

BulmaX aims only at generating HTML in regard to Bulma's components structure and classes but do not inject any css. All CSS handling is the developer's responsability.

BulmaX is a ruby only framework. There is no Rails integration and it's going to stay that way. We plan to add another interfacing layer BulmaX-rails later.

Requirements

• Ruby: 3.4+
• Phlex: 2.1+

BulmaX is still in a early stage, feel free to open issues or contributing.

Installation

BulmaX only generates the HTML structure of components, adding Bulma CSS to the project is at the developer's discretion.

In your Gemfile:

git_source(:gitlab) { |repo| "https://gitlab.com/#{repo}.git" }

gem 'bulma_x', gitlab: 'tftp/open/bulma_x'

Then run

bundle install

Example of integration with Rails & Importmap

Using importmap:

yarn add bulma
./bin/importmap pin bulma

then in your application.scss

@use "bulma";

Getting started

Using BulmaX components

The complete list of components can be found below

List of components

  base_component.rb
  base_input.rb
  block.rb
  box.rb
  breadcrumbs.rb
  button.rb
  card.rb
  checkbox.rb
  columns.rb
  component_dsl.rb
  dropdown.rb
  field.rb
  figure.rb
  file.rb
  footer.rb
  form.rb
  grid.rb
  help.rb
  hero.rb
  icon.rb
  image.rb
  input.rb
  level.rb
  link.rb
  media.rb
  message.rb
  modal.rb
  navbar.rb
  notification.rb
  pagination.rb
  panel.rb
  paragraph.rb
  progress.rb
  radio.rb
  section.rb
  select.rb
  shared
  slot.rb
  subtitle.rb
  table.rb
  tabs.rb
  tag.rb
  textarea.rb
  title.rb
  version.rb
  vertical_menu.rb

An example of section could be as follows:

<%= render BulmaX::Section.new(background_color: 'black') do %>
  <%= render BulmaX::Title.new(text_modifier: 'primary') do %>
    Section title
  <% end %>

  <%= render BulmaX::Paragraph.new do %>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  <% end %>
<% end %>

Components may contains slots

As Bulma is based on order of classes in the DOM, BulmaX knows where each content should go in advance, but not what they contain. For that, it defines slot that you can fill during the rendering of the component.

For example, the BulmaX::Card component has a slot for the header and another for the footer. You can use them like this:

<%= render BulmaX::Card.new do |card| %>
  <%= card.content(:header) do |header| %>
    <%= header.content(:title) do %>
      Card title
    <% end %>
  <% end %>

  <%= card.content(:body) do %>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  <% end %>

  <%= card.content(:footer) do |footer| %>
    <%= footer.content(:item) do %>
      <%= render BulmaX::Link.new(href: '#') do %>
        Learn more
      <% end %>
    <% end %>
  <% end %>
<% end %>

As of today, the best way to know a component's slots is to look at the source code of the component.

Create your own components

BulmaX allows you to create new components easily.

Either you can inherits the behaviour of existing components or create your own from scratch.

New component based on existing one

class TwoColumns < BulmaX::Columns
  slot :left
  slot :right

  def view_template
    super do
      content(:column) do
        slot(:left)
      end if slot?(:left)

      content(:column) do
        slot(:right)
      end if slot?(:right)
    end
  end
end

To find a complete reference to BulmaX DSL, until there is a proper documentation you can check for the files in the dsl folder.

New component from scratch

When no components fits your needs, you can create a new one from scratch.

BulmaX has a basic component that is the root of all components named BulmaX::BaseComponent. It generates a simple div and provides the whole power of BulmaX DSL to it.

class SpecificComponent < BulmaX::BaseComponent
  # => Define your slots
  # slot :slot_name, classes: ['class1', 'class2'], attributes: { turbo: 'something' }
  # slot :slot_sub_component, component: 'NameOfSubComponent'
  # slot :slot_other_component, component: OtherComponentClass

  # => Define your options
  # option :option # allows anything
  # option :option_enum, values: [:enum, :value], default: :value

  # => Define your validators
  # validate :option, -> { it.is_a?(String) }, message: 'Must be a string'

  def prepare
    # => Prefill your slots if needed
    #
    # content(:slot_name) { content }
    # content(:slot_other_component) do |other_component|
    #   other_component.content(:slot_name) { content }
    # end
  end

  def view_template
    super do
      slot(:slot_name) if slot?(:slot_name)
      slot(:slot_sub_component)
      slot(:slot_other_component) if slot?(:slot_other_component)
    end
  end

  def root_classes
    super + [
      @condition && 'custom-class' # => falsy values are removed from the classes
    ]
  end

  def root_attributes
    super.merge(
      data: {
        custom: 'value'
      }
    )
  end
end

Problems ?

Do not directly email any committers with questions or problems. A community is best served when discussions are held in public.

If you have a problem, please open an issue on the GitLab project.

Please note that BulmaX is still in early stages, its documentation is not complete yet and bugs may be present.

Contributing

See the contributing guidelines for more information on how to contribute to BulmaX.

Licence

See LICENCE for more information on the licence of BulmaX.

Authors

BulmaX is maintained by Team for the Planet and contributors.