Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/databinding/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The UI uses data binding to bind controls to the model which holds the applicati

![Preview of three panels of the OpenUI5 application that is going to be built in this tutorial. Contains three panels with name input fields, address details, and a product list.](assets/Tutorial_Data_Binding_896048e.png "The Data Binding sample app with panels for name, address, and a product list")

> :tip:
> 💡
> You don't have to do all tutorial steps sequentially, you can also jump directly to any step you want. Just download the code from the previous step, copy it to your workspace, and ensure that the application runs by calling the `webapp/index.html` file.

***
Expand Down
4 changes: 2 additions & 2 deletions packages/databinding/steps/02/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ You can define the business data within a model using various formats:

- Your own custom format \(not covered in this tutorial\)

> :note:
> 📝
> There's also a special type of model called a "resource model". This model type is used as a wrapper object around a resource bundle file. The names of such files must end with `.properties`. They're typically used for holding language-specific text.
>
> We'll use this in [Step 6: Resource Models](../06/README.md).
Expand Down Expand Up @@ -81,7 +81,7 @@ Generally speaking, a model object holding business data should be bound to the

The text that is displayed on the UI is still hard-coded and not taken from the model. We'll bind the property `greetingText` to our UI control in the next step.

> :note:
> 📝
> You can set models on every control by calling `setModel()`. The model is then propagated to all aggregated child controls \(and their children, and so on …\). All child controls then have access to that model.

***
Expand Down
2 changes: 1 addition & 1 deletion packages/databinding/steps/04/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Replace the content of the `App.view.xml` file with the following content:
</mvc:View>
```

> :note:
> 📝
> Requiring `sap/ui/layout/form/ColumnLayout` is needed because we use the `ColumnLayout` as `layout` for the `sap/ui/layout/form/SimpleForm`.
> The `sap/ui/layout/form/SimpleForm` requires the configured layout, in case it's not done by the consumer but this may cause an additional rendering cycle if rendering starts before the layout finished loading.

Expand Down
2 changes: 1 addition & 1 deletion packages/databinding/steps/05/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ If you wish to alter the binding mode, you've got two options:

- Specify the data binding mode for a specific binding instance by using the `oBindingInfo.mode` parameter. This change only applies to this data binding instance. Any other binding instances will continue to use the model's default binding mode.For more information, see [API Reference: `sap.ui.base.ManagedObject.bindProperty`](https://sdk.openui5.org/#/api/sap.ui.base.ManagedObject/methods/bindProperty).

> :note:
> 📝
> There are two important points to understand about alterations to a model object's data binding mode:
>
> - If you alter the default binding mode of a model \(as in the example above\), **all** binding instances created after that point in time will use the altered binding mode, unless you explicitly say otherwise.
Expand Down
2 changes: 1 addition & 1 deletion packages/databinding/steps/06/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ Also add the `i18n` property to the `sap.app` section and modify the `title` and
...
```

> :note:
> 📝
> The configured `supportedLocales` represent the following i18n files present \(see Step 7\):
>
> - `""` - `i18n/i18n.properties`
Expand Down
2 changes: 1 addition & 1 deletion packages/databinding/steps/08/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ panel1HeaderText=Data Binding Grundlagen
panel2HeaderText=Adressdetails
```

> :note:
> 📝
> The resource bundle files now contain new properties for the address and a new panel header text. Both panel properties are numbered.
>
> In the XML view, inside the curly brackets for the binding path of the `htmlText` element, you'll notice that the first character is a forward slash. This is necessary for binding paths that make absolute references to properties in JSON and OData models, but you must not use it for resource models. After the first forward slash character, the binding path syntax uses the object name and the property names separated by forward slash characters \(`{/address/street}`\).
Expand Down
4 changes: 2 additions & 2 deletions packages/databinding/steps/09/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ In our custom formatter, we set the first and last name currently in the model a

In the `formatMail` function, we use the `sap.m.URLHelper.normalizeEmail` function that expects an e-mail address, a mail subject, and a text body. When a user follows the link, their default email client will open with these parameters. For more information, see [API Reference: `sap.m.URLHelper.normalizeEmail`](https://sdk.openui5.org/#/api/sap.m.URLHelper/methods/normalizeEmail). The `mailSubject` resource bundle text contains a placeholder for the recipient's first name \(see below\). Therefore, we provide the name with `[firstName]`.

> :note:
> 📝
> For a detailed description of the e-mail link format, see [MDN - Creating hyperlinks: Email links](https://developer.mozilla.org/de/docs/Web/Guide/HTML/Email_links).

Enhance the `App.view.xml` file as shown below:
Expand Down Expand Up @@ -132,7 +132,7 @@ For more complex bindings, we can't use the simple binding syntax with the curly

This is a reference to the function that receives the parameters listed in the `parts` array. Whatever value the formatter function returns becomes the value set for the `href` property. The dot `formatMail`\) at the beginning of the formatter tells OpenUI5 to look for a `formatMail` function on the controller instance of the view. If you don't use the dot, the function will be resolved by looking into the global namespace.

> :note:
> 📝
> When using formatter functions, the binding automatically switches to "one-way". Therefore, you can’t use a formatter function for "two-way" scenarios. However, you can use data types \(which we explain in the following steps\).

Add the `# E-mail` section to the `i18n.properties` and `i18n_de.properties` files as shown below.
Expand Down
2 changes: 1 addition & 1 deletion packages/databinding/steps/13/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ Discontinued=Eingestellt

Now, you can click on an element in the list and view its details in the panel below. You can even edit these details, and the changes are directly reflected in the list because we use two-way binding.

> :note:
> 📝
> Element bindings can also be relative to their parent context.

***
Expand Down
4 changes: 2 additions & 2 deletions packages/navigation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ For example, a classical Web application might display the employee’s resume p

The information in the hash, namely everything that is following the `#` character, is interpreted by the router.

> :note:
> 📝
> This tutorial does not handle cross-app navigation with the SAP Fiori launchpad. However, the concepts described in this tutorial are also fundamental for navigation and routing between apps in the SAP Fiori launchpad.

We will create a simple app displaying the data of a company’s employees to show typical navigation patterns and routing features. The complete flow of the application can be seen in the figure below. We'll start with the home page which lets users do the following:
Expand All @@ -27,7 +27,7 @@ We will create a simple app displaying the data of a company’s employees to sh

Throughout this tutorial we will add features for navigating to pages and bookmarking them. We will add backward and forward navigation with common transition animations \(slide, show, flip, etc.\). We will add more pages to the app and navigate between them to show typical use cases. We will even learn how to implement features for bookmarking a specific search, table sorting via filters, and dialogs.

> :tip:
> 💡
> You don't have to do all tutorial steps sequentially, you can also jump directly to any step you want. Just download the code from the previous step and make sure that the application runs as intended.
>
> You can view the samples for all steps here in this repository.
Expand Down
2 changes: 1 addition & 1 deletion packages/navigation/steps/01/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ webapp/
└── App.view.xml
```

> :note:
> 📝
> The content of the `localService` folder will not be changed in this tutorial. The `i18n` folder will always contain the `i18n.properties` file only. Therefore, we will show both subfolders collapsed in the following steps.

## The Initial App
Expand Down
6 changes: 3 additions & 3 deletions packages/navigation/steps/02/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ Single-page applications based on OpenUI5 can use a so-called “router” to di

This section contains the global router configuration and default values that apply for all routes and targets. The property `routerClass` is special as it determines the router implementation. The default value is `sap.ui.core.routing.Router`. Here, we set the `routerClass` to `sap.m.routing.Router`, because we implement an app based on `sap.m`. All other properties in `config` are given to the router instance. For example, we define where our views are located in the app. To load and display views automatically, we also specify the `controlId` of the control that is used to display the pages and the aggregation \(`controlAggregation`\) that will be filled when a new page is displayed. We will create only XMLviews in this tutorial, so we can set the `viewType` property to `XML`. All our views will be available in the `view` folder of the namespace `ui5.tutorial.navigation`, so we can set the `path` to `ui5.tutorial.navigation.view`. The `transition` allows us to set a default value for how the transition should happen; you can choose between `slide` \(default\), `flip`, `fade`, and `show`. All parameters of the config section can be overruled in the individual route and target definitions if needed.

> :note:
> 📝
> The possible values for `routerClass` are `sap.ui.core.routing.Router`, `sap.m.routing.Router`, or any other subclasses of `sap.ui.core.routing.Router`. Compared to `sap.ui.core.routing.Router` the `sap.m.routing.Router` is optimized for mobile apps and adds the properties `level`, `transition` and `transitionParameters` which can be specified for each route or target created by the `sap.m.routing.Router`. The `transitionParameters` can also be used for custom transitions. Please check the *API Reference* for more information.

- `routes`
Expand All @@ -109,7 +109,7 @@ Single-page applications based on OpenUI5 can use a so-called “router” to di

This basic routing configuration was easy enough. However, you can’t see it in action until you have initialized the router.

> :note:
> 📝
> As of OpenUI5 version 1.30, we recommend that you define the routing in the `manifest.json` descriptor file using routes and targets. In older versions of OpenUI5, the routing configuration had to be done directly in the metadata section of the component, and with different syntax.

## `webapp/Component.ts/.js`
Expand Down Expand Up @@ -223,7 +223,7 @@ sap.ui.define(["sap/ui/core/mvc/Controller"], function (Controller) {

Create a file `Home.controller.ts` in the `webapp/controller` folder. The controller for the home view does not contain any custom logic in this step, but we will add some features to it soon. Finally, run the app by calling the `webapp/index.html` file. This will be the entry point for our app in all the next steps. As you can see, the app is initially displaying the home view that we configured as the default pattern in the routing configuration. We have now successfully enabled routing in the app.

> :note:
> 📝
> We think of routing as a set of features that dispatch hash-based URLs to an app's views and manage the views' states.
>
> Based on the routing configuration, you define the navigation between pages and pass parameters to the target views.
Expand Down
4 changes: 2 additions & 2 deletions packages/navigation/steps/04/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ The function checks if there is a previous hash value in the app history. If so,

The third parameter of `navTo("appHome", {}, true /*no history*/);` has the value `true` and makes sure that the hash is replaced. With the line `sap.ui.core.UIComponent.getRouterFor(this)` you can easily access your component’s router throughout the app. To make it even more comfortable, we also add a handy shortcut `getRouter` to the base controller. This function is now available in each subclass as well. It is also used in the `onNavBack` handler to get a reference to the router before calling `navTo`. We now have to implement the reuse in all other controllers.

> :note:
> 📝
> In OpenUI5 there are multiple options to reuse code. We recommend to use a base controller for such helper methods because this allows us to decoratively use the `onNavBack` handler directly in any XML view without adding additional code to the controller. Our base controller is an abstract controller that will not be instantiated in any view. Therefore, the naming convention `*.controller.ts` does not apply, and we can just name the file `BaseController.ts`. By not using the naming convention `*.controller.ts` we can even prevent any unintentional usage in views.

## `webapp/controller/NotFound.controller.ts/.js`
Expand Down Expand Up @@ -220,7 +220,7 @@ sap.ui.define(["ui5/tutorial/navigation/controller/BaseController"], function (B

The same applies to our `Home` controller, we now also inherit from the `BaseController`.

> :note:
> 📝
> In this step we have added the *Back* button. The user can always use the browser’s native *Back* button as well. Each app can freely configure the behavior of the *Back* button. However, there is no clean way to apply the same logic for the browser’s *Back* button in single-page applications. Tweaking the browser history or using other quirks for cancelling backward or forward navigation is not recommended due to the implementation details of the browsers. The browser’s *Back* button always uses the browser history while the *Back* button of the app can make use of the browser history **or** can implement its own navigation logic. Make sure to understand this difference and only control the *Back* button inside the app.

## Conventions
Expand Down
2 changes: 1 addition & 1 deletion packages/navigation/steps/05/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Inside the `onDisplayNotFound` handler we get a reference to the `Targets` helpe

The `sap.m.routing.Targets` object itself can be retrieved by calling `getTargets()` on the router. It provides a convenient way for placing views into the correct containers of your application. The main benefits of targets are structuring and lazy loading: you just configure the views in the routing configuration and you do not have to load the views until you really need them.

> :note:
> 📝
> In the example code we get a reference to the `sap.m.routing.Targets` object by calling `getTargets()` on `this.getRouter()` from the base controller. However, you could also get a reference to the `sap.m.routing.Targets` object by calling `this.getOwnerComponent().getRouter().getTargets()` or `this.getOwnerComponent().getTargets()`.

If you now call the app and press the *Display Not Found* button you see that the `notFound` target is displayed without changing the URL. That was easy, but suddenly our app’s *Back* button does not work anymore. The bug we have just introduced illustrates an interesting navigation trap. The application hash is still empty since we just display the target and did not hit a route.
Expand Down
2 changes: 1 addition & 1 deletion packages/navigation/steps/06/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ The `employees` entry in the `targets` section references the `ui5.tutorial.navi

The view that we are about to create has to be placed in the `webapp/view/employee` folder accordingly. This approach helps to structure the views of the app according to business objects and to better understand the navigation patterns of the app in larger projects.

> :note:
> 📝
> We could also have left out the `path` property to use the default `path` defined in the `config` section. In that case, we would have to change the `name` to `employee.EmployeeList` to achieve the same effect.

Setting the `level` to `2` helps the router to determine how to animate the \(in our case\) `slide` transition. For us, this means that a navigation from the home page to the `employees` target will be animated with a “Slide to Left” animation. In contrast to that, the back navigation from the `employees` target to the home page will be animated with a “Slide to Right” animation. This behavior is due to the fact that the home page has a lower `level` than the `employees` target.
Expand Down
4 changes: 2 additions & 2 deletions packages/navigation/steps/07/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ Next, we have to create the view `employees.Employee`; for better illustration t

Create the file `Employee.view.xml` inside the `webapp/view/employee` folder. This employee view displays master data for an employee in a panel with a `SimpleForm` control: first name, last name and so on. The data comes from a relative data binding that is set on the view level as we can see in the controller later. As we are focusing on the navigation aspects in this tutorial, we won’t go into detail on the controls of the view. Just copy the code.

> :note:
> 📝
> Requiring `sap/ui/layout/form/ResponsiveGridLayout` is needed because we use the `ResponsiveGridLayout` as `layout` for the `sap/ui/layout/form/SimpleForm`.
> The `sap/ui/layout/form/SimpleForm` requires the configured layout, in case it's not done by the consumer but this may cause an additional rendering cycle if rendering starts before the layout finished loading.

