Merge changes from master

Author: ltm

docs/angular/performance.md

@@ -4,6 +4,37 @@ sidebar_label: Performance
 
 # Angular Performance
 
+## *ngFor with Ionic Components
+
+When using `*ngFor` with Ionic components, we recommend using Angular's `trackBy` option. This allows Angular to manage change propagation in a much more efficient way and only update the content inside of the component rather than re-create the component altogether.
+
+By using `trackBy` you can provide a stable identity for each loop element so Angular can track insertions and deletions within the iterator. Below is an example of how to use `trackBy`:
+
+**home.page.html**
+```html
+<ion-item *ngFor="let item of items; trackBy:trackItems">
+  <ion-label>{{ item.value }}</ion-label>
+</ion-item>
+```
+
+**home.component.ts**
+```typescript
+
+items = [
+  { id: 0, value: 'Item 0' },
+  { id: 1, value: 'Item 1' },
+  ...
+]
+
+trackItems(index: number, itemObject: any) {
+  return itemObject.id;
+}
+```
+
+In this example, we have an array of objects called `items`. Each object contains a `value` and an `id`. Using `trackBy`, we pass a `trackItems` function which returns the `id` of each object. This `id` is used to provide a stable identity for each loop element.
+
+For more information on how Angular manages change propagation with `ngFor` see https://angular.io/api/common/NgForOf#change-propagation.
+
 ## From the Ionic Team
 
 [How to Lazy Load in Ionic Angular](https://ionicframework.com/blog/how-to-lazy-load-in-ionic-angular/)

docs/angular/your-first-app.md

@@ -21,7 +21,7 @@ Highlights include:
 * Deployed as a native iOS and Android mobile app using [Capacitor](https://capacitor.ionicframework.com), Ionic's official native app runtime.
 * Photo Gallery functionality powered by the Capacitor [Camera](https://capacitor.ionicframework.com/docs/apis/camera), [Filesystem](https://capacitor.ionicframework.com/docs/apis/filesystem), and [Storage](https://capacitor.ionicframework.com/docs/apis/storage) APIs.
 
-It’s easy to get started. Find the complete app code referenced in this guide [on GitHub](https://github.com/ionic-team/photo-gallery-capacitor-ng).
+Find the complete app code referenced in this guide [on GitHub](https://github.com/ionic-team/photo-gallery-capacitor-ng).
 
 ## Download Required Tools
 
@@ -60,6 +60,12 @@ Next, change into the app folder:
 $ cd photo-gallery
 ```
 
+Next we'll need to install the necessary Capacitor plugins to make the app's native functionality work:
+
+```shell
+npm install @capacitor/camera @capacitor/storage @capacitor/filesystem
+```
+
 ### PWA Elements
 
 Some Capacitor plugins, including the Camera API, provide the web-based functionality and UI via the Ionic [PWA Elements library](https://github.com/ionic-team/ionic-pwa-elements).

docs/angular/your-first-app/2-taking-photos.md

@@ -17,10 +17,9 @@ $ ionic g service services/photo
 Open the new `services/photo.service.ts` file, and let’s add the logic that will power the camera functionality. First, import Capacitor dependencies and get references to the Camera, Filesystem, and Storage plugins:
 
 ```typescript
-import { Plugins, CameraResultType, Capacitor, FilesystemDirectory, 
-         CameraPhoto, CameraSource } from '@capacitor/core';
-
-const { Camera, Filesystem, Storage } = Plugins;
+import { Camera, CameraResultType, CameraSource, Photo } from '@capacitor/camera';
+import { Filesystem, Directory } from '@capacitor/filesystem';
+import { Storage } from '@capacitor/storage';
 ```
 
 Next, define a new class method, `addNewToGallery`, that will contain the core logic to take a device photo and save it to the filesystem. Let’s start by opening the device camera:
@@ -29,14 +28,14 @@ Next, define a new class method, `addNewToGallery`, that will contain the core l
 public async addNewToGallery() {
   // Take a photo
   const capturedPhoto = await Camera.getPhoto({
-    resultType: CameraResultType.Uri, 
-    source: CameraSource.Camera, 
-    quality: 100 
+    resultType: CameraResultType.Uri,
+    source: CameraSource.Camera,
+    quality: 100
   });
 }
 ```
 
-Notice the magic here: there's no platform-specific code (web, iOS, or Android)! The Capacitor Camera plugin abstracts that away for us, leaving just one method call - `Camera.getPhoto()` - that will open up the device's camera and allow us to take photos. 
+Notice the magic here: there's no platform-specific code (web, iOS, or Android)! The Capacitor Camera plugin abstracts that away for us, leaving just one method call - `Camera.getPhoto()` - that will open up the device's camera and allow us to take photos.
 
 Next, open up `tab2.page.ts` and import the PhotoService class and add a method that calls the `addNewToGallery` method on the imported servce:
 
@@ -50,7 +49,7 @@ addPhotoToGallery() {
 }
 ```
 
-Then, open `tab2.page.html` and call the `addPhotoToGallery()` function when the FAB is tapped/clicked: 
+Then, open `tab2.page.html` and call the `addPhotoToGallery()` function when the FAB is tapped/clicked:
 
 ```html
 <ion-content>
@@ -81,7 +80,7 @@ export interface Photo {
 }
 ```
 
-Back at the top of the file, define an array of Photos, which will contain a reference to each photo captured with the Camera. 
+Back at the top of the file, define an array of Photos, which will contain a reference to each photo captured with the Camera.
 
 ```typescript
 export class PhotoService {
@@ -91,13 +90,13 @@ export class PhotoService {
 }
 ```
 
-Over in the `addNewToGallery` function, add the newly captured photo to the beginning of the Photos array. 
+Over in the `addNewToGallery` function, add the newly captured photo to the beginning of the Photos array.
 
 ```typescript
   const capturedPhoto = await Camera.getPhoto({
-    resultType: CameraResultType.Uri, 
-    source: CameraSource.Camera, 
-    quality: 100 
+    resultType: CameraResultType.Uri,
+    source: CameraSource.Camera,
+    quality: 100
   });
 
   this.photos.unshift({
@@ -113,17 +112,19 @@ Next, move over to `tab2.page.html` so we can display the image on the screen. A
 <ion-content>
   <ion-grid>
     <ion-row>
-    <ion-col size="6" 
-      *ngFor="let photo of photoService.photos; index as position">
+      <ion-col
+        size="6"
+        *ngFor="let photo of photoService.photos; index as position"
+      >
         <ion-img [src]="photo.webviewPath"></ion-img>
-    </ion-col>
+      </ion-col>
     </ion-row>
   </ion-grid>
 
   <!-- ion-fab markup  -->
 </ion-content>
 ```
 
-Save all files. Within the web browser, click the Camera button and take another photo. This time, the photo is displayed in the Photo Gallery! 
+Save all files. Within the web browser, click the Camera button and take another photo. This time, the photo is displayed in the Photo Gallery!
 
 Up next, we’ll add support for saving the photos to the filesystem, so they can be retrieved and displayed in our app at a later time.

docs/angular/your-first-app/3-saving-photos.md

@@ -24,7 +24,7 @@ public async addNewToGallery() {
     source: CameraSource.Camera, // automatically take a new photo with the camera
     quality: 100 // highest quality (0 to 100)
   });
-  
+
   // Save the picture and add it to photo collection
   const savedImageFile = await this.savePicture(capturedPhoto);
   this.photos.unshift(savedImageFile);
@@ -43,7 +43,7 @@ private async savePicture(cameraPhoto: CameraPhoto) {
   const savedFile = await Filesystem.writeFile({
     path: fileName,
     data: base64Data,
-    directory: FilesystemDirectory.Data
+    directory: Directory.Data
   });
 
   // Use webPath to display the new image instead of base64 since it's
@@ -63,7 +63,7 @@ private async readAsBase64(cameraPhoto: CameraPhoto) {
   const response = await fetch(cameraPhoto.webPath!);
   const blob = await response.blob();
 
-  return await this.convertBlobToBase64(blob) as string;  
+  return await this.convertBlobToBase64(blob) as string;
 }
 
 convertBlobToBase64 = (blob: Blob) => new Promise((resolve, reject) => {

docs/angular/your-first-app/4-loading-photos.md

@@ -6,7 +6,7 @@ sidebar_label: Loading Photos
 
 We’ve implemented photo taking and saving to the filesystem. There’s one last piece of functionality missing: the photos are stored in the filesystem, but we need a way to save pointers to each file so that they can be displayed again in the photo gallery.
 
-Fortunately, this is easy: we’ll leverage the Capacitor [Storage API](https://capacitor.ionicframework.com/docs/apis/storage) to store our array of Photos in a key-value store. 
+Fortunately, this is easy: we’ll leverage the Capacitor [Storage API](https://capacitor.ionicframework.com/docs/apis/storage) to store our array of Photos in a key-value store.
 
 ## Storage API
 
@@ -50,7 +50,7 @@ for (let photo of this.photos) {
   // Read each saved photo's data from the Filesystem
   const readFile = await Filesystem.readFile({
       path: photo.filepath,
-      directory: FilesystemDirectory.Data
+      directory: Directory.Data
   });
 
   // Web platform only: Load the photo as base64 data

docs/angular/your-first-app/5-adding-mobile.md

@@ -66,7 +66,7 @@ Next, update the `savePicture()` method. When running on mobile, set `filepath`
     const savedFile = await Filesystem.writeFile({
       path: fileName,
       data: base64Data,
-      directory: FilesystemDirectory.Data
+      directory: Directory.Data
     });
 
     if (this.platform.is('hybrid')) {
@@ -104,7 +104,7 @@ public async loadSaved() {
       // Read each saved photo's data from the Filesystem
       const readFile = await Filesystem.readFile({
           path: photo.filepath,
-          directory: FilesystemDirectory.Data
+          directory: Directory.Data
       });
 
       // Web platform only: Load the photo as base64 data

docs/angular/your-first-app/6-deploying-mobile.md

@@ -53,12 +53,13 @@ In order for some native plugins to work, user permissions must be configured. I
 
 ![Xcode Custom iOS Target Properties](/img/guides/first-app-cap-ng/xcode-info-plist.png)
 
-
 Each setting in `Info.plist` has a low-level parameter name and a high-level name. By default, the property list editor shows the high-level names, but it's often useful to switch to showing the raw, low-level names. To do this, right-click anywhere in the property list editor and toggle "Raw Keys/Values."
 
-Locate the `NSCameraUsageDescription` Key (it should exist already if you followed along with this tutorial) and set the Value to something that describes why the app needs to use the camera, such as "To Take Photos." The Value field is displayed to the app user when the permission prompt opens.
+Add the `NSCameraUsageDescription` Key and set the Value to something that describes why the app needs to use the camera, such as "To Take Photos." The Value field is displayed to the app user when the permission prompt opens.
+
+Follow the same process to add the other two Keys required of the Camera plugin: `NSPhotoLibraryAddUsageDescription` and `NSPhotoLibraryUsageDescription`.
 
-Next, click on `App` in the Project Navigator on the left-hand side, then within the `Signing & Capabilities` section, select your Development Team. 
+Next, click on `App` in the Project Navigator on the left-hand side, then within the `Signing & Capabilities` section, select your Development Team.
 
 ![Xcode - Selecting Development Team](/img/guides/first-app-cap-ng/xcode-signing.png)
 

docs/angular/your-first-app/7-live-reload.md

@@ -4,13 +4,13 @@ sidebar_label: Live Reload
 
 # Rapid App Development with Live Reload
 
-So far, we’ve seen how easy it is to develop a cross-platform app that works everywhere. The development experience is pretty quick, but what if I told you there was a way to go faster?  
+So far, we’ve seen how easy it is to develop a cross-platform app that works everywhere. The development experience is pretty quick, but what if I told you there was a way to go faster?
 
-We can use the Ionic CLI’s [Live Reload functionality](https://ionicframework.com/docs/cli/livereload) to boost our productivity when building Ionic apps. When active, Live Reload will reload the browser and/or WebView when changes in the app are detected. 
+We can use the Ionic CLI’s [Live Reload functionality](https://ionicframework.com/docs/cli/livereload) to boost our productivity when building Ionic apps. When active, Live Reload will reload the browser and/or WebView when changes in the app are detected.
 
 ## Live Reload
 
-Remember `ionic serve`? That was Live Reload working in the browser, allowing us to iterate quickly. 
+Remember `ionic serve`? That was Live Reload working in the browser, allowing us to iterate quickly.
 
 We can also use it when developing on iOS and Android devices. This is particularly useful when writing code that interacts with native plugins - we must run it on a device to verify that it works. Therefore, being able to quickly write, build, test, and deploy code is crucial to keeping up our development speed.
 
@@ -29,9 +29,9 @@ The Live Reload server will start up, and the native IDE of choice will open if
 With Live Reload running and the app open on your device, let’s implement photo deletion functionality. Open `tab2.page.html` and add a new click handler to each `<ion-img>` element. When the app user taps on a photo in our gallery, we’ll display an [Action Sheet](https://ionicframework.com/docs/api/action-sheet) dialog with the option to either delete the selected photo or cancel (close) the dialog.
 
 ```html
-<ion-col size="6" 
+<ion-col size="6"
     *ngFor="let photo of photoService.photos; index as position">
-  <ion-img [src]="photo.webviewPath" 
+  <ion-img [src]="photo.webviewPath"
            (click)="showActionSheet(photo, position)"></ion-img>
 </ion-col>
 ```
@@ -41,7 +41,7 @@ Over in `tab2.page.ts`, import Action Sheet and add it to the constructor:
 ```typescript
 import { ActionSheetController } from '@ionic/angular';
 
-constructor(public photoService: PhotoService, 
+constructor(public photoService: PhotoService,
             public actionSheetController: ActionSheetController) {}
 ```
 
@@ -98,7 +98,7 @@ public async deletePicture(photo: Photo, position: number) {
 
   await Filesystem.deleteFile({
     path: filename,
-    directory: FilesystemDirectory.Data
+    directory: Directory.Data
   });
 }
 ```

docs/components.md

@@ -1,4 +1,6 @@
 ---
+title: UI Components | User Interface Application Building Components
+description: Ionic Framework comes stock with a number of high-level UI components, including cards, lists, and tabs to quickly and easily build your app's user interface.
 hide_table_of_contents: true
 ---
 
@@ -50,7 +52,7 @@ import DocsCards from '@site/src/components/DocsCards';
     <p>Floating action buttons are circular buttons that perform a primary action on a screen.</p>
   </DocsCard>
 
-  <DocsCard header="Icons" href="https://ionicons.com" img="/icons/feature-component-icons-icon.png">
+  <DocsCard header="Icons" href="https://ionic.io/ionicons" img="/icons/feature-component-icons-icon.png">
     <p>Beautifully designed icons for use in web, iOS, Android, and desktop apps.</p>
   </DocsCard>
 

docs/intro/cdn.md

@@ -159,4 +159,4 @@ Ionicons is packaged by default with the Ionic Framework, so no installation is
 <script nomodule src="https://cdn.jsdelivr.net/npm/ionicons/dist/ionicons/ionicons.js"></script>
 ```
 
-> See [Ionicons usage](https://ionicons.com/usage) for more information on using Ionicons.
+> See [Ionicons usage](https://ionic.io/ionicons/usage) for more information on using Ionicons.