Headmin

A complete library of commonly used components to build an admin interface in your Ruby on Rails project.

Installation

To install Headmin into your current Rails application use bundler:

$ bundle add 'headmin'

Usage

All assets are available via the asset pipeline and can be called as if it was available in your application.

Stylesheets

Import all SCSS stylesheets like this:

@import "headmin";

• Asset Pipeline: Sprockets & sassc-rails will pickup the correct file automatically
• Node: Use a build tool like ESBuild, Webpack or Rollup to find the right file via Headmins' package.json

Javascript

Import the Headmin class into your script and initialize it. This will append its Stimulus controllers to the window.Stimulus object if it's available.

import {Headmin} from 'headmin'
Headmin.start()

Node or not to Node

With the introduction of importmap in Rails 7, you're no longer required to use node for your frontend assets. By default all assets are available via the asset pipeline and added to the default importmap.rb.

If you want to use node because you're tied to a specific build tool, you can add Headmin as a dependency to your package.json.

$ yarn add headmin

Helpers

Add the Headmin helpers to your helper file. We recommend using namespaces.

# In a, preferably namespaced, view helper
module AdminHelper
  include Headmin::AdminHelper
end

Development

For development purposes it's helpful to have both the test project and Headmin located in the same directory.

In Gemfile

gem "headmin", path: "../headmin"

In package.json

{
  "dependencies": {
    "headmin": "link:../headmin"
  }
}

To see frontend changes update live in development run

# Watches changes and builds them on-the-fly
yarn dev

Javascript

When adding new dependencies, make sure you add them to the package.json file as well as the importmap.rb file.

Testing

Run tests with

rake test

If you want to test a specific feature in a staging environment without releasing the gem, you can refer to the remote repo in your Gemfile and package.json.

In Gemfile

gem 'headmin', git: 'git@github.com:insiting/headmin.git', branch: 'feature/test'

In package.json

{
  "dependencies": {
    "headmin": "ssh://git@github.com:insiting/headmin.git#feature\/test"
  }
}

Releasing

After integration a new feature of fixing a bug, first commit and push your changes.

Update the gem

# First bundle if new runtime dependencies were added
$ bundle

# Update the version number, push commits and tag the release
$ gem bump -v {patch,minor,major,...} --push --tag

# Release to Rubygems and create a Github release tag
$ gem release --github

Update the node package

# Manually update the version number in package.json
$ yarn build 
$ npm publish 

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/headmin. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Headmin project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.