@talenra/components documentation

Tutorial: Build a Simple App

In this tutorial we're going to setup and build a very basic single page app (SPA) using Talenra component library for Angular. Start with this tutorial if you never used Talenra before.

The source of the sample app built in this tutorial is available through the main branch of our tutorials repository.

Prerequisites

Make sure you're set-up to install @talenra packages through the Talenra registry. For details, please refer to the section "Setup and Installation" of the README file.

For guidance on how to setup a new Angular project, please refer to the Angular documentation.

Generate a New Angular App

First we bootstrap our app using ng new. As we won't deal with unit testing in this tutorial, you can omit generation of tests using --skip-tests.

Example :
ng new talenra-tutorials --skip-tests

The command above will scaffold a new Angular app using the latest stable release of Angular. If you need to use a legacy version of Angular, you can use npx to define the preferred version: npx @angular/cli@19 new talenra-tutorials --skip-tests.

When prompted choose SCSS for styling. For this tutorial we do not need server-side rendering (SSR), so you can safely say "no" when prompted. After the app has been scaffolded switch to the app's directory.

Example :
cd talenra-tutorials

Install and Setup the Required @talenra Packages

Install the three Talenra libraries required in this tutorial:

  • Talenra Base (@talenra/components)
  • Talenra Icons (@talenra/icons)
  • Talenra Stylebox (@talenra/stylebox)
Example :
npm add @talenra/components @talenra/icons @talenra/stylebox

Add the Talenra icon font to the global stylesheet.

Example :
// src/styles.scss
@use '@talenra/icons/styles';

Add the normalize stylesheet from Talenra Stylebox to the global stylesheet.

Example :
// src/styles.scss
@use '@talenra/icons/styles';
@use '@talenra/stylebox';

@include stylebox.normalize();

Finally we're going to include the fonts required by the UI (Roboto Light 300, Regular 400 and Medium 500).

  • Go to Google Fonts and download Roboto font.
  • Pick the three font files (Roboto-Light.ttf, Roboto-Regular.ttf and Roboto-Medium.ttf) and move them to the directory public/fonts. Create the directory if it does not exist.
  • In the same directory create a CSS file named main.css and add the following snippet to specify the font.
Example :
/* public/fonts/main.css */
@font-face {
  font-family: 'Roboto';
  font-style: normal;
  font-weight: 300;
  font-display: swap;
  src: url(Roboto-Light.ttf) format('truetype');
}

@font-face {
  font-family: 'Roboto';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url(Roboto-Regular.ttf) format('truetype');
}

@font-face {
  font-family: 'Roboto';
  font-style: normal;
  font-weight: 500;
  font-display: swap;
  src: url(Roboto-Medium.ttf) format('truetype');
}

Then add a reference to the CSS file we just created in your app's Angular configuration file.

Example :
// angular.json
// projects › talenra-tutorials › architect › build › options
"styles": [
  "src/styles.scss",
  "public/fonts/main.css" // <--
]

Load Default Base Component Language File

The Talenra Base package comes with a default language file which contains the most common labels and messages used in the UI. This file can be loaded into your app.config.ts and be provided to your app.

Example :
// src/app/app.config.ts
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { provideRouter } from '@angular/router';

import { provideTalenraBaseConfig } from '@talenra/components/config'; // <--
import { TalenraBaseTranslations } from '@talenra/components/locales'; // <--

import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }),
    provideRouter(routes),
    provideTalenraBaseConfig({
      translation: {
        ...TalenraBaseTranslations.deCH.translations,
      },
    }),
  ],
};

App Layout

Now import the AppFrameComponent from the Base library and place it in the app's template. Additionally you can safely delete the title property as we won't need it in our app.

Example :
// src/app/app.component.ts
import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { AppFrameComponent } from '@talenra/components/app-layout'; // <--

@Component({
  selector: 'app-root',
  imports: [
    RouterOutlet,
    AppFrameComponent, // <--
  ],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss',
})
export class AppComponent {
  title = 'talenra-tutorials'; // Delete this line
}

Next replace Angular's welcome screen in your app with the <talenra-app-frame> component. The component provides the base layout and some base styles like font-family, box-sizing etc.

Example :
<!-- src/app/app.component.html -->
<talenra-app-frame />

Now you're ready to run your dev server and check the result in your browser. You should see the Talenra base layout – without any content.

Example :
ng serve

In the next step, we will add some content. Check the docs for details.

