From d71668a19e58ab81d42c19a1c1e1deff697f083f Mon Sep 17 00:00:00 2001 From: Alistair Laing Date: Wed, 19 Jun 2019 15:50:31 +0100 Subject: [PATCH] Updates the docs refer to 'govuk' namespace As part of namespacing, we need to update the links the docs point to so that they are still valid and do not break. We also needed to update the examples to show how to use the new namespace. --- .../coding-standards/components.md | 4 +-- docs/contributing/coding-standards/css.md | 2 +- docs/contributing/coding-standards/js.md | 2 +- .../coding-standards/nunjucks-api.md | 2 +- docs/contributing/tasks.md | 2 +- docs/contributing/testing-and-linting.md | 8 ++--- docs/installation/compatibility.md | 4 +-- docs/installation/installing-with-npm.md | 30 ++++++++++--------- 8 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/contributing/coding-standards/components.md b/docs/contributing/coding-standards/components.md index 3a2e1d19ff..6e007c8ced 100644 --- a/docs/contributing/coding-standards/components.md +++ b/docs/contributing/coding-standards/components.md @@ -1,6 +1,6 @@ # Components -Find components in `src/components`. +Find components in `src/govuk/components`. Components must use the `.govuk-` namespace. @@ -20,8 +20,6 @@ Components must: Component folder and files should be singular, except in cases where they are more commonly used in groups, for example, radios, breadcrumbs and checkboxes. -An example component exists in `src/components/component-example`. - Use this as the basis for creating new components. The folder structure should be: diff --git a/docs/contributing/coding-standards/css.md b/docs/contributing/coding-standards/css.md index b1a974d4e9..03892dc5fd 100644 --- a/docs/contributing/coding-standards/css.md +++ b/docs/contributing/coding-standards/css.md @@ -466,4 +466,4 @@ We document SCSS using [SassDoc](http://sassdoc.com/file-level-annotations/). Th The syntax is used to generate a [SassDoc application](http://govuk-frontend-review.herokuapp.com/docs/) that documents SCSS in a readable format. -See [colour.scss](../../../src/helpers/_colour.scss) for an example of SassDoc syntax. +See [colour.scss](../../../src/govuk/helpers/_colour.scss) for an example of SassDoc syntax. diff --git a/docs/contributing/coding-standards/js.md b/docs/contributing/coding-standards/js.md index 9f75200982..c945401241 100644 --- a/docs/contributing/coding-standards/js.md +++ b/docs/contributing/coding-standards/js.md @@ -104,7 +104,7 @@ Use default export over named export. ## Polyfilling -If you need to support older browsers, import the necessary [polyfills](/src/vendor/polyfills) and they will be added to the environment when the feature is not supported. +If you need to support older browsers, import the necessary [polyfills](/src/govuk/vendor/polyfills) and they will be added to the environment when the feature is not supported. For example, if you want to polyfill `addEventListener` for IE8, import the Event polyfills. diff --git a/docs/contributing/coding-standards/nunjucks-api.md b/docs/contributing/coding-standards/nunjucks-api.md index 36b35b0ae5..5eba514a1c 100644 --- a/docs/contributing/coding-standards/nunjucks-api.md +++ b/docs/contributing/coding-standards/nunjucks-api.md @@ -6,7 +6,7 @@ To provide a level of consistency for developers we have standardised option nam The options (arguments) accepted by the component macro are specified in a `[component-name].yaml` file as `params`. Each option should have the following attributes: `name`, `type`, `required`, `description`. -An option can additionally contain `params` that denotes nested items in the option (see [breadcrumbs component](https://github.com/alphagov/govuk-frontend/blob/master/src/components/breadcrumbs/breadcrumbs.yaml#L6)) and `isComponent: true` where the option is another component (see [checkboxes component](https://github.com/alphagov/govuk-frontend/blob/master/src/components/checkboxes/checkboxes.yaml#L11)). +An option can additionally contain `params` that denotes nested items in the option (see [breadcrumbs component](https://github.com/alphagov/govuk-frontend/blob/master/src/govuk/components/breadcrumbs/breadcrumbs.yaml#L6)) and `isComponent: true` where the option is another component (see [checkboxes component](https://github.com/alphagov/govuk-frontend/blob/master/src/govuk/components/checkboxes/checkboxes.yaml#L11)). Component macro options are shipped as `macro-options.json` in `package`. diff --git a/docs/contributing/tasks.md b/docs/contributing/tasks.md index 88a19e9b37..105a591592 100644 --- a/docs/contributing/tasks.md +++ b/docs/contributing/tasks.md @@ -75,7 +75,7 @@ This task will: **`gulp compile:components`** This task will: - - compile all `src/components/componentName/componentName.njk` files to HTML files + - compile all `src/govuk/components/componentName/componentName.njk` files to HTML files **`gulp lint`** diff --git a/docs/contributing/testing-and-linting.md b/docs/contributing/testing-and-linting.md index f76c8afd2d..9a2eb67a85 100644 --- a/docs/contributing/testing-and-linting.md +++ b/docs/contributing/testing-and-linting.md @@ -26,24 +26,24 @@ See [JavaScript Coding Standards](coding-standards/js.md#formatting-and-linting) We use [Jest](https://jestjs.io/), an automated testing platform with an assertion library, and [Puppeteer](https://pptr.dev/) that is used to control [headless Chrome](https://developers.google.com/web/updates/2017/04/headless-chrome). -We test individual components and for instance global Sass files. See [all.test.js](../../src/all.test.js). for examples of global tests we run, and [checkboxes.test.js](../../src/components/checkboxes/checkboxes.test.js) for an example of component tests. +We test individual components and for instance global Sass files. See [all.test.js](../../src/govuk/all.test.js). for examples of global tests we run, and [checkboxes.test.js](../../src/govuk/components/checkboxes/checkboxes.test.js) for an example of component tests. We aim to write the description of our tests in as "natural language" as possible, for instance "back-link component fails to render if the required fields are not included". ### Running individual tests You can run a subset of the test suite that only tests components by running: - `npm test -- src/components/button` + `npm test -- src/govuk/components/button` Note: There's a watch mode that keeps a testing session open waiting for changes that can be used with: - `npm test -- --watch src/components/button` + `npm test -- --watch src/govuk/components/button` ### Updating component snapshots [Snapshot tests](https://facebook.github.io/jest/docs/en/snapshot-testing.html) are used for preventing unintended changes - when the snapshot test runs, it compares the previously captured snapshot to the current markup. For components, the snapshots are stored in `[component-name directory]/_snapshots_`. If a snapshot test fails, review the difference in the console. If the change is the correct change to make, run: -`npm test -- -u src/components/button` +`npm test -- -u src/govuk/components/button` This will update the snapshot file. Commit this file separately with a commit message that explains you're updating the snapshot file and an explanation of what caused the change. diff --git a/docs/installation/compatibility.md b/docs/installation/compatibility.md index b74d6c6f2d..3bb2d13a5c 100644 --- a/docs/installation/compatibility.md +++ b/docs/installation/compatibility.md @@ -26,7 +26,7 @@ GOV.UK Frontend will: - no longer use `rem` for font sizes To turn on compatibility mode for all 3 legacy frameworks, add the following -variables to your project's Sass file, above `@import "govuk-frontend/all"`: +variables to your project's Sass file, above `@import "govuk-frontend/govuk/all"`: ```SCSS $govuk-compatibility-govukfrontendtoolkit: true; @@ -42,7 +42,7 @@ If you are not using any of the legacy frameworks, you can still configure GOV.UK Frontend to use the old colour palette. Add the following variable to your project's Sass file, above -`@import "govuk-frontend/all"`: +`@import "govuk-frontend/govuk/all"`: ```scss $govuk-use-legacy-palette: true; diff --git a/docs/installation/installing-with-npm.md b/docs/installation/installing-with-npm.md index fd76607a3f..56e80505a6 100644 --- a/docs/installation/installing-with-npm.md +++ b/docs/installation/installing-with-npm.md @@ -42,14 +42,14 @@ imports) if you want to override GOV.UK Frontend with your own styles. 1. To import all components, add the below to your Sass file: ```SCSS - @import "node_modules/govuk-frontend/all"; + @import "node_modules/govuk-frontend/govuk/all"; ``` 2. To import an individual component (for example a button), add the below to your Sass file: ```SCSS - @import "node_modules/govuk-frontend/components/button/button"; + @import "node_modules/govuk-frontend/govuk/components/button/button"; ``` ### Optional: Resolving SCSS import paths @@ -82,7 +82,7 @@ to include add `includePaths` to it. After resolving the import paths you can import GOV.UK Frontend by using: ```SCSS -@import "govuk-frontend/components/button/button"; +@import "govuk-frontend/govuk/components/button/button"; ``` ### Global Styles @@ -93,14 +93,14 @@ This to avoid the risk of global styles conflicting with any pre-existing global Hovever, we do include some global styles in the [GOV.UK Prototype Kit](https://github.com/alphagov/govuk-prototype-kit-private-beta) to speed up prototyping. -These [global styles](../../src/core/_global-styles.scss) are are not included by default in GOV.UK Frontend. To include these global styles in your app, you can set `$govuk-global-styles` variable to `true` before importing GOV.UK Frontend styles into your app: +These [global styles](../../src/govuk/core/_global-styles.scss) are are not included by default in GOV.UK Frontend. To include these global styles in your app, you can set `$govuk-global-styles` variable to `true` before importing GOV.UK Frontend styles into your app: ```SCSS // application.scss $govuk-global-styles: true; -@import "govuk-frontend/all"; +@import "govuk-frontend/govuk/all"; ``` ### Using GOV.UK Frontend with old frameworks @@ -127,7 +127,7 @@ Note that GOV.UK Frontend does not initialise any scripts by default; all script ### Option 1: Include JavaScript -Include the `node_modules/govuk-frontend/all.js` script on your page. You might wish to copy the file into your project or reference it from `node_modules`. +Include the `node_modules/govuk-frontend/govuk/all.js` script on your page. You might wish to copy the file into your project or reference it from `node_modules`. To initialise all components, use the `initAll` function. @@ -135,7 +135,7 @@ JavaScript in GOV.UK Frontend requires HTML to be parsed first by the browser be Including the script elsewhere will stop components from functioning or displaying correctly. ```html - + @@ -172,8 +172,6 @@ if ($radio) { } ``` -Some components such as the details or button components are initialised globally. If you want to see how these are initialised by default, see the [all.js](../../src/all.js) file. - ### Option 2: Import JavaScript If you're using a bundler such as [Webpack](https://webpack.js.org/), use the `import` syntax to import all components. To initialise them, use the `initAll` function: @@ -200,6 +198,12 @@ If you're using a bundler such as Webpack, use the `import` syntax to import a c import { Radios } from 'govuk-frontend' ``` +or + +```JS +import Button from 'govuk-frontend/govuk/components/button/button' +``` + If you're using a bundler such as [Browserify](http://browserify.org/), you may need to use the CommonJS `require`: @@ -222,8 +226,6 @@ if ($radio) { } ``` -Some components such as the details or button components are initialised globally. If you want to see how these are initialised by default, see the [all.js](../../src/all.js) file. - ### Polyfills A JavaScript polyfill provides functionality on older browsers or assistive technology that do not natively support it. @@ -270,7 +272,7 @@ To use different asset paths, also complete the below step(s). // Include images from /application/assets/images and fonts from /application/assets/fonts $govuk-assets-path: '/application/assets'; - @import "govuk-frontend/all"; + @import "govuk-frontend/govuk/all"; ``` Example 2: @@ -280,10 +282,10 @@ To use different asset paths, also complete the below step(s). $govuk-images-path: "/images/govuk-frontend/"; $govuk-fonts-path: "/fonts/"; - @import "govuk-frontend/all"; + @import "govuk-frontend/govuk/all"; ``` -2. Optional: You can also override the helpers used to generate the asset urls, for example if you are using sass-rails' asset-pipeline functionality. You can do this by setting `$govuk-image-url-function` to the name of the function(s) you wish to use. See `src/settings/_assets.scss` for more information and examples. +2. Optional: You can also override the helpers used to generate the asset urls, for example if you are using sass-rails' asset-pipeline functionality. You can do this by setting `$govuk-image-url-function` to the name of the function(s) you wish to use. See `src/govuk/settings/_assets.scss` for more information and examples. ## Include CSS and JavaScript