Skip to content

Commit

Permalink
docs: minor content tweaks
Browse files Browse the repository at this point in the history
  • Loading branch information
David Featherston committed Jun 27, 2023
1 parent 1428d08 commit ada93f9
Show file tree
Hide file tree
Showing 8 changed files with 17 additions and 21 deletions.
2 changes: 1 addition & 1 deletion docs/content/framework/1.index.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,6 @@ Using the Ripple framework, developers are able to build headless frontend websi
![SDP Architecture](/assets/img/modules/sdp-architecture.png){.rpl-u-padding-12}


To find out more about Single Digital presence please visit https://www.vic.gov.au/single-digital-presence
To find out more about Single Digital Presence please visit https://www.vic.gov.au/single-digital-presence


6 changes: 3 additions & 3 deletions docs/content/framework/2.key-concepts/1.nuxt.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@ links:
---


Nuxt is a framework for building web application that can be rendered both server side using Node.js and client side with Vue.js components. Nuxt is the framework used in Ripple to deliver headless SDP websites that connect to Tide Drupal backends for content.
Nuxt is a framework for building web applications that can be rendered both server side using Node.js and client side with Vue.js components. Nuxt is the framework used in Ripple to deliver headless SDP websites that connect to Tide Drupal backends for content.

> **"Nuxt is a fantastic choice for teams building a production-grade product on the web. It aims to bake in performance best-practices while maintaining excellent Vue.js DX"**
> **"Nuxt is a fantastic choice for teams building a production-grade product on the web. It aims to bake in performance best practices while maintaining excellent Vue.js DX"**
>
> Addy Osmani - Chief Engineer of Chrome

It is recommended that developers new to Ripple familiarise themselves with Nuxt by reading the documentation site, in particular the following sections
It is recommended that developers new to Ripple familiarise themselves with Nuxt by reading the documentation site, in particular, the following sections:

- [Introduction · Get Started with Nuxt ](https://nuxt.com/docs/getting-started/introduction)
- [Vue.js Development · Nuxt Concepts](https://nuxt.com/docs/guide/concepts/vuejs-development)
Expand Down
6 changes: 2 additions & 4 deletions docs/content/framework/2.key-concepts/3.API-endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,10 @@ links:
url: https://nuxt.com/docs/guide/directory-structure/server#api-routes
---

In Ripple 2 we use API routes to create a [backend for frontend](https://medium.com/mobilepeople/backend-for-frontend-pattern-why-you-need-to-know-it-46f94ce420b0) API that handles communicating with the Drupal Tide JSON API and maps the response to only what is required to render the page in in Ripple.

In Ripple 2 we use API routes to create a [backend for frontend](https://medium.com/mobilepeople/backend-for-frontend-pattern-why-you-need-to-know-it-46f94ce420b0) API that handles communicating with the Drupal Tide JSON API and maps the response to only what is required to render the page in Ripple.

![API routes diagram](/assets/img/modules/api-routes.png)


## Nitro server routes

Nuxt 3 introduces the concept of [server API routes](https://nuxt.com/docs/guide/directory-structure/server#api-routes) powered by the [Nitro rendering engine](https://nitro.unjs.io/) and [H3](https://github.com/unjs/h3) server.
Expand All @@ -21,7 +19,7 @@ Nitro is the server layer that creates API routes in a Nuxt application. Nitro p

## Ripple Tide API

Ripple Tide API is the module that handles communication with Tide Drupal JSON API. It provides a wrapper service for API calls to Tide and provides an interface for adding mapping functions which transform the response from Drupal into only whats needed for rendering the website. This makes creating pages easier and improves performance by moving all of the data transformation into the server bundle where it can be easily cached.
Ripple Tide API is the module that handles communication with Tide Drupal JSON API. It provides a wrapper service for API calls to Tide and provides an interface for adding mapping functions which transform the response from Drupal into only what's needed for rendering the website. This makes creating pages easier and improves performance by moving all data transformation into the server bundle where it can be easily cached.

![API routes diagram](/assets/img/modules/ripple-tide-api.png)

Expand Down
8 changes: 4 additions & 4 deletions docs/content/framework/3.guides/1.migrating.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ layout: page

## Background

Ripple 2 is a complete rewrite of both the design system and the Nuxt modules used to create SDP sites with it. It is a breaking change with the processes used to create sites and functionality used in Ripple 1. This was required due to the following reasons
Ripple 2 is a complete rewrite of both the design system and the Nuxt modules used to create SDP sites with it. It is a breaking change with the processes used to create sites and functionality used in Ripple 1. This was required due to the following reasons:

- Latest versions of Vue and Nuxt 3 introducing breaking changes
- Deprecation of IE11 support allowing us to support modern browser features
Expand Down Expand Up @@ -49,7 +49,7 @@ Content types in Tide allow for defining custom fields that can be returned via
In Ripple 1.x, each content type was added through the convention of adding a folder named tide and each content type as a subfolder. See [Ripple 1 example](https://github.com/dpc-sdp/ripple/tree/develop/examples/basic-examples/tide/modules/example-content-type).
The mapping of the tide API response was done through [tide.config.js](https://github.com/dpc-sdp/ripple/blob/develop/packages/ripple-nuxt-tide/modules/news/tide.config.j). The JSON API response was returned in its entirety and mapping the Drupal fields to Ripple components was done through the Page component.

> In Ripple 2.x we move the mapping of data to the Nuxt server layer. This allows us to only return the necessary data need to the end user, reducing the JSON payload from Drupal.
> In Ripple 2.x we move the mapping of data to the Nuxt server layer. This allows us to only return the necessary data needed to the end user, reducing the JSON payload from Drupal.
For more information on creating new content types see the guide on [creating content types](4.creating-content-types.md)

Expand All @@ -65,8 +65,8 @@ In Ripple 2, we need to add similar support - See [Guide to creating dynamic com

> This feature is still in Beta, please see the [feature proposal](https://github.com/dpc-sdp/ripple-framework/discussions/660) for more information.
Listing pages are pages which contain dynamic lists of links to other pages. These are typically used to generate index pages when there are large amounts of similar items. See https://www.vic.gov.au/grants, https://www.vic.gov.au/victorian-honour-roll-of-women for example.
Listing pages are pages that contain dynamic lists of links to other pages. These are typically used to generate index pages when there are large amounts of similar items. See https://www.vic.gov.au/grants, https://www.vic.gov.au/victorian-honour-roll-of-women for example.

In Ripple 1 there was no dedicated content type for creating listing pages and hence these page were usually created as static pages in the frontend.
In Ripple 1 there was no dedicated content type for creating listing pages and hence these pages were usually created as static pages in the frontend.

In Ripple 2 we intend to move to a standard content type that allows configuring the search experience from the backend. Please see the [feature proposal](https://github.com/dpc-sdp/ripple-framework/discussions/660) for more info.
8 changes: 3 additions & 5 deletions docs/content/framework/3.guides/2.new-sites.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@ layout: page
---


Setting up new sites with Ripple 2 is made easy with our CLI tool and provisioning process. Before you do so though please ensure you have got in touch with the SDP engagement manager (digital@dpc.vic.gov.au) prior and have submitted a support request to the Digital Victoria Help center https://digital-vic.atlassian.net/servicedesk/customer/portals

Setting up new sites with Ripple 2 is made easy with our CLI tool and provisioning process. Before you do so though please ensure you have got in touch with the SDP engagement manager (digital@dpc.vic.gov.au) prior and have submitted a support request to the Digital Victoria Help Centre https://digital-vic.atlassian.net/servicedesk/customer/portals

## Requirements

Expand All @@ -18,19 +17,18 @@ When onboarding a new project to SDP the following will be provisioned for you:
- Section.io CDN setup and configured
- Environment variables set to your project specific requirements


## Local development dependencies

Please make sure you have the following dependencies installed before proceeding. Typically local development is not performed through a docker container on the front end.

- Node version 16.11.0 or greater (We recommend installing Node through Node Version Manager - See https://github.com/nvm-sh/nvm for install guide)
- NPM version 8.1.0 or greater

Please see `engines` key in `package.json` for most accurate versions.
Please see the `engines` key in `package.json` for most accurate versions.

## Installing Ripple

> For SDP sites, this will also be applied. However if you wish to create a local install of Ripple outside of a project see below.
> For SDP sites, this will also be applied. However, if you wish to create a local install of Ripple outside of a project see below.
Installing Ripple is easy with the included CLI tool:

Expand Down
2 changes: 1 addition & 1 deletion docs/content/framework/3.guides/3.brand-application.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Value
neutral
```

Both these collections are exposed to the front-end through the Site API, and can immediately update production sites without requiring a code change or deploy.
Both these collections are exposed to the front-end through the Site API, and can immediately update production sites without requiring a code change or deployment.

## Secondary logo

Expand Down
2 changes: 1 addition & 1 deletion docs/content/framework/3.guides/5.creating-new-layers.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The `playground` folder contains the essentials to get a test Nuxt application u
The layers structure is almost identical to a normal Nuxt app, meaning you can utilise the same features and conventions as a standard Nuxt application. i.e. create a `pages` folder for new pages, create a `components` folder for new components, etc.

Other useful commands:
- `npm run build` to do a production build the `.preview` application (for testing purposes)
- `npm run build` to do a production build of the `.preview` application (for testing purposes)
- `npm run lint` to lint the layer code with [eslint](https://eslint.org/)
- `npm run test` to run any unit tests with [jest](https://jestjs.io/)

Expand Down
4 changes: 2 additions & 2 deletions docs/content/framework/3.guides/5.dynamic-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ export default defineNitroPlugin(async (nitroApp: NitroApp) => {
})
```

The individual elements of a dynamic component will be covered below.
The individual elements of a dynamic component are covered below.

## The mapping function

Expand Down Expand Up @@ -80,7 +80,7 @@ Create a Vue component that will render your dynamic component.

This component will be rendered each time your component appears on a page and will receive any props that were specified from the mapping function.

> **Important note**: For this to work, your component needs to be registered globally. The simplest way to do this is to add the to the `/components/global` folder in your layer.
> **Important note**: For this to work, your component needs to be registered globally. The simplest way to do this is to add the component to the `/components/global` folder in your layer.
>
> Because they are global it's also important to choose non generic names so that they don't clash and overwrite other dynamic components
Expand Down

0 comments on commit ada93f9

Please sign in to comment.