The motivation behind this wiki is to advice what steps need to be done in order to start using Fundamental Library for Angular.

It is applicable for an existing Angular application. In case you want to create a new application from scratch you can use @angular/cli.

1. Installing with angular-cli

   ng add @fundamental-ngx/core
   // For versions prior to 0.10 use fundamental-ngx (ng add fundamental-ngx)
   // Currently intended for npm versions lower than 7.x.x
   

2. Installing without angular-cli

   npm install @fundamental-ngx/core
   // For versions prior to 0.10 use fundamental-ngx:
   // (npm install fundamental-ngx)
   

   For fundamental-ngx version 0.16.* or higher: The fonts and the icons must be added to your project separately. Fonts and icons can be found at @sap-theming/theming-base-content.

   • Add the following to your root styles file (e.g. styles.scss):

   @font-face {
    font-family: '72';
    src: url('~@sap-theming/theming-base-content/content/Base/baseLib/baseTheme/fonts/72-Regular-full.woff') format('woff');
    font-weight: normal;
    font-style: normal;
   }
   
   @font-face {
    font-family: '72';
    src: url('~@sap-theming/theming-base-content/content/Base/baseLib/baseTheme/fonts/72-Light.woff') format('woff');
    font-weight: 300;
    font-style: normal;
   }
   
   @font-face {
    font-family: '72';
    src: url('~@sap-theming/theming-base-content/content/Base/baseLib/baseTheme/fonts/72-Bold.woff') format('woff');
    font-weight: 700;
    font-style: normal;
   }
   
   @font-face {
    font-family: 'SAP-icons';
    src: url('~@sap-theming/theming-base-content/content/Base/baseLib/baseTheme/fonts/SAP-icons.woff') format('woff');
    font-weight: normal;
    font-style: normal;
   }
   
   @font-face {
    font-family: 'BusinessSuiteInAppSymbols';
    src: url('~@sap-theming/theming-base-content/content/Base/baseLib/baseTheme/fonts/BusinessSuiteInAppSymbols.woff') format('woff');
    font-weight: normal;
    font-style: normal;
   }
   
   @font-face {
    font-family: 'SAP-icons-TNT';
    src: url('~@sap-theming/theming-base-content/content/Base/baseLib/baseTheme/fonts/SAP-icons-TNT.woff') format('woff');
    font-weight: normal;
    font-style: normal;
   }
   

   • Add to the styles array of the angular.json file:

   "node_modules/fundamental-styles/dist/icon.css"
   // For ngx with version lower than 0.12.0, add "node_modules/fundamental-styles/dist/fundamental-styles.min.css"
   

   Configure your animations.

   Install angular animations by running the following.

   npm install @angular/animations
   

   Once the above package is installed, open app.module.ts and import BrowserAnimationsModule to enable the animations:

   import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
   
   @NgModule({
     ...
     imports: [BrowserAnimationsModule],
     ...
   })
   export class DemoModule { }

   Alternatively, you can disable the animations by importing NoopAnimationsModule instead.

3. Import the modules you want to use.

   To add the entire library, add the following import to your main application module.

   import { FundamentalNgxCoreModule } from '@fundamental-ngx/core';
   // For versions prior to 0.10 use:
   // import { FundamentalNgxModule } from 'fundamental-ngx';
   
   
   @NgModule({
       ...
       imports: [FundamentalNgxCoreModule],
       // for versions prior to 0.10 use instead:
       // imports: [FundamentalNgxModule],
   })
   export class DemoModule { }

   To include an individual Angular Fundamental component in your application, you only need to import the relevant module.

   For example, to use Checkboxes, add the following import to your main application module.

   import { CheckboxModule } from '@fundamental-ngx/core/checkbox';
   
   // For versions prior to 0.10 use fundamental-ngx package
   
   
   @NgModule({
       ...
       imports: [CheckboxModule],
   })
    export class DemoModule { }

4. Add the component to your HTML.

   <fd-checkbox label="Fundamental Ngx Checkbox"></fd-checkbox>

   For more sample codes, please check out @Fundamental-NGX/Core. E.g. Moment Datetime Adapter.

1. Installing with angular-cli

   ng add @fundamental-ngx/platform
   // For versions prior to 0.10 use fundamental-ngx (ng add fundamental-ngx)
   // Currently intended for npm versions lower than 7.x.x
   

2. Installing without angular-cli

   npm install @fundamental-ngx/platform
   // For versions prior to 0.10 use fundamental-ngx:
   // (npm install fundamental-ngx)
   

3. Installing core dependent library

   Install @fundamental-ngx/core according to the steps above.

4. Installing lodash-es library

   npm i lodash-es

   Using yarn?

   yarn add lodash-es

5. Import the modules you want to use.

   To add the entire library, add the following import to your main application module.

   import { FundamentalNgxPlatformModule } from '@fundamental-ngx/platform';
   // For versions prior to 0.11.1 use fundamental-ngx package
   
   @NgModule({
       ...
       imports: [FundamentalNgxPlatformModule],
   })
   export class DemoModule { }

   To include an individual Angular Fundamental component in your application, you only need to import the relevant module.

   For example, to use Link, add the following import to your main application module.

   import { PlatformLinkModule } from '@fundamental-ngx/platform/link';

   Note: Be careful while importing the entire FundamentalNgxPlatformModule as it loads all modules; we recommend to only import relevant modules as needed.

6. Add the component to your HTML

   <fdp-link [href]="'http://www.google.com'" [title]="'Extra info as tooltip text and aria-label'">
       Standard Link
   </fdp-link>

If you're using Jest with jest-preset-angular you may see the following errors:

Unexpected value 'FundamentalNgxCoreModule' imported by the module 'DynamicTestModule'. Please add an @NgModule annotation.

This is happens because we publish library compiled with Template Engine (not Ivy) and NGCC doesn't compile it correctly because of settings in the preset.

To fix such errors please add this to your package.json and reinstall npm packages.

"postinstall-ivy": "ngcc --properties es2015 browser module main --first-only --create-ivy-entry-points",
"postinstall-ivy-umd": "ngcc --properties main --create-ivy-entry-points",
"postinstall": "npm run postinstall-ivy && npm run postinstall-ivy-umd"

If you're using Jest for running tests in the host application some additional steps needed to be done due to the Jest issues with importing ES modules.

1. Install lodash package as the development dependency. npm i -D lodash Using yarn? yarn add -D lodash Don't worry, as we're installing package as the development dependency it won't increase build size.

2. Adjust Jest config (jest.config.js) by adding these lines:

   moduleNameMapper: {
     "^lodash-es$": "lodash"
   },
   

That's it. In case of any issues please raise the issue in the github repository.