kopia lustrzana https://github.com/shoelace-style/shoelace
Update the tutorial for Rails (#1258)
* Update the tutorial for Rails * Update docs/tutorials/integrating-with-rails.md Co-authored-by: Konnor Rogers <konnor5456@gmail.com> * Update docs/tutorials/integrating-with-rails.md Co-authored-by: Konnor Rogers <konnor5456@gmail.com> * Update docs/tutorials/integrating-with-rails.md Co-authored-by: Konnor Rogers <konnor5456@gmail.com> * Update docs/tutorials/integrating-with-rails.md Co-authored-by: Konnor Rogers <konnor5456@gmail.com> * Update docs/tutorials/integrating-with-rails.md Co-authored-by: Konnor Rogers <konnor5456@gmail.com> * Update docs/tutorials/integrating-with-rails.md * Add a bit more explanation to set up icons --------- Co-authored-by: Konnor Rogers <konnor5456@gmail.com>pull/1363/head
Yuki Nishijima
GitHub
rodzic
1af711bc89
commit
f966ba97d7
|
|
@ -10,92 +10,148 @@ This integration has been tested with the following:
|
|||
|
||||
- Rails >= 6
|
||||
- Node >= 12.10
|
||||
- Webpacker >= 5
|
||||
- Yarn >= 1.22
|
||||
|
||||
## Instructions
|
||||
|
||||
To get started using Shoelace with Rails, the following packages must be installed.
|
||||
When using Shoelace, there are mostly three things that need to be served to the client browser:
|
||||
|
||||
- Javascript files for the Web Components
|
||||
- CSS files for light and dark themes (they can co-exist, but one of them is required)
|
||||
- Shoelace Icons
|
||||
|
||||
Depending on the JS bundler you are using, you may need to do some additional configuration. However, the basic steps
|
||||
should be just about the same. Also, it is recommended to read to the [Bundling section in the Installation](/getting-started/installation?id=bundling)
|
||||
to understand how Shoelace can be set up with a JS bundler in general. In this tutorial, we will assume that your Rails app
|
||||
is already set up with a JS bundler that supports importing CSS files directly (e.g. Turbopack, esbuild, Vite).
|
||||
|
||||
To get started using Shoelace with Rails, the following package must be installed.
|
||||
|
||||
```bash
|
||||
yarn add @shoelace-style/shoelace copy-webpack-plugin
|
||||
yarn add @shoelace-style/shoelace
|
||||
```
|
||||
|
||||
### Importing the Default Theme
|
||||
This is required regardless of the JS bundler you are using.
|
||||
|
||||
The next step is to import Shoelace's default theme (stylesheet) in `app/javascript/stylesheets/application.scss`.
|
||||
### Javascript & CSS
|
||||
|
||||
The next step is to import the JavaScript files and default theme for Shoelace. Add the following code to your
|
||||
entrypoint JS file (generally `application.js`).
|
||||
|
||||
```js
|
||||
// application.js
|
||||
import '@shoelace-style/shoelace';
|
||||
|
||||
// You can also add these two if the JS bundler of your choice supports importing CSS files.
|
||||
import '@shoelace-style/shoelace/dist/themes/light.css';
|
||||
import '@shoelace-style/shoelace/dist/themes/dark.css'; // Optional dark mode
|
||||
```
|
||||
|
||||
!> In this example, all Shoelace components are imported for simplicity. However, importing directly from
|
||||
`@shoelace-style/shoelace` may result in a larger bundle size than necessary. Consider importing only the components
|
||||
you actually need in the actual application.
|
||||
|
||||
You can also import the CSS inside of a `.css` file if you prefer to maintain a separate CSS entrypoint.
|
||||
Such as with CssBundling-Rails.
|
||||
|
||||
```css
|
||||
@import '@shoelace-style/shoelace/dist/themes/light';
|
||||
@import '@shoelace-style/shoelace/dist/themes/dark'; // Optional dark theme
|
||||
// application.css
|
||||
@import '@shoelace-style/shoelace/dist/themes/light.css';
|
||||
```
|
||||
|
||||
Fore more details about themes, please refer to [Theme Basics](/getting-started/themes?id=theme-basics).
|
||||
For more details about themes, please refer to [Theme Basics](/getting-started/themes?id=theme-basics).
|
||||
|
||||
### Importing Required Scripts
|
||||
### Serving up Shoelace Icons
|
||||
|
||||
After importing the theme, you'll need to import the JavaScript files for Shoelace. Add the following code to `app/javascript/packs/application.js`.
|
||||
#### Using the `shoelace-rails` gem
|
||||
|
||||
```js
|
||||
import '../stylesheets/application.scss'
|
||||
import { setBasePath, SlAlert, SlAnimation, SlButton, ... } from '@shoelace-style/shoelace'
|
||||
You do not have to do anything else if you are using [the `shoelace-rails` gem](https://github.com/yuki24/shoelace-rails).
|
||||
Here are how it works in different environments:
|
||||
|
||||
// ...
|
||||
- In development and test, the icons are served by the `ActionDispatch::Static` middleware, directly from the
|
||||
`node_modules/@shoelace-style/shoelace/dist/assets/icons` directory.
|
||||
- In production, the icon files are automatically copied into the `public/assets` directory as part of the
|
||||
`assets:precompile` rake task.
|
||||
|
||||
const rootUrl = document.currentScript.src.replace(/\/packs.*$/, '')
|
||||
#### Copying Icon files with a Rake task
|
||||
|
||||
// Path to the assets folder (should be independent from the current script source path
|
||||
// to work correctly in different environments)
|
||||
setBasePath(rootUrl + '/packs/js/')
|
||||
```
|
||||
If you are not using the `shoelace-rails` gem, you can manually copy the icon files to the `public/assets` directory.
|
||||
One way to do this is to use a rake task and add it as a dependency to the `assets:precompile` task. Most rails
|
||||
deployment processes run the `rake assets:precompile` task as of part deply, which means that the icon files will be
|
||||
copied automatically.
|
||||
|
||||
### webpack Config
|
||||
```ruby
|
||||
# Rakefile
|
||||
namespace :shoelace do
|
||||
namespace :icons do
|
||||
desc "Copy Shoelace icons to the assets path"
|
||||
task copy: :environment do
|
||||
cp_r "node_modules/@shoelace-style/shoelace/dist/assets", Rails.public_path
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
Next we need to add Shoelace's assets to the final build output. To do this, modify `config/webpack/environment.js` to look like this.
|
||||
|
||||
```js
|
||||
const { environment } = require('@rails/webpacker');
|
||||
|
||||
// Shoelace config
|
||||
const path = require('path');
|
||||
const CopyPlugin = require('copy-webpack-plugin');
|
||||
|
||||
// Add shoelace assets to webpack's build process
|
||||
environment.plugins.append(
|
||||
'CopyPlugin',
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
{
|
||||
from: path.resolve(__dirname, '../../node_modules/@shoelace-style/shoelace/dist/assets'),
|
||||
to: path.resolve(__dirname, '../../public/packs/js/assets')
|
||||
}
|
||||
]
|
||||
})
|
||||
);
|
||||
|
||||
module.exports = environment;
|
||||
```
|
||||
|
||||
### Adding Pack Tags
|
||||
|
||||
The final step is to add the corresponding `pack_tags` to the page. You should have the following `tags` in the `<head>` section of `app/views/layouts/application.html.erb`.
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<!-- ... -->
|
||||
|
||||
<%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %> <%= javascript_pack_tag
|
||||
'application', 'data-turbolinks-track': 'reload' %>
|
||||
</head>
|
||||
<body>
|
||||
<%= yield %>
|
||||
</body>
|
||||
</html>
|
||||
Rake::Task["assets:precompile"].enhance(["shoelace:icons:copy"])
|
||||
```
|
||||
|
||||
Now you can start using Shoelace components with Rails!
|
||||
|
||||
## Using Rails View Helpers
|
||||
|
||||
[the `shoelace-rails` gem](https://github.com/yuki24/shoelace-rails) is a community-maintained library that provides useful Rake tasks and Rails view helpers for
|
||||
Shoelace components. In order to use it, add the gem by running the following command:
|
||||
|
||||
```bash
|
||||
bundle add shoelace-rails
|
||||
```
|
||||
|
||||
Once it is installed, you should be able to use the following view helpers to render Shoelace components:
|
||||
|
||||
```erb
|
||||
<%= sl_form_for @user do |form| %>
|
||||
<% # Text input: https://shoelace.style/components/input %>
|
||||
<%= form.text_field :name %>
|
||||
<%= form.password_field :password, placeholder: "Password Toggle", 'toggle-password': true %>
|
||||
|
||||
<% # Radio buttons: https://shoelace.style/components/color-picker %>
|
||||
<%= form.color_field :color %>
|
||||
|
||||
<% # Radio buttons: https://shoelace.style/components/radio %>
|
||||
<%= form.collection_radio_buttons :status, { id_1: "Option 1", id_2: "Option 2", id_3: "Option 3" }, :first, :last %>
|
||||
|
||||
<% # Select: https://shoelace.style/components/select %>
|
||||
<%= form.collection_select :tag, { id_1: "Option 1", id_2: "Option 2", id_3: "Option 3" }, :first, :last, {}, { placeholder: "Select one" } %>
|
||||
|
||||
<%= form.submit %>
|
||||
<% end %>
|
||||
```
|
||||
|
||||
And this code will produce:
|
||||
|
||||
```html
|
||||
<form class="new_user" id="new_user" data-remote="true" action="/" accept-charset="UTF-8" method="post">
|
||||
<sl-input label="Name" type="text" name="user[name]" id="user_name"></sl-input>
|
||||
<sl-input label="Password" type="password" name="user[password]" id="user_password"></sl-input>
|
||||
<sl-color-picker value="#ffffff" name="user[color]" id="user_color"></sl-color-picker>
|
||||
|
||||
<sl-radio-group no-fieldset="true">
|
||||
<sl-radio value="id_1" name="user[status]" id="user_status_id_1">Option 1</sl-radio>
|
||||
<sl-radio value="id_2" name="user[status]" id="user_status_id_2">Option 2</sl-radio>
|
||||
<sl-radio value="id_3" name="user[status]" id="user_status_id_3">Option 3</sl-radio>
|
||||
</sl-radio-group>
|
||||
|
||||
<sl-select placeholder="Select one" name="user[tag]" id="user_tag">
|
||||
<sl-menu-item value="id_1">Option 1</sl-menu-item>
|
||||
<sl-menu-item value="id_2">Option 2</sl-menu-item>
|
||||
<sl-menu-item value="id_3">Option 3</sl-menu-item>
|
||||
</sl-select>
|
||||
|
||||
<sl-button submit="true" type="primary" data-disable-with="Create User">Create User</sl-button>
|
||||
</form>
|
||||
```
|
||||
|
||||
For more details about the gem, please refer to [the official README](https://github.com/yuki24/shoelace-rails).
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- There is a third-party [example repo](https://github.com/ParamagicDev/rails-shoelace-example), courtesy of [ParamagicDev](https://github.com/ParamagicDev) available to help you get started.
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue