Skip to content

Commit bb33994

Browse files
brandyscarneybrandyscarney
committed
docs(angular): add quickstart guide and update overview
1 parent 8106cb5 commit bb33994

File tree

8 files changed

+737
-11
lines changed

8 files changed

+737
-11
lines changed

‎docs/angular/overview.md

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ Ionic uses the official Angular stack for building apps and routing, so your app
3030

3131
## Installation
3232

33+
Before you begin, make sure you have [Node.js](https://nodejs.org/) (which includes npm) installed on your machine.
34+
3335
```shell-session
3436
$ npm install -g @ionic/cli
3537
$ ionic start myApp tabs --type angular
@@ -46,16 +48,24 @@ $ ionic serve █
4648
<p>Quickly set up your first Ionic Angular app and learn the basics of the framework and CLI.</p>
4749
</DocsCard>
4850

49-
<DocsCard header="Build Your First App" href="your-first-app" icon="/icons/logo-angular-icon.png">
50-
<p>Build a real Photo Gallery app with Ionic Angular and native device features.</p>
51+
<DocsCard header="Angular Documentation" href="https://angular.dev/overview" icon="/icons/logo-angular-icon.png">
52+
<p>Learn more about Angular's core concepts, tools, and best practices from the official Angular documentation.</p>
5153
</DocsCard>
5254

5355
<DocsCard header="Navigation" href="navigation" icon="/icons/component-navigation-icon.png">
54-
<p>Master navigation in Ionic Angular using Angular Router.</p>
56+
<p>Discover how to handle routing and navigation in Ionic Angular apps using the Angular Router.</p>
5557
</DocsCard>
5658

5759
<DocsCard header="Components" href="/docs/components" icon="/icons/guide-components-icon.png">
5860
<p>Explore Ionic's rich library of UI components for building beautiful apps.</p>
5961
</DocsCard>
6062

63+
<DocsCard header="Theming" href="/docs/theming/basics" icon="/icons/guide-theming-icon.png">
64+
<p>Learn how to customize the look and feel of your app with Ionic's powerful theming system.</p>
65+
</DocsCard>
66+
67+
<DocsCard header="Capacitor Documentation" href="https://capacitorjs.com/docs/" icon="/icons/guide-capacitor-icon.png">
68+
<p>Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.</p>
69+
</DocsCard>
70+
6171
</DocsCards>

‎docs/angular/quickstart.md

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
---
2+
title: Ionic Angular Quickstart
3+
sidebar_label: Quickstart
4+
---
5+
6+
<head>
7+
<title>Angular QuickStart Global Component for Generating Ionic Angular Apps</title>
8+
<meta
9+
name="description"
10+
content="Our QuickStart guide covers the basics of both Angular and Ionic Framework global components to get apps up and running. Read how to easily generate Ionic Angular apps."
11+
/>
12+
</head>
13+
14+
import DocsCard from '@components/global/DocsCard';
15+
import DocsCards from '@components/global/DocsCards';
16+
17+
Welcome! This guide will walk you through creating your first Ionic Angular app, step by step. You'll learn how to set up your development environment, generate a new project, explore the project structure, and add your first UI components and navigation.
18+
19+
If you're looking for a high-level overview of what Ionic Angular is and how it fits into the Angular ecosystem, see the [Ionic Angular Overview](overview).
20+
21+
## Prerequisites
22+
23+
Before you begin, make sure you have [Node.js](https://nodejs.org/) (which includes npm) installed on your machine.
24+
You can check by running:
25+
26+
```shell
27+
node -v
28+
npm -v
29+
```
30+
31+
If you don't have Node.js, [download it here](https://nodejs.org/en/download).
32+
33+
## Create a Project with the Ionic CLI
34+
35+
First, install the latest [Ionic CLI](../cli):
36+
37+
```shell
38+
npm install -g @ionic/cli
39+
```
40+
41+
Then, run the following commands to create and run a new project:
42+
43+
```shell
44+
ionic start myApp blank --type angular
45+
46+
cd myApp
47+
ionic serve
48+
```
49+
50+
At the first prompt, choose `Standalone`.
51+
52+
After running `ionic serve`, your project will open in the browser.
53+
54+
![Screenshot of the Ionic Angular Home page](/img/guides/quickstart/home-page.png 'Ionic Angular Home Component')
55+
56+
## Explore the Project Structure
57+
58+
Your new app's `src/app` directory will look like this:
59+
60+
```shell
61+
├── app.component.html
62+
├── app.component.scss
63+
├── app.component.ts
64+
├── app.routes.ts
65+
└── home/
66+
├── home.page.html
67+
├── home.page.scss
68+
├── home.page.spec.ts
69+
└── home.page.ts
70+
```
71+
72+
Let's walk through these files to understand the app's structure.
73+
74+
## View the App Component
75+
76+
The root of your app is defined in `app.component.ts`:
77+
78+
```ts
79+
import { Component } from '@angular/core';
80+
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
81+
82+
@Component({
83+
selector: 'app-root',
84+
templateUrl: 'app.component.html',
85+
imports: [IonApp, IonRouterOutlet],
86+
})
87+
export class AppComponent {
88+
constructor() {}
89+
}
90+
```
91+
92+
And its template in `app.component.html`:
93+
94+
```html
95+
<ion-app>
96+
<ion-router-outlet></ion-router-outlet>
97+
</ion-app>
98+
```
99+
100+
This sets up the root of your application, using Ionic's `ion-app` and `ion-router-outlet` components. The router outlet is where your pages will be displayed.
101+
102+
## View Routes
103+
104+
Routes are defined in `app.routes.ts`:
105+
106+
```ts
107+
import { Routes } from '@angular/router';
108+
109+
export const routes: Routes = [
110+
{
111+
path: 'home',
112+
loadComponent: () => import('./home/home.page').then((m) => m.HomePage),
113+
},
114+
{
115+
path: '',
116+
redirectTo: 'home',
117+
pathMatch: 'full',
118+
},
119+
];
120+
```
121+
122+
When you visit the root URL (`/`), the `HomePage` component will be loaded.
123+
124+
## View the Home Page
125+
126+
The Home page component, defined in `home.page.ts`, imports the Ionic components it uses:
127+
128+
```ts
129+
import { Component } from '@angular/core';
130+
import { IonHeader, IonToolbar, IonTitle, IonContent } from '@ionic/angular/standalone';
131+
132+
@Component({
133+
selector: 'app-home',
134+
templateUrl: 'home.page.html',
135+
styleUrls: ['home.page.scss'],
136+
imports: [IonHeader, IonToolbar, IonTitle, IonContent],
137+
})
138+
export class HomePage {
139+
constructor() {}
140+
}
141+
```
142+
143+
And the template, in the `home.page.html` file, uses those components:
144+
145+
```html
146+
<ion-header [translucent]="true">
147+
<ion-toolbar>
148+
<ion-title> Blank </ion-title>
149+
</ion-toolbar>
150+
</ion-header>
151+
152+
<ion-content [fullscreen]="true">
153+
<ion-header collapse="condense">
154+
<ion-toolbar>
155+
<ion-title size="large">Blank</ion-title>
156+
</ion-toolbar>
157+
</ion-header>
158+
159+
<div id="container">
160+
<strong>Ready to create an app?</strong>
161+
<p>
162+
Start with Ionic
163+
<a target="_blank" rel="noopener noreferrer" href="https://ionicframework.com/docs/components">UI Components</a>
164+
</p>
165+
</div>
166+
</ion-content>
167+
```
168+
169+
This creates a page with a header and scrollable content area. The second header shows a [collapsible large title](/docs/api/title#collapsible-large-titles) that displays when at the top of the content, then condenses to show the smaller title in the first header when scrolling down.
170+
171+
:::tip Learn More
172+
For detailed information about Ionic layout components, see the [Header](/docs/api/header), [Toolbar](/docs/api/toolbar), [Title](/docs/api/title), and [Content](/docs/api/content) documentation.
173+
:::
174+
175+
## Add an Ionic Component
176+
177+
You can enhance your Home page with more Ionic UI components. For example, add a [Button](/docs/api/button) at the end of the `ion-content`:
178+
179+
```html
180+
<ion-content>
181+
<!-- existing content -->
182+
183+
<ion-button>Navigate</ion-button>
184+
</ion-content>
185+
```
186+
187+
Then, import the `IonButton` component in `home.page.ts`:
188+
189+
```ts
190+
import { IonButton, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
191+
192+
@Component({
193+
// ...existing config...
194+
imports: [IonButton, IonContent, IonHeader, IonTitle, IonToolbar],
195+
})
196+
```
197+
198+
## Add a New Page
199+
200+
To add a new page, generate it with the CLI:
201+
202+
```shell
203+
ionic generate page new
204+
```
205+
206+
A route will be automatically added to `app.routes.ts`.
207+
208+
In your `new.page.html`, you can add a [Back Button](/docs/api/back-button) to the [Toolbar](/docs/api/toolbar):
209+
210+
```html
211+
<ion-header [translucent]="true">
212+
<ion-toolbar>
213+
<ion-buttons slot="start">
214+
<ion-back-button defaultHref="/"></ion-back-button>
215+
</ion-buttons>
216+
<ion-title>new</ion-title>
217+
</ion-toolbar>
218+
</ion-header>
219+
```
220+
221+
And import `IonBackButton` and `IonButtons` in `new.page.ts`:
222+
223+
```ts
224+
import { IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
225+
226+
@Component({
227+
// ...existing config...
228+
imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar],
229+
})
230+
```
231+
232+
The `ion-back-button` will automatically handle navigation back to the previous page, or to `/` if there is no history.
233+
234+
## Navigate to the New Page
235+
236+
To navigate to the new page, update the button in `home.page.html`:
237+
238+
```html
239+
<ion-button [routerLink]="['/new']">Navigate</ion-button>
240+
```
241+
242+
Then, import `RouterLink` in `home.page.ts`:
243+
244+
```ts
245+
import { RouterLink } from '@angular/router';
246+
247+
@Component({
248+
// ...existing config...
249+
imports: [IonButton, IonContent, IonHeader, IonTitle, IonToolbar, RouterLink],
250+
})
251+
```
252+
253+
:::info
254+
Navigating can also be performed using Angular's Router service. See the [Angular Navigation documentation](/docs/angular/navigation#navigating-to-different-routes) for more information.
255+
:::
256+
257+
## Add Icons to the New Page
258+
259+
Ionic Angular comes with [Ionicons](https://ionic.io/ionicons/) pre-installed. You can use any icon by setting the `name` property on the `ion-icon` component. Add the following icons to `new.page.html`:
260+
261+
```html
262+
<ion-content>
263+
<!-- existing content -->
264+
265+
<ion-icon name="heart"></ion-icon>
266+
<ion-icon name="logo-ionic"></ion-icon>
267+
</ion-content>
268+
```
269+
270+
You'll also need to import and register these icons in `new.page.ts`:
271+
272+
```ts
273+
// ...existing imports...
274+
import { IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonTitle, IonToolbar } from '@ionic/angular/standalone';
275+
import { addIcons } from 'ionicons';
276+
import { heart, logoIonic } from 'ionicons/icons';
277+
278+
@Component({
279+
// ...existing config...
280+
imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonTitle, IonToolbar],
281+
})
282+
```
283+
284+
Then, update the constructor of the page to use `addIcons`:
285+
286+
```ts
287+
export class NewPage implements OnInit {
288+
constructor() {
289+
addIcons({ heart, logoIonic });
290+
}
291+
}
292+
```
293+
294+
Alternatively, you can register icons in `app.component.ts` to use them throughout your app.
295+
296+
For more information, see the [Icon documentation](/docs/api/icon) and the [Ionicons documentation](https://ionic.io/ionicons/).
297+
298+
## Run on a Device
299+
300+
Ionic's components work everywhere: iOS, Android, and PWAs. To deploy to mobile, use [Capacitor](https://capacitorjs.com):
301+
302+
```shell
303+
ionic build
304+
ionic cap add ios
305+
ionic cap add android
306+
```
307+
308+
Open the native projects in their IDEs:
309+
310+
```shell
311+
ionic cap open ios
312+
ionic cap open android
313+
```
314+
315+
See [Capacitor's Getting Started guide](https://capacitorjs.com/docs/getting-started/with-ionic) for more.
316+
317+
## Explore More
318+
319+
This guide covered the basics of creating an Ionic Angular app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out:
320+
321+
<DocsCards>
322+
323+
<DocsCard header="Build Your First App" href="your-first-app" icon="/icons/component-content-icon.png">
324+
<p>Build a real Photo Gallery app with Ionic Angular and native device features.</p>
325+
</DocsCard>
326+
327+
<DocsCard header="Angular Documentation" href="https://angular.dev/overview" icon="/icons/logo-angular-icon.png">
328+
<p>Learn more about Angular's core concepts, tools, and best practices from the official Angular documentation.</p>
329+
</DocsCard>
330+
331+
<DocsCard header="Navigation" href="navigation" icon="/icons/component-navigation-icon.png">
332+
<p>Discover how to handle routing and navigation in Ionic Angular apps using the Angular Router.</p>
333+
</DocsCard>
334+
335+
<DocsCard header="Components" href="/docs/components" icon="/icons/guide-components-icon.png">
336+
<p>Explore Ionic's rich library of UI components for building beautiful apps.</p>
337+
</DocsCard>
338+
339+
<DocsCard header="Theming" href="/docs/theming/basics" icon="/icons/guide-theming-icon.png">
340+
<p>Learn how to customize the look and feel of your app with Ionic's powerful theming system.</p>
341+
</DocsCard>
342+
343+
<DocsCard header="Capacitor Documentation" href="https://capacitorjs.com/docs/" icon="/icons/guide-capacitor-icon.png">
344+
<p>Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.</p>
345+
</DocsCard>
346+
347+
</DocsCards>

‎sidebars.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ module.exports = {
6868
collapsed: false,
6969
items: [
7070
'angular/overview',
71+
'angular/quickstart',
7172
'angular/build-options',
7273
{
7374
type: 'category',

‎static/icons/guide-capacitor-icon.png

3.85 KB
Loading

0 commit comments

Comments
 (0)