Add integrating with rails to tutorials section

2020-10-08 08:55:50 -04:00 · 2020-10-08 08:55:50 -04:00 · e3450fd759
commit e3450fd759
--- 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)
--- 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
--- a/docs/getting-started/integrations.md
+++ b/docs/getting-started/integrations.md
@ -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)
--- a/docs/tutorials/integrating-with-rails.md
+++ 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 `<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).