administrate_tailwind_theme Gem
Introduction
administrate_tailwind_theme
is a custom theme gem for the Administrate gem, utilizing the Tailwind CSS framework. This gem revamps all views to use Tailwind CSS classes, enhancing the visual aesthetics and responsiveness of your Administrate dashboard. It also introduces additional fields like BooleanEmoji and CountryEmoji for a richer admin interface.
Features
- Tailwind CSS Integration: Complete rewrite of Administrate component classes to use Tailwind CSS.
- Additional Fields: Adds BooleanEmoji and CountryEmoji fields to your Administrate dashboard.
- Easy Setup: Automatic initializer creation and configuration.
- Rails 7, Rails-Tailwind, and Administrate Compatibility: Seamlessly works with the latest versions of these key gems.
- Flowbite Bringing a comprehensive suite of Tailwind CSS
Installation
Prerequisites
- Ruby version 2.6.0 or higher.
- Rails 7.1 or higher.
- Administrate 0.15 or higher.
- Tailwind CSS Rails 2.0 or higher.
Flowbite Integration
administrate_tailwind_theme now comes with Flowbite integration by default, bringing a rich set of Tailwind CSS components to your Administrate dashboard. For those who prefer not to use Flowbite, it can be easily disabled during the installation of the gem by setting the FLOWBITE=false
environment variable.
Setup
- Add this line to your application's Gemfile:
gem 'administrate_tailwind_theme'
- Execute:
bundle install
- After installing the gem, run the installer:
# With flowbite integration (default since 0.0.4)
rails generate administrate_tailwind_theme:install
# Without flowbite integration
FLOWBITE=false rails generate administrate_tailwind_theme:install
This will create an initializer and modify your tailwind.config.js
to ensure proper compilation of the gem's view styles.
Usage
Once installed, administrate_tailwind_theme
automatically overrides the default Administrate views. Your dashboard will now use Tailwind CSS styles. You can further customize the styles as per your application's needs.
Themed views
Like Administrate you can generate views to customize
./bin/rails g --help
...
AdministrateTailwindTheme:
administrate_tailwind_theme:install
administrate_tailwind_theme:view
administrate_tailwind_theme:views
administrate_tailwind_theme:views:edit
administrate_tailwind_theme:views:field
administrate_tailwind_theme:views:form
administrate_tailwind_theme:views:index
administrate_tailwind_theme:views:layout
administrate_tailwind_theme:views:navigation
administrate_tailwind_theme:views:new
administrate_tailwind_theme:views:show
Kaminari Themed pagination
Administrate use kaminari to handle pagination. Related views are themed with tailwind too
./bin/rails g administrate_tailwind_theme:views:kaminari
Navigations
Icons
For customizing the navigation menu with icons, you can include SVG files for each resource. Here's an example for adding an icon for User
model:
<!-- app/views/administrate/navigation/icons/_users.html.erb -->
<svg class="w-5 h-5 text-gray-500 transition duration-75 dark:text-gray-400 group-hover:text-gray-900 dark:group-hover:text-white" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 20 20">
<!-- SVG path for user icon -->
</svg>
Place this SVG file in the specified directory, and it will automatically be displayed next to the corresponding resource in the navigation menu.
Custom Fields
BooleanEmoji Field
The BooleanEmoji
field can be used to display boolean values with emojis for a more intuitive representation.
Example usage in a dashboard resource file:
ATTRIBUTE_TYPES = {
some_boolean_field: Field::BooleanEmoji,
# ...
}.freeze
CountryEmoji Field
The CountryEmoji
field is designed to display country codes with their corresponding emoji flags for a visual representation. It utilizes the iso_country_codes gem.
Example usage in a dashboard resource file:
ATTRIBUTE_TYPES = {
country_code: Field::CountryEmoji, # iso2
# ...
}.freeze
Configuration
After installation, you can modify the initializer created by the administrate_tailwind_theme:install
generator to fine-tune the theme settings.
For modifying tailwind.config.js
, we've followed the approach suggested in this Stack Overflow comment. Even though it might not be the most elegant solution, it's straightforward and works effectively.
Also, ensure your tailwind.config.js
includes the styles from this gem for proper compilation.
Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues on our GitHub repository.
License
This gem is available as open source under the terms of the MIT License.
About
This gem is maintained by Eth3rnit3. Feel free to contact at eth3rnit3@gmail.com for any queries or feedback.