Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: use InlineNotification's in all tutorials #889

Merged
merged 4 commits into from Feb 12, 2020
Merged

docs: use InlineNotification's in all tutorials #889

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6ac8fa5
docs: format tutorial notes as InlineNotification's
mattrosno Feb 10, 2020
7386e69
docs: add InlineNotification's to angular and vue tutorial
mattrosno Feb 10, 2020
fd0fd61
Merge branch 'master' into tutorial-cleanup
vpicone Feb 11, 2020
643354e
Merge branch 'master' into tutorial-cleanup
vpicone Feb 12, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
54 changes: 45 additions & 9 deletions src/pages/tutorial/angular/step-1.mdx
View file
Open in desktop
Expand Up @@ -29,7 +29,11 @@ A [preview](https://angular-step-2-carbon-tutorial.netlify.com) of what you will
allowfullscreen={true}
/>

_Note: If you get lint errors when you copy the code from the snippets, run_ `ng lint --fix` _to fix them._
<InlineNotification>

**Note:** If you get lint errors when you copy the code from the snippets, run `ng lint --fix` to fix them.

</InlineNotification>

## Prerequisites

Expand Down Expand Up @@ -219,7 +223,11 @@ Since we are starting from scratch, we need to first install Angular CLI.
npm install -g @angular/cli
```

_Note: If you are using macOS you might need to execute as a_ `sudo` _command._
<InlineNotification>

**Note:** If you are using macOS you might need to execute as a `sudo` command.

</InlineNotification>

## Create an Angular App

Expand Down Expand Up @@ -460,7 +468,11 @@ max_line_length = off
trim_trailing_whitespace = false
```

_Note: This only works with editors that support editorconfigs._
<InlineNotification>

**Note:** This only works with editors that support editorconfigs.

</InlineNotification>

## Progressive web app

Expand Down Expand Up @@ -709,7 +721,11 @@ TestBed.configureTestingModule({
```
<!-- prettier-ignore-end -->

_Note: you can find a description of the different components used in UI Shell in our [carbon-components-angular](https://github.com/IBM/carbon-components-angular/tree/master/src/ui-shell) package._
<InlineNotification>

**Note:** You can find a description of the different components used in UI Shell in our [carbon-components-angular](https://github.com/IBM/carbon-components-angular/tree/master/src/ui-shell) package.

</InlineNotification>

### Import icons

Expand Down Expand Up @@ -895,7 +911,11 @@ We're going to submit a pull request to verify completion of this tutorial step

### Continuous integration (CI) check

_Note: Before you run any tests, make sure that you are using ChromeHeadless in _`karma.conf.js`_ instead of Chrome._
<InlineNotification>

**Note:** Before you run any tests, make sure that you are using ChromeHeadless in `karma.conf.js` instead of Chrome.

</InlineNotification>

We have `lint` and `test` scripts defined in `package.json` that verify file formatting for files that have been touched since the last Git commit. You'd typically also have that script run your test suite as part of your CI build. Go ahead and make sure everything looks good with:

Expand All @@ -904,7 +924,11 @@ ng lint --fix
npm run lint && npm test
```

_Note: If this gives an error, it's likely that some of your source files are not properly formatted._
<InlineNotification>

**Note:** If this gives an error, it's likely that some of your source files are not properly formatted.

</InlineNotification>

### Git commit and push

Expand All @@ -920,12 +944,24 @@ Then, push to your repository:
git push origin angular-step-1
```

_Note: If your Git remote protocol is HTTPS instead of SSH, you may be prompted to authenticate with GitHub when you push changes. If your GitHub account has two-factor authentication enabled, we recommend that you follow these instructions to [create a personal access token for the command line](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). That lets you use your token instead of password when performing Git operations over HTTPS._
<InlineNotification>

**Note:** If your Git remote protocol is HTTPS instead of SSH, you may be prompted to authenticate with GitHub when you push changes. If your GitHub account has two-factor authentication enabled, we recommend that you follow these instructions to [create a personal access token for the command line](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). That lets you use your token instead of password when performing Git operations over HTTPS.

</InlineNotification>

_Note: If you receive a_ `non-fast-forward` _error, it's likely that your forked repository is behind the original repository and needs updated. This can happen if the tutorial was updated after you began working on it. To fix, run_ `git pull upstream angular-step-1` _to merge the changes into your branch, then you can try pushing again. Or, you can [manually merge](https://help.github.com/en/articles/syncing-a-fork) in the upstream changes._
<InlineNotification>

**Note:** If you receive a `non-fast-forward` error, it's likely that your forked repository is behind the original repository and needs updated. This can happen if the tutorial was updated after you began working on it. To fix, run `git pull upstream angular-step-1` to merge the changes into your branch, then you can try pushing again. Or, you can [manually merge](https://help.github.com/en/articles/syncing-a-fork) in the upstream changes.

</InlineNotification>

### Pull request (PR)

Finally, visit [carbon-tutorial-angular](https://github.com/carbon-design-system/carbon-tutorial-angular) to "Compare & pull request". In doing so, make sure that you are comparing to `angular-step-1` into `base: angular-step-1`. Take notice of the [Netlify](https://www.netlify.com) bot that deploys a preview of your PR every time that you push new commits. These previews can be shared and viewed by anybody to assist the PR review process.

_Note: Expect your tutorial step PRs to be reviewed by the Carbon team but not merged. We'll close your PR so we can keep the repository's remote branches pristine and ready for the next person!_
<InlineNotification>

**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but not merged. We'll close your PR so we can keep the repository's remote branches pristine and ready for the next person!

</InlineNotification>
60 changes: 50 additions & 10 deletions src/pages/tutorial/angular/step-2.mdx
View file
Open in desktop
Expand Up @@ -36,7 +36,11 @@ A [preview](https://angular-step-3-carbon-tutorial.netlify.com) of what you'll b
class="bx--iframe bx--iframe--border"
/>

_Note: If you get lint errors when you copy the code from the snippets, run_ `ng lint --fix` _to fix them._
<InlineNotification>

**Note:** If you get lint errors when you copy the code from the snippets, run `ng lint --fix` to fix them.

</InlineNotification>

## Fork, clone and branch

Expand All @@ -51,7 +55,11 @@ git fetch upstream
git checkout -b angular-step-2 upstream/angular-step-2
```

_Note: This builds on top of step 1, but be sure to check out the upstream step 2 branch because it includes the static assets required to get through this step._
<InlineNotification>

**Note:** This builds on top of step 1, but be sure to check out the upstream step 2 branch because it includes the static assets required to get through this step.

</InlineNotification>

### Build and start app

Expand Down Expand Up @@ -108,7 +116,11 @@ We've included the designs for this tutorial app in the `design.sketch` file fou

<Caption>Landing page grid</Caption>

_Pro tip:_ `CTRL-L` _toggles the layout in Sketch._
<InlineNotification>

**Pro tip:** `CTRL-L` toggles the layout in Sketch.

</InlineNotification>

We'll break this down into three rows. The first row with the gray background doesn't appear to need any columns. The second row with the white background looks like it has two columns of different widths. The third row with the gray background looks like it has four columns of equal width.

Expand Down Expand Up @@ -239,7 +251,11 @@ Now we need to modify the second row to use the `Tab` component.
</div>
```

_Note: We're using the grid for the page layout, but we also need to apply the grid within the tab content. When doing so, make sure the nested grid has the expected_ `grid` _>_ `row` _>_ `col` _DOM structure._
<InlineNotification>

**Note:** We're using the grid for the page layout, but we also need to apply the grid within the tab content. When doing so, make sure the nested grid has the expected `grid` > `row` > `col` DOM structure.

</InlineNotification>

Hold up! If you were to run [DAP](https://www.ibm.com/able/dynamic-assessment-plug-in.html) to check for accessibility violations, you'd see `Multiple navigation landmarks must have unique labels specified with aria-label or aria-labelledby` because both the `Breadcrumb` and `Tabs` components use `<nav>` elements. To fix, add `ariaLabel` to the `Breadcrumb` opening tag:

Expand Down Expand Up @@ -297,7 +313,11 @@ Then in `styles.scss` add this import after the Carbon `styles.scss` import.
```
<!-- prettier-ignore-end -->

_Note: We don't have to include this in a separate file, but it's nice to keep overrides separate from your application's styling so when migrating to future Carbon versions and if there are breaking changes via different class names, you have a consolidated list of styling declaration blocks to review._
<InlineNotification>

**Note:** We don't have to include this in a separate file, but it's nice to keep overrides separate from your application's styling so when migrating to future Carbon versions and if there are breaking changes via different class names, you have a consolidated list of styling declaration blocks to review.

</InlineNotification>

We can now add our images and text for each column in the first `Tab` in `landing-page.component.html`.

Expand Down Expand Up @@ -384,7 +404,11 @@ We've added basic layout styles in `landing-page.component.scss` and `styles.scs
</Column>
</Row>

_Pro tip:_ `CTRL-G` _toggles the grid in Sketch._
<InlineNotification>

**Pro tip:** `CTRL-G` toggles the grid in Sketch.

</InlineNotification>

Now, we need to add a space above the breadcrumb and below the heading. For that, add:

Expand Down Expand Up @@ -473,7 +497,11 @@ We also need to adjust our vertical spacing and type treatment. Like before, it'
</Column>
</Row>

_Note: You may be wondering why there are vertical gaps between the type and spacers. Each type token has a line height that's suited for its font size. The vertical spacers adjacently touch the line height boundaries and not the baseline, for consistency as well as development ease so_ `margins` _and_ `paddings` _don't need to offset line heights._
<InlineNotification>

**Note:** You may be wondering why there are vertical gaps between the type and spacers. Each type token has a line height that's suited for its font size. The vertical spacers adjacently touch the line height boundaries and not the baseline, for consistency as well as development ease so `margins` and `paddings` don't need to offset line heights.

</InlineNotification>

<!-- prettier-ignore-start -->
```scss path=src/app/home/landing-page/landing-page.component.scss
Expand Down Expand Up @@ -715,7 +743,11 @@ ng lint --fix
npm run lint && npm test
```

_Note: Having issues running this? [Step 1](</tutorial/angular/step-1#continuous-integration-(ci)-check>) has troubleshooting notes that may help._
<InlineNotification>

**Note:** Having issues running this? [Step 1](</tutorial/angular/step-1#continuous-integration-(ci)-check>) has troubleshooting notes that may help.

</InlineNotification>

### Git commit and push

Expand All @@ -731,10 +763,18 @@ Then, push to your repository:
git push origin angular-step-2
```

_Note: Having issues pushing your changes? [Step 1](/tutorial/angular/step-1#git-commit-and-push) has troubleshooting notes that may help._
<InlineNotification>

**Note:** Having issues pushing your changes? [Step 1](/tutorial/angular/step-1#git-commit-and-push) has troubleshooting notes that may help.

</InlineNotification>

### Pull request (PR)

Finally, visit [carbon-tutorial-angular](https://github.com/carbon-design-system/carbon-tutorial-angular) to "Compare & pull request". In doing so, make sure that you are comparing to `angular-step-2` into `base: angular-step-2`.

_Note: Expect your tutorial step PRs to be reviewed by the Carbon team but not merged. We'll close your PR so we can keep the repository's remote branches pristine and ready for the next person!_
<InlineNotification>

**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but not merged. We'll close your PR so we can keep the repository's remote branches pristine and ready for the next person!

</InlineNotification>
69 changes: 56 additions & 13 deletions src/pages/tutorial/angular/step-3.mdx
View file
Open in desktop
Expand Up @@ -39,7 +39,11 @@ A [preview](https://angular-step-4-carbon-tutorial.netlify.com) of what you will
allowfullscreen="true"
/>

_Note: If you get lint errors when you copy the code from the snippets, run_ `ng lint --fix` _to fix them._
<InlineNotification>

**Note:** If you get lint errors when you copy the code from the snippets, run `ng lint --fix` to fix them.

</InlineNotification>

## Fork, clone and branch

Expand Down Expand Up @@ -74,7 +78,11 @@ You should see something similar to where the [previous step](/tutorial/angular/

We'll shortcut this using the Angular CLI, if you'd like more information head over to [Angular Apollo Installation](https://www.apollographql.com/docs/angular/recipes/angular-cli/) for details.

_Note: If you have not yet installed the Angular CLI, you will need to [install the Angular CLI](https://cli.angular.io/) before running the Angular Apollo Installation._
<InlineNotification>

**Note:** If you have not yet installed the Angular CLI, you will need to [install the Angular CLI](https://cli.angular.io/) before running the Angular Apollo Installation.

</InlineNotification>

Install the following

Expand All @@ -89,9 +97,12 @@ ng add apollo-angular
ng lint --fix
```

​
_Note: In case you receive_ `ERROR in ../node_modules/graphql/subscription/subscribe.d.ts:44:3 - error TS2304: Cannot find name 'AsyncIterableIterator'.`_, you'll have to add the code below in _`tsconfig.app.json` `lib`_:_
​
<InlineNotification>

​**Note:** In case you receive `ERROR in ../node_modules/graphql/subscription/subscribe.d.ts:44:3 - error TS2304: Cannot find name 'AsyncIterableIterator'.`, you'll have to add the code below
in `tsconfig.app.json` `lib`: ​

</InlineNotification>

```javascript path=src/tsconfig.app.json
"lib": [
Expand All @@ -101,7 +112,11 @@ _Note: In case you receive_ `ERROR in ../node_modules/graphql/subscription/subsc
],
```

_Note: In case you receive _`typings.d.ts:2:13 - error TS2403: Subsequent variable declarations must have the same type. Variable 'module' must be of type 'NodeModule', but here has type '{ id: string; }'.`_, you'll have to comment out or remove the code below in _`typings.d.ts`_:_
<InlineNotification>

**Note:** In case you receive `typings.d.ts:2:13 - error TS2403: Subsequent variable declarations must have the same type. Variable 'module' must be of type 'NodeModule', but here has type '{ id: string; }'.`, you'll have to comment out or remove the code below in `typings.d.ts`:

</InlineNotification>

```javascript path=src/typings.d.ts
declare var module: {
Expand Down Expand Up @@ -253,7 +268,11 @@ The column will have two values (`url` and `homepageUrl`) and will have the stru
protected linkTemplate: TemplateRef<any>;
```

_Note: Don't forget to import_ `ViewChild` _and_ `TemplateRef`.
<InlineNotification>

**Note:** Don't forget to import `ViewChild` and `TemplateRef`.

</InlineNotification>

Now let's create a function that transforms row data to our expected header keys. Notice how we're using our new `linkTemplate` to generate the value of the `links` key in each row.

Expand Down Expand Up @@ -344,7 +363,11 @@ skeletonModel = Table.skeletonModel(10, 6);
skeleton = true;
```

_Note: Don't forget to import_ `Table`.
<InlineNotification>

**Note:** Don't forget to import `Table`.

</InlineNotification>

Then replace the comment with:

Expand Down Expand Up @@ -392,7 +415,11 @@ selectPage(page) {
}
```

_Note: We only pass the rows that we want our table to display. We can do this by slicing our array of rows depending on the first item and the page size._
<InlineNotification>

**Note:** We only pass the rows that we want our table to display. We can do this by slicing our array of rows depending on the first item and the page size.

</InlineNotification>

Finally, let's import the `LinkModule` and `PaginationModule` to `repositories.module.ts` and `repo-table.component.spec` and add the template for pagination.

Expand All @@ -415,7 +442,11 @@ Immediately after the `ibm-table` closing tag (`/>`), add the `ibm-pagination` c
```
<!-- prettier-ignore-end -->

_Note: Like the other Carbon Angular component,_ `pagination` _component examples can be found in [Storybook](https://angular.carbondesignsystem.com/?path=/story/table--with-pagination) by browsing the story and knobs._
<InlineNotification>

**Note:** Like the other Carbon Angular component, `pagination` component examples can be found in [Storybook](https://angular.carbondesignsystem.com/?path=/story/table--with-pagination) by browsing the story and knobs.

</InlineNotification>

That does it! Your data table should fetch GitHub data on first render. You can expand each row to see the repository's description. You can modify the pagination items per page and cycle through pages or jump to a specific page of repositories.

Expand All @@ -432,7 +463,11 @@ ng lint --fix
npm run lint && npm test
```

_Note: Having issues running the CI check? [Step 1](</tutorial/angular/step-1#continuous-integration-(ci)-check>) has troubleshooting notes that may help._
<InlineNotification>

**Note:** Having issues running the CI check? [Step 1](</tutorial/angular/step-1#continuous-integration-(ci)-check>) has troubleshooting notes that may help.

</InlineNotification>

### Git commit and push

Expand All @@ -448,10 +483,18 @@ Then, push to your repository:
git push origin angular-step-3
```

_Note: Having issues pushing your changes? [Step 1](/tutorial/angular/step-1#git-commit-and-push) has troubleshooting notes that may help._
<InlineNotification>

**Note:** Having issues pushing your changes? [Step 1](/tutorial/angular/step-1#git-commit-and-push) has troubleshooting notes that may help.

</InlineNotification>

### Pull request (PR)

Finally, visit [carbon-tutorial-angular](https://github.com/carbon-design-system/carbon-tutorial-angular) to "Compare & pull request". In doing so, make sure that you are comparing to `angular-step-3` into `base: angular-step-3`.

_Note: Expect your tutorial step PRs to be reviewed by the Carbon team but not merged. We'll close your PR so we can keep the repository's remote branches pristine and ready for the next person!_
<InlineNotification>

**Note:** Expect your tutorial step PRs to be reviewed by the Carbon team but not merged. We'll close your PR so we can keep the repository's remote branches pristine and ready for the next person!

</InlineNotification>