Skip to main content

3 posts tagged with "angular-beam"

View All Tags

Angular Beam 1.1.0

· 10 min read
Dries Ryckbosch
Dries Ryckbosch
Engineer
Wout Vanhaelewijck
Wout Vanhaelewijck
Front-End Engineer
caution

The beam is currently a release candidate. We will be collecting feedback before a full production-ready release is made.

Changes and improvements​

New styling​

The @nsx/ngx-ns-core runtime library was updated to version 4.5.0. The expanded CRUD pages got a refreshed look:

  • Add/edit forms, detail views, the user page and the application properties dialog get a light background, padding and rounded corners.
  • Table cells no longer wrap, so all rows have the same height. Values that do not fit are cut off with an ellipsis, the column can be resized to show more.
  • Multi-link fields are shown as a comma-separated list in tables and details.
  • BigStrings in detail views are cut off after 3 lines, with a button to show the entire value.
  • The default titles of list and detail pages and the labels of data child tabs are easier to read (e.g. Certification type overview instead of CertificationType Overview).
  • DataChildren tabs on the detail views have a new look and display their content in a box. The first tab is also automatically opened.

The new styling is already present on the Expander Exchange

Faster builds​

  • isolatedModules and skipLibCheck are enabled in the tsconfig.json.
  • Component stylesheets only import the ngx-ns-core abstracts instead of the full library.

These changes lead to build times that are significantly faster and also reduce the bundle size. Several users have experienced build times that are twice as fast.

The sidebar menu now supports groups. The base feature modules (account, assets, utils, ...) are grouped under a base group in the default full menu config. The collapsed state of the sidebar is now part of the menu service, so any component can collapse or expand the sidebar.

Filtering and searching​

  • Finders with the In or Nin operator use a multi-select.
  • Finders with the Lk (like) operator match values that contain the search text, the same as in Knockout.
  • The new angular.defaultSelectedFilter option on a DataView preselects a filter when the page opens.
  • The search bar is focused when a list page opens, and the first field of the filter form is focused when a filter is picked.
  • The filter of a data child follows its parent, also when navigating between parents with the entry paginator.
  • Multiple querySearches can be used in the frontend when using the standard-api.

Form field dependencies​

The new angular.hasFormFieldDependencies option on a DataView expands a skeleton to easily define dependencies between form fields for the add and edit forms. In combination with the angular-finder-expanders, the isLinkDriver option on a field is supported: when the driver field changes, the link target field is cleared and its options are filtered with the finder from the option.

Sorting on link fields was already possible using the service-api, but it is now possible using the standard-api as well. Requires standard-api-beam::2.1.0-rc1+ and jee-backend-beam::1.2.0-rc1+ (or minimal-jee-beam::2.7.0-rc1+)

Tables can be sorted on Ln02 link field columns. The sorting uses the name of the linked instance.

Authentication and authorization​

  • When the initial login with the identity provider fails, the user is navigated to the login page with an error instead of seeing a blank page.
  • Data child tabs on a details page are hidden when the user is not allowed to see the list page of the child.
  • Authorization denials are no longer cached when a request fails due to a connectivity error.

Migration guide​

Migrate using AI​

Copy the prompt below and let an AI agent do the heavy lifting. Keep in mind that you are still responsible for the migration so verify the migration yourself.

Update this project to the angular-beam::1.1.0-rc1. Update the expansionSettings and update the custom code. Take care to keep behavior the same. Mention any unexpected changes and changes that need to be made in feature anchors. You can use the migration guide at https://foundation.stars-end.net/docs/developer-hub/blog/angular-beam-1.1.0 for more info.

Versions​

The angular-beam::1.1.0-rc1 requires:

  • net.democritus:base-components::2026.7.0 or higher.
  • net.democritus:querysearch-expanders::3.9.0 or higher.

Both of these requirements can be satisfied by updating beams. See below on which versions you need to use.

