From e3450fd7592bd05bf08eb6e802ca5351e03f20ed Mon Sep 17 00:00:00 2001 From: Cory LaViska Date: Thu, 8 Oct 2020 08:55:50 -0400 Subject: [PATCH] Add integrating with rails to tutorials section --- docs/_sidebar.md | 3 + docs/getting-started/changelog.md | 1 + docs/getting-started/integrations.md | 131 ----------------------- docs/tutorials/integrating-with-rails.md | 96 +++++++++++++++++ 4 files changed, 100 insertions(+), 131 deletions(-) delete mode 100644 docs/getting-started/integrations.md create mode 100644 docs/tutorials/integrating-with-rails.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 2aeb22f76..90fa6217b 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -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) \ No newline at end of file diff --git a/docs/getting-started/changelog.md b/docs/getting-started/changelog.md index 0067fdc36..b4c28dbb3 100644 --- a/docs/getting-started/changelog.md +++ b/docs/getting-started/changelog.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 diff --git a/docs/getting-started/integrations.md b/docs/getting-started/integrations.md deleted file mode 100644 index b373bfc33..000000000 --- a/docs/getting-started/integrations.md +++ /dev/null @@ -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 `` of the -document, like so: - -```html - - - - - - - - <%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %> - <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %> - - <%= yield %> - -``` - -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) diff --git a/docs/tutorials/integrating-with-rails.md b/docs/tutorials/integrating-with-rails.md new file mode 100644 index 000000000..f3506cde7 --- /dev/null +++ b/docs/tutorials/integrating-with-rails.md @@ -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 `` section of `app/views/layouts/application.html.erb`. + +```html + + + + + + <%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %> + <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %> + + <%= yield %> + +``` + +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).