View Models#

First, you need view models. Then, you decorate the properties with validation and hint decorators.

Why Using View Models?#

View Models form an abstraction layer between code and pure user interface. They appear in many architectural pattern, such as Model-View-Control (MVC), Movel-View-ViewModel (MVVM), and similar constructs. A component library such as ny@f is a different kind of pattern, but the basic need for a model is still valid.

The ViewModel is essential when you want a separation of concerns between your DomainModel (DataModel) and the rest of your code.

Decoupling and separation of concerns is one of the most crucial parts of modern software architectures. Models can contain code, have actions, and work as a distinct translator between the domain model and the view. It's not the same as the business logic, it's a layer between such a layer and the user interface (UI). A UI contains logic to control visible elements, such as tooltips, hints, and validation information. All this has no or only a weak relation to an underlying business logic. Mixing the both will create code that is hard to maintain, complex, and difficult to read. In software technology we often talk about so called software entropy. That's the process of code going to change over time into an even harder to manage form, with a lot of hacks, bells, and whistles nobody understands completely and that wil eventually start to fail. Levels of abstraction help to delay this process (it's an illusion that you can avoid it entirely). Viewmodels are hence an essential part of a good architecture.

The flux architecture, delivered by the @nyaf/store module, seems to address a similar approach using store models and binding. However, this part is entirely devoted to the business logic. It's exactly that kind of abstraction we need to make great software not only by great design and an amazing stack of features, but by sheer quality, stability, with maintainable code, hard to break, and almost free of nasty bugs.

Creating a View Model#

A view model could look like this:

export class UserViewModel {

  id: Number = 0;

  @Display('E-Mail', 'E-Mail address')
  email: string = '';

  @Display('Phone Number', 'The user\'s phone')
  @Required('Please, the phone number is required')
  phoneNumber: string = '';

  @Display('User Name', 'The full name')
  userName: string = '';


The last (optional) parameter of the validation decorators is a custom error message.

Validation Decorators#

Validation decorators can be used together with the binding. After a binding action took place, usually after a change by the user, the state of the bound model updates and can be retrieved immediately. Elements bound to validation signals can use the state to show/hide elements or control sending data in code. The property names are the same as the respective decorators, just all lower case.

Decorator Usage
@MaxLength The maximum length of a text input.
@MinLength The minimum length of a text input.
@Pattern A regular expression that is used to test the text or number input.
@Range A range (from-to) for either numerical values or dates.
@Required Makes the field mandatory.
@EMail Checks input against a (very good) regular expression to test for valid e-mail pattern.
@Compare Compares with another field, usually for password comparison.
@Custom Provide a static validation function as a callback for any custom validation.

UI Decorators (property level)#

UI decorators control the appearance of elements. Not all have an immediate effect, but it's very helpful while creating components to have meta data available.

Decorator Usage
@Display Determine the label's name and an (optional) tooltip.
@DisplayGroup Groups components in <fieldset> elements. Can be ordered inside the form.
@Hidden Makes an hidden field.
@Sortable Makes a column sortable in table views.
@Filterable Adds a filter in table views.
@Placeholder A watermark that appears in empty form fields
@ReadOnly Forces a particular render type.
@TemplateHint What kind of field (text, number, date, ...) and additional styles or classes.

The UI decorators do not enforce any specific behavior. In fact, they do almost nothing in an application without explicit support. The decorators create hidden properties you can retrieve when building the UI. That way you can control the behavior of the app by setting the decorators. It's some sort of abstraction between the view model and the UI.

Mapping the Properties#

The actual properties are of the form __propName__fieldName, that means, you have to add the decorated property name at the end to retrieve the property specific value. As an example, the displayText property, created by the decorator @Display, and placed on a property email, can be retrieved by this code:

const text = this.model['__displayText__email'];

However, the internal names may change and to avoid any issues a mapping with external names is available. The following table shows the properties the decorators create.

Decorator function Properties
Display text, order, desc
DisplayGroup grouped, name, order, desc
Hidden is
Sortable is
Filterable is
Placeholder has, text
ReadOnly is
TemplateHint has, params, name

Special Decorators#

There is one more decorator that's not just defining the UI behavior but has some internal behavior.

Decorator Usage
@Translate For i18n of components

This decorator can be placed on top of the view model, on class level, or on a specific property.

export class ContactModel {

  constructor(init?: ContactModel) {
    if (init) { =; =;

  @Display('Contact Name')
  name = '';

The function expects a JSON file with translation instructions. The translation converts the text on the properties to another language:

const json = {
  'Contact Name': 'Kontaktname'

This decorator is experimental and will change in the near future to reflect a more powerful approach.

Providing the ViewModel#

To make a ViewModel accessible you use the @ViewModel(T) decorator. More about this in the chapter Data Binding.