From f85b9e1b2b08f91ce6ef54b942ed6709fa0d5dc2 Mon Sep 17 00:00:00 2001 From: Cory LaViska Date: Fri, 12 Nov 2021 10:31:13 -0500 Subject: [PATCH] update framework pages --- docs/frameworks/angular.md | 28 ++++++++++++++++++++++++++-- docs/frameworks/react.md | 10 +++++++--- docs/frameworks/vue.md | 25 +++++++++++++++++++++++-- 3 files changed, 56 insertions(+), 7 deletions(-) diff --git a/docs/frameworks/angular.md b/docs/frameworks/angular.md index cfa3576e3..22228ec7a 100644 --- a/docs/frameworks/angular.md +++ b/docs/frameworks/angular.md @@ -1,7 +1,29 @@ # Angular +Angular [plays nice](https://custom-elements-everywhere.com/#angular) with custom elements, so you can use Shoelace in your Angular apps with ease. + ## Installation -Angular [plays nice](https://custom-elements-everywhere.com/#angular) with custom elements. Just make sure to apply the custom elements schema as shown below. + +To add Shoelace to your Angular app, install the package from npm. + +```bash +npm install @shoelace-style/shoelace +``` + +Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path. + +```jsx +import '@shoelace-style/shoelace/dist/themes/light.css'; +import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path'; + +setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/'); +``` + +?> If you'd rather not use the CDN for assets, you can create a build task that copies `node_modules/@shoelace-style/shoelace/dist/assets` into a public folder in your app. Then you can point the base path to that folder instead. + +## Configuration + +Then make sure to apply the custom elements schema as shown below. ```js import { BrowserModule } from '@angular/platform-browser'; @@ -19,4 +41,6 @@ import { AppComponent } from './app.component'; export class AppModule {} ``` -?> Are you using Shoelace with Angular? This page could use some love. [Please help us improve it!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/angular.md) +Now you can start using Shoelace components in your app! + +?> Are you using Shoelace with Angular? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/angular.md) diff --git a/docs/frameworks/react.md b/docs/frameworks/react.md index b019f3346..78e3cee31 100644 --- a/docs/frameworks/react.md +++ b/docs/frameworks/react.md @@ -20,11 +20,13 @@ import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path'; setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/'); ``` -?> If you'd rather not use the CDN for assets, you can create a [copy task](https://webpack.js.org/plugins/copy-webpack-plugin/) to copy `node_modules/@shoelace-style/shoelace/dist/assets` into your app's `public` directory. Then you can point the base path to that folder instead. +?> If you'd rather not use the CDN for assets, you can create a [build task](https://webpack.js.org/plugins/copy-webpack-plugin/) that copies `node_modules/@shoelace-style/shoelace/dist/assets` into your app's `public` directory. Then you can point the base path to that folder instead. Now you can start using components! -## Importing Components +## Usage + +### Importing Components Every Shoelace component is available to import as a React component. Note that we're importing the `` _React component_ instead of the `` _custom element_ in the example below. @@ -42,7 +44,7 @@ export default MyComponent; You can find a copy + paste import for every component at the bottom of each page in the documentation. -## Event Handling +### Event Handling Many Shoelace components emit [custom events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent). For example, the [input component](/components/input) emits the `sl-input` event when it receives input. In React, you can listen for the event using `onSlInput`. @@ -86,3 +88,5 @@ function MyComponent() { export default MyComponent; ``` + +?> Are you using Shoelace with React? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/react.md) diff --git a/docs/frameworks/vue.md b/docs/frameworks/vue.md index 97ce49499..377c805e1 100644 --- a/docs/frameworks/vue.md +++ b/docs/frameworks/vue.md @@ -2,6 +2,8 @@ Vue [plays nice](https://custom-elements-everywhere.com/#vue) with custom elements, so you can use Shoelace in your Vue apps with ease. +?> These instructions are for Vue 2. If you're using Vue 3, [please help us update this page](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue.md). + ## Installation To add Shoelace to your Vue app, install the package from npm. @@ -10,6 +12,19 @@ To add Shoelace to your Vue app, install the package from npm. npm install @shoelace-style/shoelace ``` +Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path. + +```jsx +import '@shoelace-style/shoelace/dist/themes/light.css'; +import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path'; + +setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/'); +``` + +?> If you'd rather not use the CDN for assets, you can create a build task that copies `node_modules/@shoelace-style/shoelace/dist/assets` into a public folder in your app. Then you can point the base path to that folder instead. + +## Configuration + You'll need to tell Vue to ignore Shoelace components. This is pretty easy because they all start with `sl-`. ```js @@ -23,7 +38,11 @@ app.config.compilerOptions.isCustomElement = tag => tag.startsWith('sl-'); app.mount('#app'); ``` -## Binding Complex Data +Now you can start using Shoelace components in your app! + +## Usage + +### Binding Complex Data When binding complex data such as objects and arrays, use the `.prop` modifier to make Vue bind them as a property instead of an attribute. @@ -31,7 +50,7 @@ When binding complex data such as objects and arrays, use the `.prop` modifier t ``` -## Two-way Binding +### Two-way Binding One caveat is there's currently [no support for v-model on custom elements](https://github.com/vuejs/vue/issues/7830), but you can still achieve two-way binding manually. @@ -69,3 +88,5 @@ Now you can use the `v-sl-model` directive to keep your data in sync! ```html ``` + +?> Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue.md)