Skip to main content

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.