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
rodzic
1af711bc89
commit
f966ba97d7
|
@ -10,92 +10,148 @@ This integration has been tested with the following:
|
||||||
|
|
||||||
- Rails >= 6
|
- Rails >= 6
|
||||||
- Node >= 12.10
|
- Node >= 12.10
|
||||||
- Webpacker >= 5
|
- Yarn >= 1.22
|
||||||
|
|
||||||
## Instructions
|
## 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
|
```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
|
```css
|
||||||
@import '@shoelace-style/shoelace/dist/themes/light';
|
// application.css
|
||||||
@import '@shoelace-style/shoelace/dist/themes/dark'; // Optional dark theme
|
@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
|
You do not have to do anything else if you are using [the `shoelace-rails` gem](https://github.com/yuki24/shoelace-rails).
|
||||||
import '../stylesheets/application.scss'
|
Here are how it works in different environments:
|
||||||
import { setBasePath, SlAlert, SlAnimation, SlButton, ... } from '@shoelace-style/shoelace'
|
|
||||||
|
|
||||||
// ...
|
- 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
|
If you are not using the `shoelace-rails` gem, you can manually copy the icon files to the `public/assets` directory.
|
||||||
// to work correctly in different environments)
|
One way to do this is to use a rake task and add it as a dependency to the `assets:precompile` task. Most rails
|
||||||
setBasePath(rootUrl + '/packs/js/')
|
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.
|
Rake::Task["assets:precompile"].enhance(["shoelace:icons:copy"])
|
||||||
|
|
||||||
```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>
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Now you can start using Shoelace components with Rails!
|
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
|
## 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.
|
- 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