-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #875 from dpc-sdp/task/update-readme-vue3
docs: 📝 update badges, add tools and frameworks
- Loading branch information
Showing
13 changed files
with
200 additions
and
96 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
48 changes: 48 additions & 0 deletions
48
docs/content/design-system/3.develop/4.usage/1.access-to-github-packages.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| --- | ||
| title: Access to Github Packages | ||
| description: How to access and use repos hosted on Github Packages. | ||
| layout: page | ||
| --- | ||
|
|
||
| NPM allows the use of multiple repo hosts, as long as they can be identified by namespace. | ||
|
|
||
| Ripple 2 is hosted publicly on Github Packages (ghcr) under the **@dpc/sdp** namespace, so a few steps need to be followed access these packages, while also co-existing with the npm ecosystem. | ||
|
|
||
| First, create a Personal Access Token on Github: | ||
|
|
||
| 1. Visit https://github.com/settings/tokens and select **Generate new token** > **Generate new token (classic)** | ||
|
|
||
| ::DocsImageExample | ||
| --- | ||
| src: /img/generate.jpg | ||
| alt: "Screenshot of a clicked button (title Generate new token) that has opened a drop-down menu with two options: fine-grained and classic" | ||
| style: "width:360px" | ||
| --- | ||
| :: | ||
|
|
||
| 2. Fill in the **Note** and choose an **Expiration** - the 30 day default is generally fine, you'll receive a reminder to regenerate the token just before expiry | ||
|
|
||
| ::DocsImageExample | ||
| --- | ||
| src: /img/token.jpg | ||
| alt: "Screenshot of personal access token setup form, with 'Note' filled in as 'public ghcr access' and 'Expiration' set to default of 30 days" | ||
| style: "width:505px" | ||
| --- | ||
| :: | ||
|
|
||
| 3. Set the scope to only allow `read:packages`, and **Generate** token | ||
|
|
||
| ::DocsImageExample | ||
| --- | ||
| src: /img/permissions.jpg | ||
| alt: "Screenshot of scope, with only read:packages selected" | ||
| style: "width:827px" | ||
| --- | ||
| :: | ||
|
|
||
| 4. Store the resulting token somewhere secure, and add it to either a user `.npmrc` (recommended) or the project-level `.npmrc` (the url on line 2 below is protocol-less, not a comment): | ||
|
|
||
| ``` | ||
| @dpc-sdp:registry=https://npm.pkg.github.com | ||
| //npm.pkg.github.com/:_authToken=<github personal access token> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| --- | ||
| title: Vue | ||
| description: How to use Ripple components with Vue. | ||
| layout: page | ||
| --- | ||
|
|
||
| First, set up [access to Github Packages](access-to-github-packages). | ||
|
|
||
| Next, install Ripple UI in your project: | ||
|
|
||
| `npm install @dpc-sdp/ripple-ui-core --save` | ||
|
|
||
| In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue or index.js file): | ||
|
|
||
| ```js | ||
| import '@dpc-sdp/ripple-ui-core/style'; | ||
| import '@dpc-sdp/ripple-ui-core/style/components'; | ||
| ``` | ||
|
|
||
| To use a component, import it from `@dpc-sdp/ripple-ui-core/vue`, note the addition of `/vue`. | ||
|
|
||
| ```js | ||
| <script setup> | ||
| import { RplButton } from '@dpc-sdp/ripple-ui-core/vue'; | ||
| </script> | ||
|
|
||
| <template> | ||
| <RplButton variant="outlined" /> | ||
| </template> | ||
| ``` | ||
|
|
||
| Please see this [example app](https://github.com/dpc-sdp/ripple-vue-example) for a basic demonstration of how to use Ripple components in a Vue app. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| --- | ||
| title: Nuxt | ||
| description: How to use Ripple components with Nuxt in a non-SDP context. | ||
| layout: page | ||
| --- | ||
|
|
||
| First, set up [access to Github Packages](access-to-github-packages). | ||
|
|
||
| Next, install Ripple UI in your project: | ||
|
|
||
| `npm install @dpc-sdp/ripple-ui-core --save` | ||
|
|
||
| Ripple UI exports a nuxt module that you can add to your nuxt config, note the addition of `/nuxt`: | ||
|
|
||
| ```js | ||
| export default defineNuxtConfig({ | ||
| modules: [ | ||
| '@dpc-sdp/ripple-ui-core/nuxt' | ||
| ] | ||
| }) | ||
| ``` | ||
|
|
||
| In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue file): | ||
|
|
||
| ```js | ||
| import '@dpc-sdp/ripple-ui-core/style'; | ||
| import '@dpc-sdp/ripple-ui-core/style/components'; | ||
| ``` | ||
|
|
||
| There is no need to import the components as they will be registered globally by the nuxt module | ||
|
|
||
| ```js | ||
| <template> | ||
| <RplButton variant="outlined" /> | ||
| </template> | ||
| ``` | ||
|
|
||
| Even if you are not using SDP, the [Ripple Framework documentation](/framework) is a good starting point for any Nuxt development using Ripple. |
23 changes: 23 additions & 0 deletions
23
docs/content/design-system/3.develop/4.usage/4.webcomponents.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| --- | ||
| title: Web components | ||
| description: How to use the web component exports with other front-end systems. | ||
| layout: page | ||
| --- | ||
|
|
||
| > Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps. Custom components and widgets build on the Web Component standards, will work across modern browsers, and can be used with any JavaScript library or framework that works with HTML. | ||
| > | ||
| > Web components are based on existing web standards. Features to support web components are currently being added to the HTML and DOM specs, letting web developers easily extend HTML with new elements with encapsulated styling and custom behavior. | ||
| > https://www.webcomponents.org/ | ||
|
|
||
|
|
||
|
|
||
| Ripple exports a limited set of components as standard browser native web components. The advantage of using Web components is they can be dropped straight into conventional webpages and any CMS without a javascript build pipeline, such as Squiz Matrix and Salesforce. | ||
|
|
||
| Support for this output target is currently experimental, if you think you have a use case for using Web components in your project please add a comment [here](https://github.com/dpc-sdp/ripple-framework/discussions/658). | ||
|
|
||
| As with the other methods, set up [access to Github Packages](access-to-github-packages) and then install Ripple UI in your project: | ||
|
|
||
| `npm install @dpc-sdp/ripple-ui-core --save` | ||
|
|
||
| A basic example of how to use the web component exports can be found under [examples/webcomponents](https://github.com/dpc-sdp/ripple-framework/tree/develop/examples/webcomponents) in the ripple-framework monorepo. |
22 changes: 22 additions & 0 deletions
22
docs/content/design-system/3.develop/4.usage/5.css-only.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| --- | ||
| title: Styles only | ||
| description: Using the design system styles without a front-end framework. | ||
| layout: page | ||
| --- | ||
|
|
||
| Ripple UI core exports it's CSS stylesheets directly. If you have a use case where you can't use any of the other outputs, you can use our styles directly and provide your own markup based upon the rendered examples in Storybook. | ||
|
|
||
| First, set up [access to Github Packages](access-to-github-packages). | ||
|
|
||
| Next, install Ripple UI in your project: | ||
|
|
||
| `npm install @dpc-sdp/ripple-ui-core --save` | ||
|
|
||
| You can import CSS styles from the ripple-ui-core package. | ||
|
|
||
| ```js | ||
| import '@dpc-sdp/ripple-ui-core/style'; | ||
| import '@dpc-sdp/ripple-ui-core/style/components'; | ||
| ``` | ||
|
|
||
| We recommend that you lock the version of `@dpc-sdp/ripple-ui-core` so that any future changes of styles without changes to markup do not break your application. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters