Table of Contents

Create an action

What are actions ?

Actions are processes that can be called by a user when clicking on a button. They can be useful in several scenarios including opening another screen or executing a function that you have written in C#. As actions are linked to a UI view, their code can exploit the data entered by the user. In this article, you will learn how to create a new action and add it to the screen of your choice.

Creating a new action

As mentioned before, actions are linked to a UI view. Therefore, to create a new action, you need to open in Neos Studio the UI view that will host it and click on the Actions tab. There you can see the list of all the actions defined for the UI view. Click on the Add button to create a new one.

General settings

In the General tab you can define the basic settings for your action : the module responsible for adding the action in your UI view, the action name and its visibility and activation conditions. Then you can decide whether the action will open a new screen or execute a piece of code in the Action type field.

Execution constraint (from Neos 1.20)

When defining an action, you can set the Constraint property to specify a execution constraint. The constraint can be set to None or On a datasource item.

The None constraint is the default value. The behavior is then the same as before the introduction of the constraint.

When the constraint is set to On a datasource item, the action will be executed only if the datasource item is not null. This is useful when you want to execute an action on a specific item in a datasource. For example a button in a datagrid column that will execute an action on the row item or un button in a form that will execute an action on the current datasource item.

In this case, the action will be enabled only if the datasource item is not null. If the datasource item is null, the button will be disabled. Visiblity of the button is not affected by the constraint.

The Item property in the action code and the Enabled expression will be not nullable when the constraint is set to On a datasource item. This is useful to avoid having to check if Item is null.

Appearance settings

Actions are represented as buttons that will automatically appear in the toolbar of the UI view or that can be manually referenced on an action button.

The Appearance tab is used to determine how the button corresponding to an action will appear. You can set its caption, a description that will appear when hovering, a position, an icon, a size and a style. The Display mode field defines if the caption must be displayed with the icon. The Pinned property determines whether the button is directly displayed on the toolbar or hidden in a submenu named Actions.

For instance, you could configure the appearance of the button that determines the country based on the entered city this way :

Caption = Country
Description = Sets the country based on the city
Position = 1
Pinned = true
Size = Medium
Style = Primary
Icon name = edit

Open view action

When selecting the Open view option in the Action type field, a new field will appear allowing you to select the UI view that will be opened when the user triggers the action.

For example, an action that opens the list of employees in the Northwind application can be defined as follows :

Module name = Partners
Action name = ShowEmployees
Visible = true
Enable = true
ActionType = Open view
UI view to open = EmployeeUI

Code action

If you select the Code option, a C# code editor will appear and you will be able to write the code you want the action to execute when triggered.

Be aware that the code you write here will be transpiled to TypeScript and executed on the client side. When an action needs to start a heavy process, we recommend defining a server method and calling it in the action code.

When writing your code, you can access to the UI view data and methods by using the this keyword.

For example, when editing an employee in the Northwind application, if you want an action that the sets country of the employee's address based on the city, you could configure it as follows :

Module name = Partners
Action name = SetCountryFromCity
Visible = true
Enable = true
Constraint = On a datasource item
ActionType = Code
Code =

switch (Item.City)
{
    case "London":
        Item.Country = "United Kingdom";
        break;
    case "Paris":
        Item.Country = "France";
        break;
    case "Ottawa":
        Item.Country = "Canada";
        break;
    default:
        Item.Country = "Unknown";
        break;
}

Within action code and expressions, you have access to Item and Items properties :

  • Item: The element from the data source on which the action is executed.
  • Items: The elements from the data source on which the action is executed, usually the selected items.

Execution context

An action can be executed in various contexts. Each context determines how the Item and Items properties are populated:

Execution context Item Items
Toolbar DatasourceCurrent SelectedItems
Datagrid row Row [Row]
Datagrid row context menu Row SelectedItems
Datagrid footer DatasourceCurrent SelectedItems
Panel DatasourceCurrent SelectedItems
Keyboard shortcut DatasourceCurrent SelectedItems
Manual positioning in the template without the item attribute DatasourceCurrent SelectedItems
Manual positioning in the template with the item attribute Item passed via item attribute SelectedItems

Best practices

  • Use Items when the action may apply to multiple elements or can be triggered from different contexts
  • Use Item when the action is clearly intended for a single element.
Important

Never use DatasourceCurrent or SelectedItems directly. Always rely on the Item and Items properties instead, as they abstract context-dependent logic and ensure consistent behavior.

Manually creating an action button

You saw that an action will automatically be displayed in the toolbar of a UI view. However, it is possible to manually create buttons that will execute an action and position them in the UI view template.

For this, you just need to got to the Template tab of the UI view and add an action button tag where you want it to be displayed. The button will be of type action and you will need to enter the action name in the action-name property.

Here is an example for adding a SetCountryFromCity action button next to the Country field in the employee edit view template of the Northwind application :

...
    <group-box caption="Address" expanded="true">
        <horizontal-layout>
            <form-field property-name="Country" />
            <button type="action" action-name="SetCountryFromCity"/>
        </horizontal-layout>
        ...
    </group-box>

It is also possible to use the action caption in the template if needed:

<text>
    @Actions.SetCountryFromCity.Caption
</text>

Updating the application

Unlike other UI view elements, UI actions require the use of the Generate application button to be available in the application. This is due to permissions that can restrict access to UI view actions and need a full application generation to be updated.

Keyboard shortcuts

Since version 1.19, it has been possible to define a keyboard shortcut on actions.

The keyboard shortcut is visible in the action button tooltip.

If a custom action uses the same keyboard shortcut as a standard action, only the custom action will be executed.

Keyboard shortcuts of standard actions :

  • Add : Alt+N
  • Clone : Alt+C
  • Close : Alt+W
  • Refresh : Ctrl+R
  • Remove : Ctrl+D
  • Save : Ctrl+S

Relative positioning

Since version 2.2, it has been possible to position an action after another action using the Relative to location and a positive position. It's also possible to position an action before another by setting a negative position.

The real position of actions with relative positioning is calculated as follows : Position of sibling action + (Position / 1000)

Note that it's important to assign a position to the actions when there are actions with relative positioning to avoid this scenario :

  • Action1 in toolbar without position
  • Action2 in toolbar without position
  • Action3 relative to Action1 with position 1

=> The order of actions will be as follows : Action1 (0), Action2 (0), Action3 (0.0001)

When all actions have a position, there is no issue :

  • Action1 in toolbar with position 1
  • Action2 in toolbar with position 2
  • Action3 relative to Action1 with position 1

=> The order of actions will be as follows : Action1 (1), Action3 (1.0001), Action2 (2)