kopia lustrzana https://github.com/shoelace-style/shoelace
Add integrating with rails to tutorials section
Cory LaViska
rodzic
3e33fbb905
commit
e3450fd759
|
|
@ -59,3 +59,6 @@
|
|||
- [Border Radius](/tokens/border-radius.md)
|
||||
- [Transition](/tokens/transition.md)
|
||||
- [Z-index](/tokens/z-index.md)
|
||||
|
||||
- Tutorials
|
||||
- [Integrating with Rails](/tutorials/integrating-with-rails.md)
|
||||
|
|
@ -12,6 +12,7 @@ _During the beta period, these restrictions may be relaxed in the event of a mis
|
|||
- Added `spellcheck` prop to `sl-input`
|
||||
- Added `sl-icon-library` to allow custom icon library registration
|
||||
- Added `library` prop to `sl-icon` and `sl-icon-button`
|
||||
- Added "Integrating with Rails" tutorial to the docs, courtesy of [ParamagicDev](https://github.com/ParamagicDev)
|
||||
- Fixed a bug where `sl-progress-ring` rendered incorrectly when zoomed in Safari [#227](https://github.com/shoelace-style/shoelace/issues/227)
|
||||
- Fixed a bug where tabbing into slotted elements closes `sl-dropdown` when used in a shadow root [#223](https://github.com/shoelace-style/shoelace/issues/223)
|
||||
- Fixed a bug where scroll anchoring caused undesirable scrolling when `sl-details` are grouped
|
||||
|
|
|
|||
|
|
@ -1,131 +0,0 @@
|
|||
# Integrations
|
||||
|
||||
## Rails
|
||||
|
||||
### Requirements
|
||||
|
||||
Currently, this integration has been tested and working with the
|
||||
following:
|
||||
|
||||
- `Rails >= 6`
|
||||
- `Node >= 12.10`
|
||||
- `Webpacker >= 5`
|
||||
|
||||
### Getting Started
|
||||
|
||||
#### NPM packages
|
||||
|
||||
To get started using [Shoelace](https://shoelace.style) with Rails you must first
|
||||
install the following packages:
|
||||
|
||||
```bash
|
||||
yarn add @shoelace-style/shoelace copy-webpack-plugin
|
||||
```
|
||||
|
||||
#### Importing Stylesheets
|
||||
|
||||
The next step is to import the Shoelace stylesheets in a file located at
|
||||
`app/javascript/stylesheets/application.scss` like so:
|
||||
|
||||
```css
|
||||
/* app/javascript/stylesheets/application.scss */
|
||||
|
||||
@import '~@shoelace-style/shoelace/dist/shoelace/shoelace';
|
||||
```
|
||||
|
||||
#### Importing Javascript
|
||||
|
||||
After importing the stylesheet, you must now import the Javascript files
|
||||
for Shoelace.
|
||||
|
||||
To do so, navigate to the `app/javascript/packs/application.js` file and
|
||||
add the following code:
|
||||
|
||||
```js
|
||||
// app/javascript/packs/application.js
|
||||
|
||||
import '../stylesheets/application.scss'
|
||||
import { defineCustomElements, setAssetPath } from '@shoelace-style/shoelace'
|
||||
|
||||
// ...
|
||||
|
||||
// This enables all web components for the current page
|
||||
setAssetPath(document.currentScript.src)
|
||||
defineCustomElements()
|
||||
```
|
||||
|
||||
**NOTE:** The above code will import all shoelace web components for convenience. If you would like to selectively import components check out the [Using Webpack](https://shoelace.style/getting-started/installation?id=using-webpack) section of the docs.
|
||||
|
||||
#### Webpack Config
|
||||
|
||||
Now that we have our stylesheets and javascript setup, we have to add
|
||||
Shoelace's icons to the final build output. To do so, we must modify the
|
||||
`config/webpack/environment.js` file like so:
|
||||
|
||||
```js
|
||||
// config/webpack/environment.js
|
||||
|
||||
const { environment } = require('@rails/webpacker')
|
||||
|
||||
// Shoelace config
|
||||
const path = require('path')
|
||||
const CopyPlugin = require('copy-webpack-plugin')
|
||||
|
||||
// Adds shoelace icons to Webpack's build process
|
||||
environment.plugins.append(
|
||||
'CopyPlugin',
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
{
|
||||
from: path.resolve(
|
||||
__dirname,
|
||||
'../../node_modules/@shoelace-style/shoelace/dist/shoelace/icons'
|
||||
),
|
||||
to: path.resolve(__dirname, '../../public/packs/js/icons')
|
||||
}
|
||||
]
|
||||
})
|
||||
)
|
||||
```
|
||||
|
||||
#### Adding pack tags
|
||||
|
||||
The final step to this process is to add the corresponding `pack_tags` to your `app/views/layouts/application.html.erb` file.
|
||||
|
||||
You should have the following `tags` in your
|
||||
`app/views/layouts/application.html.erb` in the `<head>` of the
|
||||
document, like so:
|
||||
|
||||
```html
|
||||
<!-- app/views/layouts/application.html.erb -->
|
||||
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<!-- above tags omitted -->
|
||||
|
||||
<%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
|
||||
<%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
|
||||
</head>
|
||||
<body><%= yield %></body>
|
||||
</html>
|
||||
```
|
||||
|
||||
And that's it! You can start using Shoelace Web Components with Rails.
|
||||
|
||||
Check out the [Shoelace
|
||||
Documentation](https://shoelace.style/getting-started/usage) for more
|
||||
information on how to use Shoelace Web Components.
|
||||
|
||||
### Additional Resources
|
||||
|
||||
There is an example repo available to help you get started.
|
||||
|
||||
**Example Repo:**
|
||||
[https://github.com/ParamagicDev/rails-shoelace-example](https://github.com/ParamagicDev/rails-shoelace-example)
|
||||
|
||||
And if you would like to avoid repeating this process, check out the
|
||||
associated Railsbyte for adding Shoelace.
|
||||
|
||||
**Railsbyte - Shoelace:**
|
||||
[https://railsbytes.com/templates/X8BsEb](https://railsbytes.com/templates/X8BsEb)
|
||||
|
|
@ -0,0 +1,96 @@
|
|||
# Integrating with Rails
|
||||
|
||||
This page explains how to integrate Shoelace with a Rails app. This is a community-maintained document. For questions about this integration, please [ask the community](https://discord.gg/mg8f26C).
|
||||
|
||||
## Requirements
|
||||
|
||||
This integration has been tested with the following:
|
||||
|
||||
- Rails >= 6
|
||||
- Node >= 12.10
|
||||
- Webpacker >= 5
|
||||
|
||||
## Instructions
|
||||
|
||||
To get started using Shoelace with Rails, the following packages must be installed.
|
||||
|
||||
```bash
|
||||
yarn add @shoelace-style/shoelace copy-webpack-plugin
|
||||
```
|
||||
|
||||
### Importing the Default Theme
|
||||
|
||||
The next step is to import Shoelace's default theme (stylesheet) in `app/javascript/stylesheets/application.scss`.
|
||||
|
||||
```css
|
||||
@import '~@shoelace-style/shoelace/dist/shoelace/shoelace';
|
||||
```
|
||||
|
||||
### Importing Required Scripts
|
||||
|
||||
After importing the theme, you'll need to import the JavaScript files for Shoelace. Add the following code to `app/javascript/packs/application.js`.
|
||||
|
||||
```js
|
||||
import '../stylesheets/application.scss'
|
||||
import { defineCustomElements, setAssetPath } from '@shoelace-style/shoelace'
|
||||
|
||||
// ...
|
||||
|
||||
// This enables all web components for the current page
|
||||
setAssetPath(document.currentScript.src)
|
||||
defineCustomElements()
|
||||
```
|
||||
|
||||
?> This will import all Shoelace components for convenience. To selectively import components, refer to the [Using webpack](/getting-started/installation?id=using-webpack) section of the docs.
|
||||
|
||||
### webpack Config
|
||||
|
||||
Next we need to add Shoelace's icons 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 icons to webpack's build process
|
||||
environment.plugins.append(
|
||||
'CopyPlugin',
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
{
|
||||
from: path.resolve(
|
||||
__dirname,
|
||||
'../../node_modules/@shoelace-style/shoelace/dist/shoelace/icons'
|
||||
),
|
||||
to: path.resolve(__dirname, '../../public/packs/js/icons')
|
||||
}
|
||||
]
|
||||
})
|
||||
)
|
||||
```
|
||||
|
||||
### 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!
|
||||
|
||||
## 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.
|
||||
- If you would like to avoid repeating this process, check out the associated [Railsbyte for Shoelace](https://railsbytes.com/templates/X8BsEb).
|
||||
Ładowanie…
Reference in New Issue