expansionSettings.xml
<expansionResources>
...
<expansionResource name="org.normalizedsystems.beam:jee-backend-beam" version="1.2.0-rc1"/>
<!-- or -->
<expansionResource name="org.normalizedsystems.beam:minimal-jee-beam" version="2.7.0-rc1"/>

<expansionResource name="org.normalizedsystems.beam:angular-beam" version="1.1.0-rc1"/>
<expansionResource name="net.democritus.angular.stdapi:angular-stdapi-expanders" version="4.4.0"/>
<expansionResource name="org.normalizedsystems.beam:standard-api-beam" version="2.1.0-rc1"/>
</expansionResources>

Dependencies​

The following npm dependencies are updated by the angular-expanders:

-    "@ngx-translate/core": "17.0.0",
- "@nsx/ngx-ns-core": "3.0.0",
+ "@ngx-translate/core": "18.0.0",
+ "@nsx/ngx-ns-core": "4.5.0",

If your project uses @nsx/ngx-ns-charts, keep its version the same as the @nsx/ngx-ns-core version.

With @ngx-translate/core 18, getCurrentLang() can return undefined. Custom code that calls it may need a fallback, e.g. translateService.getCurrentLang() ?? ''.

Styling changes​

The @nsx/ngx-ns-core runtime library was updated from version 3.0.1 to 4.5.0. These changes contain styling changes and are automatically applied through the angular-expanders. You need to update custom styling to work with the new styling.

However, if you want to revert to the old styling you can follow these steps (keep in mind that this is custom styling, this will not be kept up-to-date and is not recommended):

  1. Include the _legacy-3.0.1-theme.scss file in your project at /src/styles/themes/_legacy-3.0.1-theme.scss
  2. Use the theme in your /src/styles/main.scss
/* --- themes --- */
@use 'themes/default-theme';
// @anchor:themes:start
// @anchor:themes:end
// anchor:custom-themes:start
@use 'themes/legacy-3.0.1-theme'; // Add this line
// anchor:custom-themes:end

Data access​

The legacy authorization mapping is now data driven. The <dataElement>-access-action-right-legacy-mapper.service.ts and <dataElement>-view-action-right-legacy-mapper.service.ts services are no longer expanded. Instead, each feature module expands one constants/<featureModule>-action-right-legacy-targets.ts file, and the operations are mapped in core/constants/action-right-legacy-operations.ts. The resulting legacy rights are the same as before.

car-action-right-legacy-targets.ts
export const carActionRightLegacyTargets: ReadonlyMap<string, string> = new Map<string, string>([
['car.access.carBrand', 'benefits.carBrand'],
...
// anchor:custom-legacy-targets:start
// anchor:custom-legacy-targets:end
]);

export const carActionRightLegacyRights: ReadonlyMap<string, string> = new Map<string, string>([
// anchor:custom-legacy-rights:start
// anchor:custom-legacy-rights:end
]);

To migrate:

  • Move custom code from the custom-legacy-mapper anchor of the old services to custom-legacy-rights (to map a full right) or custom-legacy-targets (to map a prefix).
  • Custom code that injects one of the old *ActionRightLegacyMapperService classes should use the ActionRightLegacyMapperService instead.
  • Remove the old service files from your project.

Other changes:

  • Access rights relating to a DataConnector now use the FeatureModule of the DataConnector. Check your data access configuration when a DataView uses a DataConnector of another FeatureModule.
  • Data child tabs require the canSeeFetchPage view right of the child data view. Check your data access configuration if child tabs are missing.
  • AuthorizationService.isAuthorizedFor() rethrows connectivity errors (status 0, 502, 503, 504) instead of treating them as "not authorized". Custom code that subscribes to it directly should handle these errors.

Filter translations​

Translations for filter fields are now specified per Finder or QuerySearch instead of in a shared filterFields block. This prevents translation key collisions between filters. Custom translations should be updated:

-        "filterFields": {
- "name": "Name",
- "awardedTo": "AwardedTo"
- },
+ "findByNameEq": {
+ "name": "Name"
+ },
+ "findByAwardedToEq": {
+ "awardedTo": "AwardedTo"
+ },

Advanced​

SCSS import path of ngx-ns-core​

The ngx-ns-core palettes, mixins and variables have moved to a separate entry. The expanded stylesheets now use:

- @use '@nsx/ngx-ns-core' as ns-core;
+ @use '@nsx/ngx-ns-core/abstracts' as ns-core;

Custom stylesheets that use @use '@nsx/ngx-ns-core' for palettes or mixins should change to @nsx/ngx-ns-core/abstracts. The rich text editor styles are no longer part of @nsx/ngx-ns-core; they are included once in main.scss with @use '@nsx/ngx-ns-core/rich-text';.

  • getSearchBarLabel() of the search bar coordinators now returns a translation key instead of the translated text. Custom code in the get-search-bar-label-* anchors should return a key and should not use the TranslateService.
  • Search bars and filters on a field with the Lk operator wrap the value in %. Custom code that adds the % itself, or reads the filter value and expects it without %, should be checked.
  • New model validations require that finder exists for a data child that has a search bar. Implement the necessary finders to solve these model validations if you encounter them.

MenuItem is now part of the new MenuEntry type, and the collapsed state of the sidebar moved from the LayoutComponent to the menu service.

- import { MenuItem } from '@nsx/ngx-ns-core/sidebar-menu'
+ import { MenuEntry } from '@nsx/ngx-ns-core/sidebar-menu'

export interface Menu {
- readonly menuItems: Signal<MenuItem[]>;
+ readonly menuItems: Signal<MenuEntry[]>;
+ readonly isMenuCollapsed: Signal<boolean>;

- setMenuItems({menuItems}: { menuItems: MenuItem[] }): void;
+ setMenuItems({menuItems}: { menuItems: MenuEntry[] }): void;
...
+ toggleMenuCollapse(): void;
+ setMenuCollapsed({collapsed}: { collapsed: boolean }): void;
}

Custom menu configurations, custom Menu implementations and custom code that uses LayoutComponent.isSidebarCollapsed should be updated.

User page​

This only affects projects using Angular and the standard-api

The user page (account/pages/user/user-my-page) is now expanded by the account base feature module. It fetches the logged-in user with the new /account/user/session/me endpoint of the base-components.

  • The selector changed from nsx-user-my-page to account-user-my-page.
  • Users need the account.user.myuser data access right to be able to access this endpoint.

Custom branding​

This only affects projects using Angular and the standard-api

If the angularApp uses the angular.hasCustomBranding option, the image of the application properties button is no longer expanded. To keep it, add the following harvest in application-properties-button.component.html:

<!-- anchor:custom-branding-application-properties:start -->
<img src="assets/images/app-properties.svg"
class="properties-icon"
alt="properties-logo">
<!-- anchor:custom-branding-application-properties:end -->

You will need to provide the app-properties.svg asset yourself too and add it as an ext file.

Login validation​

The custom-validate-login anchor in the auth service was placed after the return, so custom code in it never ran. It now runs before the return. Check that existing custom code in this anchor still does what you expect.

TypeScript configuration​

isolatedModules and skipLibCheck are enabled in the tsconfig.json. With isolatedModules:

  • Re-exports of types need export type.
  • A const enum can no longer be used from another file.

Removed legacy options​

The following backwards compatibility options are removed. Remove them from your model and update custom code that depends on them.

OptionBehavior now
angular.legacy.table.useModelProjectionThe table of a DataView always uses the Table projection.
angular.legacy.tokensThe DataView related tokens are only available in <dataView>-view.tokens.
angular.legacy.segment-parameter-mapper.genericThe specific FilterSegmentParameterMapper is always used.
angular.legacy.data-access.error-handling.generic (service-api only)The data access services always use the specific error handling.

Filters with the In operator​

Finders with the In or Nin operator now use a multi-select, and the filter field becomes a list.

-  profile?: Reference | null;
+ profileList?: Reference[] | null;

Custom code that uses the filter field or the form control should be updated. The related anchors are renamed as well, e.g. custom-profile-validators -> custom-profileList-validators. Move custom code from the old anchors to the new ones.

Angular Beam 1.0.0

· 6 min read
Dries Ryckbosch
Dries Ryckbosch
Engineer
Wout Vanhaelewijck
Wout Vanhaelewijck
Front-End Engineer

Changes and improvements​

Angular 22​

The angular-expanders have upgraded to Angular 22. It is possible to use the new features and enhancements of this update. Angular 22 also addresses various security vulnerabilities.

Base feature modules​

This is only available when using the standard-api

The base-components (account, assets, utils) could be accessed through the knockout UI, but this wasn't yet possible in the Angular UI. Now that has changed. Next to the base-components there are now base-feature-modules which allow us to include some default feature modules. With this update there are corresponding feature modules for the account, assets and utils base components. Allowing you to access and update these components and data elements just as in the knockout UI.

Account component

This includes a custom My User page accessible via the user icon in the top right. On this page users can see their own info and change their password (the password only applies for basic auth). The ability to view their info and change their password can be configured through the data access.

Include base feature modules

You have to add the base feature modules to your angularApp manually or by using the GenerateDefaultAngularApp transmuter.

AngularApp
<angularApp
xmlns="https://schemas.normalizedsystems.org/xsd/angularProjects/7/0/0"
type="angularProjects::AngularApp">
...
<featureModules>
...
<featureModule>utils</featureModule>
<featureModule>account</featureModule>
<featureModule>assets</featureModule>
</featureModules>
</angularApp>
  • By default, a menu is expanded to access each data view.
  • More customization possibilities e.g. change the menu based on the user profile.
  • A new method updateIcon was added. This method changes the icon of a MenuItem at runtime.

Application properties​

This is only available when using the standard-api

You can access the application properties through a button in the bottom left of the sidebar. This will show metadata about the application, such as the version, used expansion resources and more.

Application properties

Direct imports​

The imports defined in the mapping files of Angular expanders required the use of the from keyword. However some imports don't use, and can't use the from keyword. Therefore a new direct import type has been created to allow imports without the from keyword.

<uses type="direct" eval="'prismjs'"/>  // import "prismjs";

Generate default Angular app​

The GenerateDefaultAngularApp transmuter will add an AngularApp to your project, if not already present. It will also generate FeatureModules, DataConnectors and DataViews based no the elements model. The transmuter can be performed multiple times and is a great way to keep the elements model and Angular model in sync.

Transmutation
GenerateDefaultAngularAppApplication

Generate a FeatureModule per Component, and a DataConnector and DataView per DataElement, where the noViewLayer option is not present.

Migration guide​

Versions​

The angular-beam::1.0.0 requires net.democritus:base-components::2026.6.0. The base-components are included in the minimal-jee-beam and jee-backend-beam, so updating them will satisfy this requirement.

expansionSettings.xml
<expansionResources>
...
<expansionResource name="org.normalizedsystems.beam:minimal-jee-beam" version="2.3.0"/>
</expansionResources>
expansionSettings.xml
<expansionResources>
...
<expansionResource name="org.normalizedsystems.beam:jee-backend-beam" version="1.1.0"/>
</expansionResources>

When using Angular in combination with the standard-api as the control layer you should use the following.

expansionSettings.xml
<expansionResources>
...
<expansionResource name="org.normalizedsystems.beam:angular-beam" version="1.0.0"/>
<expansionResource name="net.democritus.angular.stdapi:angular-stdapi-expanders" version="4.0.0"/>
<expansionResource name="org.normalizedsystems.beam:standard-api-beam" version="2.0.0"/>
</expansionResources>

