1. Installing Carbon
Starting with the Carbon Angular, there are two ways to begin working with Carbon components. By the end, these two methods will produce the same result.
- Prerequisites
- Install Angular CLI
- Create an Angular App
- Install Carbon
- Run the app
- Add UI Shell
- Create pages
- Add routing
- Submit pull request
Preview
A preview of what you will build:
Prerequisites
Fork, clone and branch
This tutorial has an accompanying GitHub repository called carbon-tutorial-angular that we’ll use as a starting point for each step.
Fork
To begin, fork carbon-tutorial-angular using your GitHub account.
Clone
Go to your forked repository, copy the SSH or HTTPS URL and in your terminal run the two commands to get the repository in your local file system and enter that directory.
git clone [your fork SSH/HTTPS]cd carbon-tutorial-angular
Add upstream remote
Add a remote called upstream
so we can eventually submit a pull request once
you have completed this tutorial step.
SSH:
Or, if you prefer to use HTTPS instead of SSH with your remotes:
HTTPS:
git remote add upstream https://github.com/carbon-design-system/carbon-tutorial-angular.git
Verify that your forked repository remotes are correct:
git remote -v
Your terminal should output something like this:
origin [your forked repo] (fetch)origin [your forked repo] (push)
Branch
Now that we have our repository set up, let’s check out the branch for this tutorial step’s starting point. Run the two commands:
git fetch upstreamgit checkout -b angular-step-1 upstream/angular-step-1
Install Angular CLI
Since we are starting from scratch, we need to first install Angular CLI. Currently you need to install Angular CLI Version 8.x to work through this tutorial.
npm install -g @angular/cli
Create an Angular App
Now that we have our environment set up, starting a new Angular app is easy! If you haven’t set up the environment yet, please do so using the steps provided in Prerequisites (above). We will be using the Angular CLI to create and generate our components. It can also generate services, router, components, and directives.
To create a new Angular project with Angular CLI, just run:
ng new carbon-angular-tutorial
This will create the new project within the current directory. Make sure you do this within the cloned fork of the project. When you get prompted, enter the following.
? Would you like to add Angular routing? Yes? Which stylesheet format would you like to use? SCSS
This command will install the Angular app with all the configurations needed.
Within the project folder carbon-angular-tutorial
, the src
directory should
have the following structure:
carbon-angular-tutorial...├── src├── app│ ├── app-routing.module.ts│ ├── app.component.html│ ├── app.component.scss│ ├── app.component.spec.ts│ ├── app.component.ts
Install Carbon
Even though we installed some dependencies while creating the new app, we’ve yet to install the Carbon packages.
carbon-components
- Component stylescarbon-components-angular
- Angular components@carbon/icons
- Carbon icons
npm install carbon-components carbon-components-angular @carbon/icons
Import carbon-components styles
In src/styles.scss
, import the Carbon styles by adding the following to the
top of the file:
src/styles.scss@import '~carbon-components/scss/globals/scss/styles';
Run the app
Now we can run our app for a quick preview inside the browser.
npm start
Your app should now be running with the message:
** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **
Before we start adding components we want to start with an empty project, so
delete everything in app.component.html
except for the router-outler
. We
will also have to delete the test that was associated with this code. So in
app.component.spec.ts
, delete the should render title
and
should have as title 'carbon-angular-tutorial'
test.
Add UI Shell
Next, we’re going to create an Angular component called Header
to use with the
UI Shell Carbon component. Using Angular CLI we will create this component
inside the src/app
directory.
ng g component header --lint-fix
Folder structure
src/app/header├── header.component.html├── header.component.scss├── header.component.spec.ts└── header.component.ts
Import UI Shell
Next we’ll import our Carbon UI Shell components into app.module.ts
,
app.component.spec.ts
and header.component.spec.ts
. Set up the file like so:
src/app/app.module.tsimport { BrowserModule } from '@angular/platform-browser';import { NgModule } from '@angular/core';import { AppRoutingModule } from './app-routing.module';import { AppComponent } from './app.component';import { HeaderComponent } from './header/header.component';// carbon-components-angular default importsimport { UIShellModule, IconModule } from 'carbon-components-angular';
src/app/app.component.spec.ts,src/app/header/header.component.spec.tsimport { UIShellModule } from 'carbon-components-angular/ui-shell/ui-shell.module';
src/app/app.component.spec.ts,src/app/header/header.component.spec.tsTestBed.configureTestingModule({declarations: [HeaderComponent],imports: [UIShellModule]});
Import and register icons
Now let’s import the icons from our @carbon/icons
package. In app.module.ts
,
app.component.spec.ts
and header.component.spec.ts
, we need to import each
individual icon we will use and register them with the IconService
src/app/app.module.ts,src/app/app.component.spec.ts,src/app/header/header.component.spec.tsimport Notification16 from '@carbon/icons/es/notification/16';import UserAvatar16 from '@carbon/icons/es/user--avatar/16';import AppSwitcher16 from '@carbon/icons/es/app-switcher/16';
In the AppModule
class we’ll add a constructor that provides us with an
instance of IconService
and call registerAll
with an array of the icons we
need to use.
src/app/app.module.ts,src/app/app.component.spec.ts,src/app/header/header.component.spec.tsconstructor(protected iconService: IconService) {iconService.registerAll([Notification16,UserAvatar16,AppSwitcher16]);}
Then we need to add the template code. Populate header.component.html
with:
src/app/header/header.component.html<ibm-header name="Carbon Tutorial Angular"><ibm-header-navigation ariaLabel="Carbon Tutorial Angular"><ibm-header-item href="/repos">Repositories</ibm-header-item></ibm-header-navigation><ibm-header-global>