Expand Down Expand Up @@ -288,7 +288,7 @@ In `_onRouteMatched` we call `bindElement()` on the view to make sure that the d

We also add an event handler to the `change` event as a private function `_onBindingChange`. It checks if the data could be loaded by querying the binding context of the view. As seen in the previous steps, we will display the `notFound` target if the data could not be loaded.

> :note:
> 📝
> Instead of calling `attachMatched(…)` on a route we could also call `attachRouteMatched(…)` directly on the router. However, the event for the latter is fired for every matched event of any route in the whole app. We don’t use the latter because we would have to implement an additional check for making sure that current route is the route that has been matched. We want to avoid this extra overhead and register on the route instead.

## webapp/view/employee/EmployeeList.view.xml
Expand Down
4 changes: 2 additions & 2 deletions packages/navigation/steps/08/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,7 @@ In the routing configuration, we add a new route `employeeResume` which referenc

The target `employeeResume` references the view `employee.Resume` that we are about to create. The target’s `level` is `4`; compared to the employee target this is one level lower again. To configure a flip navigation, we simply set the transition of our target to `flip`. Together with the correct `level` configuration this will trigger the correct forward and backward flip navigation whenever the target is displayed.

> :note:
> 📝
> Possible values for the `transition` parameter are:
>
> - `slide` \(default\)
Expand Down Expand Up @@ -407,7 +407,7 @@ Create a file `Resume.controller.ts` in the `webapp/controller/employee` folder.

Create a file `ResumeProjects.view.xml` in the `webapp/view/employee` folder. This view does not have a controller as we don’t need it. It just displays a `Text` control with the projects text of the selected employee. It illustrates that using nested views works just fine in combination with navigation and routing in OpenUI5.

> :note:
> 📝
> For more complex applications, the performance is significantly increased if parts of the UI are only loaded when the user is actively selecting it. In this example, the view is always loaded even though the user never decided to display the project information. In the next steps, we will extend the UI so that the content is loaded “lazy” by OpenUI5 only when the filter item is clicked. The back-end service will fetch the data only on request and the UI will only have to be updated with the selected data instead of loading all data.

## webapp/i18n/i18n.properties
Expand Down
Loading