When using Angular in combination with the service-api as the control layer you should use the following.

expansionSettings.xml
<expansionResources>
...
<expansionResource name="org.normalizedsystems.beam:angular-beam" version="1.0.0"/>
<expansionResource name="net.democritus.angular.svcapi:angular-svcapi-expanders" version="3.8.0"/>
<expansionResource name="org.normalizedsystems.beam:service-api-beam" version="1.3.0"/>
</expansionResources>

Angular 22​

Node version requirement​

The minimum required node version has changed to ^22.22.3 || ^24.15.0 || ^26.0.0

Make sure your local machine and Dockerfile satisfy this requirement. The build pipelines on jenkins have been updated to use node 24.19.0.

ChangeDetectionStrategy​

The Default Change Detection Strategy is now OnPush. Angular's change detection uses a more optimized approach by default called ChangeDetectionStrategy.OnPush. This strategy makes components only run change detection when:

  1. An input or Signal variable changes (by reference).
  2. An event originates from the component or its children.
  3. ChangeDetectorRef.markForCheck() is called manually.

This means components with:

  • variables might not update when the variable gets a new value.
protected asyncValue: string = "default value";

myService.getValue().subscribe((newValue) => {
// OnPush won't trigger change detection for a local variable mutation.
this.asyncValue = newValue; // Won't be updated in component's template
});
  • functions in templates are not constantly being run anymore
// DOES NOT WORK AS EXPECTED
// Template: <p>{{ getFormattedName() }}</p>

name = 'Alex';

setTimeout(() => {
this.name = 'Jordan';
// getFormattedName() WILL NOT RE-RUN!
// OnPush won't trigger change detection for a local variable mutation.
}, 1000);

getFormattedName() {
return this.name.toUpperCase();
}

Fix:

  • Use signals and computed signals to define variables
  • Use previous behavior with ChangeDetectionStrategy.Eager (as a last resort)

Redundant Nullish Checks Trigger Compile Errors​

Angular’s strict template type-checker now flags unnecessary optional chaining (?.) or nullish coalescing (??) on non-nullable variables.

// Fails at compile time if `a` is guaranteed non-nullable
const result = a?.b;
const val = a ?? "default";

// Remove redundant operators
const result = a.b;
const val = a;

Optional Chaining Evaluates to undefined​

Short-circuited optional chaining expressions always evaluate to undefined (never null).

// Update strict equality checks expecting `null` to check for `undefined` instead, or use loose equality (`== null`) to catch both.
a?.b?.c === null // false
a?.b?.c === undefined // true
a?.b?.c == null // true

reportProgress deprecation​

The reportProgress field of HTTP requests has been deprecated and replaced by reportDownloadProgress and reportUploadProgress. Custom code that used this should migrate to the new fields.

baseUrl no longer allowed​

The baseUrl field is no longer allowed in the tsconfig.json. Custom paths in the tsconfig should be adjusted.

Data access​

This only affects projects using Angular, standard-api and have enabled the data access in Angular

Fixed incorrect mapping of canSeeUpdatePage, canSeeFilterPage, canSeeFetchPage, canSubmitUpdate, canSubmitFilter and canSubmitFetch in the LegacyMapperService expanders. Instead of mapping to update and fetch they will now map to modify and status. Applications that have configured data access to use update and fetch will have to update them to modify and status.

Custom branding​

  • If the angularApp uses the angular.hasCustomBranding option, The following files have had code replaced by feature anchors as part of a fix.
    • branding-text-font in index.html
    • branding-icon-font in index.html
    • branding-sidebar in layout.component.scss

To migrate add back the following harvests in the corresponding files.

index.html:

