# Headmin A complete library of commonly used components to build an admin interface in your Ruby on Rails project. [![Gem Version](https://badge.fury.io/rb/headmin.svg)](https://rubygems.org/gems/headmin) [![npm version](https://badge.fury.io/js/headmin.svg)](https://www.npmjs.com/package/headmin) ## Installation To install Headmin into your current Rails application use bundler: ```shell $ 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: ```scss @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. ```js 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. ```shell $ yarn add headmin ``` ## Helpers Add the Headmin helpers to your helper file. We recommend using namespaces. ```ruby # 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 ```ruby gem "headmin", path: "../headmin" ``` In package.json ```json { "dependencies": { "headmin": "link:../headmin" } } ``` To see frontend changes update live in development run ```shell # 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 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 ```ruby gem 'headmin', git: 'git@github.com:insiting/headmin.git', branch: 'feature/test' ``` In package.json ```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 ```shell # 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 $ gem release ``` Update the node package ```shell # 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](https://github.com/[USERNAME]/headmin/blob/master/CODE_OF_CONDUCT.md). ## License The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). ## 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](https://github.com/[USERNAME]/headmin/blob/master/CODE_OF_CONDUCT.md).