Example :
<!-- src/app/app.component.html -->
<talenra-app-frame issuerName="SVA Zürich" appName="Simple App" appVersion="2.32.3" />

Let us add some items to the side navigation using AppFrameComponent's sidenavItems property.

Example :
// src/app/app.component.ts
import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { AppFrameComponent, SidenavItem } from '@talenra/components/app-layout'; // <--

@Component({
  selector: 'app-root',
  imports: [RouterOutlet, AppFrameComponent],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss',
})
export class AppComponent {
  // Sidenav items
  protected sidenavItems: SidenavItem[] = [
    { label: 'Welcome', icon: 'beach-access', destination: '/welcome' },
    { label: 'My Feature', icon: 'assignment', destination: '/my-feature' },
  ];
}
Example :
<!-- src/app/app.component.html -->
<talenra-app-frame issuerName="SVA Zürich" appName="Simple App" appVersion="2.32.3" [sidenavItems]="sidenavItems" />

Welcome Screen

Next we're going to create a welcome component which we will later display when "Welcome" is clicked in the side navigation.

Example :
ng generate component welcome --skip-tests --skip-selector

We won't care about the welcome component's content for now, but add a basic horizontal layout, which is included in the Talenra Base package (@talenra/components).

Example :
// src/app/welcome/welcome.component.ts
import { Component } from '@angular/core';
import { WorkspaceSimpleComponent } from '@talenra/components/workspace-simple'; // <--

@Component({
  imports: [WorkspaceSimpleComponent], // <--
  templateUrl: './welcome.component.html',
  styleUrl: './welcome.component.scss',
})
export class WelcomeComponent {}
Example :
<!-- src/app/welcome/welcome.component.html -->
<talenra-workspace-simple>
  <p>welcome works!</p>
</talenra-workspace-simple>

That's it. The <talenra-workspace-simple> ensures the welcome screen will comply with the Talenra layout grid. If you resize your browser, you'll notice the horizontal margin and the max-width applied to our welcome component. Before testing the result in the browser we'll add another component and implement routing.

App Features and Routing

A component displayed within the <talenra-app-frame> is referred a "feature". Typically, features are lazy-loaded. In the next step we're going to add the feature MyFeatureComponent.

Example :
ng generate component features/my-feature --skip-tests --skip-selector

Before we're going to fine-tune the boilerplate created by ng generate, we will setup routing so we can test the app in the browser.

We have two paths (the ones we already used when we setup the side navigation): /welcome shall point to our welcome component while /my-feature shall load and display MyFeatureComponent. Everything else is redirect to /welcome for now.

Example :
// src/app/app.routes.ts
import { Routes } from '@angular/router';
import { WelcomeComponent } from './welcome/welcome.component';

export const routes: Routes = [
  { path: 'welcome', component: WelcomeComponent },
  {
    path: 'my-feature',
    loadComponent: () => import('./features/my-feature/my-feature.component').then((c) => c.MyFeatureComponent),
  },
  { path: '**', redirectTo: 'welcome' },
];

We're almost good to go. Put the router outlet in place and test the app in your browser.

Example :
<!-- src/app/app.component.html -->
<talenra-app-frame issuerName="SVA Zürich" appName="Simple App" appVersion="2.32.3.2" [sidenavItems]="sidenavItems">
  <router-outlet />
</talenra-app-frame>

Let us implement a layout as we did with the WelcomeComponent. This time we will add a header too.

First we need to import the required components from the library to our feature component.

Example :
// src/app/features/my-feature/my-feature.component.ts
import { Component } from '@angular/core';
import { WorkspaceHeaderComponent } from '@talenra/components/workspace-header'; // <--
import { WorkspaceSimpleComponent } from '@talenra/components/workspace-simple'; // <--

@Component({
  imports: [WorkspaceHeaderComponent, WorkspaceSimpleComponent], // <--
  templateUrl: './my-feature.component.html',
  styleUrl: './my-feature.component.scss',
})
export class MyFeatureComponent {}

All that's left to do is to apply the layout to our feature and add the header.

Example :
<!-- src/app/features/my-feature/my-feature.component.html -->
<talenra-workspace-simple>
  <talenra-workspace-header [path]="[ { label: 'My Feature' } ]" title="Welcome to My Feature" />
  <p>my-feature works!</p>
</talenra-workspace-simple>

Congrats! You just created a basic Talenra app. 🎉

results matching ""

    No results matching ""