-- anchor:custom-branding-icon-font:start
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200"/>
-- anchor:custom-branding-icon-font:end
-- anchor:custom-branding-text-font:start
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Maven+Pro:wght@400;500;700&display=swap" rel="stylesheet">
-- anchor:custom-branding-text-font:end

layout.component.scss:

-- anchor:custom-branding-sidebar:start
img {
height: 100%;
padding: 1.25rem 0 1.25rem 1.25rem;
&.compact-mode {
padding: 1.438rem 0 1.438rem 0.875rem;
}
}
-- anchor:custom-branding-sidebar:end

Angular Beam 0.2.0 (angular-expanders 7.0.0)

· 17 min read
Jan Hardy
Jan Hardy
R&D Engineer
Dries Ryckbosch
Dries Ryckbosch
Engineer

Changes and improvements​

Upgrade to Angular 21 and Angular Material 21​

For this release we updated all the code to Angular 21, in order to stay up to date with the releases and best practices.

Added DataProjection support​

A mechanism has been implemented to facilitate fetching of different DataProjections if the used control layer allows this (std-api). The defaults are set to details for getSingle calls and info for getList calls. This implementation also allows the use of calculated fields with the info projection now.

tip

Double check in your application if the same table columns are still shown. The option cruds.table.hide is now also taken into account.

For the moment, the possible projections are set by a ModelLoadingListener that defaults to the info ($DataConnector$-table.model.ts) and details ($DataConnector$.model.ts) projections. In the future it will be possible to manually define other projections as well.

Added Finder support​

We have added a FinderConnector and QueryConnector that implements the new abstract FilterConnector. This allows to support finders as well as querysearch at the same time (depending on what control layer you are using).

The option hasSearchBar has also been ported. Like in KO this will expand a searchbar in the header of the list page connected to a finder defined by the specified value of the option.

Related to the addition of a universal Filter feature, previously only one querysearch was supported to be used as a filter. This has been changed to any amount of querysearches and finders.

Added Authorization support​

We have added AuthorizationRights to make certain parts of the application not accessible (used in guards, directives, services). These rights can be accessed through the ACTION_AUTHORIZATION_SOURCE InjectionToken, the interface can be provided by a control layer specific implementation, or you can provide your own. Some directives have been added to handle authorization on the most common used components

  • ButtonAuthorizationDirective
  • TableRowActionMenuAuthorizationDirective

These directives handle disabling components as well as showing tooltips on why it is disabled. You can look at these as examples when wanting to use the authorization feature somewhere else.

Added support for swapping out default add/edit with DataOperations​

Using the following tags you can now conditionally turn of some expanders:

  • #angular.data-view.action.add.custom: disable default add page.
  • #angular.data-view.action.edit.custom: disable default edit page.
  • #angular.data-view.action.delete.custom: disable default delete dialog.
  • #angular.data-view.routing.add.disable: disable the add route.
  • #angular.data-view.routing.edit.disable: disable the edit route.
  • Added feature anchors to remaining DataView actions (add, edit, delete, details, list).

Refactored use of HttpClient​

We have added an API specific HttpClient. This allows for easy changing of authentication headers, error handling etc. per different API implemented. The implicit behavior of the http interceptors is also now removed. To facilitate the removal of the use of interceptors a lot of operator functions that handled the logic of the interceptors have been created.

  • handleDataAccessError
  • handleAlertError
  • handleDataAccessFormError
  • notifyDataConnectorSuccessEvent
  • notifyDataConnectorFailureEvent
Important

The new client is still based on the angular HttpClient and all functionality of this client can still be used.

Metamodel changes and additions​

Metamodel additions of abstract Connector and View. This allows for easier extension of different types of views (e.g. ListView, InstanceView, FilterView) or connectors (e.g. DataProjectionConnector, DataOperationConnector, ...).

datamodeldatamodel
For more added features check out the changelog
  • Allowed file type validation
  • Dynamic sidebar support
  • New functions folder in structure
  • Resolved filename encoding issues
  • Added error handling for std-api