diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-8/pluggable-widgets/differences-between-pluggable-and-custom-widgets.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-8/pluggable-widgets/differences-between-pluggable-and-custom-widgets.md index 42e4a3fedc8..51a06a59d07 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-8/pluggable-widgets/differences-between-pluggable-and-custom-widgets.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-8/pluggable-widgets/differences-between-pluggable-and-custom-widgets.md @@ -7,13 +7,13 @@ description: This document explains the differences between pluggable and custom ## Introduction -Pluggable widgets are the successor to [Custom widgets](/howto8/extensibility/widget-development/). Pluggable widgets are based on a modern React framework, have access to better APIs in the client, and can use more advanced properties in Studio Pro. Therefore, pluggable widgets allow you to more easily implement existing front-end libraries, tools, and your own expertise. Pluggable widgets should be used instead of custom widgets whenever possible. +Pluggable widgets are based on a modern React framework, have access to better APIs in the client, and can use more advanced properties in Studio Pro. Therefore, pluggable widgets allow you to more easily implement existing front-end libraries, tools, and your own expertise. Pluggable widgets should be used instead of custom widgets whenever possible. ## Differences Between Pluggable and Custom Widgets | Concept | Pluggable widgets | Custom widgets | | ------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| Framework | [React](/apidocs-mxsdk/apidocs/pluggable-widgets/#client-component) | [Dojo](/howto8/extensibility/widget-development/#dojo) | +| Framework | [React](/apidocs-mxsdk/apidocs/pluggable-widgets/#client-component) | Dojo | | Data access | Declarative, props-based | Imperative, callback-based | | Data updates | [Receive updates in props](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#dynamic-value) | [Subscribe](https://apidocs.rnd.mendix.com/8/client/mx.data.html#.subscribe) | | API | [Pluggable widgets API](/apidocs-mxsdk/apidocs/pluggable-widgets/) | [Mendix Client API](/apidocs-mxsdk/apidocs/client-api/) | diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md index 3a00d142d20..ba198597236 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md @@ -276,7 +276,7 @@ Do not use "Mendix Administrator." This term replaces "Mendix" and "Mendix Mobile app" (which are not to be used in the product UI or documentation). -Always use "the Mendix Developer App" and cross-reference [Getting the Mendix Developer App](/refguide8/getting-the-mendix-app/) where possible. +Always use "the Mendix Developer App" and cross-reference [Getting the Mendix Developer App](/refguide/getting-the-mendix-app/) where possible. ### Mendix Client diff --git a/content/en/docs/deployment/mobileapp.md b/content/en/docs/deployment/mobileapp.md index 16df2f72718..c94f1f25afb 100644 --- a/content/en/docs/deployment/mobileapp.md +++ b/content/en/docs/deployment/mobileapp.md @@ -19,8 +19,6 @@ This page is divided into three tabs: {{% alert color="warning" %}} Building hybrid apps in the cloud uses the PhoneGap Build service from Adobe. Because Adobe no longer maintains this service, building hybrid apps in the cloud and publishing them to app stores is no longer possible. -To build a hybrid app and publish it, see [How to Build a Mendix Hybrid App Locally](/howto8/mobile/build-hybrid-locally/) for information on local building. - To publish your app in an app store, Mendix recommends building native iOS apps instead. For more information, see [Build Native Apps](/refguide/mobile/distributing-mobile-apps/building-native-apps/). {{% /alert %}} diff --git a/content/en/docs/deployment/on-premises-design/buildpacks/cloud-foundry-deploy.md b/content/en/docs/deployment/on-premises-design/buildpacks/cloud-foundry-deploy.md index ff4fce6802b..51269ffd2fe 100644 --- a/content/en/docs/deployment/on-premises-design/buildpacks/cloud-foundry-deploy.md +++ b/content/en/docs/deployment/on-premises-design/buildpacks/cloud-foundry-deploy.md @@ -7,12 +7,10 @@ aliases: - /deployment/cloud-foundry/index.html - /howto/deploying-a-mendix-app-to-cloud-foundry.html - /refguide/deploying-a-mendix-app-to-cloud-foundry.html - - /refguide8/deploying-a-mendix-app-to-cloud-foundry.html - /refguide9/deploying-a-mendix-app-to-cloud-foundry.html - /deployment/cloud-foundry/ - /howto/deploying-a-mendix-app-to-cloud-foundry - /refguide/deploying-a-mendix-app-to-cloud-foundry - - /refguide8/deploying-a-mendix-app-to-cloud-foundry - /refguide9/deploying-a-mendix-app-to-cloud-foundry - /developerportal/deploy/cloud-foundry-deploy/ #To update these screenshots, you can log in with credentials detailed in How to Update Screenshots Using Team Apps. diff --git a/content/en/docs/howto8/_index.md b/content/en/docs/howto8/_index.md deleted file mode 100644 index 6044f19048e..00000000000 --- a/content/en/docs/howto8/_index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Studio Pro 8 How-tos" -url: /howto8/ -description: "Step-by-step guides on various Mendix topics that teach you how to build and customize apps." -weight: 92 -no_list: false -description_list: true -cascade: - - content_type: "Studio Pro 8" - - mendix_version: 8 - - banner: "Studio Pro 8 has reached its end of support. To upgrade to a supported version, see Moving from Mendix Studio Pro 8 to 9." - - old_content: true - - hide_feedback: true - - notsitemap: true - - sitemap: - priority: 0.2 -#This document is mapped to the landing page, update the link there if renaming or moving the doc file. ---- - -{{% alert color="warning" %}} -With the Mendix 11.0.0 release in June 2025, Mendix 8 has reached its end of support. This means that Mendix 8 will no longer receive support, maintenance, or updates. To ensure continued access to the latest features and security enhancements, we recommend planning an upgrade to a more recent version of the platform. -{{% /alert %}} - -## Introduction - -Browse the *Studio Pro 8 How-tos* to find step-by-step guides that teach you how to build and customize apps with Mendix. - -## How-to Categories - -The *Studio Pro 8 How-tos* are divided into the following categories: diff --git a/content/en/docs/howto8/collaboration-requirements-management/_index.md b/content/en/docs/howto8/collaboration-requirements-management/_index.md deleted file mode 100644 index ef0a7987cdb..00000000000 --- a/content/en/docs/howto8/collaboration-requirements-management/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Collaboration" -url: /howto8/collaboration-requirements-management/ -weight: 20 -no_list: false -description_list: true ---- - -## Introduction - -This category of how-tos presents information on using version control via the Mendix Team Server, collaborating via GitHub, translating app content, and other ways to collaborate and manage requirements. - -## Documents in This Category diff --git a/content/en/docs/howto8/collaboration-requirements-management/contribute-to-a-github-repository.md b/content/en/docs/howto8/collaboration-requirements-management/contribute-to-a-github-repository.md deleted file mode 100644 index abc0d80d9bf..00000000000 --- a/content/en/docs/howto8/collaboration-requirements-management/contribute-to-a-github-repository.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: "Contribute to a Mendix GitHub Repository" -url: /howto8/collaboration-requirements-management/contribute-to-a-github-repository/ -weight: 20 -aliases: - - /howto8/collaboration-project-management/contribute-to-a-github-repository.html - - /howto8/collaboration-project-management/contribute-to-a-github-repository ---- - -## Introduction - -We like to work with our community, and we encourage you to create and contribute using pull requests! - -This how-to teaches you how to do the following: - -* Contribute to a Mendix GitHub Repository according to Mendix guidelines - -## Prerequisites - -Before starting with this how-to, make sure you have completed the following prerequisites: - -* Have a [GitHub account](https://github.com/join) -* Have a [Mendix account](https://home.mendix.com/) -* Fork a repository on GitHub (for details, see [Fork a Repo](https://help.github.com/articles/fork-a-repo/)) - -## Making Changes to an Existing Repository - -To make changes to an existing repository, follow these guidelines: - -* Create a new branch from where you want to base your work on your fork (this is usually the repository's production branch) -* To quickly create a branch based on production, use `git checkout -b fix/production/my_contribution production` - * Avoiding working directly on the production branch is advised -* Make commits of logical units -* Check for unnecessary whitespace with `git diff --check` before committing. -* Make sure you have added the necessary tests for your changes -* Run all the tests to assure nothing was accidentally broken - -## Submitting Changes - -To submit changes, follow these guidelines: - -* Push your changes to the branch in your fork of the repository -* Submit a pull request to the appropriate repository in the Mendix organization (for more information, see [About Pull Requests](https://help.github.com/articles/using-pull-requests/)) -* Mention the ID's for any issues that are fixed by the changes (for more information, see [Closing Issues Using Keywords](https://help.github.com/articles/closing-issues-via-commit-messages#closing-issues-with-pull-requests)) -* After feedback has been given, Mendix expects a response within two weeks - * After two weeks, we may close the pull request if it isn't showing any activity - -## Read More - -* [Start Your Own Repository](/howto8/collaboration-requirements-management/starting-your-own-repository/) -* [Version Control](/refguide8/version-control/) -* [Share the Development Database](/howto8/collaboration-requirements-management/sharing-the-development-database/) diff --git a/content/en/docs/howto8/collaboration-requirements-management/on-premises-svn-howto.md b/content/en/docs/howto8/collaboration-requirements-management/on-premises-svn-howto.md deleted file mode 100644 index b560c65b041..00000000000 --- a/content/en/docs/howto8/collaboration-requirements-management/on-premises-svn-howto.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "Work with an On-Premises Version Control Server" -linktitle: "On-Premises Version Control Server" -url: /howto8/collaboration-requirements-management/on-premises-svn-howto/ -weight: 60 ---- - -## Introduction - -When developing Mendix applications, changes to these applications are stored in a version control system. This system is called [Team Server](/developerportal/repository/team-server/) and is part of the Mendix Platform. This means that the application's files are stored in the Mendix online environment. For more information, see [Version Control](/refguide8/version-control/). - -While this is the recommended way of working for almost all Mendix developers, you may prefer to store your application's files in a system that is controlled by your own organization. - -This how-to teaches you how to do the following: - -* Configure your Mendix apps to work with your own (on-premises) version control system - -{{% alert color="info" %}} -For version control, Mendix uses the [Subversion](https://subversion.apache.org) system (also known as SVN). This how-to will not describe how to set up an SVN server from scratch; typically, this will be taken care of by the IT department of your organization. -{{% /alert %}} - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Have knowledge of Subversion -* Have access to an SVN server and possess credentials (username and password) that give you access to that SVN server -* Know the location of the SVN server – usually this is an address similar to an internet URL (for example, `https://svn.example.com:9876/repos/myapp`) - -## Repositories - -Subversion uses repositories for storing all the data of your version-controlled app. Each Subversion server can contain many different repositories. - -For the purposes of this how-to, there are two important points to know about repositories. - -First, Mendix requires you to store each Mendix application in a separate repository. It is not possible to place multiple Mendix apps into a single repository. - -Second, when uploading an app to a repository, Mendix requires the repository to be empty (except for the recommended SVN layout, as described in [Recommended Repository Layout](https://svnbook.red-bean.com/en/1.7/svn.tour.importing.html#svn.tour.importing.layout)). Specifically, this means that the repository should contain only three empty folders, called **branches**, **tags**, and **trunk**. - -Usually, repositories are created and maintained by the administrator of your SVN server. For more details about repositories, see [Repository Administration](https://svnbook.red-bean.com/en/1.7/svn-book.html#svn.reposadmin). - -In the following sections of this how-to, it is assumed that you have a repository available for your application. - -## SVN Versions - -Mendix Studio Pro has a (built-in) Subversion client that uses version 1.9 of the SVN working copy format. This client should be compatible with any 1.x version of the SVN server, so you could use, for example, a 1.6.x or 1.9.x SVN server as well. - -{{% alert color="warning" %}} -Mendix Studio Pro uses the Subversion 1.9 working copy. Previous versions of the Mendix Desktop Modeler used a Subversion 1.7 working copy. These working copy versions are NOT compatible. - -This means that, if you use a separate SVN client (for example [TortoiseSVN](https://tortoisesvn.net/)) to work on your Mendix app, you must always use the version which matches your app model. If you open a local model from Mendix 7.x with the latest version of TortoiseSVN, **you will no longer be able to open it in Mendix**.{{% /alert %}} - -## Creating a New App to Store in an On-Premises SVN Server - -To create a new app to store in your on-premises SVN server, you must create the app from Studio Pro by following these steps: - -1. Click **New App** on the **My Apps** page. -2. In the **App Settings** dialog box, click **No** for **Enable online services**. -3. In the top menu of Studio Pro, go to **Edit** > **Preferences** > **Advanced** and make sure the **Enable private version control** box is checked. -4. In the top menu, select **Version Control** > **Upload to Version Control Server**. -5. In the [Upload to Version Control Server](/refguide8/upload-to-version-control-dialog/) dialog box, select **Private server**. -6. In the **App repository address** field, enter the address of your SVN server. This address must include the name of the repository you are going to use for your app (for example, `https://svn.example.com:9876/repos/myapp`). -7. Click **OK** to connect to the server. - -## Moving an App from Mendix Team Server to an SVN Server - -To look at moving an app from Mendix Team Server to a private SVN server, we will use the scenario of creating a new app in [Apps](/developerportal/), wherein a Team Server project is created automatically. - -{{% alert color="warning" %}} -For the purpose of creating an app to store in your on-premises SVN server, this is a deprecated workflow. -{{% /alert %}} - -1. Click **Create App** in [Apps](https://sprintr.home.mendix.com/). -2. After you have created your app, click the arrow next to **Edit App**, select **Edit in Mendix Studio Pro**, then open the app in the relevant Studio Pro version. You need to open your app in Studio Pro in order to download it to your local machine (for more information, see [Version Control](/refguide8/version-control/)). -3. Your app contains a link to the location of the Mendix Team Server by default. To replace this with the address of your own SVN server, create a ticket in the [Mendix Support Portal](https://support.mendix.com/) specifying your app and the address of your SVN server. This address must include the name of the repository you are going to use for your app (for example, `https://svn.example.com:9876/repos/myapp`). This will allow Mendix Support to change the URL of your app. -4. Wait for confirmation from Mendix Support before continuing the process. -5. With all instances of Studio Pro closed, open the folder in which your app is stored locally. -6. Delete the **.svn** and **.mendix-cache** folders (note that these folders may be hidden, in which case you will need to enable the option in your file explorer to make them visible). By deleting these folders, references to the Mendix Team Server are removed. Now, your app is ready to be uploaded to your own SVN server. -7. Double-click the **.mpr** file in the project folder to open the app again in Studio Pro (for example, if your app is called **MyApp**, this file will have the name **MyApp.mpr**). Alternatively, you can start Studio Pro, click **My Apps** > **Open App**, and browse to the abovementioned local **.mpr** file to open your app. -8. When the app is opened in Studio Pro, go to the top menu, select **Edit** > **Preferences** > **Advanced**, and make sure the **Enable private version control** box is checked. -9. In the top menu, select **Version Control** > **Upload to Version Control Server**. -10. In the [Upload to Version Control Server](/refguide8/upload-to-version-control-dialog/) dialog box, select **Private server**. -11. In the **App repository address** field, enter the address of your SVN server. This address must include the name of the repository you are going to use for your app (for example, `https://svn.example.com:9876/repos/myapp`). -12. Click **OK** to connect to the server. - -## Read More - -* [Version Control](/refguide8/version-control/) -* [Team Server](/developerportal/repository/team-server/) -* [Upload to Version Control Server](/refguide8/upload-to-version-control-dialog/) diff --git a/content/en/docs/howto8/collaboration-requirements-management/sharing-the-development-database.md b/content/en/docs/howto8/collaboration-requirements-management/sharing-the-development-database.md deleted file mode 100644 index c369b71e613..00000000000 --- a/content/en/docs/howto8/collaboration-requirements-management/sharing-the-development-database.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Share the Development Database" -url: /howto8/collaboration-requirements-management/sharing-the-development-database/ -weight: 40 ---- - -## Introduction - -All Mendix applications need a database running in the background. While developing an application it is advised to use the standard built-in database that is supplied with Mendix Studio Pro. This how-to teaches you how to open and manage the data stored inside the built-in database. - -## Prerequisites - -To get the most out of the built-in database, make sure you have completed the following prerequisites: - -* Have an internet connection (to commit the database) -* Have a Team Server-enabled application (to share the database) -* Have a running application -* Have some data in the database to commit SQL queries to - -## Type of Database - -The built-in database is a flatfile database called HSQLDB (HyperSQL DataBase). This is the leading SQL relational database software written in Java. It offers a small, fast multithreaded and transactional database engine with in-memory and disk-based tables and supports embedded and server modes. It includes a powerful command line SQL tool and simple GUI query tools. - -HSQLDB has been constantly developed over 12 years and is used as a database and persistence engine. It is known for its small size, ability to execute completely or partly in memory, its flexibility and speed. - -Therefore this type of database is excellent to use while developing and running applications in Mendix Studio Pro on a local machine. Thanks to this built in functionality, the developer doesn't have to run a local database engine and management tools. - -## Selecting the Preferred Database - -One application can make use of many different databases. Take the following steps to select the preferred database (if there is more than one configured) - -1. Double-click **Settings** in the **Project Explorer**. -2. Select the preferred database configuration and click **Make active**. - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580427.png" class="no-border" >}} - -## Starting the Database Viewer - -To start the built-in database viewer, the following steps have to be applied: - -1. Run the application locally (if this is the first time, Studio Pro will ask you to create the new database, so click **Yes**): - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580426.png" class="no-border" >}} - -2. When the application is running, open the built=in database viewer: - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580425.png" class="no-border" >}} - -3. This will result in the following screen being displayed (depending on the data model of the application): - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580424.png" class="no-border" >}} - -This is the database manager. On the left pane all tables from all modules in the running application are showed. On the right top pane it is possible to enter SQL queries and on the right lower pane the results from the entered SQL query will be shown. - -## Executing the Queries - -Queries can be executed in two ways. It can be done directly from the command line (top right pane) in SQL script, or via the explorer on the left pane. For more information about SQL, visit the following page: [https://www.w3schools.com/sql/](https://www.w3schools.com/sql/). To execute queries from the database explorer (left pane), the following steps have to be applied: - -1. Right-click any table and select the preferred action: - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580423.png" class="no-border" >}} - -2. To select all customers from the table CUSTOMER, click the first option. It will automatically fill the SQL command in the upper-right pane. - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580422.png" class="no-border" >}} - -3. Click **Execute SQL** to execute this query: - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580421.png" class="no-border" >}} - -On the lower-right pane, the results are shown and a total of 50 rows is retrieved from the database. From the standard actions it is also possible to delete, update and insert records. The standard actions can also be customized to retrieve, update or delete specific data. Advanced knowledge about the SQL language is needed to get the desired results. - -## Committing the Data Snapshot - -The built-in database can easily be shared with other members of the team. Like the business logic itself, it is possible to commit a snapshot of the database to the team server. To do this, take the following steps: - -1. Select **Version Control** > **Add Snapshot of Data**: - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580420.png" class="no-border" >}} - -2. Click **Yes** to commit if one already exists, then add the informational message and click **OK**. - -The data is now committed to the team server and can be used by other team members. - -## Updating the Data Snapshot - -To import a data snapshot into the model, the app has to be updated since the last database snapshot has been committed by another team member. To get the data from the committed database snapshot the following steps have to be applied: - -1. First the application has to be updated, so click **Update* on the **Changes** tab: - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580419.png" class="no-border" >}} - -2. To implement the data snapshot, the database has to be extracted from a ZIP file to the deployment directory: - - {{< figure src="/attachments/howto8/collaboration-requirements-management/sharing-the-development-database/18580417.png" class="no-border" >}} - -3. Now copy the data directory to the data directory in the deployment directory - -{{% alert color="warning" %}} -Make sure the names of the databases aren't the same or make a copy of your own database first so it will not be overwritten. -{{% /alert %}} - -## Read More - -* [Contributing to a GitHub repository](/howto8/collaboration-requirements-management/contribute-to-a-github-repository/) -* [Starting your own repository](/howto8/collaboration-requirements-management/starting-your-own-repository/) -* [Version Control](/refguide8/version-control/) diff --git a/content/en/docs/howto8/collaboration-requirements-management/starting-your-own-repository.md b/content/en/docs/howto8/collaboration-requirements-management/starting-your-own-repository.md deleted file mode 100644 index 4eac96e929c..00000000000 --- a/content/en/docs/howto8/collaboration-requirements-management/starting-your-own-repository.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Start Your Own GitHub Repository" -url: /howto8/collaboration-requirements-management/starting-your-own-repository/ -weight: 30 ---- - -## Introduction - -In this how-to, you will learn how to set up a GitHub repository. The repository will contain your development content and can be shared for others to contribute to an application or [Marketplace component](/appstore/submit-content/). - -## Preparation - -* Have a [GitHub account](https://github.com/join) -* Read the [Create a Repo](https://help.github.com/articles/create-a-repo) GitHub guide - -## Creating Your Repo - -First of all, your repo needs a name. You should use the same name that will be used for the item published in the [Mendix Marketplace](https://marketplace.mendix.com/). Use UpperCamelCase to replace the spaces (for example, *My first app* becomes *Mendix/MyFirstApp* on GitHub). - -The description should say what the item does. This description can also be used in the Mendix Marketplace. - -Add a *.gitignore* file to make sure you keep your repo clean. - -## Making a Widget - -When making a new widget, Mendix suggests you [Build a Pluggable Web Widget](/howto8/extensibility/create-a-pluggable-widget-one/). - -## Releases - -If you want to make a new release for the Mendix Marketplace, start with a new tag on the appropriate commit on the production or release branch. From these tags, you can create a [new release in GitHub](https://help.github.com/articles/creating-releases). In this release, set your release notes (which you can then use for the Marketplace release as well) and provide an official name. If you add the *.mpk* file as a binary file to the release tag, the Mendix Marketplace will automatically sync the *.mpk* to your new draft: - -{{< figure src="/attachments/howto8/collaboration-requirements-management/starting-your-own-repository/18580533.png" class="no-border" >}} - -You should link this to the upcoming Mendix Marketplace release by mentioning that release number in the description. - -## Read More - -* [Contributing to a GitHub repository](/howto8/collaboration-requirements-management/contribute-to-a-github-repository/) -* [Version Control](/refguide8/version-control/) -* [Sharing the Development Database](/howto8/collaboration-requirements-management/sharing-the-development-database/) diff --git a/content/en/docs/howto8/collaboration-requirements-management/translate-your-app-content.md b/content/en/docs/howto8/collaboration-requirements-management/translate-your-app-content.md deleted file mode 100644 index 031630eb5bb..00000000000 --- a/content/en/docs/howto8/collaboration-requirements-management/translate-your-app-content.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: "Translate Your App Content" -url: /howto8/collaboration-requirements-management/translate-your-app-content/ -weight: 50 ---- - -## Introduction - -Delivering your Mendix app in multiple languages is an important capability for reaching a wide audience. Most of the text that the end-user sees is stored as translatable texts (for example, labels, button names, and menu items). Using the language features of Mendix, you can quickly make your app multilingual and translate the content to many other languages. - -This how-to teaches you how to do the following: - -* Add a new language to your app -* Change the working language -* Translate individual items of text -* Translate multiple items of text in one operation -* Change multiple items of text in one operation -* Copy a translation from one language to another - -It is assumed that you know the basics of creating new apps and editing them. - -## Creating a Sample App - -To demonstrate working with languages, you will create a new app from the blank app template. You will add some text to this app, as an example, but the app you create is to demonstrate the language features of Mendix and is not intended to be run. - -When you create an app from a Mendix template, there is one language available. This is **English, United States**, which you will usually set to be the default language. This is the language which will be displayed when an end-user has no language selected, or when your app does not support their selected language. - -To create your app, do the following: - -1. Create a new app using the **Blank App** template. If given the option, leave the default language as **English, United States**. -2. Open the app in Studio Pro (images here are from Studio Pro 8.10). -3. Create a domain model in MyFirstModule with two entities: - * **Order** with the integer attribute **OrderNumber** - * **Product** with the string attribute **ProductName** - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/domain-model.png" alt="Domain model for How To" class="no-border" >}} -4. Right-click one of the entities and select **Generate overview pages…**. -5. Ensure both entities are selected and click **OK**. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/generate-pages.png" alt="Options selected for Generate Pages" class="no-border" >}} - This will generate some pages containing text for you to translate. -6. Open the page **Product_NewEdit** and add a new **Button** widget. -7. Label the new button **Order**. This button will be used to allow the end-user to order the product they are viewing. Ignore any warnings about the setup of this button. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/order-button.png" alt="Product New Edit page with an Order button" class="no-border" >}} -8. Open the page **Home_Web** and put some text into the title and subtitle. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/home-page-text.png" alt="Product New Edit page with an Order button" class="no-border" >}} - -You now have an app with some translatable texts. - -## Adding App Languages - -You can now add an additional language to your app. - -If you want to create the whole app in a language other than the current default, it is best to do this before you start creating the app. If you want to add alternative languages, it is best to do this when your app is nearing completion as it reduces the amount of work needed to do the translation from the default language, especially if there is already a translation for that language. - -To add an additional language, do the following: - -1. Select the menu item **Language > Language settings…**. -2. Click the **Add** button and select a second language. In this example we will be using *Russian, Russia*, but you can use any language you like. - {{% alert color="info" %}}It is recommended that you **don't** choose *Dutch, Netherlands* as this already contains translations for many of the translatable texts.{{% /alert %}} -3. Click **OK** to confirm. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/language-settings.png" alt="Language settings tab in the project settings dialog" class="no-border" >}} - -You will see that the default language is still *English, United States* which is what you want the end-user to see if they do not choose Russian as their language. - -## Changing the Current Language - -The current language is the language of the dictionary where any text you enter is stored. You can see which language is the current language in the status bar at the bottom right of the Studio Pro window. - -To change your current language to Russian, do the following: - -1. Click the language indicator in the status bar. -2. Click **Russian, Russia** to make that your current language. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/change-language.png" alt="Change the current language" class="no-border" >}} - -{{% alert color="info" %}} -If you do further development later on, you will need to remember to change back to your default language so that any new text is recorded there and not in a translated dictionary. -{{% /alert %}} - -## Translating an Individual Piece of Text - -Now that your current language is Russian, you can translate some of the texts into that language. - -1. Open the **Home_Web** page in Studio Pro. - - You will see that untranslated texts appear in the default language (English, United States) between angle brackets `<>`. -2. Enter your translation for the two text items on the page - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/home-page-russian.png" alt="Home page with translated text" class="no-border" >}} - -You have now added a translation for these two pieces of text. - -## Using Batch Translate - -You could translate each piece of text individually. However, there are texts which appear multiple times, for example **Cancel**, **Delete**, and **Edit**. - -Mendix offers you a way to add a translation for all occurrences of a text at once. - -### Translating Multiple Texts - -To translate multiple occurrences and multiple texts from the default language, English, to Russian in a single operation, do the following: - -1. Select the menu option **Language > Batch Translate…**. -2. Select *English, United States* as the **Source language** and *Russian, Russia* as the **Destination language**. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/batch-translate-languages.png" alt="Select English and Russian as source and destination languages" class="no-border" >}} -3. Click **OK**. - - You initially want to work just on your module, rather than everything. -4. Click **Select…** next to **Documents/modules**. This will currently be set to *(all)*. -5. Check only the module **MyFirstModule** to restrict batch translation to this module. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/batch-translate-myfirstmodule.png" alt="Select only MyFirstModule" class="no-border" >}} -6. Click **OK**. - - You can now see all the translatable texts in your module. The individual translations you made in the previous section are shown in the *Russian, Russia* column. The **#** column shows the number of times each text appears in the selected module(s). - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/batch-translate-initial.png" alt="Translatable texts in MyFirstModule" class="no-border" >}} -7. Enter translations in the destination language (**Russian, Russia**) column for a few terms: **Cancel**, **Delete**, and **Edit** for example. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/batch-translate-cancel-delete-edit.png" alt="Translate Cancel, Delete, and Edit into Russian" class="no-border" >}} -8. Click **Translate** to save the current translations. -9. **Close** the batch translate dialog and look at the page **Product_NewEdit**. You will see that these terms now have Russian translations. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/product-new-edit-partial-translation.png" alt="Product New Edit page showing the cancel button translated into Russian" class="no-border" >}} - -### Dealing With More Complex Translations - -Sometimes a single word in the source language does not have a single translation in the destination language. - -Follow the steps below to see how to deal with this situation. - -1. Follow steps **1** through **6** in the previous section to again see a list of texts in your module which can be translated from *English, United States* to *Russian, Russia*. -2. Type *Order* in the **Source text contains** field. -3. Click the translatable text `Order`. You can see that there are three places that this text is used, and they are listed at the bottom of the dialog box. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/batch-translate-order.png" alt="All source texts containing the word 'order' with the locations of the text 'order' shown" class="no-border" >}} - One of the locations of the text `Order` is an action button on the **Product_NewEdit** page. This was the button we added above whose purpose is to allow the end-user to order the product. -4. Double-click on the **Action button …** object to confirm that this is the button we were planning to use to order the product. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/product-new-edit-order.png" alt="Order button on Product New Edit page" class="no-border" >}} - -The text `Order` is being used to refer to the Order entity, but also the command to order a product. In Russian these are two different words. - -To solve this issue, you can do the following: - -1. Close the **Batch translate** dialog. Remember to click **Translate** to save any translations you have made. -2. Go to the page **Product_NewEdit**. -3. Edit the text on the button to reflect the verb *to order*. In Russian this is `заказать`. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/product-new-edit-order-russian.png" alt="Order button on Product New Edit page translated into Russian" class="no-border" >}} -4. Reopen the **Language > Batch Translate…** dialog and search for *Order* in the module *MyFirstModule*. - - You will see that the translations for *Order* have now been split between the one with the translation `заказать` and the one with no translation. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/batch-translate-order-split.png" alt="All source texts containing the word 'order' showing that ones with different translations are shown separately. " class="no-border" >}} -5. Now you can change the remaining entries for *Order* to `Заказ`, the Russian for *an order*. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/batch-translate-order-2-translations.png" alt="All source texts containing the word 'order' showing two different translations for Order. " class="no-border" >}} -6. Click **Translate** to save the translation and **OK** to close the **Batch translate…** dialog. - -You can now check that the correct translation has been applied to the other instances of *Order*. For example on the **Order_Overview** page. - -## Replacing Text in Current Language - -Once you have made some translations, you may want to look at just the translations to check for spelling or consistency. To do this, use **Batch replace…**. - -To use batch replace, do the following. - -1. Ensure that your current language is the language you want to review. Batch replace works on the currently selected language. -2. Select the menu item **Language > Batch replace…**. - - You will see all the translations which are in the current language dictionary. You can limit these to a module and search them for specific words as before. You can also see where each text is used, so you can view it in context. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/batch-replace-russian-initial.png" alt="All texts which have been translated into Russian." class="no-border" >}} - - You can see that you have been inconsistent with use of capital letters. So you need to make it more consistent. - -3. Ensure all text starts with a capital letter by typing the new text in the **Replace with** column. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/batch-replace-russian-capitals.png" alt="All texts which have been translated into Russian." class="no-border" >}} - -4. Click **Replace** to update the translation dictionary. - -## Copying to a New Language - -Having translated your app, you may want to translate it into another, related, language. For example *Dutch, Netherlands* into *Dutch, Belgium*, *English, United States* into *English, United Kingdom*, or *Russian, Russia* into *Belarusian, Belarus*. Many of the translations will be the same so you don't want to type them again. - -To copy our Russian translations into a Belarusian dictionary you can do the following: - -1. Add *Belarusian, Belarus* as an app language. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/language-settings-belarusian.png" alt="Belarusian added to the app" class="no-border" >}} -2. Open the menu option **Language > Language Operations…**. -3. Select **MyFirstModule**. You can see that there are 11 translations in the Russian dictionary. -4. Click **Copy** for the **Operation**. -5. Select *Russian, Russia* as the **Source language**. -6. Select *Belarusian, Belarus* as the **Destination language**. -7. Click **Apply**. - {{< figure src="/attachments/howto8/collaboration-requirements-management/translate-your-app-content/language-operations-copy.png" alt="Copy all Russian translations in MyFirstModule to the Belarusian dictionary" class="no-border" >}} - -Your Russian texts are copied to the Belarusian dictionary and you can now review them using batch replace or batch translate to change any cases where the Russian and Belarusian languages diverge. - -## Other Considerations - -Now you know how to make translations of translatable texts, there are a couple of other things you may wish to investigate. - -### Completeness - -You will probably want to know that you haven't missed any text that should have been translated, and it is a big task to go through your app manually and check every piece of text. - -Mendix provides you with a completeness check for your languages. You can set this by editing the language in **Language Settings**. You will then receive warnings about all text which has not been translated into that language. There is always a completeness check for the default language. - -For more information, see [Advanced Language Settings](/refguide8/language-settings/#advanced) in the *Language Settings* reference guide. - -### Sharing Translations With Other Apps - -You have seen how you can create translations easily and even copy your new translation to a new language in the current app. - -But what if you have several apps and want to add Russian to all of them? You might be happy to translate your own modules from scratch, but you won't want to translate the system module, administration module, and Atlas UI all over again as they don't change and you already have perfect translations for these. - -Mendix allows you to export a translation to an Excel file, either for the whole app or just selected modules. You can then import this translation to another app and have your translation available to you. - -For more information, see [Exporting and Importing Text](/refguide8/batch-translate/#export-import) in the *Batch Translate* reference guide. - -## Read More - -* [Language Menu](/refguide8/translatable-texts/) diff --git a/content/en/docs/howto8/collaboration-requirements-management/troubleshoot-network-issues-for-team-server.md b/content/en/docs/howto8/collaboration-requirements-management/troubleshoot-network-issues-for-team-server.md deleted file mode 100644 index d2698a61b7d..00000000000 --- a/content/en/docs/howto8/collaboration-requirements-management/troubleshoot-network-issues-for-team-server.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Troubleshoot Network Issues for Connecting to Team Server" -linktitle: "Team Server Network Issues" -url: /howto8/collaboration-requirements-management/troubleshoot-network-issues-for-team-server/ -weight: 14 -description: "Describes troubleshooting connection issues as well as the permissions and settings required to connect to Team Server." ---- - -## Introduction - -Mendix Studio Pro needs to connect to Team Server, which is where all your projects are stored. - -**This how-to explains the following:** - -* Which permissions and settings are required to connect to Team Server - -## Troubleshooting Team Server Project Network Settings - -Being unable to download the Team Server project can indicate that the security configuration of your company network is blocking access to `https://home.mendix.com` and `https://teamserver.sprintr.com/`. - -Team Server is implemented using Subversion and Mendix Studio Pro uses the HTTPS (TCP) protocol to communicate with that server. To access Team Server from within Studio Pro, the network at your location needs the following settings: - -* The HTTPS port (TCP 443) needs to be open -* The HTTP port (TCP 80) needs to be open -* WebDAV (verbs within the HTTP protocol) needs to be enabled on any proxy server - -Mendix Studio Pro connects to `https://teamserver.sprintr.com/` and with the domains shown in the diagram below over HTTPS on port 443. These domains should be added to the firewall safe list: - -{{< figure src="/attachments/howto8/collaboration-requirements-management/troubleshoot-network-issues-for-team-server/networkaccessmendixplatform.jpg" alt="Domains home.mendix.com, cloud.mendix.com, and teamserver.sprintr.com need to be accessible on port 443 from your network" class="no-border" >}} - -You can look up the IP address of `https://teamserver.sprintr.com/`. - -{{% alert color="warning" %}} -Mendix reserves the right to change the IP address at any time and without notification to the customer. This could happen if Mendix moves to a different infrastructure, for example. -{{% /alert %}} - -{{% alert color="info" %}} -Contact your network administrator and give them this information to allow them to configure your network (for example, firewall and proxy settings) correctly. -{{% /alert %}} - -## Still Having Problems? - -If this solution does not work, submit a request to [Mendix Support](https://support.mendix.com/). diff --git a/content/en/docs/howto8/collaboration-requirements-management/troubleshoot-version-control-issues.md b/content/en/docs/howto8/collaboration-requirements-management/troubleshoot-version-control-issues.md deleted file mode 100644 index 254ea6ca72a..00000000000 --- a/content/en/docs/howto8/collaboration-requirements-management/troubleshoot-version-control-issues.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: "Solve Known Version Control Issues" -url: /howto8/collaboration-requirements-management/troubleshoot-version-control-issues/ -weight: 7 -description: "This document presents a list of problems and fixes for version control issues." -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -Mendix Studio Pro contains a version control system that supports collaborating with team members. This document presents fixes that can be used when version control problems arise. - -For more information and general help on version control, see the following documents: - -* [Version Control](/refguide8/version-control/) -* [Using Version Control in Studio Pro](/refguide8/using-version-control-in-studio-pro/) - -## Errors and Fixes - -Below is a list of known errors and the steps to fix them. - -### Getting an Error Containing `SharpSvn.SvnAuthenticationException: Proxy authentication failed` - -{{< figure src="/attachments/howto8/collaboration-requirements-management/troubleshoot-version-control-issues/oopsproxy.png" alt="Error dialog with proxy authentication failed" class="no-border" >}} - -This error means that Studio Pro has problems reaching the version control server because of a proxy server. - -The proxy settings can be changed in Studio Pro by selecting **Edit** > **Preferences** and then the **Advanced** tab. In the **Proxy server** section, you can change the proxy authentication settings. Fill in the correct **User name** and **Password** for the proxy server. - -{{< figure src="/attachments/howto8/collaboration-requirements-management/troubleshoot-version-control-issues/proxysettings.png" alt="Proxy settings" class="no-border" >}} - -### Getting an Error Containing Another `SharpSvn.SvnAuthenticationException` - -This should be resolved if you sign out of Studio Pro and then log back in. - -### Getting an Error with the Message `Connection timed out` - -Follow these steps: - -1. Open the *\Users\\AppData\Roaming\Subversion\servers* file with any text editor. -2. Add the text `http-timeout = 5000` under the section `[global]`. -3. Save the file. - -### Getting an Error with the Message ` is already locked` - -Follow these steps: - -1. Install [TortoiseSVN](https://tortoisesvn.net/), as suggested in [System Requirements](/refguide8/system-requirements/). - - {{% alert color="warning" %}}Mendix Studio Pro uses the Subversion 1.9 working copy. Previous versions of the Mendix Desktop Modeler used a Subversion 1.7 working copy. These working copy versions are NOT compatible. Always use the version of TortoiseSVN that matches your app model. If you open a local model from Mendix 7.x with the latest version of TortoiseSVN, you will no longer be able to open it in Mendix.{{% /alert %}} - -2. Go to the parent directory (folder) of your app (this is the folder with the **** from the error message). -3. Right-click to open the folder's context menu and select **TortoiseSVN** > **Clean up**. - -### Getting an Error with the Message `System.Security.Cryptography.CryptographicException: Key not valid for use in specified state` - -Follow these steps to remove your user settings and restart Studio Pro. - -1. Rename *\Users\\AppData\Local\Mendix\Settings.sqlite* to *Settings.sqlite.old*. -2. Restart Studio Pro. - -### Getting an Error with the Message `SharpSvn.SvnRepositoryIOException: At least one property change failed; repository is unchanged` {#error-with-message} - -Follow these steps: - -1. Install [TortoiseSVN](https://tortoisesvn.net/), as suggested in [System Requirements](/refguide8/system-requirements/). - - {{% alert color="warning" %}}Mendix Studio Pro uses the Subversion 1.9 working copy. Previous versions of the Mendix Desktop Modeler used a Subversion 1.7 working copy. These working copy versions are NOT compatible. Always use the version of TortoiseSVN that matches your app model. If you open a local model from Mendix 7.x with the latest version of TortoiseSVN, you will no longer be able to open it in Mendix.{{% /alert %}} - -2. Open the project folder via Studio Pro by selecting **Project** > **Show Project Directory in Explorer**. -3. Right-click the white background of the project folder. -4. Select **TortoiseSVN** > **Properties**. -5. Double-click the `svn:ignore` property. -6. Copy all text via Ctrl + A followed by Ctrl + C. -7. Paste the text into a new document in Notepad++ (or another editor that understands newline conventions). -8. In the bottom right, click `CRLF` and select `LF` instead (this will replace `CRLF` with `LF`). -9. Copy all text again. -10. Go back to the window showing the `svn:ignore` property. -11. Replace the current content by pasting from the clipboard via Ctrl + A followed by Ctrl + V. -12. Click **OK** to close the `svn:ignore` property dialog box. -13. Click **OK** to close the `properties` dialog box. -14. Restart Studio Pro. - -You can now commit your app. - -### Resolving Conflicts on the 'svn:ignore' Property {#svn-ignore} - -When merging or updating branches, a conflict is sometimes reported on the app folder rather than on an individual file. This usually means there is a conflict on the `svn:ignore` property. - -In the `svn:ignore` property, Subversion records which files should be ignored. These are files that are on disk but should not be on Team Server. - -For example, the `deployment` directory is necessary for running your project, but it should not be on the Team Server. Each user has their own version of the `deployment` folder on their hard disk. - -You will need to resolve the conflict before you can commit your app to Team Server. - -#### Example - -In this example, we will focus on merging a branch into the main line. On the main line, the list of ignored files looks like this: - -[//]: # "modeler-merge-marker has not yet been renamed for Studio Pro" - -```text -modeler-merge-marker -.mendix-cache -ResolveIgnoreConflict.mpr.lock -*.launch -ResolveIgnoreConflict.mpr.bak -node_modules -``` - -On the branch, the list looks like this: - -```text -modeler-merge-marker -.mendix-cache -ResolveIgnoreConflict.mpr.lock -*.launch -ResolveIgnoreConflict.mpr.bak -.project -.classpath -deployment -``` - -{{% alert color="info" %}} -The first five lines are the same and after that, the lists deviate. -{{% /alert %}} - -Merging the branch to the main line will result in the following information message: - -{{< figure src="/attachments/howto8/collaboration-requirements-management/troubleshoot-version-control-issues/mergesuccessfuldialog.png" class="no-border" >}} - -{{% alert color="info" %}} -A conflict is reported on the project *folder*. This usually means that there is a conflict on the `svn:ignore` property. -{{% /alert %}} - -To resolve a conflict on the `svn:ignore` property, perform these steps: - -1. Install [TortoiseSVN](https://tortoisesvn.net/), as suggested in [System Requirements](/refguide8/system-requirements/). - - {{% alert color="warning" %}}Mendix Studio Pro uses the Subversion 1.9 working copy. Previous versions of the Mendix Desktop Modeler used a Subversion 1.7 working copy. These working copy versions are NOT compatible. Always use the version of TortoiseSVN that matches your app model. If you open a local model from Mendix 7.x with the latest version of TortoiseSVN, you will no longer be able to open it in Mendix.{{% /alert %}} - -2. Open the project directory in Windows File Explorer -3. Right-click the white background and choose **TortoiseSVN** > **Edit Conflicts**. The following pop-up window will be shown (resize the window to display all the information): - - {{< figure src="/attachments/howto8/collaboration-requirements-management/troubleshoot-version-control-issues/editconflictsdialog.png" class="no-border" >}} - -4. Copy all the lines starting with `modeler-merge-marker` to the clipboard. -5. Click **Manually edit property**. -6. Double-click the `svn:ignore` line in the grid. -7. Paste the previously copied lines via Ctrl + A followed by Ctrl + V. -8. Remove the special lines that start with `<<<<<<<`, `=======`, and `>>>>>>>`. For this example, we end up with the following combined ignore list: - - {{< figure src="/attachments/howto8/collaboration-requirements-management/troubleshoot-version-control-issues/combinedignorelist.png" class="no-border" >}} - - {{% alert color="info" %}}This includes both the lines from the main line and from the branch. The order is not important.{{% /alert %}} - -9. Click **OK** and then **OK** again to confirm the change. -10. Right-click the white background of the project directory and choose **TortoiseSVN** > **Edit Conflicts** again. -11. This time click **Resolve using local property**. - -You have resolved the conflict and can commit from Studio Pro. - -### Getting an Error with the Message `SharpSvn.SvnRepositoryIOForbiddenException: Access to '/.../!svn/rvr/1/trunk' forbidden` - -If you get this error, try the following options: - -* in [Apps](/developerportal/general/team/), check whether the user has access to the app: - * If they do not have access, invite them to the app - * If they do have access, remove them from the app and add them back – this will re-sync the access rules -* If the above does not work, make sure the [WebDAV protocol](https://en.wikipedia.org/wiki/WebDAV) is not blocked within your network – this protocol is [required](/refguide8/system-requirements/) by Studio Pro for [version control](/refguide8/version-control/) to work, but it might be blocked by your proxy server or other software like a firewall - -## Other Problems - -If the solutions here do not work for your version control problems, please submit a request to [Mendix Support](https://support.mendix.com/). - -## Read More - -* [Submit Support Requests](/support/submit-support-request/) diff --git a/content/en/docs/howto8/data-models/_index.md b/content/en/docs/howto8/data-models/_index.md deleted file mode 100644 index 7a3e030bcda..00000000000 --- a/content/en/docs/howto8/data-models/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Data Models" -url: /howto8/data-models/ -weight: 50 -no_list: false -description_list: true ---- - -## Introduction - -This category includes how-tos on creating data layers and setting up data validation. - -## Documents in This Category diff --git a/content/en/docs/howto8/data-models/create-a-basic-data-layer.md b/content/en/docs/howto8/data-models/create-a-basic-data-layer.md deleted file mode 100644 index 4622a64acdd..00000000000 --- a/content/en/docs/howto8/data-models/create-a-basic-data-layer.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: "Create a Basic Data Layer" -url: /howto8/data-models/create-a-basic-data-layer/ -weight: 1 ---- - -## Introduction - -This how-to explains how you can create a basic data layer for your application with Mendix. Each application can have multiple modules, and each module has its own domain model. All the domain models together define the data layer of the application. - -The domain model consists of entities and associations. An entity is the blueprint for an object in your application, like "Customer" or "Order." Associations define the relation between two entities. As soon as you deploy the application, Mendix takes care of the underlying database for you. This means that you won't have to create tables and write queries yourself. - -This how-to teaches you how to do the following: - -* Create entities and attributes -* Add enumerations -* Create associations -* Delete association behavior - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Download and install [Mendix Studio Pro](https://marketplace.mendix.com/link/studiopro/) -* Create a new app or have an existing app available - -## Creating Entities and Attributes - -To create entities and their attributes, follow these steps: - -1. Open your app's **Domain Model**: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582192.png" class="no-border" >}} - -2. Click **Entity** in the menu bar: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582191.png" class="no-border" >}} - -3. Click inside the domain model editor to create the entity: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582190.png" class="no-border" >}} - - By default, Studio Pro creates a persistable entity, which means the app's database will be able to store objects of this type of entity. -4. Start typing directly to change the name of the entity into **Customer**: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582189.png" class="no-border" >}} - -5. Right-click the **Customer** entity and select **Add** > **Attribute**: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582188.png" class="no-border" >}} - -6. Enter *Name* for the **Name** of the new attribute, and select **String** as the data **Type**: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582186.png" class="no-border" >}} - -7. Repeat the steps above to create a complete entity that looks like this: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582185.png" class="no-border" >}} - -8. Repeat the steps above again to create a second entity that looks like this: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582184.png" class="no-border" >}} - -## Adding Enumerations - -An enumeration is a predefined list of values that can be used as an attribute type. This allows users of the app to select any of the predefined values for this attribute. A good example of an enumeration is order status. Let's add an enumeration and extend the **Order** entity with an enumeration value-based attribute. - -To add enumerations, follow these steps: - -1. Right-click the module and select **Add other** > **Enumeration**. -2. Enter *OrderStatus* for the **Name** and click **OK**. -3. Click **New** to add a new enumeration value: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582181.png" class="no-border" >}} - -4. Enter *Open* for the **Caption** and click **OK**. -5. Repeat the steps above for the **Processing** and **Complete** values. You should then have the following configured values: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582179.png" class="no-border" >}} - - Click **OK** to save the enumeration. Now we will create an enumeration value-based attribute in the **Order** entity. -6. Right-click the **Order** entity and select **Add** > **Attribute**. -7. Enter *OrderStatus* for the **Name** and select **Enumeration** for the **Type**. -8. Select the **OrderStatus** enumeration and click **Select**. -9. Select **Open** for **Default value**: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582197.png" class="no-border" >}} - -10. Click **OK** to save the new attribute. The **Order** entity should look like this: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582176.png" class="no-border" >}} - -## Creating Associations - -After you have created the entities, you can start creating associations. - -To create an association, draw a line from the border of one entity to the border of the other entity to create an association. Always start at the entity that will have more instances in the system than the other one. In this case, draw an association from **Order** to **Customer**, because you will want to store more orders than customers in your application. - -{{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582175.png" class="no-border" >}} - -## Multiplicity - -This section will explain how to change the multiplicity of associations. - -By default, the domain model editor creates an association with a one-to-many multiplicity. In the above case, a customer can have multiple orders, and an order can only have one customer. If the desired multiplicity is not available in the properties list you have probably drawn the association the wrong way, so you should remove the association and draw it again the other way around. - -To change the multiplicity, double-click the **Order_Customer** association in order to open its **Properties** dialog box: - -* To change the association to a one-to-one multiplicity, select the **[1 – 1]** option in the **Multiplicity** section; this means that a customer can only have one order and vice versa: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582206.png" class="no-border" >}} - -* To change the association to a many-to-many multiplicity, select the **[* – *]** option in the **Multiplicity** section; this means that a customer can have multiple orders, and an order can have multiple customers: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582205.png" class="no-border" >}} - -## Delete Behavior {#delete-behavior} - -You can configure the delete behavior for both sides of an association. - -To configure the delete behavior, double-click the **Order_Customer** association to open its **Properties** dialog box: - -* To configure a cascading delete, select the **Delete 'Order' object(s) as well** option in the **On delete of 'Customer' object** section; this means that all the orders of a customer will also be removed if the customer is deleted: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582209.png" class="no-border" >}} - -* To configure the delete prevention, select the **Delete 'Customer' object only if it is not associated with 'Order' object(s)** in the **On delete of 'Customer' object** section; this means that a customer can only be deleted if no orders refer to this customer, and the **Error message** will be shown to a user that tries to delete a customer that has orders: - - {{< figure src="/attachments/howto8/data-models/create-a-basic-data-layer/18582208.png" class="no-border" >}} - -{{% alert color="info" %}} -Delete behavior includes objects which are in memory. This means that delete cascades and delete prevention will apply, even if the associated object has not been committed. -{{% /alert %}} - -## Read More - -* [Work with Images and Files](/howto8/data-models/working-with-images-and-files/) -* [Denormalize Data to Improve Performance](/howto8/data-models/denormalize-data-to-improve-performance/) -* [Set Up Data Validation](/howto8/data-models/setting-up-data-validation/) diff --git a/content/en/docs/howto8/data-models/denormalize-data-to-improve-performance.md b/content/en/docs/howto8/data-models/denormalize-data-to-improve-performance.md deleted file mode 100644 index 950f7535334..00000000000 --- a/content/en/docs/howto8/data-models/denormalize-data-to-improve-performance.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: "Denormalize Data to Improve Performance" -url: /howto8/data-models/denormalize-data-to-improve-performance/ -weight: 6 ---- - -## Introduction - -This how-to explains how you can improve performance by denormalizing data in Mendix. - -This how-to teaches you how to do the following: - -* Denormalize data -* Keep denormalized data in sync - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Create a [basic data layer](/howto8/data-models/create-a-basic-data-layer/) - -## Denormalization - -For an example scenario, a domain model contains two related entities called Customer and Order. The customer overview page needs to show the name of the customer and the total order amount next to each other. Showing the customer name is easy, but the total order amount needs to be calculated. - -To show the total order amount, there are two options: - -* First option: create a calculated attribute in the Customer entity to compute the total order amount - * The drawback of this option is that the calculated attributes bring down the performance of overview pages -* Second option: create a persistable attribute in the Customer entity that stores the total order amount in the database – this is called denormalization - * The drawback of this option is that the redundant data needs to be kept in sync (but this is easy with Mendix [event handlers](/refguide8/event-handlers/)) - -To enable denormalization, follow these steps: - -1. Create a domain model that looks like this: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582169.png" class="no-border" >}} - -2. Double-click the **Customer** entity to open the properties editor: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582168.png" class="no-border" >}} - -3. Add a decimal attribute **TotalOrderAmount**. -4. Create an overview and detail page for the *Customer* entity. -5. Make sure the customer overview page shows the **TotalOrderAmount** value. -6. Make sure the order detail page has a mandatory reference selector to select the customer. - -Now the application is ready to store redundant data, but you still need to keep the data in sync. - -## Keep Denormalized Data in Sync with an After Commit Event - -1. Open the domain model and double-click the Order entity to open its properties editor. -2. On the **Event handlers** tab, click **New** to add a new event handler. -3. On the **New Event Handler** dialog box, do the following: - * Select **After** as the **Moment** - * Select **Commit** as the **Event** - * Select **Yes** for **Pass the event object** - * Click **Select...** to open the microflow selector - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582166.png" class="no-border" >}} - -4. On the microflow selector, click **New** and enter a name for the new microflow (for example, *Order_AfterCommit*). -5. Click **OK** to create the new microflow, and then click **OK** again to save the event handler. -6. Open the new microflow, which should look like this: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582165.png" class="no-border" >}} - - Let's take a moment to think about what the new microflow should do. We want to calculate the total order amount and store this value in the customer object. As you can see, the current microflow only has an order object as an input parameter. So, first we need to retrieve the corresponding customer. Then we need to get all the orders of this customer and calculate the total order amount. As soon as we have the total order amount, we need to store it in the customer object. Once you're done, the microflow should look like this: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582150.png" class="no-border" >}} - -7. Open the **Toolbox**, which should be docked in the lower-right corner of Studio Pro. If you can't find the **Toolbox** there, you can open it from the **View** menu: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582163.png" class="no-border" >}} - -8. Drag a **Retrieve** activity from the toolbox to the line between the start and end event on the microflow, which will insert a new retrieve activity: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582164.png" class="no-border" >}} - -9. Double-click the new activity to open its properties on the **Retrieve Objects** dialog box and do the following: - * Select **By association** as **Source** - * Click **Select...** to open the **Association** selector - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582162.png" class="no-border" >}} - -10. On the **Select association** pop-up window, select **Order_Customer** from the **Variables** node in the tree view, and then click **Select**: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582161.png" class="no-border" >}} - - As you can see below, the **Output** section of the **Retrieve Objects** dialog box is configured automatically: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582160.png" class="no-border" >}} - -11. Click **OK** to save the activity. Your microflow should now look like this: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582159.png" class="no-border" >}} - -12. Insert another retrieve activity (as you did in step #8), double-click it to open its properties on the **Retrieve Objects** dialog box, and do the following: - * Select **From Database** as **Source** - * Click **Select...** to open the entity selector - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582157.png" class="no-border" >}} - -13. On the **Select entity** pop-up window, select **Order** via from the **Variables** node in the tree view, and then click **Select**: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582158.png" class="no-border" >}} - - As you can see below, the **XPath constraint** and **Output** sections of the **Retrieve Objects** dialog box are configured automatically: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582156.png" class="no-border" >}} - -14. Click **OK** to save the activity. Your microflow should now look like this: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582155.png" class="no-border" >}} - -15. Insert an aggregate list activity, double-click it to open its properties on the **Aggregate List** dialog box, and do the following: - * Select **OrderList** as the **Input > List** - * Select **Sum** as the **Function** - * Select **Totalprice** as the **Attribute** - * Enter *SumTotalprice* as the **Output > Variable** name - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582153.png" class="no-border" >}} - -16. Click **OK** to save the activity. Your microflow should now look like this: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582152.png" class="no-border" >}} - -17. Insert a change activity, double-click it to open its properties on the **Change Object** dialog box, and do the following: - * Select **Customer** as the **Input > Object** - * Select **Yes** as the **Commit** action - * Select **Yes** to refresh in the client (the object changes are made on the server side, and with this option, the server triggers the client to refresh the object) - * Click **New** to create a new change item -18. In the **Edit Change Item** dialog box, do the following: - * Select **TotalOrderAmount** as the **Member** - * Enter *$SumTotalprice* as the **Value** - * Click **OK** to save the change item -19. Click **OK** again to save the activity. Your microflow should now look like this: - - {{< figure src="/attachments/howto8/data-models/denormalize-data-to-improve-performance/18582150.png" class="no-border" >}} - -20. Run the application and create some customers and orders. You should now see an up-to-date value for the TotalOrderAmount. - -## Read More - -* [Work with Images and Files](/howto8/data-models/working-with-images-and-files/) -* [Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/) -* [Set Up Data Validation](/howto8/data-models/setting-up-data-validation/) -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Define Access Rules Using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Attributes](/refguide8/attributes/) -* [Event Handlers](/refguide8/event-handlers/) diff --git a/content/en/docs/howto8/data-models/migrating-your-mendix-database.md b/content/en/docs/howto8/data-models/migrating-your-mendix-database.md deleted file mode 100644 index 6a1589f7271..00000000000 --- a/content/en/docs/howto8/data-models/migrating-your-mendix-database.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "Migrate Your Mendix Database" -url: /howto8/data-models/migrating-your-mendix-database/ -weight: 7 ---- - -## Introduction - -This document explains how to migrate the data in an existing Mendix database to another Mendix database. This can be useful if you want to migrate from one type of database to another, for example MS SQL Server to PostgreSQL. - -**After completing this how-to you will know how to do the following:** - -* Migrate a non-PostgreSQL database to a PostgreSQL database -* Export a PostgreSQL database -* Upload an exported PostgreSQL database to Mendix Cloud -* Export a Mendix Cloud database -* Import into an on-premise PostgreSQL database -* Migrate a PostgreSQL database to a non-PostgreSQL database, including migrating a PostgreSQL database to SAP HANA - -## Overview - -You can copy all the data from any Mendix-supported database management system to any other Mendix-supported database management system. For example you can copy demo, test, and production databases from built-in to PostgreSQL, and from PostgreSQL to built-in. You can also migrate production data from SQL Server or Oracle (on-premises) to PostgreSQL in our cloud. - -To do this, start your app on the database you would like to copy the data to. This database should already exist and should be totally empty. To let Mendix know from which database all data should be copied, you have to set some custom configuration settings. These custom settings identify the source database and give Mendix the authentication required to access it. - -The most commonly used custom settings for database migration are: - -* SourceDatabaseType (HSQLDB, MYSQL, ORACLE, POSTGRESQL, SQLSERVER) -* SourceDatabaseHost -* SourceDatabaseName -* SourceDatabaseUserName -* SourceDatabasePassword - -For more information on the full list of available settings, see [Runtime Customization](/refguide8/custom-settings/). - -These settings can be configured as follows: - -* Studio Pro – in **Project Explorer**, expand **Project**, double-click **Settings**, edit a configuration, and go to the **Custom** tab: - - {{< figure src="/attachments/howto8/data-models/migrating-your-mendix-database/19398970.png" class="no-border" >}} - -* Service Console – click an app in the left pane, click **Configuration**, click **Advanced**, then see **Custom Mendix settings**: - - {{< figure src="/attachments/howto8/data-models/migrating-your-mendix-database/19398971.png" class="no-border" >}} - -* m2ee-tools – add the custom settings to the mxruntime section (for more information, see [Full Documented m2ee](https://github.com/mendix/m2ee-tools/blob/develop/examples/full-documented-m2ee.yaml)) - -You can migrate databases using Studio Pro, the Service Console, or m2ee-tools. The Service Console gives you the advantage of seeing a progress bar during the copy process, which is handy if you copy a lot of data which takes a long time to execute. - -{{% alert color="info" %}} -Database migration is handled by Mendix as a normal database synchronization phase during the start-up process of an app. When using m2ee-tools, it is possible that during the start-up process you will get to see messages like ‘The database has to be synchronized’ or you will see an empty message. You can ignore these messages — the database migration will be performed. -{{% /alert %}} - -{{% alert color="warning" %}} -Before the data copying process starts, the main database structure will be generated based on the source database structure. This is necessary to make sure all the data is copied without any problems, especially in cases where the source database has a larger element value than what the current domain model specifies. - -As of version [8.1](/releasenotes/studio-pro/8.1/), the source database structure and data do not change as part of the migration. -{{% /alert %}} - -## Using your PostgreSQL Database in Studio Pro - -You can configure Studio Pro to use a PostgreSQL database instead of the inbuilt (HSQLDB) database. - -To do this, perform the following steps: - -1. Open your **Project '…'** > **Settings**. -2. Click **New** to add a new configuration from the **Configurations** tab. -3. Give your configuration a new **Name**. -4. On the **Database** tab, set the following values: - * **Type** – **PostgreSQL** - * **Database name** – *default* - * **URL** – the URL for your local PostgreSQL server - * **User name** – the user name of a database administrator in your local PostgreSQL - * **Password** – the password for the user specified above - - {{< figure src="/attachments/howto8/data-models/migrating-your-mendix-database/postgresql-config.png" class="no-border" >}} - - Your new configuration will be set as the active configuration. -5. Ensure that PostgreSQL is running locally on the correct port. -6. Run your app locally. Provided your PostgreSQL database is empty, your app will configure the database to support the domain model of your app. - -{{% alert color="info" %}} -If you already have the database, for example a test database in the cloud, you can also restore this to a local PostgreSQL database. Instructions for doing this can be found in [Restore a Backup Locally](/developerportal/operate/restore-backup-locally/). -{{% /alert %}} - -## Migrating a Non-PostgreSQL Database to a PostgreSQL Database - -Mendix Cloud environment only uses PostgreSQL as a database server. The recommended way is to migrate your existing on-premises non-PostgreSQL source database to a new on-premises PostgreSQL target database. - -The source database is the database with the data that you would like to migrate to the cloud. The target PostgreSQL database should be completely empty, as in, it should not contain any tables. In the Mendix project the active configuration in Settings should point to the target database, and you should add the Custom configuration settings for the source database as explained above in the overview. - -Having configured the Mendix project, just run the application locally and it will automatically migrate the database schema and all the data from the source database to the target database. Before exporting the target database, you should always validate it first by viewing the application in a browser. - -### Exporting a PostgreSQL Database - -To export a PostgreSQL database, refer to either the [pg_dump](https://www.postgresql.org/docs/current/backup-dump.html) command line tool or the [PG Admin](https://www.pgadmin.org/docs/) visual tool documentation to understand how to create a backup of your new PostgreSQL database. - -### Uploading an Exported PostgreSQL Database to Mendix Cloud Database - -Use Mendix Portal to upload the migrated, exported database backup to Mendix Cloud. This can be accessed using the Nodes page in [Apps](https://sprintr.home.mendix.com/): select your app and environment, click **Details**, click the **Backup** tab and use the **Upload Data** button to upload your Database using the file chooser to select the exported database file from your local file system. This will stop and clear your existing environment. - -## Exporting a Mendix Cloud Database - -The same procedure can be used to export an existing Mendix Cloud database, import it into an on-premises PostgreSQL source database and migrate that to an on-premises non-PostgreSQL target database. - -Export the Mendix Cloud database via the Mendix Portal. This can be accessed using the Nodes page in the Mendix Portal: - -1. Select your app and environment. -2. Click **Backups**. -3. Optionally, create a fresh backup with recent data by clicking **Create Backup**. -4. On the backup you want to download, click **More Options** > **Download**. This downloads the database to your local file system using the database URL shown in the dialog box. - -### Importing into an On-premises PostgreSQL Database - -To import a PostgreSQL database using the downloaded database file, refer to either the [pg_dump](https://www.postgresql.org/docs/current/backup-dump.html) command line tool or the [pgAdmin](https://www.pgadmin.org/docs/) visual tool documentation to understand how to restore your downloaded database file. - -### Migrating a PostgreSQL Database To a Non-PostgreSQL Database - -Below is general guidance on how to migrate a PostgreSQL database to a different database. There is a special section for the case of migrating a PostgreSQL database being used by a Mendix application running on SAP Business Technology Platform (SAP BTP). - -#### General Guidance - -The source database is a PostgreSQL database with the downloaded database from Mendix Cloud. The target non-PostgreSQL database should be completely empty, as in, it should not contain any tables. In the Mendix project the active configuration in Settings should point to the target database, and you should add the Custom configuration settings for the source PostgreSQL database as explained above in the overview. - -Having configured the Mendix project, just run the application locally and it will automatically migrate the database schema and all the data from the source database to the target database. You should always validate it first by viewing the application in a browser. - -#### Migrating to SAP HANA on SAP BTP - -If you have a Mendix application running on SAP BTP with PostgreSQL as the database service and want to migrate the database to SAP HANA, you will need to take some extra steps to migrate the existing data. - -To do this, perform the following steps: - -1. Sign in to the SAP BTP, Cloud Foundry environment (containing the PostgreSQL service) using the Cloud Foundry command line. -2. Get the PostgreSQL service instance details from the environment variables of the application using the following command: - - `cf env {application-name}` - -3. Inspect the **VCAP_SERVICES** list, and note down the values of the following properties in the `postgresql` service: - * `dbname` – `{dbname}` - * `hostname` – `{hostname}` - * `password` – `{password}` - * `port` – `{port}` - * `username` – `{username}` - - as shown in the highlighted image below: - - {{< figure src="/attachments/howto8/data-models/migrating-your-mendix-database/sap-postgres-config.png" class="no-border" >}} - -4. Create an environment using the SAP HANA database service using Mendix Portal. -5. Deploy the mda, but **do not start the application**. -6. Sign in to the SAP BTP, Cloud Foundry environment (containing the SAP HANA service) using the Cloud Foundry command line. -7. Set the following runtime properties in the SAP HANA environment using the command line. Use the values from the PostgreSQL instance values you noted above. - - ```bash - cf set-env {application-name} MXRUNTIME_SourceDatabaseType POSTGRESQL - cf set-env {application-name} MXRUNTIME_SourceDatabaseHost {hostname}:{port} - cf set-env {application-name} MXRUNTIME_SourceDatabaseName {dbname} - cf set-env {application-name} MXRUNTIME_SourceDatabaseUserName {username} - cf set-env {application-name} MXRUNTIME_SourceDatabasePassword {password} - ``` - -8. Start the application either from the Mendix Portal or the command line. -9. Once the application is started, verify the data in the application. diff --git a/content/en/docs/howto8/data-models/setting-up-data-validation.md b/content/en/docs/howto8/data-models/setting-up-data-validation.md deleted file mode 100644 index 5e79924c744..00000000000 --- a/content/en/docs/howto8/data-models/setting-up-data-validation.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "Set Up Data Validation" -url: /howto8/data-models/setting-up-data-validation/ -weight: 2 ---- - -## Introduction - -This how-to explains how you can set up data validation with Mendix. Before you can start with this how-to you need to set up a basic data structure, otherwise there won't be any data to validate. If you don't know how to set up a basic data structure, you can take a look at [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/). - -## Data Validation on Entity Level - -This section will explain how you can add validation rules to the domain model of your module. Validation rules are always triggered when changes to an object are committed. Please note that validation rules can only be applied on entities that are persistable. - -1. Open a **domain model** in Studio Pro. -2. Double-click a persistable entity to open its **properties.** -3. Open the **Validation Rules** tab page. - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582149.png" class="no-border" >}} - -4. Click **New** to start configuring a new validation rule for this entity. - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582148.png" class="no-border" >}} - -5. Select the **attribute** of which the value should be validated. -6. Enter an **error message** that is shown to the user if the validation fails. -7. Select the **rule type**. -8. Click **OK** to save this validation rule. - -## Required Validation on Inputs, Reference Selectors and Drop-downs - -The page builder of Studio Pro allows you to configure which inputs are mandatory and what message is shown to the user if the input is empty. If you don't have a detail page yet, take a look at [this](/howto8/front-end/create-your-first-two-overview-and-detail-pages/) how-to. - -1. Open a **detail page** and double-click an input to open its properties. -2. Enter a message for **Placeholder text**. This message is shown below the input if a user clicks the save button without filling in a value. - -{{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582144.png" class="no-border" >}} - -Please note that a *required* validation rule on entity level overrules this property. - -## Advanced Data Validation with the 'Before Commit' Event - -Validation rules are great for simple validations, but Mendix also offers ways to handle more complex validations. The domain model allows you to define event handlers on entity level. The 'Before Commit' and 'After Commit' events are always triggered when an object is committed to the database. The 'After Commit' is most commonly used to calculate values of de-normalized data. With the 'Before Commit' event you can execute a microflow that must return a Boolean value. If the microflow returns 'false', the entire commit is aborted otherwise the object is stored in the database. This mechanism is great for data validation. This section will explain how you can validate data by use of the 'Before Commit' event. - -1. Open a **domain model** in Studio Pro. -2. Double-click an entity to open its **properties**. -3. Open the **Event handlers** tab page. -4. Click **New** to start configuring a new event handler for this entity. -5. Select **Before** as moment and **Commit** as event. This forces the event to trigger every time an object of this entity is committed. -6. Make sure that the event object is passed, because this object holds the data that you want to validate. - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582146.png" class="no-border" >}} - -7. Click **Select** to connect a Microflow to this event. -8. Click **New** in the Microflow selector to create a new one. -9. Click **OK** to save the event handler and open the created Microflow. It should look similar to this: - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582145.png" class="no-border" >}} - -As long as this Microflow returns a Boolean value, you are free to add any logic to determine if the data is valid or not. If the Microflow returns 'false', the commit is cancelled. Returning 'true' will commit the object. If you don't know how to work with microflows, take a look at how-to. - -## Advanced Validation with a Custom 'Save' Button - -Validating user input can also be achieved by overriding the default save button on a detail page. Start by creating an overview and detail page. If you don't know how to create overview and detail pages, take a look at [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/). Your detail page should look similar to this: - -{{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582143.png" class="no-border" >}} - -1. Right click the **Save** button and select **Delete** to remove it from the page. -2. Right click the drop-zone below the **Cancel** button and select **Add widget > Button widgets > Call microflow**. - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582142.png" class="no-border" >}} - -3. In the **Select Microflow** dialog box, click **New** to create a new microflow. It should look like this: - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582141.png" class="no-border" >}} - -4. Create a **Commit** activity to store the object in the database. -5. Create a **Close page** activity to close the detail page. - - You have now created a microflow that mimics the default 'Save' button behavior. It should look like this: - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582140.png" class="no-border" >}} - - You can now extend the Microflow to validate user input. -6. After the start event insert a **decision**. -7. Double-click the decision to open the **properties editor** and type in an expression that returns true or false. For example: *$Customer/Name != 'John'*. - - As you can see you can use the **Customer** input parameter in the expression to validate its values. -8. Save the properties by clicking **OK.** -9. Right click the line between the decision and commit activity and select **true** as condition value. In this case if the customer's name not is 'John', the object is stored in the database and the page is closed. - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582139.png" class="no-border" >}} - -10. Add an **End event** to the decision. -11. Draw an additional line from the decision to the new end event. -12. Right click the line between the decision and end event and select **false** as condition value. -13. Insert a **Validation feedback** activity between the decision and end event. In the activity's properties editor, enter these details: - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582137.png" class="no-border" >}} - - Your microflow should now look similar to this: - - {{< figure src="/attachments/howto8/data-models/setting-up-data-validation/18582138.png" class="no-border" >}} - -14. Select the **input parameter** as variable. -15. Select for example **Name** as member. -16. Enter an error message in the **Template** field. You can use indexes to dynamically insert parameters in the template. - -## Validating Multiple Attributes - -If you want to validate multiple attributes, it is best to do this in a sub-microflow: - -1. Create a Boolean variable set to `true`. Be sure to mark this variable as the **Return value**. -2. Create your validations as described above. -3. Configure the sub-microflow to change the Boolean variable to `false` after the validation feedback or error message. Connect this flow back to the main sequence flow using a merge, and continue with the next validation. -4. At the end of the sub-microflow, the variable should be `true` if it successfully passed all validations, and `false` when one or more validations have failed. -5. Add a [decision](/refguide8/decision/) that checks the return value and only allows the microflow to continue to the **Commit** event if all validations are passed. This way, you can keep the logic while performing all necessary validations at once. - -## Read More - -* [Work with Images and Files](/howto8/data-models/working-with-images-and-files/) -* [Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/) -* [Denormalize Data to Improve Performance](/howto8/data-models/denormalize-data-to-improve-performance/) -* [Set Up Data Validation](/howto8/data-models/setting-up-data-validation/) -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) diff --git a/content/en/docs/howto8/data-models/working-with-images-and-files.md b/content/en/docs/howto8/data-models/working-with-images-and-files.md deleted file mode 100644 index 5e5287fba01..00000000000 --- a/content/en/docs/howto8/data-models/working-with-images-and-files.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "Work with Images and Files" -url: /howto8/data-models/working-with-images-and-files/ -weight: 4 ---- - -## Introduction - -This how-to explains how you can work with images and files with Mendix. Out of the box Mendix supports uploading of files and images. It also allows you to view images and download files that you uploaded. First you need to create your own domain model and define which entities are images and which are files. This is done by the concept of 'inheritance', sometimes called 'generalization'. By inheriting from 'System.Image' your own entity gets all the properties of the system image entity. This means that you can use the standard platform widgets to upload and view images. The same goes for file documents. - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisite: - -* Read [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/) - -## Images - -1. Open your domain model and create an entity called **MyImage**. -2. Double-click the entity to open its properties. -3. Click **Select** at the **Generalization** property to open the entity selector. - - {{< figure src="/attachments/howto8/data-models/working-with-images-and-files/18582124.png" class="no-border" >}} - -4. Select **System.Image** and click the **Select** button. - - {{< figure src="/attachments/howto8/data-models/working-with-images-and-files/18582123.png" class="no-border" >}} - -5. Click **OK** in the entities property form. Your entity now inherits all properties from the 'System.Image' entity you selected and should look like this: - - {{< figure src="/attachments/howto8/data-models/working-with-images-and-files/18582136.png" class="no-border" >}} - -6. Create an overview and detail page to manage objects of the entity that you just created. Your detail page should look like this: - - {{< figure src="/attachments/howto8/data-models/working-with-images-and-files/18582131.png" class="no-border" >}} - -7. Open the **detail page** and double-click the ImageUploader to open its properties. On this form you can select the maximum file size, and thumbnail width and height. Mendix automatically generates a thumbnail for the images you upload via the ImageUploader. - - {{< figure src="/attachments/howto8/data-models/working-with-images-and-files/18582130.png" class="no-border" >}} - -8. Double-click the ImageViewer to open its properties. On this form you can select the default image, width, height and if the viewer should show the thumbnail or full image. - - {{< figure src="/attachments/howto8/data-models/working-with-images-and-files/18582129.png" class="no-border" >}} - -## File Documents - -1. Open your domain model and create an entity **MyDocument**. -2. Double-click the entity to open its **properties.** -3. Click **Select** at the **Generalization** property to open the entity selector. -4. In the **Select Entity** dialog box, select **System.FileDocument**. -5. Click **OK** in the entities property form. Your entity now inherits all properties from the **System.FileDocument** entity you selected and should look like this: - - {{< figure src="/attachments/howto8/data-models/working-with-images-and-files/18582126.png" class="no-border" >}} - -6. Create an overview and detail page to manage objects of the entity that you just created. If you don't know how to create those pages, take a look at [this](/howto8/front-end/create-your-first-two-overview-and-detail-pages/) how-to. Your detail page should look like this: - - {{< figure src="/attachments/howto8/data-models/working-with-images-and-files/18582125.png" class="no-border" >}} - -7. Open the detail page and double-click the FileManager to open its properties. On this form you can select the maximum file size and allowed file extensions. - - {{< figure src="/attachments/howto8/data-models/working-with-images-and-files/18582122.png" class="no-border" >}} - -## Navigation and Security - -1. Create a navigation item for your overview page to start using it. If you don't know how to set up the navigation structure, take a look at [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/). -2. If you turned on security for this application you need to configure page access on both the overview and detail pages. If you don't know how to configure page access, take a look at [How to Create a Secure App](/howto8/security/create-a-secure-app/). - -## Read More - -* [Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/) -* [Denormalize Data to Improve Performance](/howto8/data-models/denormalize-data-to-improve-performance/) -* [Set Up Data Validation](/howto8/data-models/setting-up-data-validation/) -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) diff --git a/content/en/docs/howto8/extensibility/_MAPPING.txt b/content/en/docs/howto8/extensibility/_MAPPING.txt deleted file mode 100644 index 1eaedad50e8..00000000000 --- a/content/en/docs/howto8/extensibility/_MAPPING.txt +++ /dev/null @@ -1 +0,0 @@ -There are document files in this folder that are mapped to the product. Refer to Mapping to Products for the names of these files and how to proceed. \ No newline at end of file diff --git a/content/en/docs/howto8/extensibility/_index.md b/content/en/docs/howto8/extensibility/_index.md deleted file mode 100644 index 7e5b5100ad5..00000000000 --- a/content/en/docs/howto8/extensibility/_index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Extensibility" -url: /howto8/extensibility/ -description: "A selection of how-tos that explain how to use connectors and adapters from the Marketplace." -weight: 80 -no_list: false -description_list: true ---- - -## Introduction - -One of the strengths of Mendix is that it is easy to connect your Mendix application to other systems. The [Mendix Marketplace](https://marketplace.mendix.com/) is stocked with all kinds of connectors and adapters. You are also able to extend your app by using and creating widgets. - -## Documents in This Category diff --git a/content/en/docs/howto8/extensibility/best-practices-javascript-actions.md b/content/en/docs/howto8/extensibility/best-practices-javascript-actions.md deleted file mode 100644 index 36dab8b315a..00000000000 --- a/content/en/docs/howto8/extensibility/best-practices-javascript-actions.md +++ /dev/null @@ -1,481 +0,0 @@ ---- -title: "Implement Best Practices for JavaScript Actions" -linktitle: "JavaScript Actions Best Practices" -url: /howto8/extensibility/best-practices-javascript-actions/ -weight: 60 -description: "This set of best practices will help you get the most out of your JavaScript actions." ---- - -## Introduction - -JavaScript actions can extend your app with several new functions. To implement JavaScript actions most effectively, be sure to follow these best practices. - -These best practices teach you how to do the following: - -* Create high-quality JavaScript actions -* Learn common implementation patterns -* Design better APIs -* Use JavaScript actions in nanoflows - -## Implementing Actions - -JavaScript actions are run in the browser, and each browser version has its own implementation of JavaScript Standard Style. Certain actions, therefore, can run in some browsers but not in others. For compatibility, working with ECMAScript 5 is recommended. - -Older browsers might not have the new ES6 functions implemented, so be careful copying and pasting modern sample code from the internet, especially when IE11 must be supported. Some ECMAScript 6 functions are polyfilled by the Mendix Client. - -Mendix Studio Pro contains the following polyfills from [Core JS](https://github.com/zloirock/core-js): - -* **core-js/fn/array/find** -* **core-js/fn/array/from** -* **core-js/fn/array/includes** -* **core-js/fn/array/fill** -* **core-js/fn/array/find-index** -* **core-js/fn/object/assign** -* **core-js/fn/object/entries** -* **core-js/fn/object/is** -* **core-js/fn/object/set-prototype-of** -* **core-js/fn/object/values** -* **core-js/fn/string/starts-with** -* **core-js/fn/string/ends-with** -* **core-js/fn/string/pad-end** -* **core-js/features/string/includes** -* **core-js/features/promise** -* **core-js/features/symbol** -* **core-js/features/set** -* **core-js/features/map** - -Mendix Studio Pro also contains a polyfill for Mozilla's [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). - -### Handling Input{#handlinginput} - -When creating a JavaScript action, input parameters can be used. Your JavaScript actions will be used by others, but you never know if they will be used correctly. To make actions more robust, validate all input parameters and enable defaults when possible. - -Use this code for validating input string text: - -```javascript -/** - * @param {string} text - */ -function TextToSpeech(text) { - // BEGIN USER CODE - if (text === undefined) { - // Reject when the parameter is set to 'empty' the value will be undefined - return Promise.reject("The Text parameter is required"); - } - if (text.trim() === "") { - // Reject when the text is an empty string "" - return Promise.reject("The Text parameter can not be empty"); - } - /* implementation */ - // END USER CODE - } -``` - -Use this code for validating a Mendix input object: - -```javascript -/** - * @param {MxObject} audioFile - */ -function PlayAudio(audioFile) { - // BEGIN USER CODE - if (!audioFile) { - return Promise.reject("The 'Audio file' parameter can not be empty"); - } - if (!audioFile.isA("System.FileDocument") && !audioFile.inheritsFrom("System.FileDocument")) { - return Promise.reject("The 'Audio file' parameter should inherit from System.FileDocument"); - } - if (!audioFile.get("HasContents")) { - return Promise.reject("The 'Audio file' parameter does not have any content"); - } - var allowedExtensions = ["mp3", "wav", "ogg"] - var fileName = audioFile.get("Name"); - var dotIndex = fileName.lastIndexOf("."); - var extension = fileName.substring(dotIndex + 1).toLowerCase(); - if (dotIndex === -1 || allowedExtensions.indexOf(extension) === -1) { - return Promise.reject("The 'Audio file' parameter only supports files with extension .mp3, .wav or .ogg"); - } - /* implementation */ - // END USER CODE -} -``` - -Use this code for validating an input list of objects and `attributesNames`: - -```javascript -/** - * @param {MxObject[]} objectList - * @param {string} attributeName - * @returns {Big} - */ -function SumListAttributeValues(objectList, attributeName) { - // BEGIN USER CODE - if (!attributeName || attributeName.trim() === "") { - return Promise.reject("The 'Attribute name' parameter can not be empty"); - } - if (!objectList || objectList.length === 0) { - // Resolve early, sum of empty is 0 - return Promise.resolve(new Big(0)); - } - if (!objectList[0].has(attributeName)) { - return Promise.reject("List of type " + objectList[0].getEntity() + " does not have an attribute named " + attributeName); - } - if (!objectList[0].isNumeric(attributeName)) { - return Promise.reject("List of type " + objectList[0].getEntity() + " an attribute named " + attributeName + " is not numeric"); - } - /* implementation */ - // END USER CODE -} -``` - -Use this code for default input values: - -```javascript -/** - * @param {Big} targetSize - * @param {"Module.PictureSource.camera"|"Module.PictureSource.gallery"} pictureSource - * @param {boolean} correctOrientation - * @param {string} waterMark - */ -function CameraStart(targetSize, pictureSource, correctOrientation, waterMark) { - // BEGIN USER CODE - targetSize = targetSize && targetSize > 0 ? targetSize : 150; // numeric - pictureSource = pictureSource ? pictureSource : "camera"; // enumeration - correctOrientation = correctOrientation ? true : false; // boolean - waterMark = waterMark !== undefined ? waterMark : "DEMO"; // string - /* implementation */ - // END USER CODE -} -``` - -For more detail on input types, see [JavaScript Actions](/refguide8/javascript-actions/). For more information on choosing correct input types, see the [Better APIs](#betterapis) section below. - -### Coding the Actions - -To customize your JavaScript actions, consult the sections below. - -#### Understanding the Mendix Client API - -Within the JavaScript actions, the full Mendix Client API is available. For reference, see the [Mendix Client API](/apidocs-mxsdk/apidocs/client-api/). Note that some parts of the Mendix Client API were created for widgets, and are less relevant for JavaScript actions. - -#### Using Numeric Parameters in Your JavaScript Actions - -When you use a parameter of the decimal, integer, or long types, your parameter will not be a number as you are used to in JavaScript. Instead, it will be will be a `Big` object, which comes from a JavaScript library called *Big.js* used by the Mendix Client. This is to ensure that the numbers used in your application are not constrained by default JavaScript number limitations. - -```javascript -// Precision limitation of JavaScript numbers -0.1 + 0.2 // 0.30000000000000004 -// Solved with BigJs -x = new Big(0.1) -y = x.plus(0.2) // '0.3' -``` - -If you know your JavaScript action does not require this extended precision (for example, if you expect a simple integer between 1 and 100), you can easily convert a `Big` object to a JavaScript number: - -```javascript -var numberValue = Number(bigJsValue); // number -``` - -For information on how to use *Big.js*, consult the [big.js API](https://mikemcl.github.io/big.js/). - -#### Creating Objects - -Use the following code to create objects: - -```javascript -mx.data.create({ - entity: "MyFirstModule.Cat", - callback: function(object) { - console.log("Object created on server"); - }, - error: function(error) { - console.error("Could not commit object:", error); - } -}); -``` - -For more information on creating objects, consult the [Create](https://apidocs.rnd.mendix.com/8/client/mx.data.html#.create) section of the *Mendix Client API*. - -#### Changing Objects - -Use the following code to change objects: - -```javascript -mxobj.get("Name"); // "Fred" -mxobj.set("Name", "Henry"); -mxobj.get("Name"); // "Henry" -mxobj.getOriginalValue("Name") // "Fred" -``` - -For more information on changing objects, consult the [Set](https://apidocs.rnd.mendix.com/8/client/mendix_lib_MxObject.html#set) section of the *Mendix Client API*. - -#### Loading Platform-Shipped Dependencies - -Use the following code for loading platform-shipped dependencies (please note the shipped dependencies might vary per Mendix version): - -```javascript -// Synchronous libs that are already loaded -var lang = require("mendix/lang"); -``` - -The following libraries are provided by the Mendix Client: - -* [mendix/lang](https://apidocs.rnd.mendix.com/8/client/module-mendix_lang.html) -* [mendix/validator](https://apidocs.rnd.mendix.com/8/client/module-mendix_validator.html) -* [mxui/dom](https://apidocs.rnd.mendix.com/8/client/module-mxui_dom.html) -* [mxui/html/parser](https://apidocs.rnd.mendix.com/8/client/module-mxui_html_parser.html) - -While there are Dojo and Document Object Model (DOM) functions available, they are not recommended. For more information on Dojo and DOM functions, see the [Understanding Bad Practice](#badpractice) section of this document below. - -#### Using External Dependencies in the Browser - -Loading and bundling external libraries are not currently supported. Embedding library code and CSS inside the JavaScript is not ideal. Adding the library JavaScript file and CSS into the theme folder and referencing them in the *index.html* and the *components.json* is recommended. - -Below is an example of using an external dependency based on [pdf-lib](https://github.com/Hopding/pdf-lib): - -1. Open Command Prompt and navigate to the right folder using `cd --your-project-folder--/javascriptsource/--ModuleName--/actions`. -2. Run `npm install pdf-lib`. -3. In the JavaScript action, use the following code to import the library: - - ```javascript - // This file was generated by Mendix Studio Pro. - // - // WARNING: Only the following code will be retained when actions are regenerated: - // - the import list - // - the code between BEGIN USER CODE and END USER CODE - // - the code between BEGIN EXTRA CODE and END EXTRA CODE - // Other code you write will be lost the next time you deploy the project. - import { Big } from "big.js"; - import { PDFDocument } from "pdf-lib" - - // BEGIN EXTRA CODE - ``` - -#### Understanding Hybrid App External Dependencies - -The Mendix hybrid app ships with a large set of plugins by default. For more details on default plugins, see the [November 20, 2018 Version Upgrades](/releasenotes/mobile/hybrid-app/#upgrades-20) section of the *Hybrid App Base and Template* release notes. - -It is also possible to add new plugins during a mobile build. For more information on adding new plugins, see [Publish a Mendix Hybrid Mobile App in Mobile App Stores](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/). - -The actual list of plugins use can be found in *config.xml* inside your deployment package. - -### Understanding Returns - -The JavaScript action can specify a return type such as Integer, DateTime, Object, List of object, and Generics. For more information on returns, see [JavaScript Actions](/refguide8/javascript-actions/). - -Actions can be synchronous or asynchronous. Synchronous actions will directly return the value and finish executing. An asynchronous action will return a promise, and will continue to execute and finish at a later time. The nanoflow will continue to execute when the promise is resolved. - -At its core, JavaScript is a synchronous programming language – it runs one line of code at a time. If a line of code is executing, it prevents all other JavaScript in the Mendix Client from running, making the Mendix Client appear slow. Asynchronous functions solve this problem. With asynchronous functions, a function is stored for later execution when the results are available. This way, other JavaScript is not prevented from running. - -Use the following code to employ a synchronous return for when your results are directly available: - -```javascript - /** - * @param {Big} valueA - * @param {Big} valueB - * @param {Big} - */ - function AddValue(valueA, valueB) { - // BEGIN USER CODE - return valueA.plus(valueB) - // END USER CODE - } -``` - -Use the following code to employ an asynchronous return for when your nanoflow needs to wait until an action is finished: - -```javascript - function Wait(delay) { - // BEGIN USER CODE - return new Promise(function(resolve) { - window.setTimeout(function(){ - resolve(); - }, delay); - }); - // END USER CODE - } -``` - -Many APIs and functions are designed in an asynchronous way, and use callback functions or promises. A JavaScript action expects a promise to be returned. The promise should be resolved with the return value as expected in the action. - -#### Understanding Promises - -A `Promise` object represents the eventual completion (or failure) of an asynchronous operation and its resulting value. - -Use the following code to wrap a callback API in a promise: - -```javascript -function AskConfirmation(question) { - // BEGIN USER CODE - return new Promise(function (resolve) { - mx.ui.confirmation({ - content: question, - handler: function() { - resolve(true); - }, - onCancel: function() { - resolve(false); - } - }); - }); - // END USER CODE -} -``` - -Explaining the callback code: - -* Use the standard Mendix Client to show a confirmation dialog box with an **OK** and a **Cancel** button (the execution of the nanoflow halts until the user clicks one of the buttons) -* The resolve will return a Boolean value, which is used as the return value of the action -* In the nanoflow, the return variable can be used for an alternative flow for confirmation and cancel - -#### Understanding Promise API - -This function uses the browser promise API: - -```javascript -function GetUserNameSampleRest(userID) { - // BEGIN USER CODE - if (!userID) { - return Promise.reject("The UserID parameter is required") - } - var url = "https://jsonplaceholder.typicode.com/users/" + userID; - return fetch(url) // Fetch returns a promise, gets the url and wait for result - .then(function(response) { return response.json() }) // Transform to json - .then(function(jsonData) { - return jsonData.name; // Get the data - }) - .catch(function(error) { Promise.reject("Failed to get user information") }); - }); - // END USER CODE -} -``` - -Explaining the Promise API code: - -* The URL refers to a sample API that returns a JSON object `{ id: string, name: string }`, and `fetch` is a browser API for retrieving data which returns a promise (see the [MDI Fetch API documentation](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) — the response is a promise that is converted into data with the `.json()` function (the name is accessed and returned) - -* As this is a part of a promise already, it does not need to call a `resolve` function or return a promise itself — this makes error handling on promises easier, as a single error function can be used to catch errors at all three steps: fetch, parse JSON, and accessing the data (for a more detailed explanation, see the [MDN promise documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)) - -* For more information on building a JavaScript action rest consume function, see [Build JavaScript Actions: Part 2 (Advanced)](/howto8/extensibility/write-javascript-github/). - -#### Understanding Common Promise Functions - -These are the most commonly used promise functions: - -* `new Promise(`*`executor`*`)`: creates a new promise that can be returned – the executor function gets two parameters; a resolve and a reject function -* `resolve(someValue)`: should be called with the result value – the value will be used in the nanoflow return value -* `reject(rejectReason)`: throws an error in the nanoflow, and stops the execution -* `Promise.resolve(results)`: returns a `Promise` object that is resolved with the results, which will be set in the output variable of the action in the nanoflow -* `Promise.reject(errorMessage)`: returns a `Promise` object that is rejected, and will explain that the rejection will induce an error in the nanoflow -* `.then()`: enables chaining promises, which will make the code easier to read than nested callback functions - -#### Using Promise Function Best Practices - -When using promise functions, be aware of the following: - -* Currently, JavaScript actions always expect a return type – if an action does not have a relevant returning value, choose return type `String` (the implemented return or promise can be `undefined`) -* When using a JavaScript action in a nanoflow, set the output `Use return variable` to `No` -* Return type Boolean should never be returned with an `undefined` value (this will cause an error if the returned variable is accidentally used in the nanoflow) -* It is recommended to return early so no code is executed if it can or should be skipped – for example, when validating input -* The Promises API is implemented in modern browsers, but not in IE11 (the Mendix Client will polyfill the promise functionally in all supported browsers) -* Uncaught errors in JavaScript will throw an error in microflows – currently, there is no way to add an error handler in nanoflows like you can in microflows - -## Making Reusable JavaScript Actions - -To create and refine your JavaScript actions most effectively, consult the subsections below. - -### Designing Better APIs{#betterapis} - -With well-designed APIs, JavaScript actions will become easier to reuse. Please consider the following guidelines when designing APIs: - -* Create small, functional actions – when actions with many functions are split into smaller components, the nanoflow can combine them in various ways -* Generate the fewest number of side effects – an action without a side effect does not have a state, does not depend on the state of other components, and can thus stand alone (this will also make testing and behavior predicting easier for developers) -* Do not implement actions that can be done with standard actions, and do not combine new and existing functions into single actions (instead, compose the required function with multiple actions in a nanoflow) -* Business logic should be in the nanoflow – the actions should only `Do` things, `Check` states, and `Get` data -* Create `Check` actions and `Do` actions for developers who do not know that the Mendix Client can perform the actions – for example the `CheckCameraSupported` and `OpenCamera` actions -* Name actions and parameters clearly (this will go far in documenting the API) -* Document the action, parameters, defaults, return values, errors, and compatibility – for more information, see the [Documenting JavaScript Actions](#document) section of this document below -* Only expose the most generic functionality – libraries with fewer exposed functions are easier to understand, use, maintain, and test (new features can always be added later) -* Design an API that is independent from the used library (this makes it possible to change the implementation or replace the library without changing the API) -* Use language that is familiar to developers – for example, the function name should not include implementation details; `OpenPhoneGapCamera` should be `OpenCamera` - -Consider these additional technical suggestions for best API practices: - -* Favor enumerations for limited options over a free format string – for example: source "Camera”, "Gallery", or "User choice" -* Prefer Boolean options for binary parameter – for example: 'Blocking dialog' (true / false) -* Prefer primitive return types – do not return objects where possible, but use return String or Decimal instead -* Do not change objects; create new non-persistable entity (NPE) objects instead – NPE objects should be shipped with the action in a module, and can be reused in various unrelated nanoflows -* When you are not working, make NPE objects depend on the Entity or Generic parameters (this way, you can restrict hardcoded entity names which could generate errors when the entities are renamed in the domain model) -* Validate input, and never trust that the developer is using the action correctly – for more information, see the [Handling Input](#handlinginput) section of this document above -* Provide sensible defaults for input parameters whenever possible - -### Exposing JavaScript Actions - -JavaScript Actions can be used in a nanoflow with a JavaScript action call activity. It is also possible to expose the actions in the activity list. This will make it easier for developers to find the actions. It is recommended to expose only the actions that will be reused often. - -Use **Category** to group actions, and **Icon** to give the exposed nanoflow action easy recognition inside the nanoflow: - -{{< figure src="/attachments/howto8/extensibility/best-practices-javascript-actions/narrow-expose.png" alt="exposed nanoflow with info" class="no-border" >}} - -### Publishing JavaScript Actions - -You can export a single action by right-clicking a JavaScript action in the Project Explorer then selecting **Export document to file**. Then, the exported file can be shared with other developers. A single nanoflow cannot be published in the Mendix Marketplace. Instead, publish it as a module. - -You can import a single action by right-clicking your module in the Project Explorer, and then selecting **Import document from file**. Next, select your JavaScript action file. - -A single nanoflow action cannot be published in the Mendix Marketplace. You may publish one as a module, but it is recommended to publish related nanoflow actions as a group within a module. For a module containing multiple nanoflow actions, group actions with a relevant data model like "entities" and provide relevant documentation for external dependencies. Export the module as a whole and upload it to the Mendix Marketplace. For further instructions, see [How to Share Marketplace Content](/appstore/submit-content/). - -### Documenting JavaScript Actions{#document} - -Well-documented actions are easier to reuse. Consider the following when documenting: - -* Correct naming is the most important aspect of documentation - * Use "VerbNoun" naming conventions, for example: GetUser - * Use self-explaining parameter names -* In an action's **Settings** > **Documentation** tab, describe: - * What the action is doing - * The returned value - * Supported platforms, such as web, mobile, or native - * Browser compatibility, such as Chrome, Firefox, or Edge - * Dependent modules (if any) - * The used library or function -* For parameters, add a description and provide the default if implemented -* Referring to documentation for used APIs -* Noting any external dependencies, and explain how they can be added - -## Testing JavaScript Actions - -An extensive test app can help make a JavaScript action more robust. Within a test app, try to create all possible variations of the input, accounting for empty inputs and error cases that should be handled. - -When testing, make sure you to check all compatible platforms (web, hybrid, and native). The web should handle the Mendix browser compatibility. For further information about compatibility, see the [Browsers](/refguide8/system-requirements/#browsers) section of *System Requirements*. - -When an action is not compatible with the platform, make sure it can be checked with an additional action before running into an error. For example, employ a `CheckCameraSupport` action before starting a camera. When an action is called but not compatible, it should fail gracefully or display a clear error message. - -## Debugging JavaScript Actions - -Debugging a JavaScript action's code can be done within a browser development tool. For details on how to do this, see your browser's developer tools documentation at either [Chrome Devtools](https://developers.google.com/web/tools/chrome-devtools/), [Firefox Developer Tools](https://developer.mozilla.org/en-US/docs/Tools), [Microsoft Edge Developer Tools](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium), or Safari's [Web Development Tools](https://developer.apple.com/safari/tools/). - -Initially, JavaScript actions' source code is not loaded. Their source code will be loaded right before the first execution of a module's action. From that moment on, you can find the source code in the **Sources** tab of **Developer Tools** in the folder **javascript-actions** if you are using Chrome. - -After the file is loaded, breakpoints can be set in the code by clicking the inline number (**A**, in the screenshot below). Alternatively, select **Pause on caught exceptions** could be used to find issues (**B**). As a last resort, you could alter the source code by adding the line `debugger;` (**C**). This statement will start the debugging tools the first time the action is executed, and will apply a breakpoint: - -{{< figure src="/attachments/howto8/extensibility/best-practices-javascript-actions/debugging.png" alt="debugging" width="500" class="no-border" >}} - -## Understanding Bad Practices {#badpractice} - -Not all capabilities are recommended for use. Consider the side effects that an action could have on the Mendix Client, DOM, or other widgets: - -* Do not assume your user's browser – remember not all browsers have the same capabilities -* Permanent rendering should be done using pluggable or custom widgets – the new Mendix Client will render the page at will and remove your changes (for example, when you are rendering DOM, work on a DOM node of the `index.html`) -* Changes to the DOM might be lost due to the Mendix Client which can render the DOM at will (for example, when you add a CSS class to another component the Mendix Client will render the page at will and remove your changes) – you can create and change DOM elements that are placed outside `
` -* Avoid using deprecated libraries – do not use Dojo or Dijit as they will be deprecated (jQuery should also no longer be used) -* Avoid using Boolean actions that return `undefined`– the Boolean variable is the only variable that requires a value, is the only acceptable state is `true` or `false`(other variables could be set to `undefined` and can be checked in Mendix Studio Pro as `$variable != empty`) - -## Read More - -* [Build JavaScript Actions](/howto8/extensibility/build-javascript-actions/) -* [JavaScript Actions](/refguide8/javascript-actions/) -* [Mendix Client API](/apidocs-mxsdk/apidocs/client-api/) -* JavaScript basics: - * [Mozilla JavaScript Basics](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics) - * [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) diff --git a/content/en/docs/howto8/extensibility/build-javascript-actions/_index.md b/content/en/docs/howto8/extensibility/build-javascript-actions/_index.md deleted file mode 100644 index faa9d06cecf..00000000000 --- a/content/en/docs/howto8/extensibility/build-javascript-actions/_index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Build JavaScript Actions" -url: /howto8/extensibility/build-javascript-actions/ -weight: 40 ---- - -Mendix has made nanoflows even more powerful with pluggable nanoflow actions — called JavaScript actions — in Mendix 8. With JavaScript actions, the standard set of actions can be extended with new functionality. This how-to series teaches you how to harness the power of JavaScript actions step by step: - -* [Build JavaScript Actions: Part 1 (Basic)](/howto8/extensibility/write-javascript-actions/) -* [Build JavaScript Actions: Part 2 (Advanced)](/howto8/extensibility/write-javascript-github/) -* [Build JavaScript Actions for Native Mobile](/howto8/extensibility/create-native-javascript-action/) diff --git a/content/en/docs/howto8/extensibility/build-javascript-actions/create-native-javascript-action.md b/content/en/docs/howto8/extensibility/build-javascript-actions/create-native-javascript-action.md deleted file mode 100644 index 767bce02469..00000000000 --- a/content/en/docs/howto8/extensibility/build-javascript-actions/create-native-javascript-action.md +++ /dev/null @@ -1,487 +0,0 @@ ---- -title: "Build JavaScript Actions for Native Mobile" -url: /howto8/extensibility/create-native-javascript-action/ -weight: 30 -description: "This tutorial teaches you how to build a JavaScript action for native mobile apps." ---- - -## Introduction - -Native mobile applications have faster performance and give you the ability to use device hardware features. This tutorial teaches you how to build your own JavaScript actions, specifically ones that harness your native mobile device's hardware to read Near Field Communication (NFC) tags. If you would like to use third-party modules other than an NFC scanner, refer to this tutorial as a general overview. - -This how-to teaches you how to do the following: - -* Build a JavaScript action for a native mobile app -* Add a dependency to the native JavaScript action -* Implement an NFC scanner in a JavaScript action - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install Mendix 8.6.0 (Build 715) from the [Marketplace](https://marketplace.mendix.com/link/studiopro/) -* Install the [Git](https://git-scm.com/downloads) command line tool -* Install npm's [Node.js](https://nodejs.org) -* Install [Native Builder v3.1.0](https://www.dropbox.com/sh/hpw7sshut9bco68/AABackrr75rPSgW7u5LBMkMra?dl=0) (this tutorial can only be completed using Native Builder v3.1.0 or higher) -* Have a fiscal [NFC NDEF](https://www.dummies.com/consumer-electronics/nfc-data-exchange-format-ndef/) tag for testing -* Own a mobile device with NFC capabilities - -## Building NFC JavaScript Actions - -To build NFC JavaScript actions, you will do the following: - -1. Create a Mendix project. -1. Build a native mobile app. -1. Add a native dependency. -1. Make two NFC JavaScript actions. -1. Implement the NFC Scanner in your app. - -{{% alert color="info" %}} -This tutorial's commands assume your software is installed in the following places: - -* GitHub working folder: *C:\github* -* Native Builder: *C:\native-builder* -* Studio Pro: *C:\Program Files\Mendix\8.6.0.715* -* Mendix project: *C:\MendixProjects* -{{% /alert %}} - -### Creating a Mendix Project {#test-project} - -Follow these instructions to set up your NFC project: - -1. Open Mendix Studio Pro. -1. Select **File** > **New Project**. -1. Select the **Blank Native Mobile App** (also available online [here](https://marketplace.mendix.com/link/component/109511/)). -1. Click **Use this starting point**. -1. Name your app NativeNFC and click **Create App** to close the dialog box. -1. Rename module **NativeMobile** to *NativeNFC*. You will add your implementation In this module. -1. Right-click the module and select **Add other** > **JavaScript action**. Name the new JavaScript action *HasNFCSupport*. You will create the implementation later. -1. Open the **Home_Native** page and add some welcome text for you test app. -1. Add an action button with caption *Scan NFC Tag* on your home page.
- 1. Right-click your home page and click **Add widget**.
- 2. Select **Call nanoflow button**.
- 3. Click **new**.
- 4. Set the **Name** to *ACT_ReadNFCTag*.
- 5. Change the button's caption to *Read NFC Tag*.
- 6. Save the page.
- 7. Open **ACT_ReadNFCTag**.
- 8. Drag the **HasNFCSupport** JavaScript action onto this nanoflow.
- 9. Save your nanoflow. -1. Click **Run** to deploy to the Free App environment. - -Your Mendix project should looks something like this: - -{{< figure src="/attachments/howto8/extensibility/build-javascript-actions/create-native-javascript-action/native-nfc-app-home-studio-pro.png" alt="native nfc app home" width="550" class="no-border" >}} - -### Building a Native Custom Developer App {#custom-developer-app} - -When developing a native mobile app, you can use the [Make it Native](/refguide8/getting-the-make-it-native-app/) app to quickly get started. However, this app is bundled with a limited number of functionalities. This tutorial's app requires an NFC module in order to access the native NFC capabilities. This can only be achieved by using the [Native Builder](/refguide8/native-builder/). The Native Builder can create a custom developer app which you use to see and test your app. - -In this section, you will create a normal custom developer app to learn the process. In the subsequent section [Installing a Dependency in Your Custom Developer App](#installing-dependency-app) you will create a tailored custom developer app suited for NFC tasks. - -Now you will build a native custom developer app and install it on your phone: - -1. If you do not have your GitHub and App Center keys, follow [Getting Your Tokens](/howto8/mobile/deploying-native-app/#getting-your-tokens) to get your authentication codes. -1. Complete the [Preparing Your Project](/howto8/mobile/deploying-native-app-cli/#preparing) section of *How to Build a Mendix Native App in the Cloud* using these parameters: - - ```shell - native-builder.exe prepare --java-home "C:\Program Files\AdoptOpenJDK\jdk-11.0.3.7-hotspot" --mxbuild-path "C:\Program Files\Mendix\8.6.0.715\modeler\mxbuild.exe" --project-path "Y:\MendixProjects\NativeNFC\NativeNFC.mpr" --github-access-token "a1f422..." --appcenter-api-token "a1b95a..." --project-name "Native NFC App" --app-name "Native NFC App" --app-identifier "com.mendix.howto.nativenfc" --runtime-url "https://nativenfc-sandbox.mxapps.io/" - ``` - - As a result of the `prepare` command your app is created in [App Center](https://appcenter.ms/apps): - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/create-native-javascript-action/app-center-apps.png" alt="App Center apps" width="550" class="no-border" >}} - - A new repository is created in your GitHub account: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/create-native-javascript-action/github-template-repo.png" alt="Github template repo" class="no-border" >}} - -1. To build the app for the first time, complete the [Build Your Developer App](/howto8/mobile/how-to-devapps/#build-your-developer-app) section of *Create a Custom Developer App* using this build command: - - ```shell - native-builder.exe build dev-app --project-name "Native NFC App" - ``` - - The project name should match the project names from your `prepare` command. - -Your apps are now available in the *C:\native-builder\builds* folder, where you will find*Native-NFC-App-Android-1.zip*for an Android app and*Native-NFC-App-iOS-1.zip* for an iOS app. - -{{% alert color="info" %}} - -1. During a build, the free version of the App Center will time out if the build exceeds 30 minutes. -1. By default, Native Builder builds both an iOS and Android apps. To build faster, for one platform specifically, add the parameter `--platform android` or `--platform ios` to the `build` command. - -{{% /alert %}} - -1. Install the app on your device. For more information on app installation, see the [Distributing](/howto8/mobile/deploying-native-app/#distributing) section of *How to Build a Mendix Native App in the Cloud*. -1. Open your app on your testing device. -1. Tap your NFC button. You will incur this error: **JavaScript action was not implemented**. You will implement your action later. - -### Installing a Dependency in Your Custom Developer App {#installing-dependency-app} - -In this section you will install the external library [react-native-nfc-manager](https://www.npmjs.com/package/react-native-nfc-manager) which makes adding NFC functionality easier. Mendix Studio Pro 8.6 is based on *React Native version 0.59*, which will influence the selected version of the library. You will make all changes to the **main** branch, because with each build a new branch is created (`build/{number}`) from **main** with your latest changes. - -The dependency is split into two parts: the native operating system part and the client JavaScript part. To add the dependency for the app, do the following: - -1. Open a command line interface (CLI) and change directory to your GitHub project folder: `cd C:/github/`. -1. Use your repository URL to clone the files on your machine with the command `git clone https://github.com/user-name/native-nfc-app`. -1. Open the folder containing your cloned code: `cd native-nfc-app`. -1. To install all its current dependencies, use the command `npm install`. -1. Install the required library as a dependency with the command `npm install --save react-native-nfc-manager@1.2.2`. - Note the version after the `@` sign. Versions 2 and higher are not supported on Mendix Studio Pro 8.6. - -Next you will use the `react-native link` command to link your module. This command works for React Native versions below 0.60. It is replaced in versions 0.60 and higher with auto-linking. Auto-linking does not require any linking or code changes. However, both processes have downsides and not every module supports them. - -To integrate the module into the template, you will need to make a few code changes. Using `link` you can do most changes automatically with the React Native CLI. If you wish to link automatically, follow the [Setting Up Automatic Linking](#auto-linking) section below. If you wish to link manually, see the [Setting Up Manual Linking](#manual-linking) section below. - -Regardless of which linking method you choose, complete the following steps first: - -1. Install the React Native CLI using the command `npm install -g react-native-cli@2.0.1` (note that the versions should match the React Native version of your Mendix version). -1. Link the new module with the command `react-native link react-native-nfc-manager`. - -#### Setting Up Automatic Linking {#auto-linking} - -You should see successes from the previous linking commands. Even when your linking shows successes in your CLI, linking problems may have occurred with your linked apps. To truly validate success, complete the following steps: - -1. Open *C:\github\native-nfc-app\android\app\src\main\java\com\mendix\nativetemplate\MainApplication.java*. -1. Make sure the following is included in the list of imports: `import community.revteltech.nfc.NfcManagerPackage;`. - -You can skip the Manual Linking section and move on to the [Using the Modules](#using-modules) section now. - -#### Setting Up Manual Linking {#manual-linking} - -This section shows how to link manually. This method replaces the linking steps in the *Installing a Dependency in Your App* section above and could be used for validating if the `react-native link` command succeeded. - -To link for Android devices, do the following: - -1. To expose the library to the template, you must link it using Gradle. Open **C:\github\native-nfc-app\android\settings.gradle**, then add this line of code before `include ':app' , ':mendixnative-release'`: - - ```gradle - include ':react-native-nfc-manager' - project(':react-native-nfc-manager').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-nfc-manager/android') - ``` - -1. To use the new gradle module in **C:\github\native-nfc-app\android\app\build.gradle**, add this to your list of dependencies: - - ```gradle - implementation project(":react-native-nfc-manager") - ``` - -1. Now the main application needs to initialize the NFC manager. In *C:\github\native-nfc-app\android\app\src\main\java\com\mendix\nativetemplate\MainApplication.java* add an item to the `Arrays.asList`, add a comma after the other dependency, and add the `new NfcManagerPackage()`: - - ```java - new NfcManagerPackage() - ``` - -1. When you add this file in Android Studio, the import is automatically added. If you use a plain text editor, add this import to your other imports: `import community.revteltech.nfc.NfcManagerPackage;`. - -To link for iOS devices, do the following: - -1. Open **C:\github\native-nfc-app\ios\Podfile**. -1. In the `abstract_target` section; before `end`, add a new line with `pod 'react-native-nfc-manager', :path => '../node_modules/react-native-nfc-manager'`. - -For more information about linking, see the following resources: - -* Facebook's React Native [Linking Documentation](https://facebook.github.io/react-native/docs/linking) -* The Medium post [Demystifying React Native Modules Linking](https://engineering.brigad.co/demystifying-react-native-modules-linking-964399ec731b) -* The GitHub React Native community post [Autolinking](https://github.com/react-native-community/cli/blob/main/docs/autolinking.md) - -#### Using the Modules {#using-modules} - -For Android devices, you must add code which checks if a user permits the module. Do this by adding `uses permission` in the `android/app/src/main/AndroidManifest.xml` file (specifically in the section above the ` - -``` - -For iOS you have to add permission to use NFC capabilities: - -1. Open your project in Xcode. -1. Select your project in the left menu. -1. In **Signing & Capabilities**, click **Capability** and select **Near Field Communication Tag Reading** - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/create-native-javascript-action/xcode-capabilities-nfc.png" alt="ios capabilities" class="no-border" >}} - -1. Add a usage description so the user can give their permission to use the NFC reader.
- 1. In **ios/nativeTemplate/Info.plist** right-click.
- 2. Select **Add Row**.
- 3. Title the key `NFCReaderUsageDescription` with the description: *To be able to read NFC tags, please accept.* - -#### Committing to the Template {#commit-template} - -For both platforms, you need to store your changes in the template. Push your changes to GitHub (where the Native Builder can use them later): - -1. To stage the changes, use the command `git add .` while in **C:\github\native-nfc-app**. You can check the staged files with the command `git status`. -1. Commit the files with the command `git commit -m "Add NFC Manager dependency"`. -1. Now the files are committed, but they are only stored locally on your machine. Push them to your repository with the command `git push`. This will make the changes available so that the Native Builder can create a new app with NFC support. - -### Installing a Dependency in Your Project {#install-dependency-project} - -The dependency is split into two parts: the native device part, and the client JavaScript part. In this section we will add the dependency JavaScript for the client bundle. For the bundling we need add the dependency builder can add the `react-native-nfc-manager` JavaScript code. - -1. In your CLI, open the module folder which contains your JavaScript action: - - ```powershell - cd C:\MendixProjects\NativeNFC\javascriptsource\nativenfc\actions - ``` - -1. Make sure *HasNFCSupport.js* is in this folder so you know you are in the right place. -1. Install the dependency with the command `npm install react-native-nfc-manager@1.2.2`. - -{{% alert color="info" %}} - -This will create a **node_module** folder inside your **actions** folder. There is a known issue that when you try to commit the *node_modules* folder using Apache Subversion, there could be problems if your commit contains a large number of files. To solve this, try removing unnecessary files before committing. - -{{% /alert %}} - -### Creating NFC JavaScript Actions {#nfc-ja-action} - -JavaScript actions for web and native platforms are similar. However, they have their own set of dependencies which they can build on. - -Build an action to check if a device supports NFC: - -1. Open the **HasNFCSupport** JavaScript action. -1. Change the **Return type** to **Boolean**. -1. Add this import above the `EXTRA CODE` block: - - ```javascript - import { Big } from "big.js"; - import { NativeModules } from "react-native"; - import NfcManager from "react-native-nfc-manager"; - ``` - -1. Replace the content of the `USER CODE` block with the following: - - ```javascript - if (!NativeModules.NfcManager) { - throw new Error("The NfcManager module is not available in your app."); - } - return NfcManager.isSupported(); - ``` - - Explaining the code: - - * The `NativeModules` contains all loaded modules. This allows you to check if the app has the module installed. This will throw an error when the action is used in the **Make it Native** app. - * The NfcManager is imported from your newly added module. The `isSupported` functions check if NFC is supported by the hardware. They return a Promise that will resolved to a Boolean value to indicate if NFC is supported. - - When finished, your code will look like this: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/create-native-javascript-action/action-has-nfc-support-code.png" alt="has NFC support action code" class="no-border" >}} - -1. Optionally, click the **Expose as nanoflow action** tab, select **Expose as nanoflow action**, and **Select** an icon for your JavaScript action. - -Now make an JavaScript action to read the NFC tag information: - -1. Create a JavaScript action named *ReadNFCTag*. -1. Select **Return type** > **String**. -1. Click the **Code** tab, and add the import above the `EXTRA CODE` block: - - ```javascript - import NfcManager, { Ndef } from "react-native-nfc-manager"; - ``` - -1. Add the following code to the USER CODE block: - - ```javascript - return new Promise(resolve => { - NfcManager.registerTagEvent(tag => { - NfcManager.unregisterTagEvent(); - const text = Ndef.text.decodePayload(tag.ndefMessage[0].payload); - resolve(text); - }); - }); - ``` - - Explaining the code: - - Here you return a promise that resolves a string value. The nanoflow will wait until the resolve function is called. The registration listens for tags that are picked up by the reader. When the callback function is executed as a tag is found, un-register the listener to stop listening for other tags. The payload is decoded from a byte array into text. When the resolve function is called with the text parameter, that nanoflow will receive this value as the return parameter. - - When finished, your code will look like this: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/create-native-javascript-action/action-read-nfc-tag-code.png" alt="Read NFC tag action code" class="no-border" >}} - -1. Optionally, click the **Expose as nanoflow action** tab, select **Expose as nanoflow action**, and **Select** an icon for your JavaScript action. - -### Using NFC JavaScript Actions {#use-nfc-action} - -Make a nanoflow to use your new actions: - -{{< figure src="/attachments/howto8/extensibility/build-javascript-actions/create-native-javascript-action/scan-tag-nanoflow.png" alt="Scan tag nanoflow" class="no-border" >}} - -To make the nanoflow shown above, do the following: - -1. Open **ATC_ReadNFCTag**. -1. Double-click the **Has NFC Support** action, set the **Variable name** as *HasNFCSupport*, and click **OK**. -1. Right-click the **Has NFC Support** action, select **Set error handling**, and set the type to **Custom without rollback**. -1. Create a **Show message** action, set the type as **Error**, and set the template as: *Error occurred while checking NFC support: {1}*. Add a parameter containing *$latestError*. -1. Connect the **Has NFC Support** activity to the **Show message** activity. Right-click the connection and select **Set as error handler**. -1. Add an end event under your error message, then connect the message to the end event. -1. Add a **Decision** action. In its **Expression** check for the return variable with the expression *$HasNFCSupport*, write *Has NFC support?* in **Caption**, then click **OK**. Add an end event under this show message activity. -1. If a device is not supported, show a message of type warning. Create a **Show message** action with template text *Sorry, your device does not support NFC.* and then connect this error message to the decision. -1. If a device is supported, add the **Read NFC Tag** action and store the response in the variable `TagValue`. -1. Set the sequence flows from the decision to **True** (going left) and **False** (going down). -1. Right-click the **Read NFC Tag** action and select **Set error handling**. Set the type to **Custom without rollback**. -1. Create a **Show message** action, set the type as error, and set the template text to *Error occurred while reading an NFC tag: {1}*. Use *$lastError* as the single parameter. -1. Connect the **Read NFC Tag** activity with a **Show message** activity. Right-click it, and select **Set as error handler**. -1. Connect this **Show message** action to an end point. -1. Create a **Show message** action, set the type as information, and set the template as *Your NFC tags says: {1}*. Use *$TagValue* as a parameter. -1. Optionally you can add **Show progress** and **Hide progress** activities to give your user more information while using the NFC reader. This action can be found in the **Nanoflow Commons** module. -1. Deploy your app to the sandbox. - -### Writing an NFC Tag {#write-nfc-tag} - -Now you have a way to read NFC *NDEF* tags. Next you will write some text for your tag. You can create a JavaScript action for this yourself or use an existing tool. If you use an existing tool, Mendix recommends [NFC Tools Android](https://play.google.com/store/apps/details?id=com.wakdev.wdnfc) or [NFC Tools iOS](https://apps.apple.com/us/app/nfc-tools/id1252962749). - -To write your own NFC tag, do the following: - -1. Install the NFC Tools app on your device. -1. Open the NFC Tools app. -1. Scan your tag. The **Technologies available** section should state it supports *Ndef*. The **Writeable** section should show **Yes**. -1. Tap **WRITE**, tap **Add a record**, and tap **Text**. -1. Enter the text *Hello Mendix Developer!* and tap **OK**. -1. Tap **Write / 30 Bytes**. -1. Scan your tag. You will see a **Write complete** dialog box: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/create-native-javascript-action/nfc-tools-write-tag.png" alt="write nfc tag" width="250" class="no-border" >}} - -{{% alert color="info" %}} - -This dialog box is your phone's operating system recognizing the NFC tag. On Android devices, you will see a success message anytime you touch an NFC tag to your device. What you truly need to test is your app's NFC scanning after tapping its button. You will be able to do this on all platforms: on iOS things work as expected, and on Android an app scanning NFC takes priority over the operating systems' scanning. - -{{% /alert %}} - -### Rebuilding Your Native Mobile App {#rebuilding-app} - -Now that you added NFC capability to your app's source code, you must rebuild your native mobile app and reinstall it on your device to use the new JavaScript actions. - -{{% alert color="info" %}} - -Making software is an iterative process. If you integrate your own module or build your own actions, it is highly recommended to set up a system which allows you to iterate quickly. For more information on setting up a local development environment, see the [Advanced Usage](/refguide8/native-builder/#advanced-usage) section of the *Native Builder Reference Guide*. This will require an Apple Mac with [Xcode](https://developer.apple.com/xcode/) for iOS and [Android Studio](https://developer.android.com/studio) for Android devices. - -{{% /alert %}} - -1. Open your CLI. -1. Run the following command to rebuild your NFC app: - - ```shell - native-builder.exe build dev-app --project-name "Native NFC App" - ``` - - This builder will use the configuration you set during the [Install a Dependency in Your Project](#install-dependency-project) section above. -1. After the build has successfully finished, the build file will be available in *C:\native-builder\builds*. -1. Uninstall the previous version of the app on your device. -1. Install the app on your device. For more information on installing an app on your device, see the [Distributing](/howto8/mobile/deploying-native-app/#distributing) section of *Build a Mendix Native App in the Cloud*. -1. Open the app, tap **Scan tag**, and scan your NFC tag. You should see a dialog box with the text you assigned to your tag: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/create-native-javascript-action/native-nfc-app-success-android.png" alt="read NFC successfully" width="250" class="no-border" >}} - -Congratulations for completing this NFC tutorial! To go beyond the lessons you have learned, see the sections below. - -### Hardening the Code {#hardening-nfc-action-code} - -Now you have a working NFC scanner. However, you can improve it for both Android and iOS. - -**On Android** — NFC scanning can be switched off. Also, scanning should be canceled if the back button is clicked. - -**On iOS** — Scanning can be canceled when the **Ready to Scan** dialog box is up. - -To implement these capabilities, replace all the **USER CODE** in the **ReadNFCTag** JavaScript action with the following code, then repeat the steps in the [Rebuilding Your App](#rebuilding-app) section above to build and install the updated app on your device: - -```js -// This file was generated by Mendix Studio Pro. -// -// WARNING: Only the following code will be retained when actions are regenerated: -// - the import list -// - the code between BEGIN USER CODE and END USER CODE -// - the code between BEGIN EXTRA CODE and END EXTRA CODE -// Other code you write will be lost the next time you deploy the project. -import { Big } from "big.js"; -import { BackHandler, NativeModules, Platform } from "react-native"; -import NfcManager, { Ndef } from "react-native-nfc-manager"; - -// BEGIN EXTRA CODE -// END EXTRA CODE - -/** - * @returns {Promise.} - */ -export async function ReadNFCTag() { - // BEGIN USER CODE - if (!NativeModules.NfcManager) { - throw new Error("The NfcManager module is not available in your app."); - } - if (Platform.OS === "android") { - const enabled = await NfcManager.isEnabled(); - if (!enabled) { - throw new Error("NFC is not enabled"); - } - } - - return new Promise(async(resolve, reject) => { - let success = false; - await NfcManager.start({ - onSessionClosedIOS: () => { - if (!success) { - reject(new Error("NFC session closed")); - } - } - }); - if (Platform.OS === "android") { - BackHandler.addEventListener("hardwareBackPress", async () => { - await NfcManager.unregisterTagEvent(); - await NfcManager.stop(); - return reject(new Error("NFC was canceled by the user")); - }); - NfcManager.onStateChanged( - async event => { - if (event.state === "off" || event.state === "turning_off") { - await NfcManager.unregisterTagEvent(); - await NfcManager.stop(); - return reject(new Error("NFC was disabled by the user")); - } - } - ) - } - NfcManager.registerTagEvent(async tag => { - success = true; - await NfcManager.unregisterTagEvent(); - await NfcManager.stop(); - const text = Ndef.text.decodePayload(tag.ndefMessage[0].payload); - resolve(text); - }, "Read NFC"); - }); - // END USER CODE -} -``` - -Explaining the code: - -At the beginning of the action on Android, the code checks if the NFC tag reader is switched off and throws an error if so. It creates a Promise with `resolve` and `reject` parameters. Note the `async` keyword before the function. This allows `await` to be used with an asynchronous function and lets them execute together while respecting their order in the code. The `start` will initialize the module and register a callback for iOS. This callback will be called when the **NFC NDEF reader session** becomes invalid, either because of the OS or because the **Cancel** button was tapped. - -For Android, a listener for the **hardware back** button is included. When you tap it, you will stop listening for tags, and cancel the execution by calling the `reject` function. This way the nanoflow will receive an error that is caught by the error handler. - -When the app is listening for a tag, you can switch off the NFC function in Android. This causes a *state change* that you will catch, and causes a rejection to the promise. - -The second parameter of the `registerTagEvent` function is the instruction text which appears in the iOS **Ready to Scan** dialog box. After the tag is found by the reader, you have to `stop` the NFC manager. This way you stop listening for state changes on Android, and you stop listening for the session to close in iOS. - -Congratulations on making your own native JavaScript action! Please use your own creativity to extend the NFC functionality or implement other modules with the lessons you have learned. - -## Building for Release - -Until this section, you have used a custom developer app to validate your application. When you want to distribute your app in the Google Play Store or Apple App Store, you have to make a build that includes the bundled Mendix app. - -For the full explanation on how to build, sign, and distribute your app to an app store see [Deploy Your First Mendix Native Mobile App with the Native Builder CLI](/howto8/mobile/deploying-native-app-cli/) as well as the tutorial's subsequent sections. - -{{% alert color="info" %}} - -The Native Builder will locally run MxBuild. The output is a *bundles.js* file which will be packaged with your application. Therefore, any update on your Mendix model requires a new build. You are not building a development app that updates automatically. - -{{% /alert %}} - -## Read More - -* [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* [JavaScript Actions Reference Guide](/refguide8/javascript-actions/) -* [How To Build JavaScript actions](/howto8/extensibility/build-javascript-actions/) -* GitHub's [NFC React Native Library](https://github.com/whitedogg13/react-native-nfc-manager) diff --git a/content/en/docs/howto8/extensibility/build-javascript-actions/write-javascript-actions.md b/content/en/docs/howto8/extensibility/build-javascript-actions/write-javascript-actions.md deleted file mode 100644 index 68a7b11aee7..00000000000 --- a/content/en/docs/howto8/extensibility/build-javascript-actions/write-javascript-actions.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: "Build JavaScript Actions: Part 1 (Basic)" -linktitle: "1. Build JavaScript Actions" -url: /howto8/extensibility/write-javascript-actions/ -weight: 10 -description: "This how-to teaches you how to create a JavaScript action." ---- - -## Introduction - -Mendix has made nanoflows even more powerful with pluggable nanoflow actions — called JavaScript actions — in Mendix 8. With JavaScript actions, the standard set of actions can be extended with new functionality. A JavaScript action is a reusable action based on JavaScript that runs in the client just like the nanoflow, and can use capabilities such as HTML5 browser functions, Cordova plugins, and React Native modules. JavaScript actions are similar to [Java actions](/refguide8/java-actions/), but run on the client instead of the server. To share them inside your organization, JavaScript actions can be distributed and downloaded through the private [Mendix Marketplace](https://marketplace.mendix.com/). - -This how-to teaches you how to do the following: - -* Create a JavaScript action -* Configure input and output parameters -* Implement web text to speech -* Make an asynchronous return -* Expose an action as a nanoflow action -* Use your actions in a demo - -## Create a JavaScript action: TextToSpeech - -To create a JavaScript action that can synthesize text to speech, follow these steps: - -1. Create a new **JavaScript action** in your Mendix project: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/createanewjsaction.png" alt="add javascript action from drop-down" class="no-border" >}} - -2. Give it a descriptive name: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/descriptivename.png" alt="naming dialog" class="no-border" >}} - - You can now start creating the API for the JavaScript action, which consists of parameters and a return type. - -3. Your **TextToSpeech** action only requires a single parameter. Create it by clicking the **Add** button in the top left corner. Give the parameter a name and add an extended description if desired: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/jsactiondescription.png" alt="javascript action description field" class="no-border" >}} - - You can leave the **Return type** at the default Boolean value. That means that the action will return `false` if no text is provided, and return `true` after it has successfully spoken the provided text. - -4. Next, click the **Code** tab to begin editing the JavaScript action. Now you can start writing the actual action. Mendix Studio Pro already created a default template for you, using the parameters and return type we provided: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/code.png" alt="text to speech code" class="no-border" >}} - - You can only add code between `// BEGIN USER CODE` and `// END USER CODE`. Any code outside this block will be lost. The source code is stored in your project folder under **javascriptsource** > **(module name)** > **actions** > **(action name).js**. This JavaScript action will be asynchronous, so you will be using promises to return values (for details about using promises, see Mozilla's [Using promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) guide). - -5. Now add a check to verify if the required parameter has been set correctly. The action will return `false` if no text was provided: - - ```javascript - function TextToSpeech(text) { - // BEGIN USER CODE - if (!text) { - return Promise.resolve(false); - } - return Promise.reject("JavaScript action was not implemented"); - // END USER CODE - } - ``` - -6. To enable spoken text, you will need the [Web SpeechSynthesis API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis). However, not all browsers support this experimental API. Add a check to verify if the API is available, and include an error if it is not. For future reference, add a comment with references to documentation about our API and its compatibility. - - ```javascript - function TextToSpeech(text) { - // BEGIN USER CODE - // Documentation: https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis - // Compatibility: https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis#Browser_compatibility - if (!text) { - return Promise.resolve(false); - } - if ("speechSynthesis" in window === false) { - return Promise.reject("Browser does not support text to speech"); - - } - return Promise.reject("JavaScript action was not implemented"); - // END USER CODE - } - ``` - -7. Next up is the fun part: making the application speak. Create a new `SpeechSynthesisUtterance` object and call the `speak` function. You will write this new code by overwriting the last `Return` from the previous code. - - ```javascript - function TextToSpeech(text) { - // BEGIN USER CODE - if (!text) { - return Promise.resolve(false); - } - if ("speechSynthesis" in window === false) { - return Promise.reject("Browser does not support text to speech"); - - } - var utterance = new SpeechSynthesisUtterance(text); - window.speechSynthesis.speak(utterance); - return Promise.resolve(true); - // END USER CODE - } - ``` - -8. The function will already return even when the browser is not finished speaking. To prevent this we can attach `onend` and `onerror` handlers to it. The `onend` handler runs when the application finishes speaking the text, so the promise resolves with a value of `true`. In case an error occurs, the promise is rejected and a descriptive error message is shown. After attaching these handlers, it can start speaking: - - ```javascript - function TextToSpeech(text) { - // BEGIN USER CODE - if (!text) { - return Promise.resolve(false); - } - if ("speechSynthesis" in window === false) { - return Promise.reject("Browser does not support text to speech"); - - } - // var utterance = new SpeechSynthesisUtterance(text); - // window.speechSynthesis.speak(utterance); - // return Promise.resolve(true); - return new Promise(function(resolve, reject) { - var utterance = new SpeechSynthesisUtterance(text); - utterance.onend = function() { - resolve(true); - }; - utterance.onerror = function(event) { - reject("An error occurred during playback: " + event.error); - }; - window.speechSynthesis.speak(utterance); - }); - // END USER CODE - } - ``` - -9. You have just implemented your first JavaScript action! You can start using the action in your nanoflows by adding a **JavaScript action call** and selecting the newly created **SpeechToText** action: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/selectjsactioncall.png" alt="javascript action call" class="no-border" >}} - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/selectjsactioncalldetail.png" alt="select text to speech action" class="no-border" >}} - - Optionally, you can expose the JavaScript action as a nanoflow action. When you do, you can choose a **Caption**, **Category**, and **Icon**. Note that to choose an icon your image will need to be included in an existing [image collection](/refguide8/image-collection/). - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/exposeasnanoflow.png" alt="add caption category and icon" class="no-border" >}} - - It will then appear in the **Toolbox** window when editing a nanoflow: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/iconintoolbox.png" alt="text to speech in nanoflow" class="no-border" >}} - -10. Now for a JavaScript action test run! First, make a nanoflow which features your new JavaScript action. Right-click your folder in the **Project Explorer** and click **Add nanoflow**. Then, add an action to your nanoflow, select **call a nanoflow action**, and select your JavaScript action. You will see a window which will let you edit the JavaScript action. Click the **Edit** button of the **Input Text** and type *‘Hello world'*. Then, set **Use return value** to *No* radio button. - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/calljsactionnanoflow.png" alt="edit text in call javascript action dialog" class="no-border" >}} - -11. Now you are going to put your new nanoflow to work. On a page of your app, make an action button by clicking **Add widget** in the top center toolbar. Then, under **Button Widgets**, select **Call nanoflow button**. Select your new nanoflow when prompted. - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-actions/makingwidgetbuttonhighlights.png" alt="select widget dialog" class="no-border" >}} - -12. Click a place on your page to drop your new button where you want it. With the button now on your page, you can test your work. Run your model, click your new button, and if your sound is on you should be greeted by the voice you programmed! - -## Read More{#read-more} - -* [Build JavaScript Actions: Part 2 (Advanced)](/howto8/extensibility/write-javascript-github/) -* [Implement Best Practices for JavaScript Actions](/howto8/extensibility/best-practices-javascript-actions/) -* [JavaScript Actions](/refguide8/javascript-actions/) -* [Mendix Client API](/apidocs-mxsdk/apidocs/client-api/) -* JavaScript Resources: - * [JavaScript basics](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics) - * [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) diff --git a/content/en/docs/howto8/extensibility/build-javascript-actions/write-javascript-github.md b/content/en/docs/howto8/extensibility/build-javascript-actions/write-javascript-github.md deleted file mode 100644 index 5468d53b96f..00000000000 --- a/content/en/docs/howto8/extensibility/build-javascript-actions/write-javascript-github.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -title: "Build JavaScript Actions: Part 2 (Advanced)" -linktitle: "2. Build JavaScript Actions" -url: /howto8/extensibility/write-javascript-github/ -weight: 20 -description: "This advanced how-to teaches you how to make a JavaScript action which can search for GitHub users." ---- - -## Introduction - -Mendix has made nanoflows even more powerful with pluggable nanoflow actions — called JavaScript actions — in Mendix 8. [How to Build JavaScript Actions: Part 1 (Basic)](/howto8/extensibility/write-javascript-actions/) shows you how to create a JavaScript TextToSpeech action, expose it as a nanoflow action, and then use it in a demo. In this advanced how-to you will learn to call a REST service, use a generic return type, and make an API to enhance the power of your JavaScript actions. - -This how-to teaches you how to do the following: - -* Create a JavaScript action -* Configure input and output parameters -* Call a REST service -* Make an asynchronous return -* Create Mendix objects -* Use generic return type -* Expose an action as a nanoflow action -* Use your actions in a demo - -## Prerequisites - -In [Creating a "Search GitHub User" JavaScript Action](#create-a-search) below, you will make an API which allows you to search for GitHub users. Before continuing, you can do the following to practice your API skills: - -* Learn how the GitHub API works using the [GitHub developer documentation](https://developer.github.com/v3/search/#search-users) -* Use test tooling to see how the GitHub API in action — an HTTP GET request of the URL `https://api.github.com/search/users?q=test` will result in a JSON response which you should study - -## Downloading the Project Package - -This how-to comes paired with an app package prepared for you by Mendix. To download and import the package, follow the steps below: - -1. In Mendix Studio Pro, click the Marketplace icon. -2. Search for "JavaScript Actions How-To Advanced". -3. Click the app, then click **Download** to receive an *.mpk* file. -4. Select **New Mendix Team Server**, name your app *JavaScriptActionsHowToAdvanced*, select a **Project Directory**, and click **OK**: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/import-package.png" alt="import package" class="no-border" >}} - -## Creating a “Search GitHub User” JavaScript Action {#create-a-search} - -To create a JavaScript action that can search for users on GitHub, follow the steps below: - -1. Add a new **JavaScript action** in your Mendix project: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/add-js-action.png" alt="add javascript action" class="no-border" >}} - -2. Name it *SearchGitHubUsers*: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/name-js-action.png" alt="name javascript action" class="no-border" >}} - - You can now start creating the API for **SearchGitHubUsers**, an action which consists of parameters and a return type. - -3. Your **SearchGitHubUsers** JavaScript action only requires a single parameter. Create it by clicking **Parameters** > **Add**. Name the parameter *Query,* and add an extended **Description** if desired. - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/name-query.png" alt="parameter name" class="no-border" >}} - -4. Set the **Return type** to **List**, and set **Entity** as the **GithubUser** entity: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/return-entity.png" alt="return type and entity" class="no-border" >}} - - With these parameter and return type settings, a successful search will return a list of **GithubUser** objects containing login names, avatars, URLs, and more. - -5. Click the **Code** tab to begin editing the JavaScript action. Mendix Studio Pro has created a default template using the parameters and return type you provided: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/default-code.png" alt="default code" class="no-border" >}} - - You can only add code between `// BEGIN USER CODE` and `// END USER CODE`. Any code outside this block will be lost. Source code is stored in your project folder under **javascriptsource/(module name)/actions/(action name).js**. - -6. Now add a check to verify if the required parameter has been set correctly. The action will return an empty list if no `query` was provided: - - ```javascript - function SearchGitHubUser(query) { - // BEGIN USER CODE - if (!query) { - return []; - } - return Promise.reject("JavaScript action was not implemented"); - // END USER CODE - } - ``` - -7. To enable your action to search GitHub users, implement a REST request: - - ```javascript - function SearchGitHubUser(query) { - // BEGIN USER CODE - if (!query) { - return []; - } - var url = "https://api.github.com/search/users?q=" + query; - return fetch(url) // Fetch returns a promise, gets the url and wait for result - .then(function(response) { return response.json() }) // Transform to JSON - .then(function(jsonData) { // Process JSON data - // log to the console a successful result - logger.debug("count results", jsonData.total_count); - return []; // return an empty list for now... - }); - // END USER CODE - } - ``` - - This code uses the Fetch API. Browser compatibility is irrelevant, as this API is provided by the Mendix Runtime when unavailable in the browser. - -8. Next up is the fun part: making Mendix objects. Create a new function called `createGitHubUser` that returns a `new Promise`. The executor function of the promise should use the Mendix client API to create a new object and set the attributes. -9. Loop over all results and call your new function. The `githubUsers` variable will hold an array of promises. -10. Finally, set a `Promise.all` return to wait for all promises to be resolved before the nanoflow can continue: - - ```javascript - function SearchGitHubUser(query) { - // BEGIN USER CODE - if (!query) { - return []; - } - var url = "https://api.github.com/search/users?q=" + query; - return fetch(url) - .then(function(response) { return response.json() }) - .then(function(jsonData) { - logger.debug("count", jsonData.total_count); - var gitHubUsers = jsonData.items.map(createGitHubUser); - return Promise.all(gitHubUsers); - }); - - function createGitHubUser(user) { - return new Promise(function (resolve, reject) { - mx.data.create({ - entity: "HowTo.GitHubUser", - callback: function(mxObject) { - mxObject.set("login", user.login); - mxObject.set("avatar_url", user.avatar_url); - resolve(mxObject); - }, - error: function(e) { - reject("Could create object:" + error.message); - } - }); - }); - } - // END USER CODE - } - ``` - - The entity name consists of **{(modulename)}.{(entityname)}**. The entity name, therefore, might have been different if the **GitHubUser** entity was created in another module. Because this JavaScript action has names explicitly written into it, when a module or entity is renamed, the JavaScript action will break. You will fix this hard-coded relation in [step 12](#step-twelve) below. - -11. The function will only set the `login` and `avatar_url` properties. To make it more flexible, you will make the function discover the available attributes and set them. Extend the domain model with more attributes from the API like so: - - ```javascript - function SearchGitHubUsers(query, userEntity) { - // BEGIN USER CODE - if (!query) { - return []; - } - var url = "https://api.github.com/search/users?q=" + query; - return fetch(url) - .then(function(response) { return response.json() }) - .then(function(jsonData) { - logger.debug("count", jsonData.total_count); - var gitHubUsers = jsonData.items.map(createGitHubUser); - return Promise.all(gitHubUsers); - }); - - function createGitHubUser(user) { - return new Promise(function (resolve, reject) { - mx.data.create({ - entity: "HowTo.GitHubUser", - callback: function(mxObject) { - // Dynamically set attributes - mxObject.getAttributes() - .forEach(function(attributeName) { - var attributeValue = user[attributeName]; - if (attributeValue) { - mxObject.set(attributeName, attributeValue); - } - }); - resolve(mxObject); - }, - error: function(error) { - reject("Could create object:" + error.message); - } - }); - }); - } - // END USER CODE - } - ``` - -12. Now the attributes are dynamic, but the names of the module and entity are not. To solve this, do the following:
- 1. Open **Settings** > **Type parameters**.
- 2. Click **Add**.
- 3. Provide the name *UserEntity*.
- 4. Click **OK**: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/add-user-entity.png" alt="add user entity" class="no-border" >}} - -13. Open the **General** tab again and add a new parameter of the type **Entity**. Select **Fill in a type parameter**, then from the **Type parameter** drop-down menu select **Type parameter 'UserEntity'**. This will couple the input entity with the generic type parameter: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/couple-input-with-generic.png" alt="couple input with generic" class="no-border" >}} - -14. In **Return type** > **Entity** do the following:
- 1. Click **Select**.
- 2. Select **Type Parameters** > **UserEntity**.
- 3. Click **OK**: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/select-user-entity.png" alt="select user entity" class="no-border" >}} - -15. Your final step is updating the code. The new `userEntity` parameter has already been added. In the `mx.data.create` function, set `userEntity` as the `entity` to be created. Then, add some documentation for future reference: - - ```javascript - /** - Searching users on GitHub.com, it could find users via various criteria. This action returns up to 100 results. - @param {string} query - The query contains one or more search keywords and qualifiers. Qualifiers allow you to limit your search to specific areas of GitHub. - @param {string} userEntity - The entity to match the Return type Entity - @returns {MxObject[]} - */ - function SearchGitHubUsers(query, userEntity) { - // BEGIN USER CODE - // Documentation: https://developer.github.com/v3/search/#search-users - // Will return JSON structure - // { - // "total_count": 82531, - // "incomplete_results": false, - // "items": [ - // { - // "login": "mojombo", - // "avatar_url: "http://..." - // } - // ] - // } - if (!query) { - return []; - } - var url = "https://api.github.com/search/users?q=" + query; - return fetch(url) // Fetch returns a promise, gets the URL and wait for results - .then(function(response) { return response.json() }) // Transform response to JSON - .then(function(jsonData) { // Handle the JSON - logger.debug("count", jsonData.total_count); - var gitHubUsers = jsonData.items.map(createGitHubUser); - return Promise.all(gitHubUsers); - }); - - function createGitHubUser(user) { - // Wrap the Mendix Client API in a promise - return new Promise(function (resolve, reject) { - mx.data.create({ - entity: userEntity, - callback: function(mxObject) { - // Dynamically set attributes - mxObject.getAttributes() - .forEach(function(attributeName) { - var attributeValue = user[attributeName]; - if (attributeValue) { - mxObject.set(attributeName, attributeValue); - } - }); - resolve(mxObject); - }, - error: function(error) { - reject("Could create object:" + error.message); - } - }); - }); - } - // END USER CODE - } - ``` - -16. You have just implemented an advanced JavaScript action! Start using the action in your nanoflows by adding a **JavaScript action call**, and then selecting the newly created **SearchGitHubUsers** action: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/add-jsaction-call.png" alt="add javascript action call" class="no-border" >}} - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/select-searchgithub-users.png" alt="select search GitHub users" class="no-border" >}} - - Optionally, you can expose the JavaScript action as a nanoflow action. When you do, you can choose a **Caption**, **Category**, and **Icon**. Note that your icon image will need to be in an existing [image collection](/refguide8/image-collection/): - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/nanoflow-options.png" alt="nanoflow options" class="no-border" >}} - - It will then appear in the **Toolbox** window when editing a nanoflow: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/toolbox-window.png" alt="toolbox window" class="no-border" >}} - -17. To test your JavaScript action, do the following:
- 1. Add the **SearchGitHubUsers** action to the search nanoflow then double-click it.
- 2. Click **User entity** > **Select**, then double-click the **GitHubUser** entity.
- 3. Click **Query** > **Edit**, then type in *$GithubSearch/Query* and click **OK**.
- 4. To display the results in the user interface, type *UserList* into the **List** field.
- 5. Your finished **Call JavaScript Action** will look like this: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/variable-display.png" alt="list display" class="no-border" >}} - -18. To edit your **Change object** activity, do the following:
- 1. Double-click your **Change object** activity.
- 2. Select **GithubSearch(HowTo.GithubSearch)** from the **Object** drop-down menu.
- 3. Click **Action** > **New**.
- 4. Select **HowTo.GithubSearch_GithubUser(ListofHowTo.GithubUser)** from the **Member** drop-down menu.
- 5. Type *$UserList* into the **Value** field and click **OK**.
- - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/edit-change-item.png" alt="edit change" class="no-border" >}} - - 6. Your finished **Change object** action will look like this: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/change-object-final.png" alt="change object" class="no-border" >}} - -19. Run your project, then use your new search action to find a GitHub user: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/find-user.png" alt="find user" class="no-border" >}} - -20. If your project did not function correctly, consult the **Solution** folder to see correct versions of the nanoflow and JavaScript action: - - {{< figure src="/attachments/howto8/extensibility/build-javascript-actions/write-javascript-github/solution.png" alt="solution" class="no-border" >}} - -Congratulations! Using the power of JavaScript actions, your app can search for any GitHub user. - -## Read More - -* [Build JavaScript Actions: Part 1 (Basic)](/howto8/extensibility/write-javascript-actions/) -* [Mendix Client API](/apidocs-mxsdk/apidocs/client-api/) -* [JavaScript Actions](/refguide8/javascript-actions/) -* JavaScript Resources - * [JavaScript Basics](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics) - * [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) - * [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) diff --git a/content/en/docs/howto8/extensibility/build-native-widget.md b/content/en/docs/howto8/extensibility/build-native-widget.md deleted file mode 100644 index 8173cb85e06..00000000000 --- a/content/en/docs/howto8/extensibility/build-native-widget.md +++ /dev/null @@ -1,1435 +0,0 @@ ---- -title: "Build a Pluggable Native Widget" -url: /howto8/extensibility/build-native-widget/ -description: "Describes building a native widget, configuring it, and styling it in a Mendix app." -weight: 10 -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -Pluggable widgets, introduced in Mendix 8, enable developers to create new widgets beyond the core widgets shipped with Mendix Studio Pro. The pluggable widgets API works for both web and native mobile, offering you unique power and flexibility. For the web platform, the rendering is based on React and the React DOM. For mobile, the rendering uses the React Native framework. - -In this how-to, you will learn to create a group box pluggable widget for native mobile applications with React Native. - -This how-to teaches you core widget concepts by having you build configure, and style a group box widget. For more information on customizing pluggable widgets, see the [Pluggable Widgets API Documentation](/apidocs-mxsdk/apidocs/pluggable-widgets/). - -A group box can be used to visually group related widgets together. Group boxes are displayed as a frame around nested widgets with an optional header. Group boxes can be configured to collapse and expand dynamically, and look like this: - -{{< figure src="/attachments/howto8/extensibility/build-native-widget/group-box-tease.png" alt="final widget" class="no-border" >}} - -This how-to teaches you how to do the following: - -* Generate a widget structure -* Put a pluggable widget into a Mendix app -* Configure your widget's properties and styling to suit multiple platforms - -**Are you in a hurry?** - -Clone this [code sample](https://github.com/mendix/native-group-box-pluggable-widget-sample) from GitHub with all group box features from this how-to already implemented. - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install the latest version of Mendix Studio Pro 8.18.x. -* Install the Mendix Make It Native app for Mendix 8 on a mobile device or an emulator. -* Install [Node.js](https://nodejs.org) v16. -* Install the latest [Yeoman](https://yeoman.io/) with the following command: - - ```shell - npm install -g yo - ``` - -* Install the latest Mendix Pluggable Widget Generator for Yeoman for Mendix 8 with the following command: - - ```shell - npm install -g @mendix/generator-widget@"<9" - ``` - -* Install an integrated development environment (IDE) of your choice (Mendix recommends [Microsoft Visual Studio Code](https://code.visualstudio.com/)) -* Have a basic understanding of: - * Microsoft's Command Prompt or the Unix command line - * [TypeScript](https://www.typescriptlang.org/) - * [React](https://reactjs.org) - -## Building a Native Group Box Widget - -To build a group box widget for native mobile, you will follow these steps: - -1. Scaffold a pluggable widget project. -2. Create a Mendix test project. -3. Build the group box widget. - -The following subsections will elaborate on each of these steps. - -### Scaffolding a Pluggable Widget Project - -The Pluggable Widget Generator is the quickest way to start developing a pluggable widget. When you run this generator with Yeoman, Yeoman will scaffold your project folder with a folder structure and certain files recommended by Mendix. - -To scaffold your project folder for the group box widget, follow these steps: - -1. Open up a terminal. -2. Change the current working directory to the folder where you want to store your widget project. - - {{% alert color="info" %}}Make sure to store your widget project in a folder not connected to Dropbox. Dropbox blocks files from being watched, which will prevent you from completing this document. - {{% /alert %}} - -3. Start the generator by executing the following command: - - ```shell - yo @mendix/widget GroupBox - ``` - -4. The generator will ask you for some input during setup. Provide this information to the generator: - - * Widget name: {*GroupBox*} - * Widget description: {*Widget to group building blocks, snippets, or other widgets.*} - * Organization name: {*Your organization*} - * Copyright: {*Your copyright statement*} - * License: {*Apache-2.0*} - * Initial version: {*1.0.0*} - * Author: {*Your name*} - * Mendix Project path: {*./tests/testProject/*} - * Programming language: {**TypeScript**} - * Widget type: {**For native mobile apps**} - * Widget template: {**Empty widget (recommended for more experienced developers)**} - * Unit tests: {**No**} - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/pluggable-widget-generator-input.png" alt="Pluggable Widget Generator input" class="no-border" >}} - -5. Your widget will build. If your project has been scaffolded correctly, you will see the following message: - - `> Widget successfully built!! Please open Mendix Studio Pro and start playing with your new widget.` - -Note that whenever it is required to reinstall NPM package dependencies inside the scaffolded widget development project with an NPM version of 7 or higher, make sure to run the installation script with an extra flag: `npm install --legacy-peer-deps`. - -### Creating a Mendix Test Project - -In order to test your group box widget, you will a Mendix application that uses this widget in various ways. Create a Mendix project for this application by following these steps: - -1. Open Studio Pro. -2. Create a new project by clicking **File** > **New Project**. -3. Select the **Blank Native Mobile App** (do not select **Blank App**). -4. Click the **Use this starting point** button -5. Fill in the following details in the **App Settings** dialog box: - * App name: *GroupBoxTestProject* - * Enable online services: *No* -6. Click **Create app**. - -Follow these steps to add the Mendix project as a test project to your widget project, so that you can start modeling with the new widget: - -1. Close the project in Mendix Studio Pro by clicking **File** > **Close Project**. -2. Move the contents of the Mendix project folder into **tests/testProject**, which is located inside your group box widget project folder. - -Create a test case by following these steps: - -1. Build the widget by running `npm run build` in the root folder of the pluggable widget. -2. Open the Mendix test project in **tests/testProject** by selecting **File** > **Open Project**. -3. In the **Open App** dialog box, select **Locally on disk**. -4. Open the *GroupBoxTestProject.mpr* file inside your group box widget project folder. -5. Set the **Security level to Off** in Project Security. -6. Open **Home_Native** page. -7. Delete all widgets from the page. -8. Edit the page properties and set all Spacing properties to Inner medium. -9. Search in Toolbox for the **Group Box** widget. If you cannot find it, press F4 to refresh the project widgets. -. Drag the widget into the empty container: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/initial-widget.png" alt="initial widget" class="no-border" >}} - -10. Double-click the widget, fill in your name as the **Default value**, and click **OK**. - -You have set up your test project. To verify that your Mendix test project is set up correctly, follow these steps: - -1. In Studio Pro, run the test project locally. -2. Use the Make It Native app to open your new app. -3. Verify that your app's home page contains the yellow text **Hello {your name}**. - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/1-yellow-text-mobile.png" alt="hello user" class="no-border" >}} - -### Building the Group Box Widget - -Now that your widget sample code is running, it is time to transform your sample widget into an actual group box widget. To do so, you will follow these steps: - -1. Create a static UI. -2. Add widget properties. -3. Make the widget collapsible. -4. Add an expand and collapse icon property. -5. Add a collapsible property. -6. Add a custom default style. -7. Add a design property. - -The following paragraphs will elaborate on each of these steps. Open up your group box widget project folder in your IDE of choice. From now on, all file references will be relative to this project folder. - -#### Creating a Static UI - -Define the structure and default style of the group box widget with these steps: - -1. Open **src/components/HelloWorldSample.tsx**. - - This file contains the display component of your widget. Display components describe the widget's UI in terms of React Native components and contain the widget's behavioral logic. Display components do not interact with Mendix-specific APIs and therefore are usable in any React Native application. - -2. Replace the **render** method with the following code snippet: - - ```tsx - render(): ReactNode { - return ( - - - Header caption - - - - - Content - - - ); - } - ``` - - The **render** method uses two built-in components from React Native: **\** and **\**. **\** is a component like a \
or \ from HTML, whereas the **\** component is used to display some text. To learn more about the built-in components, consult the [React Native website](https://facebook.github.io/react-native/). - -3. Open up a terminal. -4. Change the current working directory to your project folder. -5. Execute the following command to bundle your widget and update the widget bundle in your Mendix test project: - - ```shell - npm start - ``` - - The executed script will keep watching your source files and rebundle the widget every time you save one of these files. - -6. Open your Mendix test project in **test/MxTestProject** in Mendix Studio Pro. -7. Run the project locally. -8. Verify with the Make It Native app that your app looks like the image below: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/2-header-caption-mobile.png" alt="basic app" class="no-border" >}} - - {{% alert color="info" %}}If you encounter an error with the widget in Studio Pro, you might have to update the widget by right clicking on it or synchronize the project directory by pressing F4 to fix it. - {{% /alert %}} - -The UI of your widget does not look like a group box yet. Apply a default style to make it look like one with the following steps: - -1. Open *src/components/HelloWorldSample.tsx*. -2. Replace the following **defaultStyle** constant: - - ```tsx - const defaultStyle: CustomStyle = { - container: {}, - label: { - color: "#F6BB42" - } - }; - ``` - - with this: - - ```tsx - const defaultStyle: CustomStyle = { - container: { - borderColor: "#000000", - borderRadius: 4, - borderWidth: 1, - overflow: "hidden" - }, - header: { - backgroundColor: "#000000", - display: "flex", - flexDirection: "row", - justifyContent: "space-between", - paddingVertical: 10, - paddingHorizontal: 15 - }, - headerContent: { - color: "#FFFFFF", - fontSize: 16, - fontWeight: "bold" - }, - content: { - paddingVertical: 10, - paddingHorizontal: 15 - }, - label: { - color: "#F6BB42" - } - }; - ``` - - The objects assigned to the properties of **defaultStyle** are passed to the style props of the React Native components that you use in the **render** method. The property names inside the objects are similar to CSS style properties. To learn more about the supported properties and what effect they have, visit the following links: - - * [\ style props](https://facebook.github.io/react-native/docs/view-style-props) - * [\ style props](https://facebook.github.io/react-native/docs/text-style-props) - -3. Save all files to rebundle and update the Mendix test project. -4. Refresh the Mendix app inside the Make It Native app. -5. Verify that the group box widget looks like the image below: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/3-bw-header.png" alt="black white widget" class="no-border" >}} - -When you build a widget for native mobile, keep in mind that the widget can be used on both iOS and Android. Both platforms have their own design language, and you should adhere as much as possible to both languages. To do this, you will sometimes need to define platform-specific styling or use platform-specific React Native components. - -For the group box widget it would be nice to have square corners on Android devices. Apply this style behavior with the following steps: - -1. In **src/components/HelloWorldSample.tsx** you must adjust the import statement in order to use the **Platform** detection feature. Change the import from this: - - ```tsx - import { Text, View } from "react-native"; - ``` - - to this: - - ```tsx - import { Text, View, Platform } from "react-native"; - ``` - -2. Change the value of `defaultStyle.container.borderRadius` from `4` to `Platform.OS === "ios" ? 4 : 0` so that the initialization of the **defaultStyle** constant look as follows: - - ```tsx - const defaultStyle: CustomStyle = { - container: { - borderColor: "#000000", - borderRadius: Platform.OS === "ios" ? 4 : 0, - borderWidth: 1, - overflow: "hidden" - }, - header: { - backgroundColor: "#000000", - display: "flex", - flexDirection: "row", - justifyContent: "space-between", - paddingVertical: 10, - paddingHorizontal: 15 - }, - headerContent: { - color: "#FFFFFF", - fontSize: 16, - fontWeight: "bold" - }, - content: { - paddingVertical: 10, - paddingHorizontal: 15 - }, - label: { - color: "#F6BB42" - } - }; - ``` - -3. Save all files to rebundle and update the Mendix test project. -4. Refresh the Mendix app inside the Make It Native app. -5. Verify that the group box widget looks like the image below (if you are using an Android test device, your border will look a little different): - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/3a-bw-header.png" alt="black white widget" class="no-border" >}} - -As you might have noticed, the display component is still called **HelloWorldSample**. Next you will introduce the term "GroupBox" in your code: - -1. In **src/components/HelloWorldSample.tsx** change the class name from `HelloWorldSample` to *GroupBox*. -2. Change the file name to *GroupBox.tsx*. -3. Rename the **HelloWorldSampleProps** interface to *GroupBoxProps*. -4. Change the **GroupBox** class declaration to the following: - - ```tsx - export class GroupBox extends Component - ``` - -The changes you made in steps one and two cause errors in your container component defined in *src/GroupBox.tsx*. The container component is used by the Mendix Client, receives property data from this client, and forwards this data to the display component. - -To fix the errors in the container component, use these steps: - -1. Open *src/GroupBox.tsx*. -2. Replace the following import: - - ```tsx - import { HelloWorldSample } from "./components/HelloWorldSample"; - ``` - - with this: - - ```tsx - import { GroupBox as WrappedGroupBox } from "./components/GroupBox"; - ``` - -3. Rename the **HelloWorldSample** component in the **render** method to *WrappedGroupBox*. - -You are not using the **label** property of the **defaultStyle** constant anymore in the **render** method of the display component. Remove it by doing the following: - -1. Open **src/components/GroupBox.tsx**. -2. Remove the **label** property from the **defaultStyle** constant: - - ```tsx - const defaultStyle: CustomStyle = { - container: { - borderColor: "#000000", - borderRadius: Platform.OS === "ios" ? 4 : 0, - borderWidth: 1, - overflow: "hidden" - }, - header: { - backgroundColor: "#000000", - display: "flex", - flexDirection: "row", - justifyContent: "space-between", - paddingVertical: 10, - paddingHorizontal: 15 - }, - headerContent: { - color: "#FFFFFF", - fontSize: 16, - fontWeight: "bold" - }, - content: { - paddingVertical: 10, - paddingHorizontal: 15 - } - }; - ``` - -3. Open **src/GroupBox.tsx**. -4. Remove the **label** property from the **CustomStyle** interface and add the new style properties **header**, **headerContent**, **content**: - - ```tsx - export interface CustomStyle extends Style { - container: ViewStyle; - header: ViewStyle; - headerContent: TextStyle; - content: ViewStyle; - } - ``` - -5. Save all files to rebundle and update the Mendix test project. -6. Refresh the Mendix app inside the Make It Native app. -7. Verify that the group box widget still looks the same after the refactoring: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/3-bw-header.png" alt="black white widget" class="no-border" >}} - -#### Adding Widget Properties - -Now that you have a basic group box, give the Mendix developer the possibility to customize it with the help of widget properties: a header caption and a content property. - -#### Header Caption Property - -Next you will allow the Mendix developer to alter the header caption of your widget. You can reuse the code and configuration of the default value property you used earlier to alter the **Hello World** output of the sample widget. - -1. Open **src/GroupBox.xml** and change the yourName property to this: - - ```xml - - Header caption - - - ``` - -2. Save the file. As soon as you save the file, the script running in the background will rebundle the widget and generate new typings in **typings/GroupBoxProps.d.ts**. These typings define the props the container component will receive. Some errors will surface in the container component because you renamed the property. - -3. Open **src/GroupBox.tsx** and change this line in your render method: - - `return ;` - - to this: - - `return ;` - - Note that our display component doesn't receive a **headerCaption** prop yet. - -4. Your display component does not receive a headerCaption prop yet, so open **src/components/GroupBox.tsx** and replace this: - - ```tsx - export interface GroupBoxProps { - name?: string; - style: CustomStyle[]; - } - ``` - - with this: - - ```tsx - export interface GroupBoxProps { - headerCaption?: string; - style: CustomStyle[]; - } - ``` - -5. You still need to use the **headerCaption** prop in the render method to display the actual text in your header. Adjust the render method like this: - - ```tsx - render(): ReactNode { - return ( - - - {this.props.headerCaption} - - - - - Content - - - ); - } - ``` - -Do these final steps to sync and run your app: - -1. In Studio Pro press F4 or select **Project > Synchronize Project Directory** to sync your app with the changes you made to **src/GroupBox.xml**. -2. An error will tell you to update your widget. Right-click the Group Box widget and select **Update widget**. -3. Double-click the same widget and you will now see your new property. -4. Fill in some caption text, click **OK**, and rerun your app locally to see your caption text in the app: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/4-this-is-my-text.png" alt="sample text mobile" class="no-border" >}} - -#### Content Property - -You will also want Mendix developers to be able to fill content in the group box like building blocks, snippets, and other widgets. To enable this, do the following: - -1. In **src/GroupBox.xml**, add a content property element above the header caption property. -2. Change the name element from **Group Box** to *Group box* so its name fits correct conventions. -3. Remove the "needsEntityContext" attribute from the widget element, since this is no longer necessary. -4. Your file should now look like this: - - ```xml - - - Group box - - - - - - Content - Widgets to place inside. - - - Header caption - - - - - - ``` - -5. Save the file. -6. Open **src/GroupBox.tsx**. -7. Change the **render** method as follows to pass the content (React Native components) to the display component: - - ```tsx - render(): ReactNode { - const { content, headerCaption, style } = this.props; - - return ( - - {content} - - ); - } - ``` - -8. Save the file. -9. Open **src/components/GroupBox.tsx**. -10. Adjust the **render** method to render the content: - - ```tsx - render(): ReactNode { - const { children, headerCaption } = this.props; - - return ( - - - {headerCaption} - - - - {children} - - ); - } - ``` - -Verify that the new content property works: - -1. Go back to Studio Pro. -2. Press F4 or select **Project > Synchronize Project Directory** to bring your application in sync with the changes to the **src/GroupBox.xml** file. -3. Update the group box widget again. A content area will appear in the page editor: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/content-area.png" alt="content area" class="no-border" >}} - -4. Drag a **Call nanoflow button** widget into the content area. -5. Click **New** and a new nanoflow *ACT_ShowMessage*. -6. Double-click the button and change the **Caption** to *Show message*. -7. Navigate to **ACT_ShowMessage**. -8. Drag a **Show message** activity into your nanoflow. -9. Double-click the activity and add the text *Hello World!* to the **Template**, then click **OK**. -10. Rerun the app locally. -11. With the Make It Native app, verify that your button is inside the group box and is triggering a message popup saying **Hello World!**. - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/5-hello-world.png" alt="hello world" class="no-border" >}} - -It would be nice to hide the content area of the group box completely when there is no content added to the group box in Mendix Studio Pro: - -1. In *src/components/GroupBox.tsx* import the `Children` component so your total components look like this: - - ```tsx - import { Children, Component, ReactNode, createElement } from "react"; - ``` - -2. Extract the rendering of the content area from the **render** method to a lambda method called **renderContent**: - - ```tsx - private renderContent = (): ReactNode => { - if (Children.count(this.props.children) === 0) { - return null; - } - - return {this.props.children}; - }; - ``` - -3. Make a call to **renderContent** in the **render** method. When you do this, your **render** method will look like this: - - ```tsx - render(): ReactNode { - return ( - - - {this.props.headerCaption} - - - - {this.renderContent()} - - ); - } - ``` - -4. To see your changes, drag a new **Group box** widget onto your home page. Run your project and check to see that your new group box with no content shows no empty white box: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/6-button-inside.png" alt="new group box" class="no-border" >}} - -5. Delete the empty **Group box** widget you created in the previous step, then rerun your app to save your changes. - -#### Making the Widget Collapsible - -Now that your widget can contain content, the next challenge is to hide this content by making the group box Collapsible. - -To start, make the complete header clickable: - -1. Navigate to the display component (**src/components/GroupBox.tsx**). -2. Import the React component **ComponentClass** so that your React imports look like this: - - ```tsx - import { Children, Component, ReactNode, createElement, ComponentClass } from "react"; - ``` - -3. Import the React Native components **TouchableOpacity** and **TouchableNativeFeedback** so that your React Native imports look like this: - - ```tsx - import { Text, View, Platform, TouchableOpacity, TouchableNativeFeedback } from "react-native"; - ``` - -4. Create the following lambda method that is responsible for rendering the clickable header: - - ```tsx - private renderHeader = (): ReactNode => { - const view = ( - - {this.props.headerCaption} - - - - ); - - const Touchable: ComponentClass = Platform.OS === "ios" ? TouchableOpacity : TouchableNativeFeedback; - - return {view}; - }; - ``` - - In the method above, the **Touchable** constant is a dynamic component. Depending on which platform on your app is running, the **Touchable** constant represents either the React Native built-in component **TouchableOpacity** or **TouchableNativeFeedback**. Each platform uses a different component to achieve a different type of tap feedback. Tapping on Android causes a ripple effect, whereas on iOS tapping causes an opacity effect. - -5. Change the **render** method to make use of **renderHeader**: - - ```tsx - render(): ReactNode { - return ( - - {this.renderHeader()} - {this.renderContent()} - - ); - } - ``` - -6. Make sure all files have been saved. -7. Reload your test app in the Make It Native app to view the change. -8. Verify the header is clickable by tapping it. You should see a light-up effect on iOS. Note that on Android, the ripple effect is not visible on a black background, so you cannot verify yet if it is clickable. - -Now make it possible to expand or collapse the group box: - -1. Navigate to the display component (**src/components/GroupBox.tsx**). -2. Create an **GroupBoxState** interface below the **GroupBoxProps** one: - - ```tsx - export interface GroupBoxState { - collapsed: boolean; - } - ``` - -3. Change the class definition to give our component a state to keep track on whether it is collapsed or not: - - ```tsx - export class GroupBox extends Component - ``` - -4. Set collapsed to **false** as the initial state inside the class: - - ```tsx - readonly state: GroupBoxState = { - collapsed: false - }; - ``` - -5. To change the collapsed state, add a property **toggleCollapsed** to the class and assign the following arrow function to it: - - ```tsx - private toggleCollapsed = (): void => { - this.setState(prevState => ({ collapsed: !prevState.collapsed })); - }; - ``` - -6. Let the **Touchable** component execute the **toggleCollapsed** method when it is tapped. Also, add a switch between a plus and minus character in the header depending on the state. The **renderHeader** method should look as follows: - - ```tsx - private renderHeader = (): ReactNode => { - const view = ( - - {this.props.headerCaption} - - - - ); - - const Touchable: ComponentClass = Platform.OS === "ios" ? TouchableOpacity : TouchableNativeFeedback; - - return {view}; - }; - ``` - -7. Change the **renderContent** method to only render the content when the group box is not collapsed: - - ```tsx - private renderContent = (): ReactNode => { - if (this.state.collapsed || Children.count(this.props.children) === 0) { - return null; - } - - return {this.props.children}; - }; - ``` - -8. Verify in the Make it Native app that you can expand and collapse the group box by tapping your widget's header. - -#### Adding an Expand and Collapse Icon Property - -The next step is to allow a Mendix developer to use a custom icon in the clickable header. First, define the properties and adjust the display component so that it can render icons: - -1. Navigate to **src/GroupBox.xml**. -2. Add two icon properties to set an icon for indicating the actions expand and collapse: - - ```xml - - - Group box - - - - - - Content - Widgets to place inside. - - - Header caption - - - - Expand icon - Icon used to indicate that the group box can be expanded. - - - Collapse icon - Icon used to indicate that the group box can be collapsed. - - - - - ``` - -3. Add property groups around the properties to create a more readable properties window in Studio Pro: - - ```xml - - - Group box - - - - - - - Content - Widgets to place inside. - - - - - Caption - - - - Expand icon - Icon used to indicate that the group box can be expanded. - - - Collapse icon - Icon used to indicate that the group box can be collapsed. - - - - - - ``` - -4. Save the *.xml* file. -5. Navigate to the display component **src/components/GroupBox.tsx**. -6. Add two new props for an expand and collapse icon by changing the **GroupBoxProps** interface: - - ```tsx - export interface GroupBoxProps { - collapseIcon?: ReactNode; - expandIcon?: ReactNode; - headerCaption?: string; - style: CustomStyle[]; - } - ``` - -7. Create a property **renderIcon** and assign an arrow function to it that uses the **expandIcon** and **collapseIcon** props: - - ```tsx - private renderIcon = (): ReactNode => { - const { collapseIcon, expandIcon } = this.props; - - if (this.state.collapsed) { - return expandIcon ? expandIcon : +; - } - - return collapseIcon ? collapseIcon : -; - }; - ``` - -8. Change the method **renderHeader** so that it makes use of **renderIcon**: - - ```tsx - private renderHeader = (): ReactNode => { - const view = ( - - {this.props.headerCaption} - {this.renderIcon()} - - ); - - const Touchable: ComponentClass = Platform.OS === "ios" ? TouchableOpacity : TouchableNativeFeedback; - - return {view}; - }; - ``` - -Next you have to pass the icons configured by the Mendix developer to your display component. If an icon is not explicitly configured, you will pass a default glyph (glyphs are provided by the Mendix Client). Glue everything together in the container component by doing the following: - -1. Navigate to the container component **src/GroupBox.tsx**. -2. Create two constants outside the class which hold the glyph references: - - ```tsx - const defaultCollapseIconGlyph = "glyphicon-minus"; - const defaultExpandIconGlyph = "glyphicon-plus"; - ``` - -3. Add the following imports: - - ```tsx - import { DynamicValue, NativeIcon, ValueStatus } from "mendix"; - import { Icon } from "mendix/components/native/Icon"; - import { GroupBox as WrappedGroupBox, GroupBoxProps as WrappedGroupBoxProps } from "./components/GroupBox"; - ``` - -4. Add a property **renderIcon** to the **GroupBox** class and assign the following arrow function to it: - - ```tsx - private renderIcon = (toBeRenderedIcon: DynamicValue | undefined, glyph: string): ReactNode => { - const nativeIcon: NativeIcon = - toBeRenderedIcon && toBeRenderedIcon.status === ValueStatus.Available - ? toBeRenderedIcon.value - : { type: "glyph", iconClass: glyph }; - - return ; - }; - ``` - -5. Adjust the **render** method so that it makes use of **renderIcon**: - - ```tsx - render(): ReactNode { - const { collapseIcon, expandIcon, content, headerCaption, style } = this.props; - - const props: WrappedGroupBoxProps = { - headerCaption, - collapseIcon: this.renderIcon(collapseIcon, defaultCollapseIconGlyph), - expandIcon: this.renderIcon(expandIcon, defaultExpandIconGlyph), - style - }; - - return {content}; - } - ``` - -6. Navigate to Studio Pro. -7. Press F4 or select **Project > Synchronize Project Directory** to bring your application in sync with the changes you made to the **src/GroupBox.xml** file. -8. Update the group box widget. -9. Double-click your widget. -10. In the **Icon** described as **Icon used to indicate that the group box can be expanded** click **Edit**. -11. Click the € sign and click **Select**: -12. Click **OK**, then run the app locally. -13. Inspect your changes. Notice that you cannot see any icon in group box's header. This is because your background color and text color are both black. Remember that in the **defaultStyle** constant of your display component you defined that text of React Native components that get the **headerContent** style applied to it should be white. However, you are not explicitly applying this style to our **Icon** component that you pass from our container component to the display component. You could argue to move the creation of the **Icon** component inside your display component, but this will go against the strict separation of concerns related to the container and display component, since the **Icon** component is Mendix specific. Therefore, it should be part of the container component. - -Fix your icon issue by introducing a default style for your container component: - -1. In **src/GroupBox.tsx** add the following **defaultStyle** constant outside the container component class: - - ```tsx - const defaultStyle: CustomStyle = { - container: {}, - header: {}, - headerContent: { - color: "#FFFFFF", - fontSize: 16 - }, - content: {} - }; - ``` - -2. Import the `mergeNativeStyles` function: - - ```tsx - import { Style, mergeNativeStyles } from "@mendix/pluggable-widgets-tools"; - ``` - -3. Add the following private attribute to the container component class: - - ```tsx - private readonly styles = mergeNativeStyles(defaultStyle, this.props.style); - ``` - - The **mergeNativeStyles** function will take the styling of the **defaultStyle** constant as a starting point and will override this with properties supplied in the **style** prop. - -4. Adjust the **renderIcon** method so that it returns an **Icon** component with a color and size defined: - - ```tsx - private renderIcon = (toBeRenderedIcon: DynamicValue | undefined, glyph: string) => { - const nativeIcon: NativeIcon = - toBeRenderedIcon && toBeRenderedIcon.status === ValueStatus.Available - ? toBeRenderedIcon.value - : { type: "glyph", iconClass: glyph }; - - return ( - - ); - }; - ``` - -5. Refresh the app in the Make It Native app. You should see the white icons in the correct size: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/7-better-button-inside.png" alt="better button" class="no-border" >}} - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/8-collapsed-w-euro-sign.png" alt="collapsed with euro" class="no-border" >}} - -#### Adding a Collapsible Property {#adding-a-collapsible-property} - -You are close to completing your group box widget. There are two more features essential for a Mendix developer: setting if the group box should be collapsible and setting the initial state of being collapsed or not. - -First change the widget property configuration: - -1. Navigate to **src/GroupBox.xml**. -2. Add a **collapsible** property underneath the **content** property: - - ```xml - - - Group box - - - - - - - Content - Widgets to place inside. - - - Collapsible - - - No - Yes (start expanded) - Yes (start collapsed) - - - - - - Caption - - - - Expand icon - Icon used to indicate that the group box can be expanded. - - - Collapse icon - Icon used to indicate that the group box can be collapsed. - - - - - - ``` - -3. Add a property group **Common** below the **Header** property group and include the system properties **Name** and **Visibility** to improve the properties window even more: - - ```xml - - - Group box - - - - - - - Content - Widgets to place inside. - - - Collapsible - - - No - Yes (start expanded) - Yes (start collapsed) - - - - - - Caption - - - - Expand icon - Icon used to indicate that the group box can be expanded. - - - Collapse icon - Icon used to indicate that the group box can be collapsed. - - - - - - - - - - ``` - -4. Add this image as a widget icon by following the substeps below: - - 1. Download this image: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/group-box.png" alt="Group box icon" class="no-border" >}} - - 2. Generate a Base64 representation of the *.png* file: - - **— For Windows**: - - 1. Open command prompt.
- 2. Change your current working directory to the folder where *GroupBox.png* is stored.
- 3. Execute the following command to generate the Base64 representation:
- - ```shell - certutil -encode GroupBox.png data.b64 - ``` - - Upon success, you will see a **data.b64** file in the same location as your original image. - - **— For Unix**: - - 1. Open a terminal.
- 2. Change the current working directory to the folder where the "GroupBox.png" is stored.
- 3. Execute the following command to generate the Base64 representation:
- - ```shell - base64 -i GroupBox.png -o data.b64 - ``` - - Upon success, you will see a **data.b64** file in the same location as your original image. - - 3. Add **data.b64** to the icon element in the *.xml* file. For ease, the contents of the file you made is included below. You can simply copy and paste this snippet with its binary Base64 representation included into your *xml* file: - - ```xml - - - Group box - - iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAAHdbkFIAAAAAXNSR0IArs4c6QAA ArVJREFUeAHtWk12gjAQBl4X9Q72PsVFnxufN+ihegOfG18XtfeRO9gVNBMZDPlx gIAQGDcxmczMN99MQohGkc9nt9sVCWVgChNiAAloKbBuOaU9hTBJDPGjKI7HYyyJ 2u/3aZ7nP24y7BIw8AIiUIZO+v2XFnlhGPrdrmqOYC4i80oVGJLY0JodqH0UdUgW 7er30fEN3LGM9c0njZlI45sEjilpEwXqyEpExffT1Vj7AmJ23q6kp1Lp7lko1gxg yaJBva0qTxFUBhCSImv+tYsy6oxfiYwgirw56KeQmpfcBGfetnUBDEv7WRhxYVc5 QMcowH7frR6oAQAdpqfrRWxua+xTrb6VCUcXoVPpuwJzAsBNlHLskguHt+3eNaEc NwDoFBH63mIDgIsqb0+lAT1A753EFxgDYAaYAXUfyMSSWuvr1HeZsf7kGVAPJLXH 55DIkyTZHA6HM/hQl2H17B7SOdhWrwXUVSD9Lu5paDCA9Lc5ksVJvDl/vMqcor56 JFNzjnJs1RrAMdm2OQ9GefFVU751qpoSObfJ5SwnA/oh0+Lg4VDTWnIy8NB6j0KD gWc/C6bHQNPcdc2CzvDoDDAAZoAZYAaYAWaAGVjsiSjreqBhPWZgbgxU9yMYmPpO i2Mzams/HUNctgdB9U49o8AxFCM24zmAM7Ed+j0R/QzV6u+huh9bBehzZt0nK0CP vs29ma5L9dW/e7jmEnuUscZddnC8fQUk8ScARQN9tdKmsE3ZE5eNMMfmPytllIma vHUFlDehjX4PrnnqqVPervfmv30F9BTIVMyQFUDtolMJpCsOrgCKOT4HUAwFLl/8 EmACAq9gb/hcAd4UBm6AKyDwBHrD5wrwpjBwA1wBgSfQGz5XgDeFgRtYfAXwjZBe wfAXTzFmu3XVp4bWh1tjiI0/zIDCwD+0qr6OmQMSvQAAAABJRU5ErkJggg== - - - - - Content - Widgets to place inside. - - - Collapsible - - - No - Yes (start expanded) - Yes (start collapsed) - - - - - - Caption - - - - Expand icon - Icon used to indicate that the group box can be expanded. - - - Collapse icon - Icon used to indicate that the group box can be collapsed. - - - - - - - - - - ``` - -5. Save the *.xml* file. - -Now support this section's two features with your display component: - -1. Navigate to the display component **src/components/GroupBox.tsx**. -2. Add a prop for collapsibility and a prop for the initial state of being collapsed or not to the **GroupBoxProps** interface: - - ```tsx - export interface GroupBoxProps { - startCollapsed?: boolean; - collapsible: boolean; - collapseIcon?: ReactNode; - expandIcon?: ReactNode; - headerCaption?: string; - style: CustomStyle[]; - } - ``` - -3. Change the initialization of the state so that the collapsed state starts with the value passed through the **startCollapsed** prop: - - ```tsx - readonly state: GroupBoxState = { - collapsed: !!this.props.startCollapsed - }; - ``` - - If you do not want the group box to be collapsible at all, you must remove the **Touchable** component that wraps the header to prevent toggling the collapsed state. Moreover, remove the icons inside the header indicating the group box is collapsible. Enact these changes by following these steps: - -4. Change the **renderHeader** method so that it does not render the **Touchable** component around the header **View** component: - - ```tsx - private renderHeader = (): ReactNode => { - const { collapsible, headerCaption } = this.props; - - const view = ( - - {headerCaption} - {this.renderIcon()} - - ); - - if (collapsible) { - const Touchable: ComponentClass = Platform.OS === "ios" ? TouchableOpacity : TouchableNativeFeedback; - return {view}; - } - - return view; - }; - ``` - -5. Prevent the header **View** component from being rendered at all when the group box is not collapsible and there is no header caption. Otherwise, the header would be visible as an empty block: - - ```tsx - private renderHeader = (): ReactNode => { - const { collapsible, headerCaption } = this.props; - - const view = ( - - {headerCaption} - {this.renderIcon()} - - ); - - if (collapsible) { - const Touchable: ComponentClass = Platform.OS === "ios" ? TouchableOpacity : TouchableNativeFeedback; - return {view}; - } else if (headerCaption) { - return view; - } - - return null; - }; - ``` - -6. Change the **renderIcon** method to prevent an icon from being rendered when the group box is not collapsible by adding a guard that returns null: - - ```tsx - private renderIcon = (): ReactNode => { - const { collapsible, collapseIcon, expandIcon } = this.props; - - if (!collapsible) { - return null; - } - - if (this.state.collapsed) { - return expandIcon ? expandIcon : +; - } - - return collapseIcon ? collapseIcon : -; - }; - ``` - -7. Change the **render** method to so it can function when there is neither header nor content to be rendered by returning null: - - ```tsx - render(): ReactNode { - const renderedHeader = this.renderHeader(); - const renderedContent = this.renderContent(); - - if (!renderedHeader && !renderedContent) { - return null; - } - - return ( - - {renderedHeader} - {renderedContent} - - ); - } - ``` - -The last thing to do is change the container component so that the properties get passed to the display component: - -1. Navigate to the container component **src/GroupBox.tsx**. -2. Change the **render** method to supply the display component with the information from the collapsible prop that the container component receives: - - ```tsx - render(): ReactNode { - const { collapsible, collapseIcon, expandIcon, content, headerCaption, style } = this.props; - - const isCollapsible = collapsible !== "no"; - - const props: WrappedGroupBoxProps = { - collapsible: isCollapsible, - headerCaption, - collapseIcon: this.renderIcon(collapseIcon, defaultCollapseIconGlyph), - expandIcon: this.renderIcon(expandIcon, defaultExpandIconGlyph), - style - }; - - if (collapsible) { - props.startCollapsed = collapsible === "yesStartCollapsed"; - } - - return {content}; - } - ``` - -3. Navigate to Studio Pro. -4. Press F4 or select **Project > Synchronize Project Directory** to bring your application in sync with the changes you made to the **src/GroupBox.xml** file. -5. Update the group box widget. Notice that now your widget has the icon you loaded into its *xml*: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/groupbox-64-icon.png" alt="groupbox 64" class="no-border" >}} - -6. Verify that the collapsible property options behave correctly by double-clicking your widget and testing each collapsible property option on your test device: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/collapsible-properties.png" alt="collapsible properties" class="no-border" >}} - -#### Adding a Custom Default Style - -Although you have an extensively featured group box widget, you can still improve its styling. Currently, the widget receives basic styling which has been baked its code. You can make the Mendix Client override this default styling by defining a custom default style for the widget in Atlas UI. To define a custom default style, follow these steps: - -1. Open **test/MxTestProject/theme/styles/native/app/custom.js**. This file will let you define a custom default style for your group box widget. - -2. Add the following imports and constant to *custom.js* to define a default custom style: - - ```js - import { brand } from "../core/variables"; - import shadeblendconvert from "../core/helpers/_functions/shadeblendconvert"; - - export const com_mendix_widget_native_groupbox_GroupBox = { - container: { - borderColor: brand.primary - }, - header: { - backgroundColor: brand.primary - }, - headerContent: { - color: "#000000" - } - }; - ``` - - Note that the name of the constant has to be almost the same as the widget ID. However, the widget ID's periods need to be underscores. Using this convention, the Mendix Client can apply the custom style defined in this constant to the group box widget. - -3. Save the file and refresh the your app in the Make It Native app to see your new default style. On Android, note the ripple effect on the header that was previously not visible: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/9-default-styling.png" alt="default styling" class="no-border" >}} - -#### Adding a Design Property - -It would be nice to provide the developer with some pre-defined styles that can be used for the group box. Create three style classes for the group box based on the brand colors success, warning, and danger: - -1. In **test/MxTestProject/theme/styles/native/app/custom.js**, add the following constants to end of the file: - - ```js - export const groupBoxSuccess = { - container: { - borderColor: brand.success - }, - header: { - backgroundColor: shadeblendconvert(0.4, brand.success) - }, - headerContent: { - color: "#000000" - } - }; - - export const groupBoxWarning = { - container: { - borderColor: brand.warning - }, - header: { - backgroundColor: shadeblendconvert(0.4, brand.warning) - }, - headerContent: { - color: "#000000" - } - }; - - export const groupBoxDanger = { - container: { - borderColor: brand.danger - }, - header: { - backgroundColor: shadeblendconvert(0.4, brand.danger) - }, - headerContent: { - color: "#000000" - } - }; - ``` - -2. In Studio Pro, double-click the group box widget. -3. Navigate to the appearance section. -4. In the **Class** field, fill in *groupBoxWarning* to apply the warning style to the group box. -5. Click **OK** and rerun the app locally to see the warning style: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/10-warning-styling.png" alt="warning styling" class="no-border" >}} - -Defining all the different styles inside **test/MxTestProject/theme/styles/native/app/custom.js** can make your code less readable. To prevent this, extract the styles specifically for the group box widget and store them in a separate file: - -1. Create a new file **test/MxTestProject/theme/styles/native/app/group-box.js**. -2. Move all the code from **test/MxTestProject/theme/styles/native/app/custom.js** into the new file. -3. Add the following import to **test/MxTestProject/theme/styles/native/app/custom.js**: - - ```javascript - export * from "./group-box"; - ``` - -4. Refresh your app in the Make It Native app to verify the custom warning style is still being applied to the group box widget. - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/10-warning-styling.png" alt="warning styling" class="no-border" >}} - -The developer needs to have the class names memorized to apply a certain group box style. By using a design property this will no longer be necessary: - -1. Open **test/MxTestProject/theme/settings-native.json**. -2. At the bottom after the "com.mendix.widget.native.slider.Slider" property, add the following property: - - ```json - "com.mendix.widget.native.groupbox.GroupBox": [ - { - "name": "Group box style", - "type": "Dropdown", - "description": "Style of the group box.", - "options": [ - { - "name": "Success", - "class": "groupBoxSuccess" - }, - { - "name": "Warning", - "class": "groupBoxWarning" - }, - { - "name": "Danger", - "class": "groupBoxDanger" - } - ] - } - ] - ``` - - Note that the property name must be the same as the widget ID. This will ensure this design property can be configured for your group box widget in Studio Pro. - -3. In Studio Pro, press F4 or select **Project > Synchronize Project Directory** to bring your application in sync with the changes you made to the previous two files. - -4. Double-click the group box widget and navigate to the **Appearance** tab. - -5. Verify that there is a design property called **Group box style**. - -6. Select the **Success** style and click **OK**: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/success-design-property.png" alt="success style" class="no-border" >}} - -7. Rerun the app locally and verify the new success style in the Make It Native App: - - {{< figure src="/attachments/howto8/extensibility/build-native-widget/11-success.png" alt="mobile success" class="no-border" >}} - -## Read More - -* [Pluggable Widgets API Documentation](/apidocs-mxsdk/apidocs/pluggable-widgets/) -* [How to Implement Native Mobile Styling](/howto8/mobile/native-styling/) -* [Native Mobile Styling Reference Guide](/refguide8/native-styling-refguide/) -* [How to Build Pluggable Widgets](/howto8/extensibility/pluggable-widgets/) diff --git a/content/en/docs/howto8/extensibility/howto-connector-kit.md b/content/en/docs/howto8/extensibility/howto-connector-kit.md deleted file mode 100644 index b34cb002468..00000000000 --- a/content/en/docs/howto8/extensibility/howto-connector-kit.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: "Build Microflow Actions Using the Mendix Connector Kit" -linktitle: "Microflow Actions Using Connector Kit" -url: /howto8/extensibility/howto-connector-kit/ -description: "Describes creating custom Microflow actions using advanced Connector Kit options." -weight: 80 -#To update screenshots of these microflows in Studio Pro, use the SlackRekognition-main-master app, which is saved locally in Other Resources > Documentation Backups (No Update). ---- - -## Introduction - -The goal of the Mendix [Connector Kit](https://www.mendix.com/blog/introducing-mendix-connector-kit/) is to enable Java developers to easily add powerful and robust new microflow actions to their Mendix toolbox. These microflow actions can be shared in the Mendix Marketplace, so anyone can benefit from them without having to know Java. - -To illustrate the power of the Connector Kit, here's a high-level design diagram for an application Mendix recently built: a Slack bot that enables users to determine things and people in pictures taken with a mobile Slack app: - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/slack-rekogition-bot-architecture.png" alt="Slack Rekognition Bot design" class="no-border" >}} - -The Mendix application consists of a small number of microflows that use Mendix microflow actions to offer a conversational user interface using [Slack](https://slack.com/) and different Amazon services: [S3](https://aws.amazon.com/s3/), [Rekognition](https://aws.amazon.com/rekognition/), and [Lex](https://aws.amazon.com/lex/). - -This image shows what the microflow toolbox looks like after including all the modules that provide connectors to the services used: - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/slack-rekogition-bot-toolkit.png" alt="Slack Rekognition bot toolbox" class="no-border" >}} - -For the basics of building toolbox actions, see the [Introducing the Mendix Connector Kit](https://www.mendix.com/blog/introducing-mendix-connector-kit/) blog post. - -This how-to teaches you how to do the following: - -* Use advanced features when creating your own microflow actions -* Create the **Create object list** action -* Create the **Import string** action -* Create the **Join objects in list** action - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/toolkit-connector-kit-demo.png" alt="Connectorkit demo toolbox" class="no-border" >}} - -## Creating Generic Actions Using Type Parameters - -Let's start with type parameters. In the **Type parameters** tab in the Java action definition dialog box, you can use a type parameter if you want to ensure that certain parameters of your action share the same entity but you do not know the name of this entity when defining the actions. - -For example, suppose you want to create an action that takes two objects of the same entity and returns a list containing both objects. You can use a type parameter to guarantee that both the input parameters for specifying the objects and the resulting list all use the same entity. - -To create a generic action using type parameters, follow these steps: - -1. Define the type parameter to hold the entity used by all the parameters: - - {{< figure src="/attachments/howto8/extensibility/howto-connector-kit/join_objects_type_par.png" alt="Type parameter tab" class="no-border" >}} - -2. Create parameters using the previously defined type parameter *EntityToJoin*: - - {{< figure src="/attachments/howto8/extensibility/howto-connector-kit/join_objects_pars.png" alt="Type parameter use" class="no-border" >}} - -3. The action needs the following parameters: - * **Entity** – this is used to specify the entity of the objects to join - * The entity selected by the user will be stored in the type parameter *EntityToJoin* - - {{< figure src="/attachments/howto8/extensibility/howto-connector-kit/join_objects_type_par_def.png" alt="Type parameter use definition" class="no-border" >}} - - * **Object1** – the first object to be added to the new list - - * This needs to be an object of the `EntityToJoin` entity - * **Object2** – the second object to be added to the new list - * **Return type** – the result of the action will be a list of `EntityToJoin` objects - -The Java implementation still uses strings to specify the name of an entity, which means that you can upgrade your existing Java actions to use these new parameter types without having to refactor your existing code. - -Finally, here's the actual Java implementation of the action defined: - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/join_objects_javacode.png" alt="Java implementation join object" class="no-border" >}} - -You now have a reusable action in your toolbox that will join two objects into a list as illustrated by this example: - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/join_objects_use.png" alt="Join objects use" class="no-border" >}} - -As you can see, type parameters enable creating typesafe generic actions. - -## Executing Microflows - -The following example illustrates how you can use microflow parameters. The microflow below creates a list of **Product** objects and calls a microflow for every project object to initialize it: - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/init-loop.png" alt="Init loop" class="no-border" >}} - -Here's an alternative to the microflow above that uses a custom Java action to replace the loop, instantiation, and initialization of the objects with a Java action: - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/init-list-use.png" alt="Init list loop with action" class="no-border" >}} - -The action uses the following parameters: - -* **ResultEntity** – the entity used for the default object and the result list -* **DefaultObject** – the default value for the objects to be instantiated -* **InitializationMicroflow** – a microflow that will be called for every new object to initialize it -* **ListSize** – the number of objects to be created in the list - -The return type is a list of new initialized objects. - -As you can see below, this action uses a new parameter type (**Microflow**) to indicate that the user needs to specify a microflow. When using the action, Studio Pro will show a list of microflows to make this as easy to use as possible. - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/initialize_list_mf_pars.png" alt="Initialize list using microflow action parameters" class="no-border" >}} - -In the Java implementation for this action, you'll see the following details for the parameters: - -* **ResultEntity** – a string with the entity name used for the default object and the result list -* **DefaultObject** – an IMendixObject instance containing the default object -* **InitializationMicroflow** – a string containing the name of the initializing microflow -* **ListSize** – a long variable containing the number of objects desired in the list - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/initilialize_list_java_1.png" alt="Initialize list java implementation 1" class="no-border" >}} - -The `executeAction` method is where all the magic happens: - -1. It initializes an ArrayList for the result. -2. It has a for-loop to create the desired number of objects. -3. The objects are created using `Core.instantiate()`. The entity name specified in the action is used as the input to specify what entity to instantiate. -4. The system determines if a default object was specified. If so, it copies all the attribute values to the new object. -5. The system executes the initialization microflow using `Core.execute()`. -6. Add the newly instantiated and initialized object to the result list. -7. The list of new objects is returned. - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/initilialize_list_java_2.png" alt="Initialize list java implementation 2" class="no-border" >}} - -Microflow parameters are especially useful for handling events. For example, the community-supported [MQTT Client](https://marketplace.mendix.com/link/component/3066/Mendix/MQTT-Client) connector (via the [GitHub MQTTClient project](https://github.com/ako/MqttClient)) will execute a microflow when receiving an IoT sensor event so it can be handled using a user-specified microflow. - -## Using Import and Export Mappings - -Now we will discuss an example of how you can use mappings in your Java actions. In this example, you'll create an action to import a string using an import mapping. This is not particularly useful, seeing there is a default action in your toolbox already that provides this functionality called **Import with mapping**. However, as an example, it illustrates how to use mappings. - -This is an image of what we are building: an action to import JSON strings: - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/example_import_string_use.png" alt="Example import string use" class="no-border" >}} - -The action requires the user to provide a string with the JSON to import, select an import mapping, and define the entity of the result. Finally, a name needs to be provided for the result of the import mapping. - -The action is defined as follows: - -* **InputString** – a string parameter containing the JSON to be imported -* **ImportMapping** – the name of the mapping to be used for importing the JSON -* **ResultEntity** – the type of object that will be the result of the import -* **Return type** – an object of the type specified with `ResultEntity` - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/import_string_action_pars.png" alt="Import String with mapping Java action parameters" class="no-border" >}} - -Implement the action in Java as follows: - -1. Create an InputStream from the JSON input so it can be read by the import mapping. -2. Use `Core.integration().importStream()` to import the JSON with the specified mapping. -3. Return the first object imported. - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/import_string_java.png" alt="Import String Java action" class="no-border" >}} - -## Some Development Tips - -### Unit Testing - -When developing connector modules, you can use the unit test module to test the actions you are implementing. - -If you want to publish your module with custom microflow actions to the Mendix Marketplace for easy reuse, it's best to have a module containing only the reusable parts. Add another module to your project with all the test microflows and anything else you need -while developing your application. - -In the screenshot below, observe two important points. First, the **ConnectorKitDemo** module only contains the actions you want to publish to the Marketplace. To do this, right-click the module and select **Export module package...**. Second, the **ConnectorKitDemoTests** module contains all the functionality you need while developing the reusable module: a small domain model with some sample data and some test pages. It also contains the unit test microflow **Test_InitProduct**, which will be called by the unit test module. - -{{< figure src="/attachments/howto8/extensibility/howto-connector-kit/project_test.png" alt="Mendix Connector kit module project with tests" class="no-border" >}} - -### Managing Libraries - -When you export the module package for publishing in the Marketplace, you only want to include the relevant Java libraries. The easiest way to manage this is to use a build tool to specify and download the relevant dependencies. - -The [ConnectorKitDemo](https://github.com/ako/ConnectorKitDemo) project on GitHub contains two examples of how to do this, which are described below. - -The first example is [Apache Ivy](https://ant.apache.org/ivy/), which is a Java library specifically created for managing dependencies. Ivy is small enough that you can include it in your Mendix project. You can create two configurations in an *ivy.xml* configuration file: one -to specify all the jars needed to run the project and execute the tests, and one to specify the libraries that should be included when publishing the module for reuse in the Marketplace. The demo project contains two configurations called **default** and **export** in the [ivy.xml](https://github.com/ako/ConnectorKitDemo/blob/master/ivy.xml) configuration file. - -The second example is [Gradle](https://gradle.org/), which is a full-fledged build tool where you can define tasks to build your project. The example in the demo project uses Gradle only to manage the dependencies. Again, it defines [two build configurations](https://github.com/ako/ConnectorKitDemo/blob/master/build.gradle): one requiring all the dependencies, and one requiring the libraries needed for exporting the module (in this case, just a library to call Slack). - -Before developing custom Java actions, follow these steps: - -1. Run the build tool to download all the dependencies. -2. Run the build tool to delete all the libraries in your *userlibs* folder. -3. Download only the jars to be included in the published module. -4. Export the module and upload it to the Mendix Marketplace. diff --git a/content/en/docs/howto8/extensibility/howto-datastorage-api.md b/content/en/docs/howto8/extensibility/howto-datastorage-api.md deleted file mode 100644 index c1994a827fa..00000000000 --- a/content/en/docs/howto8/extensibility/howto-datastorage-api.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: "Use Mendix Data Storage APIs to Build Reusable Microflow Actions" -linktitle: "Data Storage APIs for Reusable Microflows" -url: /howto8/extensibility/howto-datastorage-api/ -weight: 90 -description: "Describes creating custom microflow actions using Data Storage APIs." ---- - -## Introduction - -Mendix Studio Pro supports two query languages to retrieve data: - -* XPath as an easy to use query language to retrieve objects -* OQL is a SQL based language, more focused on powerful reporting facilities - -You can use these query languages in Mendix Studio Pro, but both languages are also available through a Java API. You can use these APIs to implement powerful reusable microflow actions through the Connector Kit. In addition to XPath and OQL, the Mendix APIs also enable you to use standard SQL on your Mendix database. - -This how to describes how you can build the following microflow actions: - -* Retrieve advanced XPath - returns a list of entities as specified by an XPath expression -* Retrieve advanced OQL - returns a list of entities as specified by an OQL query -* Retrieve Dataset OQL - returns a list of entities as specified by a Dataset OQL query -* Retrieve advanced SQL - returns a list of entities as specified by a SQL query -* Create first Monday of month list - returns a list of dates of the first Monday of every month in a specified range -* Register global entity listeners - run custom Java code for every object change - - {{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image001.png" alt="Microflow actions toolbox" class="no-border" >}} - -For more information on Java programming for Mendix, see [Java Programming](/refguide8/java-programming/). - -For more information on calling Java actions from a microflow, see [Java Actions](/refguide8/java-actions/). - -## Retrieving Advanced XPath - -The goal is to create a microflow action where a user can specify an XPath expression and which result entities are expected. The action will execute the XPath statement and return the resulting list of objects. - -In practice, this is not a very useful microflow action as you can already do this with the standard retrieve action in Mendix Studio Pro. The goal, however, is to illustrate how you can use the XPath Java API. - -The Java action needs the following parameters: - -* A string where the user can specify the XPath expression to be executed -* A result entity where the user specifies which entity is to be returned -* A return type which specifies that the action returns a list of the entities specified in the previous parameter. - - {{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image003.png" class="no-border" >}} - -A type parameter is required to define what object types should be returned in the list. This is specified using the ResultEntity parameter: - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image005.png" class="no-border" >}} - -Finally, you should define how you want to display the microflow in the microflow toolbox. This consists of a caption, a category and an icon: - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image007.png" class="no-border" >}} - -The implementation of this Java action is pretty straightforward; you can use the [Core.retrieveXPathQuery](https://apidocs.rnd.mendix.com/8/runtime/com/mendix/core/Core.html#retrieveXPathQuery(com.mendix.systemwideinterfaces.core.IContext,java.lang.String,int,int,java.util.Map,int)) API to execute your XPath expression and return a list of Mendix objects. - -The implementation also validates that the list returned contains objects of the entity specified. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image009.png" class="no-border" >}} - -Now you have a new microflow action in the toolbox that you can use in your microflows. - -Here’s an example domain model with two entities: Department and Employee. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image011.png" class="no-border" >}} - -You can drag the Java action created above from the toolbox into a microflow. In this example, you want to retrieve all Employee objects and return a list of these objects. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image013.png" class="no-border" >}} - -## Retrieving Objects Using OQL - -The following example illustrates how you can use the OQL APIs for reporting purposes. OQL is the general-purpose Mendix query language, very much resembling SQL. The biggest differences between OQL and SQL are: - -* OQL is expressed in entity and attribute names instead of table names and column names. This makes it easier to use, as you do not have to know the technical data model as stored in the database -* OQL is database vendor independent, so you can run the same OQL statement on all databases supported by Mendix - -The following non-persistable entity shows what data you are interested in for your report: - -* For every department you want to know - * its name, - * the birthday of the oldest employee - * the birthday of the youngest employee - * the total salary bill - * the average salary of the employees - * the minimum salary paid to an employee - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image017.png" class="no-border" >}} - -Using OQL, you can query this data as follows: - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image018.png" class="no-border" >}} - -Note that here you use the alias (**as ...**) to map the results of the selection to the attributes in the entity. - -You can create a generic microflow action to execute OQL queries and return a list of objects. The Java action has the following parameters: - -* OqlQuery – a string containing the OQL query -* ResultEntity – which entity will hold the retrieved data -* A list of the ResultEntity specified as a return type. - -As in the XPath example above, a **Type parameter** is defined to specify that the return list uses the type specified in ResultEntity. - -Additionally, you need to expose the Java action as a microflow action, provide a caption and an icon. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image020.png" class="no-border" >}} - -The Java action illustrated below does the following: - -* Retrieves all data using the Mendix API Core.retrieveOQLDataTable() -* Loops through all the rows, creates a new object of the type specified by ResultEntity. - - {{% alert color="info" %}}Setting a Java action parameter of type **Entity of type parameter...** (*ResultEntity* in the example above) creates a Java string in the action which contains the name of the entity type. This string can be passed to Core.instantiate to create a new object.{{% /alert %}} - -* Loops through all columns of a record and copies the column value to an attribute with the same name. If an attribute with a column name does not exist, a message is printed, and the loop continues -* The Mendix object created is added to the list to be returned - -Note that in this case, as show in the domain model screenshot and the OQL screenshot above, the names of the attributes and columns match exactly. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image021.png" class="no-border" >}} - -The result is a generic OQL action that you can use in your microflows as follows: - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image023.png" class="no-border" >}} - -## Retrieving Objects Using OQL Specified in a Dataset - -Instead of coding the OQL statement in a string parameter, you can also use a Dataset. This has the benefit the that Mendix Studio Pro will validate your OQL query. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image040.png" class="no-border" >}} - -This time, you need to define a Java action that will take the name of the dataset. This action will get the OQL from the DataSet, execute it, and return a list of Mendix objects. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image041.png" class="no-border" >}} - -The microflow to execute the Java action is similar to the previous example, but instead of an OQL query, you specify the name of the Dataset. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image042.png" class="no-border" >}} - -Below is the Java code to get the Dataset OQL, execute the OQL, and retrieve the Objects. You use the [Core.createOQLTextGetRequestFromDataSet](https://apidocs.rnd.mendix.com/8/runtime/com/mendix/core/Core.html#createOQLTextGetRequestFromDataSet(java.lang.String)) method to get the OQL query of the Dataset specified. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image043.png" class="no-border" >}} - -## Retrieving Objects Using SQL - -An API is available to allow you to execute SQL queries on the application database (this feature is in beta). Using this API, you can create a microflow action to execute SQL: similar to the action for OQL in the previous sections. - -The definition of the Java action resembles the OQL action, but instead of an OQL parameter you have an SQL parameter. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image025.png" class="no-border" >}} - -The Java implementation below implements the following steps: - -* Use *Core.dataStorage().executeWithConnection()* to execute some Java statements that receive a JDBC connection from the internal connection pool. This API is constructed to enable the Mendix Platform to guarantee that connections are returned to the pool after usage. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image026.png" class="no-border" >}} - -* With the JDBC connection you can now implement your Java as you would with a regular JDBC connection. -* A prepared statement is created, executed and the resulting records are made available through a ResultSet. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image027.png" class="no-border" >}} - -* Next you loop through all the records in the ResultSet and create a Mendix object as specified by the user via ResultEntity. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image028.png" class="no-border" >}} - -You can find the complete Java source code on GitHub: [RetrieveAdvancedSQL](https://github.com/ako/QueryApiBlogPost/blob/master/javasource/hr/actions/RetrieveAdvancedSql.java). - -You now have a generic SQL action that can be used in microflows to retrieve data from your application database. The query in this example returns the same data as the OQL earlier, so you can reuse the non-persistable entity DepartmentSummary as defined previously. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image029.png" class="no-border" >}} - -{{% alert color="info" %}} -Note that in case of SQL statements you need to implement security constraints yourself. -{{% /alert %}} - -## PostgreSQL-specific SQL - -Using the JDBC connection you can benefit from vendor specific database extensions, like Oracle Pl/SQL or Postgres user-defined functions. - -{{% alert color="warning" %}} -If you use vendor specific database functionality you will not be able to deploy your application seamlessly on other platforms and databases. Therefore, we advise you to use SQL only if you have no alternative way of implementing your requirements. In most cases you should be able to use OQL to achieve the same result, whilst keeping your application database independent. -{{% /alert %}} - -The following example illustrates the use of PostgreSQL-specific functionality. It serves as an example of how you can do this, but in this specific case an alternative solution, either using microflows or Java actions, is better as it would keep your application database independent. - -The requirement for this example is to generate a list of dates for all first Mondays of the month between a range specified by the user. - -This example has a page where a user can enter a start and end date. The microflow triggered by the “Generate first Mondays of the month” button will print all the respective dates. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image031.png" class="no-border" >}} - -In Postgres you can query a list of the dates of all Mondays between these dates using the following Postgres specific query: - -* Using a common table expression (CTE), you create a set of all first dates of every month in the range -* Using another CTE you determine the dates of the Mondays for these months -* Finally, you select these dates if they still fall in range specified - -For example: - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image032.png" class="no-border" >}} - -### Creating the Java Action - -You create a Java action with parameters for the start date and the end date. You have a specific entity to return a list of the dates: Hr.FirstMondayDate. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image033.png" class="no-border" >}} - -### Creating the Java Code - -1. Specify the required SQL statement in the Java method. JDBC queries expect the parameters to be specified by question marks (?) in the SQL statement. - - {{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image034.png" class="no-border" >}} - -2. Next, use the Mendix API to execute some statements using the JDBC connection. Here you create a prepared statement, define the JDBC parameter values, and execute the SQL query. - - {{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image035.png" class="no-border" >}} - -3. Using the FirstMondayDate Java proxy, instantiate a new Mendix object and set the date attribute. -4. Finally, return the created list of dates. - - {{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image036.png" class="no-border" >}} - -When you use this in a microflow, you just need to specify the start and end dates, and the name of the resulting list. This example iterates through all the data objects in the list and prints the date of that object. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image037.png" class="no-border" >}} - -You will see the list of dates in the console. - -{{< figure src="/attachments/howto8/extensibility/howto-datastorage-api/image039.png" class="no-border" >}} - -## Global Custom Entity Event Listeners - -Global entity event listeners enable you to define generic event handlers on all entities. This enables you to build generic validations or create a real-time data export to a central datastore. You can use a Java action to register any desired event handler, most likely in the *After App Startup Microflow*. - -### Example code to Register the Event Listener. - -This code will log old and new attribute value for all changes to attributes before making changes in the database: - -```java -public java.lang.Boolean executeAction() throws Exception { - // BEGIN USER CODE - Core.getListenersRegistry().registerBeforeCommitListener(objects -> { - ILogNode logger = Core.getLogger("BeforeCommitListener"); - for (IMendixObject obj : objects) { - logger.info("ObjectType: " + obj.getType()); - - List> changedMembers = obj.getChangedMembers(getContext()); - - logger.info(String.format("Has changed members: %b? Number of changed members: %d", obj.isChanged(), changedMembers.size())); - for (IMendixObjectMember member : changedMembers) { - logger.info( - String.format("Changed member %s : %s -> %s", member.getName(), - member.getOriginalValue(getContext()) != null ? member.getOriginalValue(getContext()).toString() : "", - member.getValue(getContext()) != null ? member.getValue(getContext()).toString() : "" - ) - ); - } - } - }); - return true; - // END USER CODE -} -``` - -This example will trigger a listener for every object change before writing the changes to the database. To find out what attributes have been changed, you can use the **getChangedMembers** method, as illustrated above. diff --git a/content/en/docs/howto8/extensibility/pluggable-widgets/_index.md b/content/en/docs/howto8/extensibility/pluggable-widgets/_index.md deleted file mode 100644 index 5593cd47030..00000000000 --- a/content/en/docs/howto8/extensibility/pluggable-widgets/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Build Pluggable Web Widgets" -url: /howto8/extensibility/pluggable-widgets/ -weight: 20 ---- - -Pluggable web widgets are Mendix's custom-built widgets based on React. This language allows you to tailor-make widgets easily and with fewer errors. For more information on pluggable web widgets, see [Pluggable Widgets API](/apidocs-mxsdk/apidocs/pluggable-widgets/), [Client APIs Available to Pluggable Widgets](/apidocs-mxsdk/apidocs/client-apis-for-pluggable-widgets-8/), and [Pluggable Widget Property Types](/apidocs-mxsdk/apidocs/property-types-pluggable-widgets-8/).This how-to series teaches you how to harness the power of pluggable web widgets step by step: - -* [Build a Pluggable Web Widget: Part 1](/howto8/extensibility/create-a-pluggable-widget-one/) -* [Build a Pluggable Web Widget: Part 2 (Advanced)](/howto8/extensibility/create-a-pluggable-widget-two/) diff --git a/content/en/docs/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one.md b/content/en/docs/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one.md deleted file mode 100644 index d11d4be46e3..00000000000 --- a/content/en/docs/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one.md +++ /dev/null @@ -1,399 +0,0 @@ ---- -title: "Build a Pluggable Web Widget: Part 1" -linktitle: "1. Build Pluggable Web Widget" -url: /howto8/extensibility/create-a-pluggable-widget-one/ -weight: 10 -description: "This how-to teaches you how to create a pluggable web widget." ---- - -## Introduction - -Pluggable web widgets are the new generation of custom-built widgets. These widgets are based on React and use a different architecture than the older custom widgets based on Dojo. With pluggable web widgets, you can develop powerful tools in simple, precise ways. In the first part of this series, you will learn to create a text input widget. - -This how-to teaches you how to do the following: - -* Generate a widget structure -* Create a basic text input widget -* Add a label - -**Are you in a hurry?** - -Clone this [code sample](https://github.com/mendix/text-box-sample) from GitHub with the basic and advanced features already implemented. - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install [Node.js](https://nodejs.org) v12.0.0 or any higher version. - * For Windows, install using this [official installer](https://nodejs.org/en/download/package-manager/#windows) - * For Mac, install using [Homebrew](https://docs.brew.sh/Installation) and these [official tools](https://nodejs.org/en/download/package-manager/#macos) -* Install [Yeoman](https://yeoman.io/) with the following command: - - ```shell - npm install -g yo - ``` - -* Install the latest Mendix Pluggable Widget Generator for Yeoman for Mendix 8 with the following command: - - ```shell - npm install -g @mendix/generator-widget@"<9" - ``` - -* Install an integrated development environment (IDE) of your choice (Mendix recommends [Microsoft Visual Studio Code](https://code.visualstudio.com/)) -* Have a basic understanding of [TypeScript](https://www.typescriptlang.org/) - -## Creating a TextBox Input Widget - -The following steps teach you how to build a pluggable input widget, and show you how to use the new pluggable widget API. - -### Creating a Test Project{#creating-a-test-project} - -1. Open Mendix Studio Pro and create a new test project by selecting **File > New Project** from the top menu bar and then **Blank App**. -2. Create a test case for the new widget:
- 1. In the domain model of **MyFirstModule**, add a new entity.
- 2. Add a new attribute of type **String**.
- 3. Open **MyFirstModule’s** **Home** page.
- 4. There, add a **Data view** widget, double-click the widget, and give it a data source microflow by selecting **Data source** > **Type** > **Microflow**.
- 5. Next to the microflow field click the **Select** button, and click **New**.
- 6. Provide the name *DSS_CreateTestObject* to this new microflow.
- 7. Click the **Show** button. This will open the microflow editor. Then click the **OK** button to close the dialog box.
- 8. Add a new **Create object** action on your microflow. - -3. Open the new **Create object** action's properties by double-clicking it. For its **Entity**, click the **Select** button and choose the entity you created above. Then click **OK** to close the dialog box. -4. Right-click the **Create Entity** activity, then click **Set $NewEntity as Return Value**. -5. Go back to the home page, open the **Add Widget** menu, and then add a **TextBox** widget inside the data view. -6. Open the Textbox's properties and select the **Datasource Attribute (path)** string attribute you created above. Then click the **OK** button to close the dialog box. The end result should look like this: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one/createtestobject.png" class="no-border" >}} - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one/microflowcreateentity.png" class="no-border" >}} - -### Widget Scaffolding - -The Pluggable Widget Generator is the quickest way to start developing a widget. It creates a widget’s recommended folder structure and files. - -Using a terminal or command line, navigate to your new Mendix app's folder, create a new folder named *CustomWidgets*, and start the generator using: - -```powershell -mkdir CustomWidgets -cd CustomWidgets -yo @mendix/widget TextBox -``` - -The generator will ask you a few questions during setup. Answer the questions by specifying the following information: - -* Widget name: *{Your widget name}* -* Widget Description: *{Your widget description}* -* Organization Name: *{Your organization name}* -* Copyright: *{Your copyright date}* -* License: *{Your license}* -* Initial Version:*{Your initial version number}* -* Author: *{Your author name}* -* Mendix App path: *../../* -* Programming language: **TypeScript** -* Which type of components do you want to use? **Class Components** -* Widget type: **For web and hybrid mobile apps** -* Widget template: **Empty widget (recommended for more experienced developers)** -* Unit tests: **No** -* End-to-end tests: **No** - -{{% alert color="warning" %}} -Currently, **Organization Name** cannot include a dash "-" character. Dashes in the organization name will result in an error when running your app, asking to check if the widgets "were generated with the latest version of the pluggable-widgets-tools and are ES6 modules." - -To fix this in an existing widget, modify the `packagePath` property of its **package.json** file and rebuild the widget. -{{% /alert %}} - -{{< figure src="/attachments/howto/extensibility/pluggable-widgets/create-a-pluggable-widget-one/generatorblack-new.png" alt="mx generator" class="no-border" >}} - -Note that whenever it is required to reinstall NPM package dependencies inside the scaffolded widget development project with an NPM version of 7 or higher, make sure to run the installation script with an extra flag: `npm install --legacy-peer-deps`. - -### Adding the Attribute - -Open the **(YourMendixProject)/CustomWidgets/TextBox** folder in your IDE of choice (any IDE is fine if it can execute commands). From now on, all file references will be relative to this path. To set up your new widget, first you must use an attribute of the context object and display that attribute in an input field: - -1. To prevent future errors, remove the file *src/components/HelloWorldSample.tsx*. Errors in *TextBox.editorPreview.tsx* will be dealt with in step 6 below. -2. In *src/TextBox.xml*, the generator creates a sample property `sampleText`. Remove this property and add the new property `Text attribute`: - - ```xml - - - Text Box - Edit text input - - - - - Attribute (path) - - - - - - - - - ``` - - Explaining the code: - - * *TextBox.xml* is the [widget definition file](/apidocs-mxsdk/apidocs/pluggable-widgets/#widget-definition) used in Studio Pro which reads the widget's capabilities - * The property `pluginWidget=true` will make the widget work with the new widget API - * The property `needsEntityContext=true` is set up to allow the attribute to be taken from context - * The property of the [type attribute](/apidocs-mxsdk/apidocs/property-types-pluggable-widgets-8/#attribute) only allows the selection of string attributes from the domain model - -3. The typescript typing based on the XML will be generated automatically. Start the development process with the following command: `$ npm run dev`. - - This process will bundle the widget and generate the properties into *typings/TextBoxProperties.d.ts*. - - {{% alert color="info" %}}The console will show the error below, as we did not implement our `TextInput` component. We will solve the error in the [Labeling the Input](#label-input) of this how-to.{{% /alert %}} - - ```text - ERROR in ./src/TextBox.tsx - Module not found: Error: Can't resolve './components/HelloWorldSample' in 'C:\Users\john.doe\textboxtest-main\CustomWidgets\TextBox\src' - @ ./src/TextBox.tsx 14:0-28:2 - ``` - -4. Create a new file, *components/TextInput.tsx*. This will be the display component. A display component does not interact with APIs and can be re-used in any React application. Paste the following code into *TextInput.tsx*: - - ```tsx - import { Component, ReactNode, createElement } from "react"; - - export interface InputProps { - value: string; - } - - export class TextInput extends Component { - render(): ReactNode { - return ; - } - } - ``` - - Explaining the code: - - * The interface defines the properties of the React components — the value is passed to the component and it will render an HTML input element with the given value - * The component is a class extending `Component` and should be exported to be used in other components - * The render method is the only required function in a component, and it will return the expected DOM for the browser (for more information, see React’s [component documentation](https://reactjs.org/docs/react-component.html)) -5. The container component *TextBox.tsx* receives the properties in the runtime, and forwards the data to the display component. The container works like glue between the Mendix application and the display component. In the *TextBox.tsx* overwrite the render function until they look like this: - - ```tsx - import { Component, ReactNode, createElement } from "react"; - import { hot } from "react-hot-loader/root"; - - import { TextBoxContainerProps } from "../typings/TextBoxProps"; - import { TextInput } from "./components/TextInput"; - - import "./ui/TextBox.css"; - - class TextBox extends Component { - render(): ReactNode { - const value = this.props.textAttribute.value || ""; - return ; - } - } - - export default hot(TextBox); - ``` - - Be sure all the imports are included before moving on from this step. - - Explaining the code: - - * The `textAttribute` is an object that will automatically have the actual data stored in the attribute — when the data is changed, it will cause an update of the component, and the new data will be displayed in the input - -6. Alter *Textbox.editorPreview.tsx* by adding the `TextInput` import to *Textbox.editorPreview.tsx*: - - ```tsx - import { TextInput } from "./components/TextInput"; - ``` - - Then, override the class lines in *Textbox.editorPreview.tsx* until they look like this: - - ```tsx - export class preview extends Component { - render(): ReactNode { - return ; - } - } - ``` - - Before moving on from this step, you should remove the import lines concerning the **Hello World** sample text from *TextBox.editorPreview.tsx* and *TextBox.tsx*, as these lines are no longer in use. - -7. Add a test widget to the project home page:
- 1. To find your widget for the first time you need to refresh from the files system. Use F4 or select **Project > Synchronize Project Directory** from the Mendix Studio Pro menu.
- 2. Navigate to **Home > Add widget** in the editor menu.
- 3. Select the newly-created **TextBox** widget at the bottom of the list.
- 4. Place the widget below the standard text widget.
- 5. Open the widget properties. In the **Data source** tab **select** the **Text attribute** from the attribute created in [Creating a Test Project](#creating-a-test-project) above. - - The end result will be similar to the screenshot below: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one/updateallwidgets.png" class="no-border" >}} - - {{% alert color="info" %}}The widgets in Studio Pro are not automatically updated. First, run the `npm run dev` command again. To refresh your widgets, press F4 or select **Project > Synchronize Project Directory** from the Mendix Studio Pro menu to reload the widgets from the file system. Finally, right-click the widget and select Update all widgets to update the newly-changed properties in the widget.{{% /alert %}} - -8. When running the project, the new widget is already functional. The first text box is a standard Text box widget and the second is your pluggable web widget. When data is changed in the first input and the cursor is moved to the next widget, the data of your widget is also updated: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one/twotextwidgets.png" alt="two text widgets" class="no-border" >}} - -### Adding Style - -The input works, but the styling could be improved. In the next code snippets, you will add the default styling to make your TextBox widget look like a Mendix widget. Also, you need to pass the `Class`, `Style` and `Tab index` [standard properties](/apidocs-mxsdk/apidocs/client-apis-for-pluggable-widgets-8/#standard-properties) from the `Common` tab which originate from the **Edit Custom Widget** dialog box: - -{{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one/customwidgetedit.png" alt="custom widget" class="no-border" >}} - -1. In *TextBox.tsx*, pass the properties from the runtime to the `TextInput` component: - - ```tsx - class TextBox extends Component { - render(): ReactNode { - const value = this.props.textAttribute.value || ""; - return ; - } - } - ``` - -2. In *components/TextInput.tsx*, add the attributes to the interface and render them in the input: - - ```tsx - import { CSSProperties, Component, ReactNode, createElement } from "react"; - import classNames from "classnames"; - export interface InputProps { - value: string; - className?: string; - index?: number; - style?: CSSProperties; - tabIndex?: number; - } - export class TextInput extends Component { - render(): ReactNode { - const className = classNames("form-control", this.props.className); - return ; - } - } - ``` - - Explaining the code: - * The style property is a React style object which can be passed to an HTML element directly - * `classNames` is an external utility function which dynamically creates and combines class names; it must be imported before it can be used (for the full API, see the property’s [documentation](https://github.com/JedWatson/classnames)) - * Each property with a question mark is optional -3. Your efforts will result in a well-styled input widget: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one/styledinputwidgets.png" alt="styled widgets" class="no-border" >}} - -### Labeling the Input{#label-input} - -While the Mendix input widgets come with labels, you will need to add one to TextBox manually. With the new API it is easy to [add a label](/apidocs-mxsdk/apidocs/property-types-pluggable-widgets-8/#label) to any widget. - -1. In the *TextBox.xml* file, add an element `` with a child element `` above the existing `` element: - - ```xml - - - - ``` - - This will add the **Show label** radio buttons in the widget properties tab **Label** (after synchronizing the Project Directory and updating the widget). When **Show label** is set to true, it will automatically render the label for you in the page editor and the browser: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one/edittextboxtwo.png" alt="edit text box two" class="no-border" >}} - -2. Preview the label in the page editor: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one/editdataviewone.png" alt="edit data view one" class="no-border" >}} - -3. This will result in a label above or next to the input depending on the available space, data view `Form orientation`, and the `Label width (weight)`: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-one/inputwidgetswithlabel.png" alt="input widgets with label" class="no-border" >}} - -### Handling Updates - -The value from the attribute can be displayed and updated using the other input, however you cannot change the value directly from within your widget. You can close the loop by following these steps. - -1. In *TextBox.tsx*, create a function that will update the attribute and pass it to the `TextInput` component: - - ```tsx - class TextBox extends Component { - private readonly onUpdateHandle = this.onUpdate.bind(this); - render(): ReactNode { - const value = this.props.textAttribute.value || ""; - return ; - } - private onUpdate(value: string): void { - this.props.textAttribute.setValue(value); - } - } - ``` - - Explaining the code: - - * JavaScript can pass functions from one object to another — this way, the Mendix API stays in the container `TextBox component` and provides a function to the display component to pass updates back to the attribute - * When a function is passed to another component, the function might have a scoping issue — this can be solved by binding the context `this` to the function before passing it to the display component (for more information, see this [freeCodeCamp blog post](https://medium.freecodecamp.org/this-is-why-we-need-to-bind-event-handlers-in-class-components-in-react-f7ea1a6f93eb)) - -2. In *components/TextInput.tsx*, handle the change events of the input and pass the new value to the `onUpdate` function of the container component: - - ```tsx - import { CSSProperties, ChangeEvent, Component, ReactNode, createElement } from "react"; - import classNames from "classnames"; - export interface InputProps { - value: string; - className?: string; - index?: number; - style?: CSSProperties; - tabIndex?: number; - onUpdate?: (value: string) => void; - } - export class TextInput extends Component { - private readonly handleChange = this.onChange.bind(this); - render(): ReactNode { - const className = classNames("form-control", this.props.className); - return ; - } - private onChange(event: ChangeEvent): void { - if (this.props.onUpdate) { - this.props.onUpdate(event.target.value); - } - } - } - ``` - - Explaining the code: - - * The input's `value` is set by the `this.props.value`, and this property is not changed directly; the update function will use the `setValue` to trigger a re-render with the updated property - * There are two ways of handling input changes in React: [controlled components](https://reactjs.org/docs/forms.html#controlled-components) or [uncontrolled components](https://reactjs.org/docs/uncontrolled-components.html) - * The `onUpdate` function is optional and it should be checked for availability before executing it - * The custom widget TextBox will still not pass text to the Text box widget after this step — it will gain this functionality in [Build a Text Box Pluggable Widget: Part 2 (Advanced)](/howto8/extensibility/create-a-pluggable-widget-two/). - -Congratulations, you have now made a fully functional input widget! - -Continue with the next tutorial to learn how to add validation feedback, custom validations, and an on-change event activity. You will also learn how to handle a read-only state, improve web accessibility, and make a Mendix Studio Pro preview. - -## Read More - -* [Build a Pluggable Web Widget: Part 2 (Advanced)](/howto8/extensibility/create-a-pluggable-widget-two/) -* [Pluggable Widgets API](/apidocs-mxsdk/apidocs/pluggable-widgets/) -* [Client APIs Available to Pluggable Widgets](/apidocs-mxsdk/apidocs/client-apis-for-pluggable-widgets-8/) -* [Pluggable Widget Property Types](/apidocs-mxsdk/apidocs/property-types-pluggable-widgets-8/) diff --git a/content/en/docs/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two.md b/content/en/docs/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two.md deleted file mode 100644 index de5865a61ad..00000000000 --- a/content/en/docs/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two.md +++ /dev/null @@ -1,611 +0,0 @@ ---- -title: "Build a Pluggable Web Widget: Part 2 (Advanced)" -linktitle: "2. Build Pluggable Web Widget" -url: /howto8/extensibility/create-a-pluggable-widget-two/ -weight: 20 -description: "This how-to teaches you how to add advanced features to your TextBox input widget." ---- - -## Introduction - -The new pluggable widget API makes building feature-complete widgets much easier. This how-to will go beyond [How to Build a Pluggable Web Widget: Part 1](/howto8/extensibility/create-a-pluggable-widget-one/) and teach you how to add advanced features to your TextBox input widget. - -This how-to teaches you how to do the following: - -* Configure widget edit permissions -* Add validation feedback -* Add custom validations -* Create an onChange action -* Improve accessibility for screen readers -* Enable Mendix Studio Pro preview - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Complete [Build a Pluggable Web Widget: Part 1](/howto8/extensibility/create-a-pluggable-widget-one/) - -## Adding Advanced Features to Your TextBox Input Widget - -To add advanced features to your TextBox input widget, consult the sections below. - -### Configuring Edit Permissions - -Right now the input is editable for any user at all times. However, the input should be disabled in cases when: - -* A user does not have the security rights to edit -* A user is given read-only permission -* The context data view is not editable -* Mendix developers specify so in the widget's configuration - -To add these restrictions, follow the instructions below: - -1. In *TextBox.xml* add the [system property](/apidocs-mxsdk/apidocs/property-types-pluggable-widgets-8/#editability) for `Editability` inside the `propertyGroup` of `Data source` (where you put the attribute inside `propertyGroup` will affect how the attribute renders in the Mendix Studio Pro): - - ```xml - - - - ``` - -2. Run `npm run build` to update the widget. When viewing in Studio Pro, the `Editability` property can been seen here: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two/editability-property-studio-pro.png" alt="Editability studio pro" width="500" class="no-border" >}} - -3. Now add read-only functionality to your widget. In *TextBox.tsx*, replace the `render` function with the code below to check if the input should be disabled and pass it to in the `TextInput` component: - - ```tsx - render(): ReactNode { - const value = this.props.textAttribute.value || ""; - return ; - } - ``` - - Explaining the code: - - * The `textAttribute` has a property `readOnly`, which will be set to `true` based on: - * If entity access is read only; based on the security model - * If the containing data view is set to `Editable: No` - * If the system property `Editability` is set with a true condition - -4. In *components/TextInput.tsx*, add the `disabled` property to the `InputProps` interface and set the HTML input attribute to `disabled`: - - ```tsx - import { CSSProperties, ChangeEvent, Component, ReactNode, createElement } from "react"; - import classNames from "classnames"; - export interface InputProps { - value: string; - className?: string; - index?: number; - style?: CSSProperties; - tabIndex?: number; - onUpdate?: (value: string) => void; - disabled?: boolean; - } - export class TextInput extends Component { - private readonly handleChange = this.onChange.bind(this); - render(): ReactNode { - const className = classNames("form-control", this.props.className); - return ; - } - private onChange(event: ChangeEvent) { - if (this.props.onUpdate) { - this.props.onUpdate(event.target.value); - } - } - } - ``` - - After altering this code, do the following to see your changes:
- 1. Run `npm run build` to update the widget.
- 2. In Mendix Studio Pro, press F4 to synchronize your project directory.
- 3. Right-click your TextBox widget and select **Update widget**. Then click **Run Locally**.
- 4. Click **View** to see your changes. - - Explaining the code: - - * The property `disabled` in an input element will behave according to the HTML's specifications — it will not respond to user actions, cannot be focused, is removed from the tab order, and will not fire any events - -5. When you select **Never** for your TextBox widget's `Editable` property in Mendix Studio Pro, the widget will function like this: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two/settonever.png" alt="editable never result" width="500" class="no-border" >}} - - Explaining the code: - - * The theme styling will apply the disabled style to the input in the same way as the standard input widget in the disabled state - -### Adding Validation Feedback - -This section teaches you how to add validation to your TextBox widget. Using microflows and nanoflows, validation feedback can easily be provided. - -1. Drag a **call microflow button** widget below your TextBox widget and drop it there. On the subsequent dialog box, click **New** to assign a new microflow to your button, name it *Validation_Microflow*, and click **OK**: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two/validation-microflow-dialog.png" alt="validation microflow dialog box" width="500" class="no-border" >}} - - Before moving forward, go back to your app's **Home** page, double-click your validation button, and name it *Show validation feedback*. - -2. Open your *Validation_Microflow* and drop a **Validation feedback** activity into your microflow: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two/addingvalidation.png" alt="validation feedback client activity" width="500" class="no-border" >}} - - To define your validation feedback activity:
- 1. Double-click the **Validation feedback** activity.
- 2. Set **Variable** to **Entity (MyFirstModule Entity)**.
- 3. Set **Member** to **Attribute**, and type *Validation feedback from a microflow* into **Template**.
- 4. Click **OK**.
- 5. Click **File** > **Save All** from the Mendix Studio Pro drop-down menu. - -3. To render the message, create a new component *components/Alert.tsx*: - - ```tsx - import { FunctionComponent, createElement } from "react"; - import classNames from "classnames"; - export interface AlertProps { - alertStyle?: "default" | "primary" | "success" | "info" | "warning" | "danger"; - className?: string; - } - export const Alert: FunctionComponent = ({ alertStyle, className, children }) => - children ? ( -
- {children} -
- ) : null; - Alert.displayName = "Alert"; - Alert.defaultProps = { alertStyle: "danger" }; - ``` - - Explaining the code: - - * The `Alert` component does not have a state and can be written as a stateless function component - * The component has a `displayName` for debugging and error messages - * A `function` component can also have default properties which are set directly on the prototype - -4. In *TextBox.tsx*, the validation feedback can be accessed though the attribute `validation` property and shown in the `Alert` component. Replace the `render` function with the following code: - - ```tsx - render(): ReactNode { - const value = this.props.textAttribute.value || ""; - const validationFeedback = this.props.textAttribute.validation; - return - - {validationFeedback} - ; - } - ``` - -5. Add `Fragment` to the current React import (shown below), and add a new `Alert` import underneath the existing imports in *TextBox.tsx*: - - ```tsx - import { Component, ReactNode, Fragment, createElement } from "react"; - import { Alert } from "./components/Alert"; - ``` - - After altering this code, do the following to see your changes:
- 1. Run `npm run build` to update the widget.
- 2. In Mendix Studio Pro, press F4 to synchronize your project directory.
- 3. Right-click your TextBox widget and select **Update widget**. Then click **Run Locally**.
- 4. Click **View** to see your changes. - - Explaining the code: - - * React nodes each require a root element — to create a non-rendering element and group the container elements, a `Fragment` can be used - * When there is no error the validation will be empty, the `Alert` will not show, and the component will return `null` - - Now, your widget will show validation feedback from its microflow: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two/microflowwithvalidationfeedback.png" alt="validation feedback demo" width="350" class="no-border" >}} - -### Customizing Validation - -Validation can come from a modeled microflow or nanoflow, but can also be widget specific. For this sample you will learn to implement a custom, required [text template](/apidocs-mxsdk/apidocs/property-types-pluggable-widgets-8/#texttemplate) message which will show when the input is empty. - -1. In *TextBox.xml*, add the `requiredMessage` property inside the `propertyGroup` of `Data source`: - - ```xml - - Required message - - - An input text is required - - - ``` - - Explaining the code: - - * `textTemplate` strings are translatable strings which can also have attributes and data values - * Default values can be added to the XML and are language specific - -2. In *TextBox.tsx*, add a validation handler to the attribute after the `onUpdate` function: - - ```ts - componentDidMount(): void { - this.props.textAttribute.setValidator(this.validator.bind(this)); - } - - private validator(value: string | undefined): string | undefined { - const { requiredMessage } = this.props; - if (requiredMessage && requiredMessage.value && !value) { - return requiredMessage.value; - } - return; - } - ``` - - After altering this code, do the following to see your changes:
- 1. Run `npm run build` to update the widget.
- 2. In Mendix Studio Pro, press F4 to synchronize your project directory.
- 3. Right-click your TextBox widget and select **Update widget**. Then click **Run Locally**.
- 4. Click **View** to see your changes. - - Explaining the code: - - * The `componentDidMount` is a lifecycle method of the React component, and is only called once - * The custom validator is registered to the attribute, and is called after each `setValue` call — the new value is only accepted when the validator returns no string - * When the validator returns an error message, it will passed to the attribute, and a re-render is triggered — the standard `this.props.textAttribute.validation` will get the message and display it in the same way as the validation feedback - -3. When entering text and removing all characters, the following error is shown: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two/nocharerror.png" alt="no character error" width="500" class="no-border" >}} - -### Adding an OnChange Action - -Until now the components did not keep any state. Each keystroke passed through the `onUpdate` function, which set the new value. The newly-set value was received through the React lifecycle, which updated the property and called the `render` function. This method can cause many rendering actions to be triggered by all widgets that are using that same attribute, such as a re-render for each keystroke. This pattern also makes it also difficult to trigger an onChange action. The onChange action should only trigger on leaving the input combined with a changed value. - -1. In *TextBox.xml*, add the `onChangeAction` inside `properties` and edit the `textAttribute` property by adding a reference in the `onChange` attribute to the key of the action : - - ```xml - - - Attribute (path) - - - - - - - - - - On change - - - - ``` - - After altering this code, do the following to see your changes:
- 1. Run `npm run build` to update the widget.
- 2. In Mendix Studio Pro, press F4 to synchronize your project directory.
- 3. Right-click your TextBox widget and select **Update widget**. Then click **Run Locally**.
- 4. Click **View** to see your changes. - - Adding this code will allow you to select various actions: - - {{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two/variousactions.png" alt="various actions" class="no-border" >}} - -2. In *TextBox.tsx*, check if `onChangeAction` is available and call the execute function `onLeave` when the value is changed. When doing this, replace the `onUpdate` function with your new `onLeave` function: - - ```tsx - class TextBox extends Component { - private readonly onLeaveHandle = this.onLeave.bind(this); - componentDidMount(): void { - this.props.textAttribute.setValidator(this.validator.bind(this)); - } - render(): ReactNode { - const value = this.props.textAttribute.value || ""; - const validationFeedback = this.props.textAttribute.validation; - return - - {validationFeedback} - ; - } - private isReadOnly(): boolean { - this.props.textAttribute.readOnly; - } - private onLeave(value: string, isChanged: boolean): void { - if (!isChanged) { - return; - } - this.props.textAttribute.setValue(value); - } - private validator(value: string | undefined): string | undefined { - const { requiredMessage } = this.props; - if (requiredMessage && requiredMessage.value && !value) { - return requiredMessage.value; - } - return; - } - } - ``` - -3. In *components/TextInput.tsx*, introduce a state for input changes and use the `onBlur` function to call the `onLeave` function by replacing the `onUpdate` function: - - ```tsx - import { CSSProperties, Component, ReactNode, createElement, ChangeEvent } from "react"; - import classNames from "classnames"; - - export interface InputProps { - value: string; - className?: string; - index?: number; - style?: CSSProperties; - tabIndex?: number; - id?: string; - disabled?: boolean; - onLeave?: (value: string, changed: boolean) => void; - } - interface InputState { - editedValue?: string; - } - export class TextInput extends Component { - private readonly onChangeHandle = this.onChange.bind(this); - private readonly onBlurHandle = this.onBlur.bind(this); - readonly state: InputState = { editedValue: undefined }; - componentDidUpdate(prevProps: InputProps): void { - if (this.props.value !== prevProps.value) { - this.setState({ editedValue: undefined }); - } - } - render(): ReactNode { - const className = classNames("form-control", this.props.className); - return ; - } - private getCurrentValue(): string { - return this.state.editedValue !== undefined - ? this.state.editedValue - : this.props.value; - } - private onChange(event: ChangeEvent): void { - this.setState({ editedValue: event.target.value }); - } - private onBlur(): void { - const inputValue = this.props.value; - const currentValue = this.getCurrentValue(); - if (this.props.onLeave) { - this.props.onLeave(currentValue, currentValue !== inputValue); - } - this.setState({ editedValue: undefined }); - } - } - ``` - - Explaining the code: - - * The `componentDidUpdate` function is a React lifecycle function that is called before rendering, directly after an update of the properties - * The state `editedValue` will be empty until the input value is changed by the user - * The `setState` function will update the state and will re-render the component (in the rendering, the new value is taken from `editedValue`) - * The `onBlur` function will set the new value in the attribute through the container component — the state is reset, and the new value is received by an update of the attribute (which will propagate as a new property value) - * The `onLeave` function will set the value. The `setValue` function will automatically call the onChange action, as this is connected with the XML configuration - -### Adding Accessibility - -To make the input widget more accessible for people using screen readers, you will need to provide hints about the input. - -1. In *TextBox.tsx*, replace the `render` function with `id`, `required`, and `hasError` properties: - - ```tsx - render(): ReactNode { - const value = this.props.textAttribute.value || ""; - const validationFeedback = this.props.textAttribute.validation; - const required = !!(this.props.requiredMessage && this.props.requiredMessage.value); - return - - {validationFeedback} - ; - } - ``` - -2. In *components/Alert.tsx*, add the `id` and `alert` properties: - - ```tsx - import { FunctionComponent, createElement } from "react"; - import classNames from "classnames"; - export interface AlertProps { - id?: string; - alertStyle?: "default" | "primary" | "success" | "info" | "warning" | "danger"; - className?: string; - } - export const Alert: FunctionComponent = ({ alertStyle, className, children, id }) => - children ? ( -
- {children} -
- ) : null; - Alert.displayName = "Alert"; - Alert.defaultProps = { alertStyle: "danger" }; - ``` - -3. In *components/TextInput.tsx*, add the `id` property to the `InputProps` and pass it from the `TextBox` component to the `TextInput` component: - - ```tsx - export interface InputProps { - id?: string; - value: string; - className?: string; - index?: number; - style?: CSSProperties; - tabIndex?: number; - hasError?: boolean; - required?: boolean; - disabled?: boolean; - onLeave?: (value: string, changed: boolean) => void; - } - ``` - - Then add the `id` and `aria` attributes to be rendered: - - ```tsx - render(): ReactNode { - const className = classNames("form-control", this.props.className); - const labelledby = `${this.props.id}-label` - + (this.props.hasError ? ` ${this.props.id}-error` : ""); - return ; - } - ``` - - After altering this code, do the following to see your changes:
- 1. Run `npm run build` to update the widget.
- 2. In Mendix Studio Pro, press F4 to synchronize your project directory.
- 3. Right-click your TextBox widget and select **Update widget**. Then click **Run Locally**.
- 4. Click **View** to see your changes. - - Explaining the code: - - * The `Label` component provided by the platform has a `for` attribute which will have a reference to the widget's ID — you must set the ID for the screen reader, so that it can link the label to the `this` input - * The `Label` component will have an ID `-label` — you must link the input's `aria-labelledby` to the ID of the label - -You have now made your widget compatible with screen readers. If a screen reader is describing your app aloud, it will list the widget elements to the user. - -### Enabling Preview Mode - -To easily view changes to your widget while in Mendix Studio Pro's **Design mode**, you can add preview functionality to your TextBox widget. Note that the properties received in preview mode will be slightly different than at the runtime level. - -To add preview mode functionality, create a new file *src/TextBox.editorPreview.tsx* and add this code to it: - -```tsx -import { Component, createElement, ReactNode } from "react"; -import { TextBoxPreviewProps } from "../typings/TextBoxProps"; -import { TextInput } from "./components/TextInput"; - -declare function require(name: string): string; - -export class preview extends Component { - render(): ReactNode { - const value = `[${this.props.textAttribute}]`; - return ; - } -} - -export function getPreviewCss(): string { - return require("./ui/TextBox.css"); -} -``` - -Explaining the code: - -* The display component `TextInput` can be fully re-used to display the preview -* There is no need to attach any event handlers for updates - -### Grouping and System Properties - -All pluggable widgets will automatically benefit from the `Visibility` property, which can be used to set the [conditional visibility](/apidocs-mxsdk/apidocs/property-types-pluggable-widgets-8/#visibility) of a widget. Within *widget.xml*, property groups can be used to move a property to a specific tab or place properties in a group. For more detailed information on property groups, see the [Property Groups](/apidocs-mxsdk/apidocs/pluggable-widgets/#property-groups) section of the *Pluggable Widgets API Documentation*. - -To apply this knowledge, reorganize the `properties` section in *TextBox.xml* to make the properties look like the core text box properties (which you can see after double-clicking the widget): - -```xml - - - - - Attribute (path) - - - - - - - - - - - - - - - - - - Required message - - - A input text is required - - - - - - - - - - - - On change - - - - - -``` - -Your code alterations will produce the following result: - -{{< figure src="/attachments/howto8/extensibility/pluggable-widgets/create-a-pluggable-widget-two/property-grouping-studio-pro.png" alt="property dialog Studio Pro" width="500" class="no-border" >}} - -## Read More - -* [Build a Pluggable Web Widget: Part 1](/howto8/extensibility/create-a-pluggable-widget-one/) -* [Pluggable Widgets API](/apidocs-mxsdk/apidocs/pluggable-widgets/) -* [Client APIs Available to Pluggable Widgets](/apidocs-mxsdk/apidocs/client-apis-for-pluggable-widgets-8/) -* [Pluggable Widget Property Types](/apidocs-mxsdk/apidocs/property-types-pluggable-widgets-8/) diff --git a/content/en/docs/howto8/extensibility/widget-development/_index.md b/content/en/docs/howto8/extensibility/widget-development/_index.md deleted file mode 100644 index 6167c9be156..00000000000 --- a/content/en/docs/howto8/extensibility/widget-development/_index.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Build Custom Widgets" -url: /howto8/extensibility/widget-development/ -weight: 30 -no_list: false -description_list: true ---- - -## Introduction - -A Mendix custom widget is a part of the user interface in your Mendix app that enables functionality and interaction with the users of the app. A custom widget can alter the interface, data, and images of the app as well as the way the app works. These custom widgets bridge the gap between using standard Mendix components (for example, buttons and list views) and creating very specific components yourself. - -Custom widget development can be difficult at the beginning. The resources below will help you start your widget development. - -## Prerequisites - -In order to create widgets, you need a good understanding of how JavaScript works. These texts can help you get started: - -* [JavaScript: The Good Parts](https://www.oreilly.com/library/view/javascript-the-good/9780596517748/) -* [You Don't Know JS](https://github.com/getify/You-Dont-Know-JS) -* [Learning JavaScript Design Patterns](https://addyosmani.com/resources/essentialjsdesignpatterns/book/) - -## Specific Widget Topics - -The sections below describe the Mendix resources that can help you understand how widgets are built. - -### Introduction Videos - -* [Expert Series: Kickstart Your Widget Development](https://www.youtube.com/watch?v=MZ0Ihu2QGYY) - -### Dojo {#dojo} - -Custom widgets are Dojo widgets. In order to understand how widgets are structured and what their lifecycle is, you need to know how Dojo widgets are built. You can consult this quick introduction: - -* [Dojo Documentation Tutorials](https://dojotoolkit.org/documentation/#tutorials) - -For details on the widget lifecycle, reference this documentation: - -* [Writing Your Own Widget](https://dojotoolkit.org/reference-guide/1.10/quickstart/writingWidgets.html) -* [dijit.\_WidgetBase](https://dojotoolkit.org/reference-guide/1.10/dijit/_WidgetBase.html) -* [Tutorial: Widget Lifecycle](https://apidocs.rnd.mendix.com/6/client/tutorial-widget-lifecycle.html) - -### Widget Scaffolding - -In the past we created widgets using Brackets and a plugin. With the new JavaScript/Node.js tools that have recently come out, we deprecated this way of creating widgets. The new way of creating widgets is done using Yeoman and a generator. - -This information is covered in [Expert Series: Kickstart Your Widget Development](https://www.youtube.com/watch?v=MZ0Ihu2QGYY). - -### Interacting with Mendix Runtime - -Widgets have the ability to get data from the Runtime, manipulate objects, show validations, and set references. This is done through the Client API. For the latest version of the this API, see [Client API](/apidocs-mxsdk/apidocs/client-api/). - -### Configuring the Widget in Mendix - -Mendix has a specific way of configuring your widget through the use of an XML file. For more information and an example, see [WidgetName](https://github.com/mendix/AppStoreWidgetBoilerplate/blob/master/src/WidgetName/WidgetName.xml) in the AppStoreWidgetBoilerplate repository. - -For the full reference on writing a widget XML, see the [Build Widgets with XML](/howto8/extensibility/use-xml-widget/). - -### Boilerplate - -The Yeoman widget generator ships two versions of a boilerplate created by Mendix. The source code for this boilerplate is available in the [AppStoreWidgetBoilerplate repository](https://github.com/mendix/AppStoreWidgetBoilerplate). - -## Further Reading - -This category of how-tos presents in-depth information on how to build your own widgets. A few more tips are below. - -### Learn by Example - -Most of the widgets in the [Mendix Marketplace](https://marketplace.mendix.com/) are open-source and available on GitHub. You can find the **View on GitHub** link on the right side of the Marketplace screen: - -{{< figure src="/attachments/howto8/extensibility/widget-development/appstore-github-link.png" class="no-border" >}} - -### Learn by Doing - -Using the widget generator, you get a test project. With the test project (or your own project), you can quickly start creating widgets. - -By debugging your widgets, you will quickly learn where you make mistakes and how the widget lifecycle works. - -### Ask the Community - -Within the Mendix community of developers, there are plenty of widget developers. The [Mendix Community](https://community.mendix.com/) is the place to go to when you have questions. - -## Documents in This Category diff --git a/content/en/docs/howto8/extensibility/widget-development/add-a-preview-image-for-custom-widget.md b/content/en/docs/howto8/extensibility/widget-development/add-a-preview-image-for-custom-widget.md deleted file mode 100644 index 6d27e99738a..00000000000 --- a/content/en/docs/howto8/extensibility/widget-development/add-a-preview-image-for-custom-widget.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "Build a Preview Image for a Custom Widget" -linktitle: "Preview Image for Custom Widget" -url: /howto8/extensibility/add-a-preview-image-for-custom-widget/ ---- - -## Introduction - -This how-to will show you how to specify a preview image that will be rendered in Studio Pro. - -This how-to teaches you how to do the following: - -* Configure a preview image for custom widgets - -## Prerequisites - -Before starting with this how-to, make sure you have completed the following prerequisites: - -* Download and install [Mendix Studio Pro](https://marketplace.mendix.com/link/studiopro/) -* Read [Custom Widgets](/howto8/extensibility/widget-development/) - -## Adding a Preview Image to Your Custom Widget Package - -You need to put an image file named *preview.png* next to your custom widget XML configuration file: - -{{< figure src="/attachments/howto8/extensibility/widget-development/add-a-preview-image-for-custom-widget/01_Folder_View.png" class="no-border" >}} - -After packaging your custom widget, the image provided will be rendered in Studio Pro whenever it is used: - -{{< figure src="/attachments/howto8/extensibility/widget-development/add-a-preview-image-for-custom-widget/02_Preview.png" class="no-border" >}} - -Please note that older versions of Studio Pro ignore this image and render a grey rectangle as usual. diff --git a/content/en/docs/howto8/extensibility/widget-development/use-xml-widget.md b/content/en/docs/howto8/extensibility/widget-development/use-xml-widget.md deleted file mode 100644 index 9917d6fe021..00000000000 --- a/content/en/docs/howto8/extensibility/widget-development/use-xml-widget.md +++ /dev/null @@ -1,344 +0,0 @@ ---- -title: "Build Widgets with XML" -url: /howto8/extensibility/use-xml-widget/ ---- - -## Requirements - -This document assumes you have a basic understanding of XML and Mendix Studio Pro. For more information on XML, visit [W3 Schools - XML](https://w3schools.com/xml/). - -## Start of the Widget XML - -An XML file always starts with the XML version and encoding declaration. These are standard and should be present in every XML file. Mendix Studio Pro uses the widget XML file to create the property input fields, which show up when you add your widget to a form. Our widget declaration XML starts at the `` element. This is the root element that will contain all our settings for this widget. - -## Widget Element {#Widgets-XMLreferenceguide-Widgetattributes} - -### Attributes - -| Attribute | Description | -| --- | --- | -| id | The id is where your widget is located. The path to the js file, starting at the root folder, separated by dots. Note that this is case-sensitive. | -| needsEntityContext | This Boolean determines whether your widget requires an object to be passed as the EntityContext and is required. If this is set to "true", the widget can only be used within a dataview or a templategrid. If set to "false", the widget can be used anywhere, but won't have an object passed to it automatically. | -| offlineCapable | This Boolean determines whether your widget can be used on pages that are accessible through the offline profile. If this attribute is not set, or set to "false", the widget cannot be used offline. If set to "true", the widget can be used offline. Keep in mind that there are a number of restrictions when working offline. Calling a microflows or fetching data using XPath are examples of features that are not supported offline. For more information, see the [Ensuring Your App Is Offline-First](/refguide8/offline-first/#limitations) section of *Offline First*. | -| xmlns | The XML namespace used by the widget. The value of this attribute is the same for every widget. `` | - -### Child elements {#Widgets-XMLreferenceguide-id} - -Inside the widget element are 4 child elements. - -| Element | Description | -| --- | --- | -| Name | The name property is what your widget will be called in Mendix Studio Pro. It will also be used to name the different instances of your widget by adding a number to the end of it each time it is used in a form. | -| Description | The description determines the mouse-over tooltip over your widget in the Custom Widgets toolbar. | -| Icon | Every element or widget in Studio Pro has its own icon. Your new widget's icon can be defined with this property. It is a [Base64](https://en.wikipedia.org/wiki/Base64) representation of the image, so that it can be used in an XML file. | -| Properties | The individual property elements will be grouped inside the “properties” element as in the code snippet below. | - -```xml - - HelloWorld - The description of this widget. - - - - - -``` - -## Property element {#Widgets-XMLreferenceguide-Name} - -Any properties you define in your widget XML file can be set using Mendix Studio Pro and they will be passed to your JavaScript file, so you can use them in your widget. - -### Child elements - -Every property element contains at least the following 3 child elements. - -| Element | Description | -| --- | --- | -| Caption | This element is used to add the name of the property. This is how it will show up in the Properties list in Mendix Studio Pro. | -| Category | This element defines in what category this property will be shown in the Properties list in Mendix Studio Pro. Common categories are “Behavior”, “Appearance” and “Data source”. | -| Description | This element is used to add a useful description of the property, so the end-user knows what it’s for. | - -### Attributes - -All property elements define at least 2 attributes: **key** and **type**. The value of **key** is the name of the property in your widget, so use a descriptive name. The value of **type** refers to the type of the property, for example “string” or “integer”. Based on the type of the property, you may have to define additional attributes and/or child elements. - -Other possible attributes are: - -| Attribute | Description | -| --- | --- | -| isList | Only used for the Object property type. | -| entityProperty | Assigns an entity to a property. This should point to the **key** attribute of the **entity** to which it is related. This could also be relative (like `"../entityName"`) when the attribute is inside an object list: ``| -| allowNonPersistableEntities | Allows the selection of a non-persistable entity. (By default this is false.) | -| defaultValue | The default value that a property starts with when it is created. | -| required | Specifies if the property is a required field or not. Defaults to "True" if not present. | -| isDefault | Marks a property as the default property that is selected when the widget is selected. | -| multiline | Makes the string input multiple lines, which is useful for long texts. | -| parameterIsList| Requires the parameter of a microflow to be a list of the type defined in the **entityProperty**. | -| isPath | *("no", "optional", "yes")* The path for an attribute or entity property, it can be either "no", "optional" or "yes", where "no" is the default value if the property is left out. The "optional" means that the attribute/entity can be either the current entity (or an attribute of the current entity) or an entity (or attribute) over a 1-deep association. | -| pathType | *("reference", "referenceSet")* This defines what sort of reference should be shown for an entity/attribute over an association, either a "reference" or a "referenceSet". | - -The different property types and their respective required attributes are discussed below. - -## Property Types {#Widgets-XMLreferenceguide} - -Every property requires the **key** and **type** attribute. - -Any property can have the **isDefault** or **required** attribute. - -{{% alert color="info" %}} -The **required** attribute defaults to "true". -{{% /alert %}} - -### Attribute - -A property of type Attribute is always related to an entity: it uses the entityContext if it is set on true, otherwise an entityProperty is required. It enables the user in Mendix Studio Pro to select one of the attributes of the related entity (optionally over an association). - -```xml - - Background Color - Data source - - - - - -``` - -An attribute property has an extra required child element: a list of attributeTypes that define what type of attributes are accepted. This could be any of the following: - -* AutoNumber -* Binary -* Boolean -* Date and time -* Decimal -* Enumeration -* Hashed String -* Integer -* Long -* String - -### Boolean - -A property of type Boolean requires the attribute defaultValue. - -```xml - - Visibility - Data source - Whether the widget is initially visible. - -``` - -What it looks like in Mendix Studio Pro: - -{{< figure src="/attachments/howto8/extensibility/widget-development/use-xml-widget/16844049.png" class="no-border" >}} - -### Entity - -A property of the type Entity allows the user to configure a non-persistable entity in Mendix Studio Pro. This entity can then be used in your JavaScript to retrieve all the necessary information. - -```xml - - Color - Data source - The Color entity to use. - -``` - -### EntityConstraint - -The EntityConstraint lets you put a constraint on either the entity you specify with entityProperty or, if needsEntityContext is set to true and no entityProperty is defined, to the entity passed as context. - -```xml - - Color constraint - Data source - The XPath constraint on the entity. - -``` - -### Enumeration - -The enumeration property has an extra required child element: a list of enumerationValues. An enumerationValue contains a **key** attribute and a **caption** within their tag. - -This presents the user with a drop-down list of options, based on the **captions** in Mendix Studio Pro. The **keys** will reach your widget's JavaScript as an enumeration. - -It requires a default value to be set, which should correspond with one of the enumerationValue keys. - -```xml - - Textcolor - Appearance - The textcolor of the message in the widget - - Red - Black - White - - -``` - -What it looks like in Mendix Studio Pro: - -{{< figure src="/attachments/howto8/extensibility/widget-development/use-xml-widget/16844042.jpg" class="no-border" >}} - -### Form - -The form property lets you pass a form to the widget. If needsEntityContext is set to "true", it automatically receives the object context. - -```xml - - Help Form - Behaviour - Form to open - -``` - -{{% alert color="info" %}} -For forms containing a data view, remember that calling a form with a dataview, if needsEntityContext is set to "false" in your widget, still requires an object to work. -{{% /alert %}} - -### Image - -The image property lets the user select an image from Mendix Studio Pro's images to pass it to the widget. - -```xml - - Picture - Data Source - Select an image to add. - -``` - -### Integer {#Widgets-XMLreferenceguide-Integer} - -The integer property lets you to pass an integer to the widget. This property requires the attribute defaultValue. - -```xml - - Height - Appearance - The height of the widget - -``` - -### Microflow - -The Microflow property allows a user to select a microflow in Mendix Studio Pro. There are three options: - -1. If needsEntityContext is set to "true", the selected microflow is required to have the context entity as an input parameter (as this will automatically be passed into it). -2. If needsEntityContext is set to false and no entityProperty attribute is specified, the microflow will have no input parameters. -3. If the entityProperty attribute is specified, the selected microflow is required to have this entity as an input parameter. - -```xml - - Message Microflow - Data source - Return value: the message to show. - - -``` - -The Microflow property has an extra required child element: returnType. Use this to set what type of value you return. Studio Pro will then enforce this on the microflow that is assigned. - -Possible return types are shown below: - -* Void -* Boolean -* Integer -* Date and time -* String -* Object - -### Nanoflow - -The Nanoflow property allows a user to select a nanoflow in Mendix Studio Pro. There are three options: - -1. If needsEntityContext is set to "true", the selected nanoflow is required to have the context entity as an input parameter (as this will automatically be passed into it). -2. If needsEntityContext is set to false and no entityProperty attribute is specified, the nanoflow will have no input parameters. -3. If the entityProperty attribute is specified, the selected nanoflow is required to have this entity as an input parameter. - -```xml - - Validation Nanoflow - Behavior - Return value: whether the given object is validated successfully - - -``` - -The Nanoflow property has an extra required child element: returnType. Use this to set what type of value you return. Studio Pro will then enforce this on the nanoflow that is assigned. - -Possible return types: - -* Void -* Boolean -* Integer -* Date and time -* String -* Object - -### Object - -The object property is an array of packaged sub-properties. It packages multiple other properties into an object, of which multiple can be passed to the widget. It always requires the isList attribute, which needs to be set to "true". - -```xml - - Collection - Appearance - Add the properties to show in your collection - - - - Number - Data source - Give us a number - - - Text - Data source - And a text! - - - -``` - -What it looks like in Mendix Studio Pro: - -{{< figure src="/attachments/howto8/extensibility/widget-development/use-xml-widget/16844048.png" class="no-border" >}} - -### String - -The string property lets you to pass a string to the widget. - -```xml - - Message - Data source - A hardcoded message - -``` - -### TranslatableString - -The translatableString property is similar to a normal string property, except you can add translated versions of the default value for different languages. To achieve this, the `translatableString` property has an extra required child element: a list of translations. The Mendix Studio Pro language will match the assigned value. - -```xml - - Message - Data source - A hardcoded message - - Add your message here. - Vul hier je bericht in. - - -``` - -What it looks like in Mendix Studio Pro: - -{{< figure src="/attachments/howto8/extensibility/widget-development/use-xml-widget/16844045.png" class="no-border" >}} - -{{% alert color="info" %}} -Remember to use the correct language notation according to the [Java supported locales](https://www.oracle.com/java/technologies/javase/locales.html). -{{% /alert %}} diff --git a/content/en/docs/howto8/front-end/_MAPPING.txt b/content/en/docs/howto8/front-end/_MAPPING.txt deleted file mode 100644 index 1eaedad50e8..00000000000 --- a/content/en/docs/howto8/front-end/_MAPPING.txt +++ /dev/null @@ -1 +0,0 @@ -There are document files in this folder that are mapped to the product. Refer to Mapping to Products for the names of these files and how to proceed. \ No newline at end of file diff --git a/content/en/docs/howto8/front-end/_index.md b/content/en/docs/howto8/front-end/_index.md deleted file mode 100644 index 419106a1bf8..00000000000 --- a/content/en/docs/howto8/front-end/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Front End" -url: /howto8/front-end/ -weight: 30 -no_list: false -description_list: true ---- - -## Introduction - -Looking to create great user experiences and a user-friendly graphical user interface (GUI) for your app? You will find all the information you need here, from how to create pages to how to set up the navigation structure and implement best practices. - -## Documents in This Category diff --git a/content/en/docs/howto8/front-end/atlas-ui/_index.md b/content/en/docs/howto8/front-end/atlas-ui/_index.md deleted file mode 100644 index 4d9b6acd7b0..00000000000 --- a/content/en/docs/howto8/front-end/atlas-ui/_index.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: "Atlas UI" -url: /howto8/front-end/atlas-ui/ -weight: 5 -aliases: - - /howto8/front-end/create-a-custom-theme-with-the-mendix-ui-framework.html - - /howto8/ux/create-a-custom-theme-with-the-mendix-ui-framework.html - - /howto8/front-end/create-a-custom-theme-with-the-mendix-ui-framework - - /howto8/ux/create-a-custom-theme-with-the-mendix-ui-framework ---- - -{{% alert color="info" %}} -The Atlas UI Resources module is deprecated, as is Atlas 2. If you are still using Atlas 2, Mendix recommends that you [migrate from Atlas 2 To Atlas 3](/refguide9/moving-from-atlas-2-to-3/). -{{% /alert %}} - -## Introduction - -Mendix Atlas UI is the design framework that makes building elegant user experiences a rapid process. It was built upon three design principles: simplicity, harmony, and flexibility. Simplicity helps you focus on what is important. We’ve simplified the design process with readymade page templates, building blocks, and widgets that can be arranged and customized to suit your app. Our design elements are harmonious, bringing a unified aesthetic to your app landscape. Atlas UI is built to be fully responsive, ensuring quality across scale without losing functionality. - -Visit the [Atlas UI site](https://atlas2.mendix.com/) for detailed previews and descriptions of all Atlas UI elements, or see the Atlas UI Framework [GitHub repository](https://github.com/mendix/Atlas-UI-Framework). If you wish to customize your Mendix apps' styling, see [How to Customize Your Styling Using Calypso](/howto8/front-end/calypso/). - -### Design Principles - -Atlas UI has a philosophy based on the core principles described below. These principles guide all our design decisions at Mendix, and we encourage every Mendix user to adopt them when building their own apps. - -#### Simplicity - -Freedom from complexity: we strive for simplicity to help you focus on what is important. - -#### Harmony - -Create familiarity and consistency throughout your apps landscape, regardless of the device you use. - -#### Flexibility - -Design apps that look good and scale in all situations without losing an intuitive and consistent experience. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/atlas_ui_preview.png" class="no-border" >}} - -## Design Elements - -Our UI library is fully integrated. After choosing a navigation layout, you can find page templates, building blocks, and widgets directly in your **Toolbox**. These UI elements form the foundation of your app. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/designelements.png" class="no-border" >}} - -**1** **Navigation Layouts** - -When building a Mendix app, the first thing you do is choose a navigation layout. These layouts are the frame within which your dynamic pages are housed, and they provide consistent structure throughout your app. - -**2** **Page Templates** - -Page templates are predesigned collections of building blocks that can be used as-is, or you can enhance them with custom building blocks and widgets. - -**3** **Building Blocks** - -Building blocks are single-purpose user interface elements and are comprised of multiple widgets. Multiple building blocks are usually used together on one page. - -**4** **Widgets** - -Widgets are small user interface elements (alerts, buttons, charts, etc.) used to enhance existing building blocks. - -**5** **Design Properties** - -You can further customize widgets by changing their design properties. Colors, text, and many other variables can be altered to make the widget what you need it to be. - -## Read More - -* [Get Started with Atlas UI](/howto8/front-end/get-started-with-atlasui/) -* [Migrate Existing Apps to Atlas UI](/howto8/front-end/migrate-existing-projects-to-atlasui/) -* [Create Company Atlas UI Resources](/howto8/front-end/create-company-atlas-ui-resources/) -* [Share Company Atlas UI Resources](/howto8/front-end/share-company-atlas-ui-resources/) -* [Create Custom Preview Images for Building Blocks and Page Templates](/howto8/front-end/create-custom-preview-images-for-building-blocks-and-page-templates/) -* [Troubleshooting Atlas UI Changes](/refguide8/migration-atlas/) -* [How to Customize Your Styling Using Calypso](/howto8/front-end/calypso/) diff --git a/content/en/docs/howto8/front-end/atlas-ui/create-company-atlas-ui-resources.md b/content/en/docs/howto8/front-end/atlas-ui/create-company-atlas-ui-resources.md deleted file mode 100644 index 8b10224ca06..00000000000 --- a/content/en/docs/howto8/front-end/atlas-ui/create-company-atlas-ui-resources.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Create Company Atlas UI Resources" -url: /howto8/front-end/create-company-atlas-ui-resources/ -weight: 30 ---- - -{{% alert color="info" %}} -The Atlas UI Resources module is deprecated, as is Atlas 2. If you are still using Atlas 2, Mendix recommends that you [migrate from Atlas 2 To Atlas 3](/refguide9/moving-from-atlas-2-to-3/). -{{% /alert %}} - -## Introduction - -Creating Atlas UI resources for your company is a great way to keep your company's apps in sync with your company brand. It’s easier to scale and manage apps throughout your app landscape when all the resources are neatly organized in a single module. - -This how-to teaches you how to do the following: - -* Create your own UI resources -* Create page templates -* Export resources - -## Creating Page Templates - -The Atlas UI resources include a large variety of page templates to use. When creating an app, a lot of pages you create will be custom-made, and developers may want to reuse these page templates within the app or in other apps without having to start from scratch. This is now possible in Mendix Studio Pro. - -In the example below, we’ll go through the steps of creating a new page template and talk about how the page template behaves in a local app and in the **UI Resources** module. - -### Example Scenario - -In Studio Pro, go to the **Project Explorer** of your app and right-click the page you want to use as the page template. In this example, we are using a dashboard page. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_page_templates.png" class="no-border" >}} - -Name the page template you want to create, then select your layout type. **Responsive** layouts are best when your app will be viewed on multiple screen sizes. **Tablet-specific** and **Phone-specific** types are best for their respective devices. The **Pop-up** layout type should be chosen when you would like the content of your page to be seen in a pop-up window or dialog box. The **Preview layout** is the default layout that will be used when creating the page template. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_page_template_name.png" class="no-border" >}} - -The page template is now a new document type in the module with its own icon. In the page templates **Properties** pane, there are some properties important for the template: - -* **Display name** — the name of the page template, which will be shown in the **Create page** dialog box -* **Image** — the page template preview image, which will be shown in the **Create page** dialog box -* **Show when** — there are three options for when to show the page template: **Creating new pages** (default), **Generating edit pages**, and **Generating select pages** -* **Layout type** — the layout type is needed to categorize the page as suitable for a responsive, tablet, phone, or pop-up type -* **Preview layout** — the default layout that will be used when creating the page template - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_page_template_properties.png" class="no-border" >}} - -When you create a new page in the module, it will now also show the created page template. The example below shows how the page template has been added to the **Local** category. Everything that has been created will stay **Local** until we move the page templates in the UI Resources module. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_page_template_local.png" class="no-border" >}} - -Page templates in Atlas UI are all built with building blocks. In the next section, we will walk through the steps of creating building blocks. - -## Creating Building Blocks - -Building blocks are single-purpose user interface elements comprised of multiple widgets. Multiple building blocks are usually used together on one page. Atlas UI comes with a variety of building blocks like cards, forms, headers, and controls. - -Every page can contain building blocks by grouping widgets together. In our example, we have a building block that consists of a container, title, text, and a button. This is a simple building block that is often used in apps. - -Go to a page and select a group of widgets that can be used as a building block. Right-click the container or parent widget that includes the widgets, then select **Create building block**: - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_bb.png" class="no-border" >}} - -Name the building block you want to create: - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_bb_name.png" class="no-border" >}} - -The building block is now a new document type in the module with its own icon. In the building block **Properties** pane, there are two properties important for the building block: - -* **Display name** — the name of the building block that will show in the **Toolbox** pane of Studio Pro -* **Image** — the building block preview image that will be shown in the **Toolbox** pane of Studio Pro - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_bb_properties.png" class="no-border" >}} - -The building block is now available in the **Toolbox**, where users can drag it and other building blocks onto the page. The example below shows that the building block has been added to the **Local** category. Everything that has been created will stay **Local** until we move the building block into the **UI Resources** module. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_bb_toolbox.png" class="no-border" >}} - -## Moving from Local to Atlas UI Resources {#moving-from-local-to-atlas-ui-resources} - -Now that it’s clear how to create page templates and building blocks, we need to discuss how to get our resources from the **Local** category into a module that can be shared with our apps and users. - -Let’s begin by placing our page template inside the **UI_Resources** module under **App Store modules**: - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_moving_local.png" class="no-border" >}} - -In our example, the new page template has been added to the dashboard category. When we now create a new page in Mendix Studio Pro, the **Template** is available in the **Create Page** wizard under the **Dashboards** category: - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/creating_open_pt.png" class="no-border" >}} - -The **UI_Resources** module has been organized with folders that can be renamed and used as categories for page templates and building blocks. The sorting is done using numbers in front of the name, which can be altered to change the order in which they appear. Page templates and building blocks can be placed inside the same folder to reuse the same category names. - -Adding an underscore to the folder name in Studio Pro (for example, **_Layouts**) ensures that the folder doesn’t get added to the categories for page templates or building blocks. - -## Export Company Atlas UI Resources - -When the resources are ready to be shared with multiple developers or apps, the module can be exported from the Project Explorer. You are free to change the name of a module as long as the module has been exported as a UI resource package. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-company-atlas-ui-resources/export_ui_module.png" class="no-border" >}} - -The module can now be imported in other apps or uploaded to the [Mendix Marketplace](https://marketplace.mendix.com/). There is an option to make the resource module available for private use only so that everybody in your company can benefit from and extend the module. - -## Read More - -* [Get Started with Atlas UI](/howto8/front-end/get-started-with-atlasui/) -* [Create Custom Preview Images for Building Blocks and Page Templates](/howto8/front-end/create-custom-preview-images-for-building-blocks-and-page-templates/) -* [Migrate Existing Apps to Atlas UI](/howto8/front-end/migrate-existing-projects-to-atlasui/) -* [Share Company Atlas UI Resources](/howto8/front-end/share-company-atlas-ui-resources/) diff --git a/content/en/docs/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates.md b/content/en/docs/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates.md deleted file mode 100644 index 3300c089544..00000000000 --- a/content/en/docs/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: "Create Custom Preview Images for Building Blocks and Page Templates" -linktitle: "Custom Preview Images" -url: /howto8/front-end/create-custom-preview-images-for-building-blocks-and-page-templates/ -weight: 50 ---- - -{{% alert color="info" %}} -The Atlas UI Resources module is deprecated, as is Atlas 2. If you are still using Atlas 2, Mendix recommends that you [migrate from Atlas 2 To Atlas 3](/refguide9/moving-from-atlas-2-to-3/). -{{% /alert %}} - -## Introduction - -To make your custom UI resources easy to browse, you can create custom preview images for your building blocks and page templates. We’ve provided downloadable templates in the *.sketch* and *.psd* formats, which are available on the [Atlas UI site](https://atlas2.mendix.com). - -This how-to teaches you how to do the following: - -* Create building block preview images in various editors -* Create page template preview images in various editors - -## Creating Building Block Preview Images - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates/create_custom_image_bb.png" class="no-border" >}} - -### Creating a Building Block Preview Image in Sketch - -To create a building block preview image in Sketch, follow these steps: - -1. Download the [Atlas UI image templates resources pack](https://atlas2.mendix.com/index3.html#/resources/7881299347899269). -2. Open the Sketch file named **BB_previewimage.sketch**. This file contains two artboards. The first artboard shows an example of how custom preview images look in the Studio Pro's Toolbox. The second artboard is where you place your image. -3. Hide the layer called **Template**, then insert your preview image into the **Building Block preview** folder. -4. When you are happy with your image, select your artboard. -5. In the **Export** dialog box that appears on the lower-right side of your screen, make sure the preferences are set to the following: - * **Size**: 1x - * **Format**: PNG - - {{< figure src="/attachments/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates/create_custom_image_bb_sketch.png" class="no-border" >}} - -6. Export your image. - -### Creating a Building Block Preview Image in Photoshop - -To create a building block preview image in Photoshop, follow these steps: - -1. Download the [Atlas UI image templates resources pack](https://atlas2.mendix.com/index3.html#/resources/7881299347899269). -2. Open the Photoshop file named **BB_previewimage.psd**. -3. Double-click the smart object in the **Layers** panel. - - {{< figure src="/attachments/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates/create_custom_image_bb_photoshop.png" class="no-border" >}} - -4. Replace the contents of the folder with your building block preview image. -5. Save your changes and navigate back to your template file. -6. If you are happy with your image, export your file as a *.png* file. - -### Creating a Building Block Preview Image in Illustrator - -To create a building block preview image in Illustrator, follow these steps: - -1. Download the [Atlas UI image templates resources pack](https://atlas2.mendix.com/index3.html#/resources/7881299347899269). -2. Open the Illustrator file named **BB_previewimage.ai**. This file contains two artboards. The first artboard shows an example of how custom preview images look in the Studio Pro's Toolbox. The second artboard is where you place your image. -3. Hide the layer called **Template**, then insert your preview image into the **Building Block preview** folder. -4. When you are happy with your image, select your artboard. -5. Click **File** > **Export for screens**, then select the **BB Image@2x** artboard. -6. Make sure the preferences are set to the following: - * **Scale**: 1x - * **Format**: PNG - - {{< figure src="/attachments/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates/create_custom_image_bb_illustrator.png" class="no-border" >}} - -7. Export your image. - -### Creating a Building Block Preview Image in Another Image Editor - -You can also create your building block preview image in a different image editor of your choice. Building block preview images should be 280px wide and 216px tall. Save the image as a *.png* file. - -## Creating Page Template Preview Images - -{{< figure src="/attachments/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates/create_custom_image_pt.png" class="no-border" >}} - -### Creating a Page Template Preview Image in Sketch - -To create a page template preview image in Sketch, follow these steps: - -1. Download the [Atlas UI image templates resources pack](https://atlas2.mendix.com/index3.html#/resources/7881299347899269). -2. Open the Sketch file named **PT_previewimage.sketch**. This file contains three artboards. The first two artboards show examples of how page template preview images look. The third artboard is where you place your image. -3. Hide the layer called **Template**, then insert your preview image into the **Building Block preview** folder. -4. When you are happy with your image, select your artboard -5. In the **Export** dialog box that appears on the lower-right side of your screen, make sure the preferences are set to the following: - * **Size**: 1x - * **Format**: PNG - - {{< figure src="/attachments/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates/create_custom_image_pt_sketch.png" class="no-border" >}} - -6. Export your image. - -### Creating a Page Template Preview Image in Photoshop - -To create a page template preview image in Photoshop, follow these steps: - -1. Download the [Atlas UI image templates resources pack](https://atlas2.mendix.com/index3.html#/resources/7881299347899269). -2. Open the Photoshop file named **PT_previewimage.psd**. -3. Double-click the smart object in the **Layers** panel. - - {{< figure src="/attachments/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates/create_custom_image_pt_photoshop.png" class="no-border" >}} - -4. Replace the contents of the folder with your page template preview image. -5. Save your changes and navigate back to your template file. If you are happy with your image, export your file as a *.png* file. - -### Creating a Page Template Preview Image in Illustrator - -To create a page template preview image in Illustrator, follow these steps: - -1. Download the [Atlas UI image templates resources pack](https://atlas2.mendix.com/index3.html#/resources/7881299347899269). -2. Open the Illustrator file named **PT_previewimage.ai**. This file contains three artboards. The first two artboards show examples of how page template preview images look. The third artboard is where you place your image. -3. Hide the layer called **Template**, then insert your preview image into the **Page template preview** folder. -4. When you are happy with your image, select your artboard -5. Click **File** > **Export for screens**, then select the **PT@2x** artboard. -6. Make sure the preferences are set to the following - * **Scale**: 1x - * **Format**: PNG - - {{< figure src="/attachments/howto8/front-end/atlas-ui/create-custom-preview-images-for-building-blocks-and-page-templates/create_custom_image_bb_illustrator.png" class="no-border" >}} - -7. Export your image. - -### Creating a Page Template Preview Image in Another Image Editor - -You can also create your page template preview image in a different image editor of your choice. Page template preview images should be 255px wide and 255px tall. Save the image as a *.png* file. - -## Read More - -* [Get Started with Atlas UI](/howto8/front-end/get-started-with-atlasui/) -* [Create Company Atlas UI Resources](/howto8/front-end/create-company-atlas-ui-resources/) -* [Migrate Existing Apps to Atlas UI](/howto8/front-end/migrate-existing-projects-to-atlasui/) -* [Share Company Atlas UI Resources](/howto8/front-end/share-company-atlas-ui-resources/) diff --git a/content/en/docs/howto8/front-end/atlas-ui/get-started-with-atlasui.md b/content/en/docs/howto8/front-end/atlas-ui/get-started-with-atlasui.md deleted file mode 100644 index bd0f1ea59b6..00000000000 --- a/content/en/docs/howto8/front-end/atlas-ui/get-started-with-atlasui.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Get Started with Atlas UI" -url: /howto8/front-end/get-started-with-atlasui/ -weight: 10 ---- - -{{% alert color="info" %}} -The Atlas UI Resources module is deprecated, as is Atlas 2. If you are still using Atlas 2, Mendix recommends that you [migrate from Atlas 2 To Atlas 3](/refguide9/moving-from-atlas-2-to-3/). -{{% /alert %}} - -## Introduction - -This how-to teaches you how to do the following: - -* Choose an app template -* Choose a page template -* Customize your theme - -## Prerequisite - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Have a Mendix account (sign up [here](https://www.mendix.com/try)) - -## Choosing Your App Template - -in [Apps](https://sprintr.home.mendix.com/index.html), click **Create App**. You will see a number of apps marked with **ATLAS UI**, which are Atlas UI-based app templates. You can select one to get started. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/get-started-with-atlasui/start_choose_your_starter_app.png" alt="App template in Mendix Portal" class="no-border" >}} - -For more information about Atlas UI, see [Atlas UI](/howto8/front-end/atlas-ui/). - -## Choosing a Page Template - -You can choose a page template when you create a new page. - -For example, **Dashboard Action Tiles**, **Dashboard Charts**, **Dashboard Expenses** are page templates. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/get-started-with-atlasui/start_choose_a_page_template.png" alt="Page Template" class="no-border" >}} - -Once the page is created, you can customize it. - -## Customizing Your Theme - -The **Theme Customizer** allows you to customize your app. - -## Read More - -* [How to Create Custom Preview Images for Building Blocks and Page Templates](/howto8/front-end/create-custom-preview-images-for-building-blocks-and-page-templates/) -* [How to Migrate Existing Apps to Atlas UI](/howto8/front-end/migrate-existing-projects-to-atlasui/) -* [How to Share Company Atlas UI Resources](/howto8/front-end/share-company-atlas-ui-resources/) diff --git a/content/en/docs/howto8/front-end/atlas-ui/migrate-existing-projects-to-atlasui.md b/content/en/docs/howto8/front-end/atlas-ui/migrate-existing-projects-to-atlasui.md deleted file mode 100644 index 68b5f34e52b..00000000000 --- a/content/en/docs/howto8/front-end/atlas-ui/migrate-existing-projects-to-atlasui.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "Migrate Existing Apps to Atlas UI" -url: /howto8/front-end/migrate-existing-projects-to-atlasui/ -weight: 20 ---- - -{{% alert color="info" %}} -The Atlas UI Resources module is deprecated, as is Atlas 2. If you are still using Atlas 2, Mendix recommends that you [migrate from Atlas 2 To Atlas 3](/refguide9/moving-from-atlas-2-to-3/). -{{% /alert %}} - -## Introduction - -Atlas UI brings a lot of features to the process of building an app. But what if you already have a Mendix app that looks great and runs smoothly? No problem! To get an existing Mendix app to work with Atlas UI, there are a couple of steps to follow. This how-to describes how to upgrade existing Mendix projects to Atlas UI. - -This how-to teaches you how to do the following: - -* Prepare your app for Atlas UI -* Replace the UI Framework module -* Replace existing navigation layouts -* Perform some optional actions - -## Replacing the UI Framework Module - -{{% alert color="warning" %}} -The Atlas UI Resources module is deprecated, as is Atlas 2. If you are still using Atlas 2, Mendix recommends that you [migrate from Atlas 2 To Atlas 3](/refguide9/moving-from-atlas-2-to-3/). -{{% /alert %}} - -To get the full experience of Atlas UI, it’s necessary to import the Atlas UI Resources module. Every app includes a module called **UI_Resources** that can be found under **Project** > **App Store modules** in Studio Pro. This module contains all the layouts, page templates, and building blocks. The **UI Framework** folder in this module contains the old Mendix UI Framework content, which we will be upgrading to Atlas UI. - -To replace the UI Framework, follow these steps: - -1. Delete the **UI_Resources** module. -2. Download and import the [Atlas UI Resources](https://marketplace.mendix.com/link/component/104730) module from the Mendix Marketplace. -3. When the Atlas UI Resources module is downloaded from the Mendix Marketplace, it will be found in **App Store modules**: - - {{< figure src="/attachments/howto8/front-end/atlas-ui/migrate-existing-projects-to-atlasui/migrate_dm_appstore.png" class="no-border" >}} - -After the import is complete, there may be some errors in the **Error** pane for navigation profiles or layouts that do not exist. Be sure to resolve all of these errors. - -Once the Atlas UI Resources module is imported, all the new resources will be available in Studio Pro. When creating a new page, a new set of page templates for all devices will be available. In the **Toolbox**, a new tab will be added called **Building blocks**. You can drag building blocks from this pane onto your pages. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/migrate-existing-projects-to-atlasui/migrate_dm_bb_toolbox.png" alt="Image of Mendix Atlas UI" class="no-border" >}} - -## Replacing Existing Navigation Layouts - -The Atlas UI Resources module comes with navigation layouts, which are required in order to use the page templates. If your existing navigation layouts are in a separate module, you will have to replace all the layouts for your pages with the Atlas UI layouts in order to make use of the new page templates. It is possible to keep using your old navigation layouts, but you will not be able to access the full capabilities of Atlas UI if you choose to do so. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/migrate-existing-projects-to-atlasui/migrate_dm_navlayouts.png" class="no-border" >}} - -## Reusing Parts of Your Old Theme (Optional) - -A lot of Mendix projects have a custom theme. If this is the case for your project, your old theme can be found in the Project Explorer folder named **theme_old**. The Atlas UI framework is similar to the Mendix UI Framework, so it is possible to reuse parts of your custom variables file. - -{{< figure src="/attachments/howto8/front-end/atlas-ui/migrate-existing-projects-to-atlasui/migrate_old_theme.png" alt="Image of Mendix Atlas UI" class="no-border" >}} - -## Read More - -* [Get Started with Atlas UI](/howto8/front-end/get-started-with-atlasui/) -* [Create Company Atlas UI Resources](/howto8/front-end/create-company-atlas-ui-resources/) -* [Create Custom Preview Images for Building Blocks and Page Templates](/howto8/front-end/create-custom-preview-images-for-building-blocks-and-page-templates/) -* [Share Company Atlas UI Resources](/howto8/front-end/share-company-atlas-ui-resources/) -* [Troubleshooting Atlas UI Changes](/refguide8/migration-atlas/) diff --git a/content/en/docs/howto8/front-end/atlas-ui/share-company-atlas-ui-resources.md b/content/en/docs/howto8/front-end/atlas-ui/share-company-atlas-ui-resources.md deleted file mode 100644 index c7378fadca2..00000000000 --- a/content/en/docs/howto8/front-end/atlas-ui/share-company-atlas-ui-resources.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: "Share Company Atlas UI Resources" -url: /howto8/front-end/share-company-atlas-ui-resources/ -weight: 40 ---- - -{{% alert color="info" %}} -The Atlas UI Resources module is deprecated, as is Atlas 2. If you are still using Atlas 2, Mendix recommends that you [migrate from Atlas 2 To Atlas 3](/refguide9/moving-from-atlas-2-to-3/). -{{% /alert %}} - -## Introduction - -Creating company UI resources is a great way to let Mendix developers quickly create new beautiful applications with out-of-the-box company-branded themes, page templates, and building blocks. This is a great way to align multiple apps with the same UI resources, keeping your company brand as well as look and feel consistent. - -This how-to teaches you how to do the following: - -* Share the UI Resources module -* Maintain the UI Resources module - -## Exporting Your Company Atlas UI Resources - -When your custom resources are ready to be shared with multiple developers or apps, you can export the module from the **Project Explorer** in Studio Pro. To do this, right-click the **UI Resources** module, export it, and save it: - -{{< figure src="/attachments/howto8/front-end/atlas-ui/share-company-atlas-ui-resources/sharing_export_uiresources.png" class="no-border" >}} - -You are free to change the name of the module after it has been exported as a UI resource package. - -The module can now be imported in other apps or uploaded to the Mendix Marketplace. It is also possible to make the module available for private use only, so that everybody in your company can benefit from and extend it. - -In the next section, the process of sharing UI resources will be made clear. - -## Sharing and Maintaining Your Company Atlas UI Resources - -The Mendix Marketplace is a great way to share UI resources throughout your company. Everybody in your company can benefit from using these UI resources, and you can document and keep track of changes made to the resources. Never worry about losing your UI resources or making errors, because everything is taken care of with the Mendix Marketplace version control system. - -There are two important options to keep in mind when uploading a UI resources module: - -* **Publish to** — this option lets you share the UI resources in a private Marketplace (company-only) or with the public audience (the entire Mendix community) -* **Category** — choose the **UI Resources** category to make the module available as a UI resources module - -{{< figure src="/attachments/howto8/front-end/atlas-ui/share-company-atlas-ui-resources/sharing_appstore_addcontent.png" class="no-border" >}} - -When you upload new UI resources to the public Mendix Marketplace, the content will need to be reviewed and approved by Mendix. However, when you publish UI resources to the private Marketplace, the content will not have to be reviewed, and it will be directly available in your company after publishing. - -## Using Your Company Atlas UI Resources - -This section describes how Mendix developers in your company can benefit from the UI Resources module. - -### Including the UI Resources Module With a Company App Template - -A UI Resources module is a great way to keep all the UI resources centralized in your application. It would be a lot of work to download the UI Resources module every time a Mendix developer starts a new Mendix app. An easier way to share the UI Resources for new Mendix apps is to create a blank company app template with the UI Resources module already included. This blank app can also be extended with logic and data, depending on what your Mendix developers need to quickly create Mendix applications. - -Let’s start with creating a new Mendix application in the Mendix Portal or directly in Mendix Studio Pro: - -1. Select the **Blank App** and open the new app in Studio Pro: - - {{< figure src="/attachments/howto8/front-end/atlas-ui/share-company-atlas-ui-resources/sharing_createnewapp.png" class="no-border" >}} - -2. Expand at the **App Store modules** at the Mendix **Project** level and find the default **Atlas_UI_Resources** module. Right-click this module and delete it: - - {{< figure src="/attachments/howto8/front-end/atlas-ui/share-company-atlas-ui-resources/sharing_delete_module.png" class="no-border" >}} - -3. Now it’s time to import your company UI resources (if you have not created the UI resources yet, see [How to Create Company UI Resources](/howto8/front-end/create-company-atlas-ui-resources/)). Import these resources by clicking **App Store** in the top toolbar of Studio Pro, and then selecting **UI Resources** in the left sidebar **Categories** menu. -4. Download the company UI resources module you have created. -5. When the download is complete, the UI resources will be visible in the **App Store modules** in **Project Explorer**. Be sure to check if all the errors are resolved before continuing. - -Now that you have added your company UI resources to your company app template, you can share the app in the Mendix Marketplace just as you did with the company UI resources (see the next section for details). The company app template will be available for your Mendix developers to use whenever they want to create a new app, allowing them to save time and skip downloading the company UI resources separately. - -#### Sharing and Maintaining Your Company App Template - -Now that you have created a company app template, the next step is to share it with your company. The easiest way to do this is by uploading it to the private Marketplace. - -There are four important options to keep in mind when uploading your company app template: - -* **Where can people find your content?** — this option must be set to **Private Marketplace** -* **Category** — select the **Create New App** -* **Sub category** — select the **Starter Apps** sub-category to make the app available as a template in the "create new app flow" for the Mendix Platform -* **Impressions** — impressions contain the images that are shown when creating a new app in the Mendix Platform - -{{< figure src="/attachments/howto8/front-end/atlas-ui/share-company-atlas-ui-resources/sharing_appstore_addcontent_starterapp.png" class="no-border" >}} - -These are examples of app impression images: - -{{< figure src="/attachments/howto8/front-end/atlas-ui/share-company-atlas-ui-resources/sharing_createnewapp_detail.png" class="no-border" >}} - -### Using the UI Resources Module from the Mendix Marketplace - -The UI Resources module can be easily downloaded through the Mendix Marketplace in Studio Pro. By downloading the UI Resources module in existing Mendix apps, developers can benefit from all the new UI resources. - -To use the UI Resources module from teh Mendix Marketplace, follow these steps: - -1. Open the Mendix Marketplace in Studio Pro and then select **UI Resources** in the left sidebar **Categories** menu: - - {{< figure src="/attachments/howto8/front-end/atlas-ui/share-company-atlas-ui-resources/sharing.png" class="no-border" >}} - - The available UI resources will appear in the middle section of the Marketplace. The **Private** label indicates that the UI resources are only available for your company. - -2. Select the UI resources that have been created by your company: - - {{< figure src="/attachments/howto8/front-end/atlas-ui/share-company-atlas-ui-resources/sharing_detail.png" class="no-border" >}} - -3. To download the UI resources inside your project, click **Download**. After downloading your company's UI Resources module, it will appear under **App Store modules**. The module can always be updated by downloading a new version from the Mendix Marketplace when new resources are added. - -## Read More - -* [Get Started with Atlas UI](/howto8/front-end/get-started-with-atlasui/) -* [Create Company Atlas UI Resources](/howto8/front-end/create-company-atlas-ui-resources/) -* [Create Custom Preview Images for Building Blocks and Page Templates](/howto8/front-end/create-custom-preview-images-for-building-blocks-and-page-templates/) -* [Migrate Existing Apps to Atlas UI](/howto8/front-end/migrate-existing-projects-to-atlasui/) diff --git a/content/en/docs/howto8/front-end/charts-tutorials/_index.md b/content/en/docs/howto8/front-end/charts-tutorials/_index.md deleted file mode 100644 index 1f2b1617a3b..00000000000 --- a/content/en/docs/howto8/front-end/charts-tutorials/_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Use the Charts Widgets" -url: /howto8/front-end/charts-tutorials/ -weight: 20 -description: "These how-tos will guide you in using charts in Mendix apps." ---- - -The following how-tos are available here: - -* [Create a Basic Chart](/howto8/front-end/charts-basic-create/) -* [Use Any Chart](/howto8/front-end/charts-any-usage/) -* [Fine-Tune a Chart with Advanced Settings](/howto8/front-end/charts-advanced-tuning/) -* [Use the Charts Theme](/howto8/front-end/charts-theme/) -* [Create a Dynamic Series Chart](/howto8/front-end/charts-dynamic-series/) -* [Use a Chart with a REST Data Source](/howto8/front-end/charts-basic-rest/) -* [Use the Plotly Images REST Service Endpoint](/howto8/front-end/charts-plotly-images-rest/) diff --git a/content/en/docs/howto8/front-end/charts-tutorials/charts-advanced-tuning.md b/content/en/docs/howto8/front-end/charts-tutorials/charts-advanced-tuning.md deleted file mode 100644 index 21113d50490..00000000000 --- a/content/en/docs/howto8/front-end/charts-tutorials/charts-advanced-tuning.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: "Fine-Tune a Chart with Advanced Settings" -linktitle: "Chart Advanced Tuning" -url: /howto8/front-end/charts-advanced-tuning/ -weight: 30 -description: "Describes the settings you can use to change chart layouts and types" ---- - -## Introduction - -The individual Charts widgets can be fine-tuned with advanced settings. The settings can affect the layout, configuration and data. - -This how-to teaches you how to do the following: - -* Change font style (layout) -* Change chart type (data series) -* Enable toolbar (configuration) - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Installed the latest version of Mendix Studio Pro -* Downloaded the latest [Chart Widget](/appstore/widgets/charts/) from the Mendix Marketplace -* Set up a chart, see [How to Create a Chart](/howto8/front-end/charts-basic-create/) - -## Changing the Layout {#layout-changes} - -This is what the original chart looks like: - -{{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-toggle-editor.png" alt="chart" class="no-border" >}} - -To create a custom layout, follow these steps: - -1. Open an app containing a chart. -2. Open the page with the charts widget. -3. Open the charts widget settings. -4. Go to the tab **Advanced**. -5. Set the **Mode** to **Developer**. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-widget-properties-advanced.png" alt="chart widget properties" class="no-border" >}} -6. Run the app. -7. In your browser, open the page with the chart. -8. Click on the button **Toggle Editor**. -9. In the **Layout** section add the following **Custom setting**: - - ```json - { - "font": { - "family": "Open Sans", - "size": 14, - "color": "#555" - } - } - ``` - -10. Change the font settings till the chart shows the required font. Copy the font settings. - - {{% alert color="warning" %}}Please note that changes made in the editor will not persist unless they are stored in the advanced settings of the widget or in the theme.{{% /alert %}} - - After making some changes, the chart looks like this: - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-toggle-editor-open.png" alt="chart editor" class="no-border" >}} - -11. Paste the new font settings into the **Layout options** property in the **Advanced** tab. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-widget-properties-advanced-layout.png" alt="chart editor" class="no-border" >}} - -12. Change the **Mode** back to **Advanced** in Studio Pro, this will remove the Toggle Editor button from the chart. - -{{% alert color="warning" %}} - -Please note that the advanced settings only apply to the chart in Advanced or Developer mode. - -{{% /alert %}} - -## Changing the Chart Type - -This is what the chart looks like before making any changes: - -{{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-widget-bar.png" alt="chart editor" class="no-border" >}} - -To create a custom configuration, follow these steps: - -1. Repeat steps 1 to 8 from the [layout instructions](#layout-changes). -2. Select the name of the series you want to display differently from the drop-down menu: in this case **Series 1**. -3. Edit the **Custom settings**; change them to `{ "type": "line" }`. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-widget-bar-line-combination.png" alt="chart editor" class="no-border" >}} -4. Copy the custom settings. -5. In Studio Pro, open the **Series 1** configuration. -6. Paste the new configuration for the data into the **(Layout) Options** property in the **Advanced** tab. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-widget-bar-line-combination-properties.png" alt="chart editor" class="no-border" >}} - -After the changes, the chart looks like this: - -{{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-widget-bar-line-combination-result.png" alt="chart editor" class="no-border" >}} - -## Changing the Configuration - -To create custom a configuration, follow these steps: - -1. Repeat steps 1 to 8 from the [layout instructions](#layout-changes). -2. Select **Configuration** from the drop-down menu. -3. Edit the **Custom settings**, change them to `{ "displayModeBar": true }`. -4. Add more Custom settings as desired. See [here](https://plot.ly/javascript/configuration-options/) for more configuration settings. -5. The changes made in the editor are not persistable; copy the required settings. -6. Paste the new configuration into the **Configuration options** property in the **Advanced** tab. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-widget-properties-advanced-config.png" alt="chart editor" class="no-border" >}} -7. Change **Mode** to **Advanced**, set Studio Pro to remove the **Toggle Editor** button. - - {{% alert color="warning" %}}Please note that the advanced settings only apply to the chart in Advanced or Developer mode{{% /alert %}} - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-config-toolbar.png" alt="chart editor" class="no-border" >}} - -## Read More - -Reference for the [advanced properties](/refguide8/charts-configuration/#advanced) - -Layout options: [cheat sheet](/refguide8/charts-advanced-cheat-sheet/#layout-all) -Configuration options: [cheat sheet](/refguide8/charts-advanced-cheat-sheet/#config-options) -Data series options: [cheat sheet](/refguide8/charts-advanced-cheat-sheet/#data-series) - -Full reference: https://plot.ly/javascript/ diff --git a/content/en/docs/howto8/front-end/charts-tutorials/charts-any-usage.md b/content/en/docs/howto8/front-end/charts-tutorials/charts-any-usage.md deleted file mode 100644 index 526f258db2a..00000000000 --- a/content/en/docs/howto8/front-end/charts-tutorials/charts-any-usage.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: "Use Any Chart" -url: /howto8/front-end/charts-any-usage/ -weight: 20 -description: "How to use the Any Chart widget to create advanced charts" ---- - -## Introduction - -The basic chart widgets provide a set of easy to configure charts such as line, bar, column, pie, and so forth. These charts can be fine tuned with the advanced options. - -When the advanced options are not enough, the **Any Chart** widget can be used. - -With **Any Chart** you can build all the chart types that are possible with Plotly.js as well as options for configuring charts dynamically. So, if you want to build a 3D chart or have a dynamic set of series, **Any Chart** is your friend. - -This how-to teaches you how to do the following: - -* Create a line chart with sample data -* Export data for a chart -* Fine tune the chart with the run-time playground - -## Prerequisites - -Before starting this how-to, make sure you have the following prerequisites: - -* The latest version of Mendix Studio Pro -* The latest [Any Chart](/appstore/modules/any-chart/) module -* An understanding of JSON data structures - -## Chart Structure - -An **Any Chart** widget can be configured with a JSON **Data** array and **Layout** object. The configuration can be set statically, via the **Source attribute** or with the **Sample data**. - -The configuration in the **Source attribute** will be merged into the static settings and will overwrite any common properties. The **Sample data** is for demo purposes at run time when there is no **Source** attribute selected or when rendering sample data in the Studio Pro preview. - -## Creating a Chart - -To create a line chart with the **Any Chart** widget, follow these steps: - -1. Create a page with a data view (Chart context). -2. Add the Any Chart widget in the data view. -3. Select the line chart sample from the [Any Chart cheat sheet](/refguide8/charts-any-cheat-sheet/#line-chart): - - ```json - [ { "x": [ 1, 2 ], "y": [ 1, 2 ], "type": "scatter" } ] - ``` - -4. In Studio Pro, copy the data into the Any Chart widget property tab **Data**, field **Static**. -5. Run the app to confirm the chart renders correctly. -6. Split the data into static and dynamic parts that are going to be generated from the domain model. - - Static : - - ```json - [ { "type": "scatter" } ] - ``` - - Sample data : - - ```json - [ { "x": [ 1, 2 ], "y": [ 1, 2 ] } ] - ``` - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-any-usage/any-chart-configuration.png" alt="Any Chart Configuration" class="no-border" >}} - -7. Run the app to preview the chart. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-any-usage/charts-any-sample.png" alt="Any Chart result" class="no-border" >}} - -## Exporting Data - -To generate JSON data for the Charts widget, follow these steps: - -1. Add a **Data** string (unlimited length) attribute to the Chart (context) entity. -2. In the widget, set the **Source attribute** field in the **Data** tab. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-any-usage/any-chart-configuration-attribute.png" alt="Select data attribute" class="no-border" >}} -3. Create a **JSON Structure** and use the **Sample data** as the snippet. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-any-usage/any-chart-json-structure-line-chart-data.png" alt="Create export mapping" class="no-border" >}} -4. Create an **Export Mapping** with the **JSON Structure**. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-any-usage/any-chart-line-chart-export-mapping-select.png" alt="Select data structure" class="no-border" >}} - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-any-usage/any-chart-line-chart-export-mapping.png" alt="Map objects" class="no-border" >}} -5. Create a microflow that retrieves the data. -6. Use the **Export Mapping** to generate a **String Variable**. Store the value in the object attribute that is selected as **Source attribute**. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-any-usage/any-chart-export-microflow.png" alt="Export microflow" class="no-border" >}} - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-any-usage/any-chart-export-microflow-structure.png" alt="Export microflow" class="no-border" >}} - -If need be, the layout can also be generated in the same way as the data. In most cases, a **Static** layout will suffice. - -## Fine tuning - -Editing the JSON configuration in Studio Pro can be cumbersome. With the live preview editor, developers can directly see the output of their changes. - -{{% alert color="warning" %}} - -The editor is only a playground and no settings are stored. All changes you make in the runtime preview that you wish to use the next time you view the app have to be applied to your **Any Chart** widget too. - -{{% /alert %}} - -To fine tune a Charts widget configuration, follow these steps: - -1. In the **Data** tab, set the **Mode** option to **Development**. - -2. Run the app, and open the page containing the chart. - -3. Click the **Toggle Editor** button on the top right of the chart to fine-tune your settings. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-toggle-editor-open.png" alt="chart editor" class="no-border" >}} - -4. In the editor, select either **Data** or **Layout** from the drop-down menu. - -5. Edit Static or Data settings. - -6. Copy the new settings and apply them in Studio Pro. - -7. Re-run the app to confirm the changes have been applied. - -## Read More - -* **Any Chart** properties: [Any Chart](/refguide8/charts-any-configuration/) -* The most common chart types: [Any Chart Cheat Sheet](/refguide8/charts-any-cheat-sheet/) -* The most common settings: [Configuration Cheat Sheet](/refguide8/charts-advanced-cheat-sheet/) -* The full JSON reference: [https://plot.ly/javascript/reference/](https://plot.ly/javascript/reference/) -* [JSON Structures](/refguide8/json-structures/) -* [Export Mappings](/refguide8/export-mappings/) diff --git a/content/en/docs/howto8/front-end/charts-tutorials/charts-basic-create.md b/content/en/docs/howto8/front-end/charts-tutorials/charts-basic-create.md deleted file mode 100644 index e769b9e9735..00000000000 --- a/content/en/docs/howto8/front-end/charts-tutorials/charts-basic-create.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "Create a Basic Chart" -url: /howto8/front-end/charts-basic-create/ -weight: 10 -description: "How to create a basic chart and configure the display options" ---- - -## Introduction - -The charts widget provides a basic implementation of different types of chart (for example: area, line, bar, column, and pie) in a Mendix application. - -This how-to teaches you how to do the following: - -* Create a chart with basic sample data - -* Configure the chart display options - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Download the latest [Charts Widget](/appstore/widgets/charts/) from the Mendix Marketplace - -## Implementing the Charts Widget in an Existing App - -In this section, you will create a chart with basic sample data. - -## Setting up the Domain Model - -To use the Charts widget, a specific data structure is set up. This is defined by entities and attributes in the domain model. - -1. Create a new module called **charts**. - -2. Configure your domain model to contain an entity **Value** with a string attribute **xValue** and a decimal attribute **yValue**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-entity.png" alt="Value entity" class="no-border" >}} - -## Creating a Data Entry Page - -To create a basic data entry page from which the Charts widget will fetch data, follow these steps: - -1. Right Click on value entity. - -2. Select **Generate overview pages**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-rest-generate-overview-pages.png" alt="Generate overview pages for Value entity" class="no-border" >}} - -3. Add the **Value_NewEdit** page to user navigation. - -## Adding the Charts Widget to a New Page - -1. Create a page named *ShowChart*. - -2. Add it to the user navigation. - -3. Add a **Data view** to this page that contains the **Value** entity and has a microflow as a data source. - -4. Create a new microflow named **DS_NewValue** to fill the data view. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-create-new-value.png" alt="Data view showing the Value entity" class="no-border" >}} - -5. Right-click the data view and select **Go to microflow**. - -6. In the new **DS_NewValue** microflow, create a new *Value* object and set that object as the return. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-new-values-microflow.png" alt="New Value microflow" class="no-border" >}} - -7. On the ShowChart page, add the widget **Area chart**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-select-chart.png" alt="Select widget" class="no-border" >}} - -8. The final page should look like this. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-widget-page.png" alt="Final widget Page" class="no-border" >}} - -## Configuring the Charts Widget - -To configure a Charts widget, follow these steps: - -1. Open the page with the Charts widget. - -2. Right-click the **Area chart** and select **Properties**. - -3. In the tab **Chart properties**, add a new **Series** property. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-series.png" alt="Chart Series" class="no-border" >}} - -4. In the tab **Data source**, select *Value* as the **Entity**. - -5. Set the **Data source** as **Database**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/chart-add-entity.png" alt="select Entity" class="no-border" >}} - -6. In the tab **Data points**, select *xValue* as the **X-axis data attribute** and *yValue* as the **Y-axis data attribute**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-data-points.png" alt="select Data Points" class="no-border" >}} - -## Viewing the Chart - -To view the chart, follow these steps: - -1. Run the app. - -2. In your browser, open the data entry page. - -3. Enter data values for **x value** and **y value**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-front-end.png" alt="Enter Data" class="no-border" >}} - -4. Click the **Save** button. - -5. Open the **ShowChart** page to view the chart created. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-area-chart.png" alt="Show Chart" class="no-border" >}} - -## Read More - -* [Use a Chart With a REST Data Source](/howto8/front-end/charts-basic-rest/) -* [Use Any Chart](/howto8/front-end/charts-any-usage/) -* [Use Charts Themes](/howto8/front-end/charts-theme/) diff --git a/content/en/docs/howto8/front-end/charts-tutorials/charts-basic-rest.md b/content/en/docs/howto8/front-end/charts-tutorials/charts-basic-rest.md deleted file mode 100644 index b43cc3859d8..00000000000 --- a/content/en/docs/howto8/front-end/charts-tutorials/charts-basic-rest.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "Use a Chart with a REST Data Source" -url: /howto8/front-end/charts-basic-rest/ -weight: 60 ---- - -## Introduction - -With the Charts widgets, you can use data from a REST Service to plot graphs. - -This how-to teaches you how to do the following: - -* Publish a REST API -* Use a REST endpoint as a data source for the Charts widget - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Create an app -* Import the latest [Charts Widgets](/appstore/widgets/charts/) from the Mendix Marketplace - -## Setting up Data to be Exposed by a REST Endpoint - -Mendix allows you to publish REST Web services natively from Studio Pro. Using these capabilities you can publish a REST service and use it in our Charts widget to plot graphs. - -To create an Area Chart with data from a REST service, follow these steps: - -{{% alert color="info" %}} - -For more information on publishing a REST API refer to this Mendix document: [Published REST Operation](/refguide8/published-rest-operation/) - -{{% /alert %}} - -1. Create a new module in your app. -1. Rename the module to *ChartsREST*. -1. Open the Domain model. -1. Create **Value** and **Series** entities with the attributes and association shown in the picture below. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-rest/charts-rest-domain.png" alt="Chart Rest Domain" class="no-border" >}} -1. Right-click **Value** and select **Generate overview pages...**. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-rest-generate-overview-pages.png" alt="Chart Rest Enter Data" class="no-border" >}} -1. Add the **Value_NewEdit** page generated to your navigation. -1. Run the app. -1. In your browser, open the NewEdit page. -1. Add values and series by entering data in the appropriate fields. - -## Publishing the Service - -To use data from a model in the REST service, you need to create a JSON structure. - -### Creating the Structure - -1. Create a **JSON Structure** - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-rest/chart-series-json-structure.png" alt="Charts Rest MD" class="no-border" >}} - -### Configuring the REST Service - -To configure the REST service, follow these steps: - -1. Add **Published REST service**. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-rest/charts-rest-publish.png" alt="Charts Rest Publish" class="no-border" >}} - -1. Add REST Service **Microflow**. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-rest/charts-rest-microflow.png" alt="Charts Rest Microflow" class="no-border" >}} - -1. Add **Export mapping**. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-rest/charts-rest-export-mapping.png" alt="Charts Rest Export Mapping" class="no-border" >}} - -## Using REST as a Data Source - -To use the REST Data source endpoint in your chart, follow these steps: - -1. Create a page in your app containing an **Area chart** widget. - -1. Double-click the **Area chart** widget. - -1. In the tab **Chart properties**, add a new chart **Series** property. - -1. Add **Series name** and **Entity**. - -1. Select **Data source** REST endpoint. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-rest/charts-rest-series.png" alt="Chart Rest Series" class="no-border" >}} - -1. Add the **REST URL**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-rest/charts-rest-url.png" alt="Chart Rest URL" class="no-border" >}} - -1. In the tab **Data points**, select the **X-axis data attribute** and the **Y-axis data attribute**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-data-points.png" alt="select Data Points" class="no-border" >}} - -1. Add Parameters to the REST Request. The **contextId**, **series name** are provided by default. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-rest/charts-rest-parameters.png" alt="select Data Points" class="no-border" >}} - -1. Run your app and view the chart. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-rest/charts-rest-area-chart.png" alt="Show Chart" class="no-border" >}} - -## Read More - -* [Use Chart Data Source REST](/howto8/front-end/charts-basic-create/) -* [Use Any Chart](/howto8/front-end/charts-any-usage/) -* [Use Theme Charts](/howto8/front-end/charts-theme/) diff --git a/content/en/docs/howto8/front-end/charts-tutorials/charts-dynamic-series.md b/content/en/docs/howto8/front-end/charts-tutorials/charts-dynamic-series.md deleted file mode 100644 index 11b7150318c..00000000000 --- a/content/en/docs/howto8/front-end/charts-tutorials/charts-dynamic-series.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "Create a Dynamic Series Chart" -url: /howto8/front-end/charts-dynamic-series/ -weight: 50 ---- - -## Introduction - -The charts widget provides a basic implementation of dynamic series. This allows you to vary the number of data series (for example lines on a line chart) in your chart at runtime, based on the data in your app. - -This how-to teaches you how to do the following: - -* Create a chart with dynamic series - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Download the latest [Charts Widget](/appstore/widgets/charts/) from the Mendix Marketplace - -## Setting up Chart Data - -### Setting up the Domain Model - -In order to create the Charts widget with dynamic series, a specific data structure is set up. - -1. Configure your domain model to contain an entity **Value** with attributes **xValue** and **yValue**. -1. Add another entity, **Series**, with attributes **name**, **color**, and **fillColor**. -1. Add an association **Value_Series** between the two entities. - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-dynamic-series/charts-dynamic-series-model.png" alt="Values entity" class="no-border" >}} - -### Entering Data for the Chart - -Now you need to enter data for the chart. - -1. Right-click the **Series** entity. -2. Choose **Generate overview pages...**. -3. Select both **Series** and **Value** as the entities for which to generate pages. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-dynamic-series/charts-dynamic-series-generate-pages.png" alt="Generate Series and Value overview and data entry pages" class="no-border" >}} - -4. Connect the **Series_Overview** page to the navigation. -5. **Run** the app (locally). -6. Enter some sample data. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-dynamic-series/charts-dynamic-series-data-entry.png" alt="Enter data for chart" class="no-border" >}} - -## Configuring the Charts Widget - -### Adding a Chart Page - -Now you need to create a page containing the chart. - -1. Create a new page. -2. Add a data view which uses a microflow to make a context which is the first object of the **Value**. -3. Add an **Area chart** widget inside the data view. - -### Configuring the Area Chart with Dynamic Series - -To configure a Charts widget with a dynamic series, follow these steps: - -1. Right-click the area chart widget and select **Properties**. -1. In the tab **Chart properties**, add a new **Series** property. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-basic-create/charts-series.png" alt="Chart Series" class="no-border" >}} - -1. In the tab **Data source**, select **Dynamic**. -1. Set the **Data entity** to *Value*. This is the entity from which the data values will be retrieved. -1. Set the **Data source** as **Database** (note that REST endpoints are not supported for dynamic series). - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-dynamic-series/charts-dynamic-series-select.png" alt="select Dynamic" class="no-border" >}} - -1. In the tab **Data Points**, set: - - * **X-axis data attribute** to *Value/xValue* - * **Y-axis data attribute** to *Value/yValue* - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-dynamic-series/charts-dynamic-series-data-points.png" alt="select Data Points" class="no-border" >}} - -1. In the tab **Dynamic series**, set: - - * **Series entity** to *Series* - * **Series name attribute** to *Series/name* - * **Line color attribute** to *Series/color* - * **Area color attribute** to *Series/fillcolor* - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-dynamic-series/charts-dynamic-series-attributes.png" alt="select Data Points" class="no-border" >}} - -1. Add the charts page to user navigation. - -## Viewing the Chart - -To view the chart, follow these steps: - -1. Run the app (locally). -1. Open the page containing the dynamic series chart. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-dynamic-series/charts-dynamic-series-chart.png" alt="Dynamic Series Chart" class="no-border" >}} - -## Read More - -* [Create a Basic Chart](/howto8/front-end/charts-basic-create/) -* [Fine_Tune a Chart with Advance Settings](/howto8/front-end/charts-advanced-tuning/) -* [Use Any Chart](/howto8/front-end/charts-any-usage/) diff --git a/content/en/docs/howto8/front-end/charts-tutorials/charts-plotly-images-rest.md b/content/en/docs/howto8/front-end/charts-tutorials/charts-plotly-images-rest.md deleted file mode 100644 index 10aa9110f46..00000000000 --- a/content/en/docs/howto8/front-end/charts-tutorials/charts-plotly-images-rest.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: "Use the Plotly Images REST Service Endpoint" -linktitle: "Plotly Images REST Endpoint" -url: /howto8/front-end/charts-plotly-images-rest/ -weight: 70 ---- - -## Introduction - -The [Plotly API images endpoint](https://api.plot.ly/v2/images) turns a plot into an image of the desired format. A set of body parameters and headers are passed to the endpoint, which returns an image when a request is made. - -This how-to teaches you how to do the following: - -* Call *Plotly API Images*' REST Endpoint - -* Save images returned from generated by the endpoint - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Create an account on **plot.ly**: you can sign up to plot.ly here: https://plot.ly/accounts/login/?action=signup#/ -* Retrieve the plotly API key which goes with your account; your API key can be found on the settings page when you are logged in to the site - -## Setting up the Domain Model - -To set up the domain model for use with the plotly REST service endpoint, follow these steps: - -1. Create two entities: **Image** and **DataSource**. - -1. **Image** should be a specialization of the **System.Image** entity, so set **Generalization** to *System.Image*. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-image-entity.png" alt="image entity" class="no-border" >}} -1. **DataSource** should be non-persistable with **Data** and **Layout** string attributes. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-data-source-entity.png" alt="DataSource entity" class="no-border" >}} - -## Calling the 'Plotly API Images' REST Endpoint - -To make a call to *Plotly API images* REST endpoint, follow these steps: - -1. Add a blank page to the existing module. - -1. Add a **Data view** with data source as a microflow that returns a new **DataSource** object. - -1. In the **Data view**, place input widgets with source attribute as **Data** and **Layout**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-data-view.png" alt="Data view" class="no-border" >}} - -1. In the footer of the *Data view*, add a **Call microflow button**. - -1. Link the button to a new microflow: *ACT_Call_REST*. - -1. Rename the button *Call Plotly REST Service*. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-button.png" alt="Configured microflow" class="no-border" >}} - -1. Right click the button, select to **Go to on click microflow...**. - -1. Build the microflow as shown below. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-microflow.png" alt="Configured microflow" class="no-border" >}} - -1. The **Call REST service** activity is configured as follows: - - * In the tab **General**, the **Location** should be set to *https://api.plot.ly/v2/images* - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-location.png" alt="Location" class="no-border" >}} - * Select the **HTTP Method** as *POST* - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-method.png" alt="HTTP Method" class="no-border" >}} - - * In the tab **HTTP Headers**, Enter your plotly user name and API key (more information on plotly authentication can be found here: https://api.plot.ly/v2/#authentication) - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-authorization.png" alt="Authorization" class="no-border" >}} - - {{% alert color="warning" %}}Custom HTTP headers 'Content-Type' and 'Plotly-Client-Platform' must be provided{{% /alert %}} - - * In the tab **Request**, select *Custom request template*; the request is a 'JSON' object with the structure - - ``` JSON - { - "figure": { - "data": [{"y": [10, 10, 2, 20]}], - "layout": {"width": 700} - }, - "format": "png", - "encoded": false - } - ``` - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-request.png" alt="Request tab" class="no-border" >}} - - For more request parameter details, see the documentation here: [Plotly REST API, v2](https://api.plot.ly/v2/images#fields). - - {{% alert color="warning" %}}When `encoded` is set to `true`, a base64 image url is returned.

In the field **Template**, escape the opening brace, `{`, by using a double opening brace, `{``{`.{{% /alert %}} - - * In the tab **Response**, set **Response handling** to *Store in a file document* - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-response.png" alt="Response tab" class="no-border" >}} - - * Set **Output > Type** to the **Image** entity - -## Saving the Image - -To save images generated by the REST service, follow these steps: - -1. Add a **Show page** activity to the *ACT_Call_REST* microflow. - -1. Select a new page. - -1. Set the generated image object as the **Object to pass** to the page. - -1. Set the layout of the page as a popup. - -1. Place a **Data view** in the page and populate it as shown below: - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-display-image.png" alt="Display image page" class="no-border" >}} - -1. Run the app. - -1. In the browser, open the page with the **Call Plotly REST Service** button. - -1. Fill in the **Data** and **Layout** fields. An example is shown in the image below. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-fill-data.png" alt="Fill in data" class="no-border" >}} - -1. Click the **Call Plotly REST Service** button. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-plotly-images-rest/charts-call-rest-image-save.png" alt="Save image" class="no-border" >}} - -1. Click the **Save** button to save the image which is displayed. - -## Read More - -* [Plotly images endpoint](https://api.plot.ly/v2/images) -* [Call a REST Service Action](/refguide8/call-rest-action/) diff --git a/content/en/docs/howto8/front-end/charts-tutorials/charts-theme.md b/content/en/docs/howto8/front-end/charts-tutorials/charts-theme.md deleted file mode 100644 index 2dd2141090c..00000000000 --- a/content/en/docs/howto8/front-end/charts-tutorials/charts-theme.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: "Use the Charts Theme" -url: /howto8/front-end/charts-theme/ -weight: 40 -description: "How to set up a theme which will be applied to all the charts created with charts widgets in an app" ---- - -## Introduction - -The look of individual **Charts** widgets can be fine tuned with advanced settings. A theme allows developers to create global settings that apply to all charts. In this way color, language, font and many more things can be set for all the charts in an app. - -This how-to teaches you how to do the following: - -* Change the font style for all charts -* Add a theme configuration - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Download the latest [Chart Widget](/appstore/widgets/charts/) from the Mendix Marketplace -* Set up a chart: see [How to create a charts](/howto8/front-end/charts-basic-create/) - -## Creating a Chart Theme - -This is how the original chart looks: - -{{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-toggle-editor.png" alt="chart" class="no-border" >}} - -### Creating an Advanced Custom Configuration - -To create the required custom configuration easily, follow these steps: - -1. Open the app with the chart(s). -1. Open a page with a chart. -1. Open the chart widget settings. -1. Go to the tab **Advanced**. -1. Set the **Mode** to **Developer**. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-widget-properties-advanced.png" alt="chart widget properties" class="no-border" >}} - -1. Run the app. -1. Open the page with the chart in the browser. -1. Click the **Toggle Editor** button. -1. In the **Layout** section add the **Custom settings**. - - ```json - { - "font": { - "family": "Open Sans", - "size": 14, - "color": "#555" - } - } - ``` - -1. Change the font settings, till the chart shows the required font. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-advanced-tuning/charts-toggle-editor-open.png" alt="chart editor" class="no-border" >}} - - {{% alert color="warning" %}}Please note that the editor changes will not persist. They need to be stored in the advanced settings of the widget or stored in the theme.{{% /alert %}} - -1. In Studio Pro, set **Mode** in the chart widget to **Advanced**, to remove the Toggle Editor button. - - {{% alert color="warning" %}}Please note that the theme settings only apply to charts in Advanced or Developer mode.{{% /alert %}} - -### Adding a Theme Configuration - -To add a theme file which will apply to all charts in the app, follow these steps: - -1. From Studio Pro, go to the menu **Project > Show Project Directory in Explorer**. -1. Open the **theme** folder. -1. Create a new file: *com.mendix.charts.json* - - {{% alert color="info" %}}Please note that
- * the file name is case sensitive
- * the file extension is `json`
- * the file must contain a *json* object, even if this is empty — for example `{ }` - {{% /alert %}} - -### Changing the Font Globally - -To change the font in all charts in the app, follow these steps: - -1. Edit the *[project folder]/theme/com.mendix.charts.json* file in a plain text editor. -1. Replace or update the content. In the **layout** section, place the style changes that were created in the first section of this how to. - - ```json - { - "layout": { - "font": { - "family": "Impact", - "size": 20, - "color": "#4682B4" - } - } - } - ``` - -1. Restart the Mendix app. -1. Validate the expected result. - - {{< figure src="/attachments/howto8/front-end/charts-tutorials/charts-theme/charts-toggle-editor-changed.png" alt="chart updated" class="no-border" >}} - -## Read More - -* [Charts](/refguide8/chart-widgets/) -* [Layout samples](/refguide8/charts-advanced-cheat-sheet/#layout-all) -* [Configuration samples](/refguide8/charts-advanced-cheat-sheet/#config-options) diff --git a/content/en/docs/howto8/front-end/configuring-your-theme.md b/content/en/docs/howto8/front-end/configuring-your-theme.md deleted file mode 100644 index dc7fb427416..00000000000 --- a/content/en/docs/howto8/front-end/configuring-your-theme.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "Configure Your Theme" -url: /howto8/front-end/configuring-your-theme/ -weight: 15 -aliases: - - /howto8/ux/configuring-your-theme.html - - /howto8/ux/configuring-your-theme -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -This document describes how to configure the styling of your page in Studio Pro. - -## Configuring Your Theme - -The styling that is loaded when opening your Mendix application in a web browser is configured in the HTML of your index pages. - -To ensure that the same styling is loaded when viewing your page in Studio Pro, you can configure the `"cssFiles"` property in *settings.json* in the theme folder of your app. For example, in this configuration, `styles/web/css/main.css` is loaded when viewing a page in Studio Pro: - -```json -{ - "cssFiles": [ "styles/web/css/main.css" ] -} -``` - -To avoid having to maintain the styling that is loaded in the client and Studio Pro separately, you can use the following token in your index pages to load the same styling in the client: `{{themecss}}`. - -```html - - {{themecss}} - -``` diff --git a/content/en/docs/howto8/front-end/create-your-first-two-overview-and-detail-pages.md b/content/en/docs/howto8/front-end/create-your-first-two-overview-and-detail-pages.md deleted file mode 100644 index 6855ac0e555..00000000000 --- a/content/en/docs/howto8/front-end/create-your-first-two-overview-and-detail-pages.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "Create Your First Two Overview and Detail Pages" -linktitle: "Create Overview and Detail Pages" -url: /howto8/front-end/create-your-first-two-overview-and-detail-pages/ -weight: 25 ---- - -## Introduction - -This how-to explains how you can create overview and detail pages in Mendix. - -This how-to teaches you how to do the following: - -* Create overview and detail pages -* Configure navigation and security - -## Prerequisites - -Before starting with this how-to, make sure you have completed the following prerequisite: - -* Set up a basic data structure by reading [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/): - - {{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18582175.png" class="no-border" >}} - -## Creating Overview and Detail Pages Automatically - -To create the overview and detail pages for your data structure, follow these steps: - -1. In the domain model, right-click the **Customer** entity and select **Generate overview pages**. -2. Select both entities in the **Generate pages** dialog box. -3. Click **OK**. - -And there you go! For each entity, an overview page and a detail page is generated. Also, an **Entity_Menu** snippet is created and added to each overview page. - -{{% alert color="info" %}} -Mendix can do even more of the work for you if you create an Excel spreadsheet with two tabs (one for the header and data for **Customer** and the other for the header and data for **Order**). When you are creating a new app, select **App from a spreadsheet** and upload your Excel spreadsheet. -{{% /alert %}} - -## Creating Overview and Detail Pages Manually - -For a better understanding of Mendix Studio Pro, this section describes the manual steps for creating these pages. - -### Creating the Overview Page - -To create a new overview page and add it to your app, follow these steps: - -1. Right-click the module and select **Add** > **Page**. -2. Click **Responsive**. -3. Enter *CustomerOverview* in **Page name**. -4. Select *Sidebar_Full_Responsive* as the navigation layout. -5. Click **Blank**, then select the **Blank** page template**and click**OK**: - - {{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18581337.png" class="no-border" >}} - -6. Click **Data Grid** in the menu bar of the page builder to select the data grid widget: - - {{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18581335.png" class="no-border" >}} - -7. Click inside the page editor to create the data grid widget: - - {{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18581334.png" class="no-border" >}} - -8. Right-click the data grid and select **Select Entity**. -9. Select the **Customer** entity in the **Select Data Source** pop-up window and click **Select**: - - {{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18581345.png" class="no-border" >}} - -10. Click **OK** to auto-fill the data grid with search fields and columns: - - {{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18581343.png" class="no-border" >}} - -You should now have an overview page with a data grid like this: - -{{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18581330.png" class="no-border" >}} - -### Creating the Detail Page - -To create a new detail page manually, follow these steps: - -1. Right-click **New** on the data grid on the overview page and select **Generate page**. -2. Select **PopupLayout** as the **Navigation layout**. -3. Select **Form horizontal** and then click **OK**: - - {{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18581327.png" class="no-border" >}} - -4. Right-click **New** on the data grid on the overview page again and select **Go to page**: - - {{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18581326.png" class="no-border" >}} - - You should now have a detail page like this: - - {{< figure src="/attachments/howto8/front-end/create-your-first-two-overview-and-detail-pages/18581325.png" class="no-border" >}} - -## Navigation and Security - -Now create a navigation item for your overview page to start using it. For details on how to set up the navigation structure, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/). - -If you switched on security for this application, you also need to configure page access on both the overview and detail pages. For more information, see [How to Create a Secure App](/howto8/security/create-a-secure-app/). - -## Read More - -* [Atlas UI](/howto8/front-end/atlas-ui/) -* [Use Layouts and Snippets](/howto8/front-end/layouts-and-snippets/) -* [Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/) -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Page](/refguide8/page/) diff --git a/content/en/docs/howto8/front-end/custom-error-page.md b/content/en/docs/howto8/front-end/custom-error-page.md deleted file mode 100644 index dc2f61655b8..00000000000 --- a/content/en/docs/howto8/front-end/custom-error-page.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Create Custom Error Pages" -url: /howto8/front-end/custom-error-page/ -weight: 55 ---- - -## Introduction - -Whenever your application is stopped, you are presented with the infamous green monsters. To present your app users with a more professional looking page when the application is down, Mendix enables the creation of custom error pages on *Mendix Cloud*. - -You can create an `offline.html` page, a `404.html` page, and a `403.html` page. - -The different files serve different purposes: - -* `offline.html`: will be served when your application has been stopped manually -* `404.html`: will be served whenever a path does not exist -* `403.html`: will be served when access to a resource is denied, because an IP filter has been implemented or because of client certificate restrictions. - -If you do not create these files, the default "green monsters" will be used instead for each scenario. - -{{< figure src="/attachments/howto8/front-end/custom-error-page/monsters.png" class="no-border" >}} - -This how-to teaches you how to do the following: - -* Create a custom error page - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Have a local repository of the app -* Have your app *hosted in Mendix Cloud* - -## Create a Custom Error Page - -1. Open the local folder of your app. -2. Go to **theme**: - - {{< figure src="/attachments/howto8/front-end/custom-error-page/theme.png" class="no-border" >}} - -3. Create a new folder named *error_page*: - - {{< figure src="/attachments/howto8/front-end/custom-error-page/error-page.png" class="no-border" >}} - -4. In the **error_page** folder, place your *offline.html* file: - - {{< figure src="/attachments/howto8/front-end/custom-error-page/offline.png" class="no-border" >}} - - Optionally, you can also create *404.html* and *403.html* pages. - - {{% alert color="info" %}}In these *.html* files, you can only refer to external resources or resources under the absolute path `/error_page/`; the `/error_page/` path is the only one that will be available when the application is stopped.{{% /alert %}} - -5. Commit the changes in Studio Pro. - -{{% alert color="warning" %}} -It might take up to an hour to before the custom error page is visible when the app is offline. -{{% /alert %}} - -### Example Offline Page - -An example `offline.html/404.html/403.html` page could look like this: - -```html - - - - - - - - This application is currently offline. - - -``` - -This example refers to *style.css* and *script.js*, which you should also create and place in the **error_page** directory if you want to have special styling and/or JavaScript. diff --git a/content/en/docs/howto8/front-end/customize-styling/_index.md b/content/en/docs/howto8/front-end/customize-styling/_index.md deleted file mode 100644 index 37095c46a7f..00000000000 --- a/content/en/docs/howto8/front-end/customize-styling/_index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Customize Your Styling" -url: /howto8/front-end/customize-styling/ -weight: 9 -description: "These how-tos will guide you in styling your Mendix apps." ---- - -The following how-tos are available here: - -* [Customize Your Styling Using Calypso](/howto8/front-end/calypso/) -* [Customize Your Styling Using Gulp](/howto8/front-end/use-gulp-and-sass/) diff --git a/content/en/docs/howto8/front-end/customize-styling/calypso.md b/content/en/docs/howto8/front-end/customize-styling/calypso.md deleted file mode 100644 index b91e8ae6cdb..00000000000 --- a/content/en/docs/howto8/front-end/customize-styling/calypso.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "Customize Styling Using Calypso" -url: /howto8/front-end/calypso/ -weight: 10 -description: "This document teaches you how to use Calypso, a tool which improves the way you edit styling." ---- - -## Introduction - -Calypso is a tool which makes it easier for you to customize your Mendix apps' styling. Designers and front-end specialists, Mac users and Windows users — everyone can easily use this tool without installing any external dependencies. Everything is packaged inside Calypso. You simply need to install Calypso, choose your Mendix app, and start customizing. As you customize, Calypso eases your work by doing the following: - -* Checks *SCSS* files for errors -* Compiles *SCSS* files to *CSS* -* Shows notifications on errors -* Moves compiled files to your deployment folder -* Injects the compiled *CSS* files into your browser so you can preview changes instantly - -Calypso is the easiest styling solution for most users. However, if you already use a Gulp service worker in your development workflow please consult [How to Set Up Gulp and Sass](/howto8/front-end/sass-eight/) for a styling solution which might suit you better. - -For a deep-dive look into styling with Calypso, check out this video: - -{{< vidyard id="M2NCccTnfnh7Yx2gjEyBpf" >}} - -## Prerequisites - -* Download Calypso [here](https://github.com/mendix/Atlas-UI-Framework/releases/download/calypso-v1/Calypso.Setup.1.0.0.exe) - -## Setting Up Calypso - -1. Install Calypso. -2. Open Calypso: - - {{< figure src="/attachments/howto8/front-end/customize-styling/calypso/calypso.png" alt="calypso" class="no-border" >}} - -3. In the **Hostname** drop-down menu, select the host name of your Mendix app's device (or put its IP address in manually by clicking **Other** and typing in the IP address). - - Most Windows users should select **localhost**. If you are running Windows through a virtual machine, use your virtual machine's IP address as the **Hostname** or you can forward your port from your host machine to your virtual machine. Alternatively you can install Calypso on a virtual machine and choose **localhost**. - -4. If this is your first time using Calypso, you may have to tell your Windows firewall to **Allow access** to use Calypso. -5. Configure your **Port**. - - A Mendix app normally runs on port 8080. However, if you are running multiple Mendix apps, or changed your port configuration, your port number may be different. Find your port information by navigating to **Project {'YourProjectName'}** > **Settings** in your **Project Explorer**, read your port number in **Application root URL** ({host name:port number}), then type that number into Calypso's **Port** field. - -6. In **Apps Collection**, click the **Browse** button and then select the folder which contains all your Mendix apps. Configuring this enables you to switch easily between apps. -7. Complete **App Folder** by selecting the folder of the Mendix app you want to work on from the drop-down menu. -8. Complete **Watching** to specify which files you want to be processed by Calypso. - - Most users will only need to select the **Watching** > **theme/styles** option. However, when you are building custom error pages or are using JavaScript on your pages, you may wish to select the other two folders as well. - - {{< figure src="/attachments/howto8/front-end/customize-styling/calypso/calypso-watching.png" alt="files to watch" class="no-border" >}} - -9. Click the sun in the upper-right corner to toggle between dark mode and regular mode: - - {{< figure src="/attachments/howto8/front-end/customize-styling/calypso/dark-mode.png" alt="dark mode" class="no-border" >}} - -10. Click **Run Locally** in Mendix Studio Pro to use Calypso. - -11. Click the **Start** button in Calypso. This will start a browser page which will let you view your running app. The browser address will match the address in Calypso's **Console**: - - Browser address: - - {{< figure src="/attachments/howto8/front-end/customize-styling/calypso/browser-address.png" alt="browser address" class="no-border" >}} - - Calypso's **Console**: - - {{< figure src="/attachments/howto8/front-end/customize-styling/calypso/console.png" alt="console" class="no-border" >}} - -## Testing Calypso - -With your Mendix app and Calypso running, complete the steps below to see how Calypso works: - -1. Add a button widget to your app's **Home_Responsive** page: - - {{< figure src="/attachments/howto8/front-end/customize-styling/calypso/drop-a-button.png" alt="drop a button" class="no-border" >}} - -2. Run your app again by clicking **Run Locally** to see your new button in your browser: - - {{< figure src="/attachments/howto8/front-end/customize-styling/calypso/blue-button.png" alt="blue text button" class="no-border" >}} - -3. Click **Project** > **Show Project Directory in Explorer**. -4. Open `theme\styles\web\sass\app\_custom-variables.scss` . -5. Change `$brand-primary: #0595DB;` to `$brand-primary: brown`, then save your changes. -6. Look at your app in your browser again. The button's text has switched from blue to brown. - - {{< figure src="/attachments/howto8/front-end/customize-styling/calypso/brown-button.png" alt="brown text button" class="no-border" >}} - -Good job! You've installed Calypso and used it to customize your styling quickly and easily. - -## Read More - -* [Get Started with Atlas UI](/howto8/front-end/get-started-with-atlasui/) -* [Migrate Existing Apps to Atlas UI](/howto8/front-end/migrate-existing-projects-to-atlasui/) -* [How to Set Up Gulp and Sass](/howto8/front-end/sass-eight/) diff --git a/content/en/docs/howto8/front-end/customize-styling/use-gulp-and-sass/_index.md b/content/en/docs/howto8/front-end/customize-styling/use-gulp-and-sass/_index.md deleted file mode 100644 index 9d921af1df6..00000000000 --- a/content/en/docs/howto8/front-end/customize-styling/use-gulp-and-sass/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Customize Styling Using Gulp" -url: /howto8/front-end/use-gulp-and-sass/ -weight: 30 ---- - -{{% alert color="info" %}} -Mendix recommends the Calypso GUI styling tool for most users. For more information, see [Customize Your Styling Using Calypso](/howto8/front-end/calypso/). -{{% /alert %}} - -To use Gulp and Sass in your Mendix app, start with [How to Set Up Gulp and Sass](/howto8/front-end/sass-eight/). - -For more details, move to [How to Start Styling with Gulp and Sass](/howto8/front-end/style-with-gulp-and-sass/). diff --git a/content/en/docs/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight.md b/content/en/docs/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight.md deleted file mode 100644 index b03cd292311..00000000000 --- a/content/en/docs/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: "Set Up Gulp and Sass" -url: /howto8/front-end/sass-eight/ -weight: 1 -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -{{% alert color="info" %}} -Styling in a Mendix app is easy to do once you get the hang of it. For the majority of styling needs, you can use Mendix's styling tool: Calypso. For more information, see [How to Use Calypso](/howto8/front-end/calypso/). -{{% /alert %}} - -However, using Gulp and Sass can be better for certain users. If you already use a Gulp service worker in your development workflow, you may wish to style you Mendix app using Gulp and Sass instead of Calypso. - -This how-to teaches you how to do the following: - -* Prepare your app -* Set up your Sass files -* Work with Sass - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -1. Install [Visual Studio Code (VSC)](https://code.visualstudio.com/). -2. On the [Gulp for Mendix theming](https://github.com/mendix/ux-theming) GitHub project, click **Releases**: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/releases.png" class="no-border" >}} - -3. Download the **Gulp.zip** file: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/gulp.png" class="no-border" >}} - -4. Install Node.js for task-running and automation through gulp. Install the latest LTS version from [Node.js](https://nodejs.org/en/): - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/node.png" class="no-border" >}} - -5. Install version **1.7.15** of [TortoiseSVN](https://osdn.net/projects/tortoisesvn/storage/Archive/1.7.15/Application/). - -## Preparing Your App - -To prepare your app, follow these steps: - -1. Open the app directory (via **Project** > **Show Project Directory in Explorer** in Studio Pro). -2. Unpack the *Gulp.zip* file into your main app folder. You will then see a *Gulpfile* and *package* file that look like this: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/unpack.png" class="no-border" >}} - - After you have unpacked the *Gulp.zip* into your app folder, you can remove the *zip* file. -3. Open **Windows PowerShell** as an administrator: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/powershell.png" class="no-border" >}} - -4. Copy the address as text from your main project folder and paste it into Powershell (your project folder cannot contain spaces and should not be too long): - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/copy.png" class="no-border" >}} - -5. Provide the directory for your app folder in PowerShell: `cd ‘directory for your app folder’` -6. Adjust permissions by writing `Set-ExecutionPolicy -ExecutionPolicy ByPass -Scope CurrentUser` then pressing Enter . -7. Write `npm install` or use `npm install gulp-cli -g` with your app running locally on Studio Pro: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/write-install.png" class="no-border" >}} - - If you use `npm install`, you may receive an error. PowerShell will tell you to use `npm run dev` instead. If that does not work, use `npm install run`. - - {{% alert color="info" %}}You should do this for each new app! That way, you will not have to repeat the installation step whenever you reopen the app and Powershell.{{% /alert %}} - -8. Write `npm run dev`. Your screen should then look like this: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/gulp-dev.png" class="no-border" >}} - - At this point, you are ready to start working with Sass. - -9. You also need to add the following selected items into the ignore list of TortoiseSVN for each new app. If you do not, your app will take too long to commit a change. You will only have to do this *once* when you set it up for your project: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/selected-ignore.png" class="no-border" >}} - - To do that, right-click each item and select **TortoiseSVN** > **Add to ignore list**: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/add-ignore.png" class="no-border" >}} - - You will receive a confirmation when the items have been added to the ignore list. You can also double-check via TortoiseSVN: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/check-ignore.png" class="no-border" >}} - - If you need to remove an item from the ignore list, right-click it and select **TortoiseSVN** > **Remove from ignore list**. - -10. Open your app in Studio Pro, then click **Run Locally** and **View**. - -## Setting Up Your Sass Files - -Final steps! Read below to open and work with Sass: - -1. Open the main app folder and go to **theme** \> **styles** \> **sass** \> **custom**. -2. Double-click either the *custom.scss* or *_custom-variables.scss* file, which will open in VSC: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/custom-variables.png" class="no-border" >}} - - If you open the *custom* file, you will see the following screen: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/import.png" class="no-border" >}} - -3. Click **Open Folder** in the **EXPLORER** and then select the **sass** folder: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/sass-folder.png" class="no-border" >}} - -4. Remove the **Welcome**, since you will not need this: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/welcome.png" class="no-border" >}} - -### Keeping Your Sass in the Custom Folder - -It is important to keep in mind that you are only working in the **custom** folder. You will not make any changes in the **lib** folder, but you can use that as a reference. You will only use the contents of the *_variables.scss* file to get the variables you need and copy them in your *_custom-variables.scss* file. The variables can differ from the default font sizes, colors, background colors, heights, and so on. In the *_custom-variables.scss* file, you can also make your own variables, for example `$brand-blue: #48B0F7;`. - -You can now work on the Sass structure and organize everything neatly by creating sub-folders and files in the **custom** folder. You can also look in the **lib** folder to get an idea of which folders and files you will most likely use in your app. - -When you create a new Sass file, follow this naming guideline: *\_{namefilehere}.scss*. For example: - -{{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/name-example.png" class="no-border" >}} - -### Importing New Sub-Folders and Files - -Before you can see any changes in your app with your new Sass, you need to import the folders and files first. If you open *custom.scss*, you will see this: - -`@import "custom-variables";` - -To import all the sub-folders and files you have created, write this: - -```scss -@import "custom-variables"; -// base -@import "base/login"; -``` - -After you import everything, you are finally ready to Sass! - -## Working with Sass - -Here is an example of custom Sass: - -```scss -.pageheader-title { - color: red; -} - -.pageheader-subtitle { - color: green; -} -``` - -To implement this in your app, open the project in Mendix Studio Pro. You can find the defined class names in almost every element (for example, titles and subtitles). In this example, double-click the title **Event App** in Studio Pro, and you can see that the name has the standard class name for Studio Pro. - -{{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/sass-eight/class-name.png" class="no-border" >}} - -You can remove **spacing-outer-bottom-medium**, as that is a variable that contains defined styling code. If you do not remove this, you will probably have trouble later in the app if you, for example, want to position your title somewhere else. - -{{% alert color="info" %}} -The inline styling is used in this example. That is because the inline styling will always overrule your code in VSC. -{{% /alert %}} - -### Seeing Your Changes - -When you add, remove, or change something in Studio Pro, you need to save your changes and run the app locally to see your styling changes in the browser. - -For example, when you set a color for your title and subtitle, click **Run Locally** then **View**. When browser automatically opens, you will see the following URL: - -`http://localhost:8080/index.html?profile=Responsive` - -You then need to replace the `8080` with `3000` in order to sync the browser with your VSC changes. That means the URL should be this: - -`http://localhost:3000/index.html?profile=Responsive` - -{{% alert color="info" %}} -If you use a Mac laptop, you can open this URL: `http://windows-10:3000`. -{{% /alert %}} - -You can test this by changing the color of `.pageheader-subtitle` from green to blue in the example above. If you have correctly synced with the browser, you can already see that the subtitle color changes into blue. - -## Summary - -Practice the routine above a few times and you will master it in no time. In addition, keep the following summary in mind: - -* Make sure Powershell is working properly, or else your code will not be registered Studio Pro -* Use the following to install gulp for each new project: - * `npm install` - * `npm install gulp-cli -g` - * If the commands above do not work, you can also use `npm run dev`, though keep in mind you are not installing the gulp -* Make sure the app is running locally in Studio Pro (you will not be able to see your changes if the app is not running) -* If you change or add something in Studio Pro, save it and run the app again -* Make sure you are working in the right folder (which in VSC is always **sass** > **custom**; you should not work in **lib**) -* Do not make use of inline styling via Studio Pro -* Be sure to change the portal of `localhost:8080` into `localhost:3000` -* Add the following items to the TortoiseSVN ignore list: - * *node_modules* - * *Gulpfile* - * *package* - -Have fun styling! - -## Troubleshooting - -You may encounter certain issues when styling your app using Gulp and Sass. Here are some common problems, and the steps you can take to fix them: - -### Theme Folder Issues - -When using UX-theming in Mendix 8, some issues might occur with an infinite loop or folders not being recognized. - -This is probably because your theme folder has changes. The Mendix 8 theme structure uses distinct folders for **web** and **native** styling files. Make sure you set the following folders correctly in your Gulpfile: - -```js -// What is the name of the style folder in this theme folder? -var sourceStyleFolder = 'theme/styles/web'; - -// What is the name of the style folder in the deployment folder? -var deploymentStyleFolder = 'styles/web'; -``` - -### Apache Subversion Issues - -Other issues might occur with SVN and possible rewriting of *Gulpfile.js*. To fix these issues, try the following solutions: - -* Remove *node_modules*, *package.json*, *package-lock.json* and *Gulpfile.js*, then replace them with a fresh copy downloaded from Mendix's [ux-theming repository](https://github.com/mendix/ux-theming/) -* Ignore not only *node_modules* but also *Gulpfile.js* — this means you will have to add the *Gulpfile* to the project if you download it again or someone in your team is working on it -* Make sure you are using the most recent LTS version of [Node.js](https://nodejs.org/en/) - -## Read More - -* [How to Start Styling with Gulp and Sass](/howto8/front-end/style-with-gulp-and-sass/) -* [How to Use Calypso](/howto8/front-end/calypso/) diff --git a/content/en/docs/howto8/front-end/customize-styling/use-gulp-and-sass/style-with-gulp-and-sass.md b/content/en/docs/howto8/front-end/customize-styling/use-gulp-and-sass/style-with-gulp-and-sass.md deleted file mode 100644 index 6c448e59d8c..00000000000 --- a/content/en/docs/howto8/front-end/customize-styling/use-gulp-and-sass/style-with-gulp-and-sass.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "Start Styling with Gulp and Sass" -url: /howto8/front-end/style-with-gulp-and-sass/ -weight: 2 ---- - -## Introduction - -{{% alert color="info" %}} -This how-to is based on the blog post [How Do I Start Styling In Mendix (Gulp & Sass)](https://medium.com/@jasonteunissen/how-do-i-start-styling-in-mendix-gulp-sass-6b37ddaf8de6) by Jason Teunissen, UX Consultant at [Appronto](https://developer.mendixcloud.com/link/partnerprofile/8870). -{{% /alert %}} - -{{% alert color="info" %}} -For the majority of styling needs, you can use Mendix's styling tool: Calypso. For more information, see [How to Use Calypso](/howto8/front-end/calypso/). However, certain users who prefer Gulp may find this document useful. -{{% /alert %}} - -You can use [Gulp](https://gulpjs.com/) to watch the files for any changes you make when styling with Sass. Gulp triggers auto-refresh by default so that your changes are immediately visible in the browser. - -This how-to teaches you how to do the following: - -* Set up the Gulp project -* Run Gulp - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Complete [How to Set Up Gulp and Sass](/howto8/front-end/sass-eight/) - -## Setting Up the Gulp Project - -To set up the Gulp project, follow these steps: - -1. Download *gulp.zip* from [mendix/ux-theming](https://github.com/mendix/ux-theming/releases). -2. Unzip the folder into your project's root folder. -3. In your terminal, go to your project root folder by typing `cd`, then drag your root file into the terminal. Please note that if you do this on Windows and you encounter errors with installing the dependencies, open your CMD or PowerShell as Administrator. -4. Install the dependencies by typing `npm install`: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/style-with-gulp-and-sass/cd.png" class="no-border" >}} - -## Running Gulp - -To run Gulp, follow these steps: - -1. You should still be in your root if you just finished the installation, so type `npm run dev` in your root. -2. Make sure your Mendix project is running. -3. For a quick test to see if everything is working, open *theme/styles/sass/custom/_custom-variables.scss* and type `body{ background-color: red; }`. Your background will then be a beautiful red: - - {{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/style-with-gulp-and-sass/red.png" class="no-border" >}} - -{{% alert color="info" %}} -If you are using Parallels on Mac, you can access your Mendix project on your Mac browser by going to your Parallels machine (for example, `http://10.211.55.3:30001` — this is different on each setup). -{{% /alert %}} - -And that's it! Now you are ready to start styling your Mendix app with Sass. - -## Development and Production - -When running `npm run dev`, Sass will compile the CSS files unminified and with source-mapping. This helps in debugging the styling, as a modern browser will point to the *.scss* file where a rule is specified. - -When using this in production, you should run `npm run build` before committing and deploying. This will disable source-mapping and will minify the CSS files to minimize the file size. - -## Mendix Portal Apps - -When you use this setup in a collaborative app, please note that you will need to add the **node_modules** folder to the **SVN ignore**. This folder is generated by running `npm install` (as described in the [Installing Gulp](#34)) section) and contains too many files. It is important not to forget this step! - -If you have [TortoiseSVN](/refguide8/using-version-control-in-studio-pro/#tortoisesvn-subclipse) installed, right-click the **node_modules** folder and select **TortoiseSVN** > **Add to ignore list**: - -{{< figure src="/attachments/howto8/front-end/customize-styling/use-gulp-and-sass/style-with-gulp-and-sass/svn-ignore.jpg" class="no-border" >}} - -{{% alert color="warning" %}} -Always use the version of TortoiseSVN which matches your app model. If you open a local model from Mendix 7.x with the latest version of TortoiseSVN, **you will no longer be able to open it in Mendix**. -{{% /alert %}} - -## Troubleshooting - -If you encounter issues using this setup, please read the [Troubleshooting](https://github.com/mendix/ux-theming#troubleshooting) section in the GitHub repo documentation. If this does not resolve your issue, please [create a new GitHub issue](https://github.com/mendix/ux-theming/issues/). - -## Read More - -* [How Do I Start Styling In Mendix (Gulp & Sass)](https://medium.com/@jasonteunissen/how-do-i-start-styling-in-mendix-gulp-sass-6b37ddaf8de6) -* [mendix / ux-theming](https://github.com/mendix/ux-theming) diff --git a/content/en/docs/howto8/front-end/layouts-and-snippets.md b/content/en/docs/howto8/front-end/layouts-and-snippets.md deleted file mode 100644 index 24d2983aa9d..00000000000 --- a/content/en/docs/howto8/front-end/layouts-and-snippets.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: "Use Layouts and Snippets" -url: /howto8/front-end/layouts-and-snippets/ -weight: 30 ---- - -## Introduction - -This document will cover the basics of how to create pages using layouts and snippets. - -This how-to teaches you how to do the following: - -* Create style layouts -* Create snippets - -## Layouts - -This section describes what a layout consists of and what its value is. - -### Page Components - -When you look at a page, you can see that a page consists of two important components: - -* Layout — the structure of the page (just like PowerPoint has one or more layout presets) -* Content — what is displayed within the structure of the page - -While modeling the pages, you select a layout when a page is created. - -### The Value of Layouts - -Layouts are used to structure the user interface. They allow us to define a default page structure, which can be reused as a template for pages. With this structure, you can design the way the application is presented to the end-user. The best practice is to predefine the UI structure before you start modeling the app. There was a blank layout, although this is a basic setup for layouts and there are some predefined layout structures available. - -These are some available predefined layout structures: - -* DesktopLayout - * For presenting a header with a logo and menu bar - * Content placeholder used - * A footer with text used -* PopupLayout - * Contains only a content placeholder - -Most users start by creating an application interface for the desktop user, but it's easy to unlock the app for mobile and tablet users. For each device, you can create a set of layouts that fit the specific layout needs for the device. When device-specific layouts have been created, they can be used as templates for creating device-specific pages: - -{{< figure src="/attachments/howto8/front-end/layouts-and-snippets/layout-compare.png" class="no-border" >}} - -## Styling - -In addition to layouts, the application should have a certain look and feel, such as a color scheme matching the customer brand. This is accomplished with CSS/Bootstrap and with a set of predefined classes that are connected to the Mendix page elements through the CSS file. This part of the application design allows for a lot of flexibility, though it is an advanced process and requires specific CSS and HTML knowledge. For the current scope of this how-to, you will use the default styling. - -### Creating a New Layout - -As already mentioned, a set of predefined layouts is available that fits basic needs encountered while developing a basic app. However, when you want a more sophisticated app, a more advanced setup of layouts may be needed. The following sections will explain the basics of creating a new layout. - -### Layout Widgets - -In this section, the main elements used for the creation of a new layout are discussed. Thereafter, basic design approaches will be discussed. - -#### Layout Container - -A layout container is used to divide the layout into regions such as the header, sidebar, and footer. A layout container must be the only top-level widget. In addition, a layout container can only be placed directly in another layout container. - -#### Regions - -With regions, you divide the layout container into sections in order to position the layout elements in specific fixed positions. Each region contains either a placeholder or a specific widget. - -#### Placeholders - -A placeholder can be used in a layout to define an area that can be filled in in a page based on that layout or in another layout defining that layout as the primary layout. - -{{< figure src="/attachments/howto8/front-end/layouts-and-snippets/placeholders.png" class="no-border" >}} - -When the area is filled in a page, this will be the content area of that page, showing the dynamic data as specified in that page. When a layout inherits from another layout, the area can filled with a new layout container in order to define this specialized layout. It can also be kept empty, and then it will be filled in a page. - -#### Inheritance - -A layout can also be based on another layout, which is called the "primary layout" in this context. If a layout is based on a primary layout, the layout can fill the areas defined by the primary layout and define new area using placeholders. Pages that use a layout based on a primary layout will only see the areas defined by the layout, not those of the primary layout. - -## Desktop, Tablet, or Mobile? - -All pages can be opened on all device types, because the generated HTML for the pages is HTML5. However, each device has its own specific UI design needs. Therefore, it is logical for you to define a set of layouts per device type that serves the needs of that specific device type. - -By default, the desktop and phone layouts are available out-of-the-box, and the design of the layouts can be customized to your needs. You can change and extend the default layouts as well as create new layouts as needed. - -Be careful with how you design these layouts. For example, in the mobile apps, you do not want to have too many regions, or the design will look crowded and confusing to the end-user. On the other hand, a desktop application might require different regions that allow for more content to be shown and details to be displayed. - -### Layout Examples {#layout-examples} - -These are some layout examples: - -* Basic layout for responsive/desktop pages: - - {{< figure src="/attachments/howto8/front-end/layouts-and-snippets/basic-desktop.png" class="no-border" >}} - -* Basic layout for mobile pages: - - {{< figure src="/attachments/howto8/front-end/layouts-and-snippets/basic-mobile.png" class="no-border" >}} - -* Primary layout with added menu: - - {{< figure src="/attachments/howto8/front-end/layouts-and-snippets/primary.png" class="no-border" >}} - -{{% alert color="info" %}} - -By adjusting the canvas width, you can emulate the end-user's view of the page in Studio Pro. For example, the desktop layout has a canvas width of 800, and the default phone layouts have a width of 500. The property canvas width only applies to the view in Studio Pro, and the actual width of the page depends on the opened browser or the optional pop-up window size. - -{{% /alert %}} - -After defining the structure of the layout with the layout container(s), the region's content must be defined. This can either be done per page, with page-specific elements (for example, by adding data widgets in the empty areas), or within the layout in order to define the elements that will be used on each page with this layout. It is common that this will be the general app navigation or specific navigation for a specific function. All the widgets can be used, except data and input widgets, since they need a source. - -Two of the most useful widget types are menu widgets and snippets. You will learn more about those two types below. - -## Menu Widgets - -### Menu Bar - -The menu bar widget shows a configured menu in the form of a horizontal bar with items. The items can have sub-items, and the main item in the menu can be expanded. Sub-items can go only one level deep (a sub-item cannot have its own sub-item). The menu item points to either the page or the microflow that will open or start when the item is clicked. - -{{< figure src="/attachments/howto8/front-end/layouts-and-snippets/menu-bar.png" class="no-border" >}} - -### Navigation Tree - -The navigation tree widget shows a configured menu in the form of a tree. Items can have sub-items when the main item is expanded. The menu structure of the navigation tree can have up to three levels. In the end, a menu item points to either the page or the microflow that will open or start when the item is clicked. - -{{< figure src="/attachments/howto8/front-end/layouts-and-snippets/nav-tree.png" class="no-border" >}} - -### Simple Menu Bar - -The simple menu bar widget shows a configured menu in the form of a horizontal bar with images and captions. Items cannot have sub items (the menu structure can only have one level). The menu item points to either the page or the microflow that will open or start when the item is clicked. - -{{< figure src="/attachments/howto8/front-end/layouts-and-snippets/simple-menu.png" class="no-border" >}} - -### Menu Source - -The items that are shown in the menu widget are determined by the menu source. A menu widget is either filled from a menu configured in the **Navigation** document or a **Menu** page resource: - -* **Project** > **Navigation** — when selected, the menu items are taken from one of the menus defined in this document; use this for the main menu of your application -* **Add Other** > **Menu** — when selected, the menu items are taken from this page resource; use this menu for auxiliary menus - -When you have selected the project navigation as source, the device profile must be determined for the correct navigation menu: - -{{< figure src="/attachments/howto8/front-end/layouts-and-snippets/edit-menu-bar.png" class="no-border" >}} - -For the desktop, use the **Responsive** menu. - -For tablet and phone configuration, you need to choose the appropriate profile type. See the section [Device Profiles](#profiles) below for details. - -### Project Navigation - -The **Navigation** document defines the main navigation structure of the application for end-users. It allows you to set the home page of your application as well as define menu structures for use in menu widgets. The home page can vary based on the roles a user has. If security is enabled, the menu will only show the items to which the user has access. - -### Device Profiles {#profiles} - -At the heart of the navigation model in Mendix, are three device types: Desktop, Tablet, and Phone. You can define separate home pages and menus for each of these three devices. The Desktop device type is always enabled, while the following Tablet and Phone profiles can be enabled or disabled: - -* **Hybrid tablet app online** -* **Hybrid tablet app offline** -* **Hybrid phone app online** -* **Hybrid phone app offline** -* **Tablet browser** -* **Phone browser** - -{{< figure src="/attachments/howto8/front-end/layouts-and-snippets/device-profiles.png" class="no-border" >}} - -When a user visits a Mendix application, they are automatically redirected to the home page of the appropriate device type (for details, see the section [Redirection to Device Types](#RedirectiontoDeviceTypes)). - -For more information on navigation profiles, see [Navigation in Mendix](/refguide8/navigation/). - -### Menu Document - -A menu document defines a navigation menu that can be used by a menu widget. Typically, the main menus for your application are defined in device types, while you use menu documents for auxiliary menus (for example, a side bar). A menu consists of a list of menu items, which optionally contain sub-items. Depending on the widget a number of levels are allowed. - -{{< figure src="/attachments/howto8/front-end/layouts-and-snippets/menu-document.png" class="no-border" >}} - -### Redirection to Device Types {#RedirectiontoDeviceTypes} - -The Mendix Runtime automatically redirects users to the home page of the appropriate device type based on the device they are using. This happens by examining the `User-Agent` string that is sent by the device's browser. This is the default configuration for the redirection: - -| User-Agent String Regular Expression | Device Type | -| ------------------------------------ | ----------- | -| `Android.*Mobile` or `iPhone` | Phone | -| `Android` or `iPad` | Tablet | -| (Other) | Desktop | - -The string for specific user interphases can also be configured within the server custom settings (this is more advanced and not covered here). - -If a device type is not enabled, it falls back to another device type: - -| Device Type | Fallback | -| ----------- | ------------------------------------ | -| Phone | Tablet, Desktop | -| Tablet | Phone, Desktop | -| Desktop | (None, as Desktop is always enabled) | - -It is also possible to force the client to use a specific device type by adding a `profile` query string parameter to the URL when visiting a Mendix application. The possible values are `Desktop`, `Tablet`, and `Phone`. - -## Snippets - -Snippets are reusable interface parts that can be used on pages and layouts. Using snippets requires Mendix business engineers to modify fewer places in the interface and allows for a smoother transition as well as a user-friendly experience. For example, you can have a snippet that is used both in the contents area of a template grid and in a data view. Changes you make to the snippet will be applied in all places where the snippet is used. - -In addition, a snippet can define an entity that serves as a context for the widgets placed in it. For example, if you set the *Course* entity for a snippet, you could place a text box that shows the *Course Title* on the snippet without having to define a data view first. When an entity is defined on a snippet, it needs to be placed inside a context for that entity in each place that you use the snippet (for example, a data view). - -{{< figure src="/attachments/howto8/front-end/layouts-and-snippets/snippet.png" class="no-border" >}} - -## Read More - -* [Atlas UI](/howto8/front-end/atlas-ui/) -* [Use Layouts and Snippets](/howto8/front-end/layouts-and-snippets/) -* [Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/) -* [Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/) -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) diff --git a/content/en/docs/howto8/front-end/style-google-maps.md b/content/en/docs/howto8/front-end/style-google-maps.md deleted file mode 100644 index 341d5c9b0ac..00000000000 --- a/content/en/docs/howto8/front-end/style-google-maps.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Style Google Maps" -url: /howto8/front-end/style-google-maps/ -weight: 60 ---- - -## Introduction - -Google Maps is a very powerful addition to your applications. You can use it to display locations, areas, routes, etc. By default every map overview looks the same, like on the default Google Maps website. There is now a new option available on the Google Maps widget to style the map overview to make it match your application design. Follow the steps below to sauce-up the map overviews in your applications with a minimal amount of effort! - -**After completing this how-to you will know:** - -* How to configure the new style feature of the Google Maps widget -* Find and implement the right style matching your application -* Upload new styles to support the community - -## Preparation - -Before you start this how-to, please make sure you have completed the following prerequisites. - -* Have the latest version of the [Google Maps](/appstore/widgets/google-maps/) widget in your app - -{{% alert color="warning" %}} -These instructions are for the Google Maps widget which you can download from the Marketplace. The Google Maps widget within the Atlas UI template has different options. -{{% /alert %}} - -## Adding the Style - -### Widget Properties - -In this chapter I will explain how you can add styling to the Google Maps widget. - -1. Open the properties of your Google Maps widget and go to the **Customisation** tab. - {{< figure src="/attachments/howto8/front-end/style-google-maps/19398957.png" class="no-border" >}} - -2. Simply enter the style in the **Style Array** section and you're done! - {{< figure src="/attachments/howto8/front-end/style-google-maps/19398956.png" class="no-border" >}} - - Here is the example styling: - - ```json - [{"featureType":"all","elementType":"labels","stylers":[{"visibility":"off"}]},{"featureType":"administrative","elementType":"all","stylers":[{"visibility":"off"}]},{"featureType":"administrative","elementType":"labels","stylers":[{"visibility":"off"}]},{"featureType":"landscape","elementType":"all","stylers":[{"visibility":"on"}]},{"featureType":"landscape","elementType":"geometry.fill","stylers":[{"color":"#abce83"}]},{"featureType":"landscape","elementType":"labels","stylers":[{"visibility":"off"}]},{"featureType":"poi","elementType":"all","stylers":[{"visibility":"off"}]},{"featureType":"road","elementType":"geometry.fill","stylers":[{"visibility":"simplified"}]},{"featureType":"road","elementType":"labels.text.fill","stylers":[{"color":"#5B5B3F"}]},{"featureType":"road","elementType":"labels.text.stroke","stylers":[{"color":"#ABCE83"}]},{"featureType":"road","elementType":"labels.icon","stylers":[{"visibility":"off"}]},{"featureType":"road.highway","elementType":"geometry","stylers":[{"color":"#EBF4A4"}]},{"featureType":"road.arterial","elementType":"all","stylers":[{"visibility":"off"}]},{"featureType":"road.local","elementType":"all","stylers":[{"visibility":"off"}]},{"featureType":"transit","elementType":"all","stylers":[{"visibility":"off"}]},{"featureType":"water","elementType":"geometry","stylers":[{"visibility":"on"},{"color":"#aee2e0"}]}] - ``` - -3. The example style will give you this result: - {{< figure src="/attachments/howto8/front-end/style-google-maps/19398958.png" class="no-border" >}} - -### Finding the Right Style - -Choosing an existing style sheet from a large library that fits your application will save you a lot of time. Here is a community website where new styles are uploaded on a regular basis: [https://snazzymaps.com/](https://snazzymaps.com/). - -1. On the website click **Explore:** - {{< figure src="/attachments/howto8/front-end/style-google-maps/19398959.png" class="no-border" >}} -2. Explore the styles to find one that matches your application and click it: - {{< figure src="/attachments/howto8/front-end/style-google-maps/19398960.png" class="no-border" >}} -3. On the lefthand pane you will see the style array: - {{< figure src="/attachments/howto8/front-end/style-google-maps/19398961.png" class="no-border" >}} -4. Now simply press **Copy.** The style is copied to your clipboard. -5. Open the **Customisation** tab of the Google Maps widget and paste the style array you just copied from snazzymaps: - - {{< figure src="/attachments/howto8/front-end/style-google-maps/19398962.png" class="no-border" >}} - - The style array: - - ```json - [{"featureType":"all","elementType":"labels.text.fill","stylers":[{"color":"#ffffff"}]},{"featureType":"all","elementType":"labels.text.stroke","stylers":[{"color":"#000000"},{"lightness":13}]},{"featureType":"administrative","elementType":"geometry.fill","stylers":[{"color":"#000000"}]},{"featureType":"administrative","elementType":"geometry.stroke","stylers":[{"color":"#144b53"},{"lightness":14},{"weight":1.4}]},{"featureType":"landscape","elementType":"all","stylers":[{"color":"#08304b"}]},{"featureType":"poi","elementType":"geometry","stylers":[{"color":"#0c4152"},{"lightness":5}]},{"featureType":"road.highway","elementType":"geometry.fill","stylers":[{"color":"#000000"}]},{"featureType":"road.highway","elementType":"geometry.stroke","stylers":[{"color":"#0b434f"},{"lightness":25}]},{"featureType":"road.arterial","elementType":"geometry.fill","stylers":[{"color":"#000000"}]},{"featureType":"road.arterial","elementType":"geometry.stroke","stylers":[{"color":"#0b3d51"},{"lightness":16}]},{"featureType":"road.local","elementType":"geometry","stylers":[{"color":"#000000"}]},{"featureType":"transit","elementType":"all","stylers":[{"color":"#146474"}]},{"featureType":"water","elementType":"all","stylers":[{"color":"#021019"}]}] - ``` - -6. And there it is: - {{< figure src="/attachments/howto8/front-end/style-google-maps/19398963.png" class="no-border" >}} - -### Upload Your Own Style Array - -Supporting communities is cool. Therefore I will also show you how to upload your own custom style array to the website. - -1. Go-to Snazzymaps and click **Create.** - **{{< figure src="/attachments/howto8/front-end/style-google-maps/19398964.png" class="no-border" >}}** -2. Now you will see a handy quick style method for altering your map appearance: - {{< figure src="/attachments/howto8/front-end/style-google-maps/19398965.png" class="no-border" >}} - - Happy modeling! - -## Read More - -* [Atlas UI](/howto8/front-end/atlas-ui/) -* [Layouts and Snippets](/howto8/front-end/layouts-and-snippets/) -* [Setting Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/) -* [Creating your first two Overview and Detail pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/) diff --git a/content/en/docs/howto8/front-end/styles.md b/content/en/docs/howto8/front-end/styles.md deleted file mode 100644 index c396ac2de3f..00000000000 --- a/content/en/docs/howto8/front-end/styles.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: "Implement Classes" -url: /howto8/front-end/styles/ -description: "Presents details on using class names for text colors, buttons, and other style elements." -weight: 45 ---- - -## Introduction - -This page contains useful class names that can be used to make your app more beautiful without writing CSS. Class names can be added to the properties of page widgets. Several classes can be added to the same widget by separating the class names with a space. - -Class names can be entered in two locations: - -* The **Properties** panel of Studio Pro -* The **Properties** pop-up window for the widget - -This how-to teaches you how to do the following: - -* Use class names to implement text and background colors, typography, buttons, list views, alerts, and other elements - -## Text Colors - -Add these classes to an element to change the text color to your theme colors: - -* `text-default`: default text color -* `text-primary`: primary brand color -* `text-info`: info brand color -* `text-success`: success brand color -* `text-warning`: warning brand color -* `text-danger`: danger brand color - -These are standard useful text colors: - -* `text-white`: white text -* `text-black`: black text -* `text-gray-primary`: primary gray text -* `text-gray`: gray text -* `text-gray-dark`: dark gray text -* `text-gray-darker`: darker gray text -* `text-gray-light`: light gray text -* `text-gray-lighter`: lighter gray text - -## Background Colors - -The background colors are based on your theme colors. These are the same colors as for the buttons: - -* `background-primary`: primary background color -* `background-info`: info background color -* `background-success`: success background color -* `background-warning`: warning background color -* `background-danger`: danger background color - -A lighter variant of the background color also sets the matching foreground color: - -* `bg-primary`: primary background color -* `bg-info`: info background color -* `bg-success`: success background color -* `bg-warning`: warning background color -* `bg-danger`: danger background color - -These are background colors for your layout: - -* `background-layout`: default layout background -* `background-layout-secondary`: alternative layout background -* `background-default`: default layout background -* `background-default-dark`: dark layout background -* `background-default-darker`: darker layout background -* `background-default-light`: light layout background -* `background-default-lighter`: lighter layout background - -## Typography - -These are useful classes for text items: - -* `text-normal`: normal text -* `text-bold`: bold text -* `text-spacing`: adds spacing to the text bottom and top -* `text-lined`: underlines the text-lined -* `text-break`: breaks text over multiple lines -* `text-uppercase`: transforms the text to upper case -* `text-lowercase`: transforms the text to lower case -* `text-capitalize`: capitalizes every word - -To align texts, add these to the container holding the text: - -* `text-right`: aligns the text to the right -* `text-center`: aligns the text to the center -* `text-left`: aligns the text to the left (default) - -Other: - -* `nowrap`: don't wrap texts - -## Buttons - -You can change the appearance of a button: - -* `btn-lg`: large button -* `btn-sm`: small button -* `btn-block`: spans the full width of the parent -* `btn-bordered`: bordered button -* `btn-transparent`: transparent background -* `btn-image`: transparent button with image nicely align -* `pull-right` or `btn-right`: aligns the button to the right -* `btn-attached-right`: adds left margin -* `btn-attached-left`: adds right margin -* `btn-attached-bottom`: adds top margin -* `btn-attached-top`: adds bottom margin - -## Layout Grid - -You can change the appearance of a layout grid: - -* `v-center`: vertically aligns elements in a Bootstrap row; add this class on a row in a layout grid -* `no-gutter`: removes padding for Bootstrap columns; add this class on a row in a layout grid - -{{% alert color="info" %}}**Phones:** - -For phones, also add `col-xs-N` (where `N` is the size of the column) to the layout grids to make the columns appear next to each other. - -{{% /alert %}} - -For more information on grid options, including suggestions and examples, see [Bootstrap CSS Grid Options](https://getbootstrap.com/docs/3.3/css/#grid-options). - -## List View - -Change the way items appear in a list: - -* `listview-lined`: list view widget with only a bordered bottom in a list view item -* `listview-striped`: list view widget with striped list view items -* `listview-seperated`: list view widget with list view items separated -* `listview-stylingless`: list view widget without spacing and background - -## Alerts - -Create alerts with standard containers. - -* `alert`: makes an alert of a container; use in combination with the next classes -* `alert-success`: creates a success alert -* `alert-info`: creates an info alert -* `alert-warning`: creates a warning alert -* `alert-danger`: creates a danger alert - -Also see [Bootstrap Alert Component](https://getbootstrap.com/docs/3.3/components/#alerts). - -## Other - -Change the way tabs appear: - -* `tab-mobile`: makes the tab full width and stick to the header - -## More Bootstrap - -Many of these classes are part of Bootstrap. For more information about classes and Bootstrap, see [Bootstrap CSS](https://getbootstrap.com/docs/3.3/css/). - -## Read More - -* [Mendix Atlas UI](https://atlas2.mendix.com/) diff --git a/content/en/docs/howto8/front-end/use-navigation-layouts.md b/content/en/docs/howto8/front-end/use-navigation-layouts.md deleted file mode 100644 index fc674bad6d6..00000000000 --- a/content/en/docs/howto8/front-end/use-navigation-layouts.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -title: "Use Navigation Layouts" -url: /howto8/front-end/use-navigation-layouts/ -weight: 12 -description: "This guide teaches you how to use navigation layouts." ---- - -## Introduction - -This document will cover the basics of how you work with navigation layouts. - -This how-to teaches you how to do the following: - -* Select the right navigation layout -* Understanding the difference between top and left navigation -* Configure the sidebar toggle - -## Selecting the Correct Navigation Layout - -When building an app with Mendix, the first thing you have to decide is which navigation layout to choose. These layouts are the frames within which your dynamic pages are housed, and provide consistent structure through your app. - -Layouts specify what goes where. Each page is based on a layout. The layout contains widgets and structures that return on every page based on that layout. - -Mendix's Atlas UI provides two distinct web layouts for you to choose from: Atlas Default and Atlas Topbar. - -### Atlas Default - -The default layout of Atlas is a responsive layout which can be used across web, tablet, and mobile devices: - -{{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.1_atlasdefault.png" width="350" class="no-border" >}} - -It has three regions: top, left, and center. The top region contains the brand logo of your application, the left region your navigation menu, and the center region your dynamic content: - -{{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.1_atlasdefaultregions.png" width="350" class="no-border" >}} - -The navigation menu of Atlas Default is a toggled menu. Options for this toggled menu are to **shrink content (initially open)** or to **shrink content (initially closed)**: - -* **Shrink content (initially open)** — the navigation menu will initially start open at its maximum width, displaying both the menu item's description and icon. When toggled it will move to its minimum width and display just the menu item's icon. The page's content (center region) also starts shrunk to make space for the open menu: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.1_shrinkingcontentopenoption.gif" width="350" class="no-border" >}} - -* **Shrink content (initially closed)** — the navigation menu will initially start closed at its minimum width displaying just the menu item's icon. When toggled it will move to its maximum width and display both the menu item's icon and description. The page's content (center region) does not start shrunk, but will shrink when sidebar is toggled: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.1_shrinkingcontentclosedoption.gif" width="350" class="no-border" >}} - -### Atlas TopBar - -The TopBar layout of Atlas a responsive layout which can be used -across web, tablet and mobile devices: - -{{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.2_atlastopbar.png" width="350" class="no-border" >}} - -It has three regions: top, left, and center. The top region though contains both the brand logo and the navigation menu. The left region does contain a navigation menu, but it is only visible at phone screen size. At that screen size the navigation menu in the top region will be hidden and replaced with a hamburger toggle which triggers the opening and closing of the left region. The center region houses the dynamic content of your app: - -{{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.2_atlastopbarregions.png" width="350" class="no-border" >}} - -The options for the sidebar (unlike the Atlas Default) are only applicable at phone screen size. You then have two options for how the sidebar is toggled: **slide over content** and **push content aside**: - -* **Slide over content** — the sidebar will move to overlay on top of the content, hiding a portion (depends on the width of the sidebar) of the content: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.2_slidingovercontent.gif" width="350" class="no-border" >}} - -* **Push content aside** — the sidebar will push the content off-screen: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.2_pushingcontentaside.gif" width="350" class="no-border" >}} - -### Comparing the Two Layouts - -Choosing which of the two layouts (Atlas Default and Atlas Topbar) is right for you comes down to choosing between top navigation versus left navigation, The information below will help you determine which approach better suits your users. The sections below assume your app is designed for users who read left to right, but Mendix may release more design guidance and options for other language cultures in the future. - -When it comes down to designing for your users, context is key. A navigation that works well in one context may not as well in another. To determine which navigation is best for your app, it is important to understand the different contexts where the top and left navigation work best: - -{{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.3_topvsleftnavigation.png" width="350" class="no-border" >}} - -#### Scanning - -A left navigation is faster and more efficient for users to scan. In just three visual fixations, users scan six items in the left navigation compared to the three items scanned in the top navigation. The left navigation also facilitates a vertical scanning direction that is natural for people, while the top navigation forces a horizontal scanning direction that people often use when they are reading. - -#### Page Space - -A top navigation conserves more vertical page space than a left navigation. With a left navigation, the navigation links occupy the left column of your page. This shrinks and narrows the content area of your page, which means you will have less space for your content. A top navigation, however, uses minimal vertical space which allows you to fill your page's content area with content only. - -#### Item Priority - -Items in a top navigation do not have equal weight. The leftmost items carry more visual weight than other items because of their placement in the primary visual area (top left). Items in the upper-left area get more exposure and are often seen as more important than other items. The items in left navigation, however, do have equal weight because they are all placed on the left with no other items in their opposing direction on the right. Because users read items from left to right, the priority direction for reading items is stronger horizontally than vertically. - -#### Visibility - -Top navigation items are more visible because they are always above the fold and are easier to find. Left navigation items are not always above the fold; sometimes if you have too many items a few of them can get pushed below the fold. Top navigations are also easier to find because they are usually accompanied by the header and logo, both of which are visually dominant objects on a web page. - -## Configuring the Sidebar - -### Set the Toggled Sidebar to Shrinking Content (Initially Open): - -To configure the toggled sidebar to shrinking content (initially open), follow these steps: - -1. Open the page properties of the **Home_Web** page: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.1_pageproperties.png" width="350" class="no-border" >}} - -2. In the **General** tab, select **Atlas_Default** as the layout: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.1_layoutselection.png" width="350" class="no-border" >}} - -3. Then in the breadcrumb, navigate to the **Atlas_Default** navigation layout: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.1_breadcrumb.png" width="350" class="no-border" >}} - -4. Open the region properties of the left sidebar: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.1_regionproperties.png" width="350" class="no-border" >}} - -5. In the **General** tab, select **Shrinking content (initially open)** as the toggle mode: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.1_shrinkcontentopen.png" width="350" class="no-border" >}} - -### Toggling the Sidebar for Shrinking Content (Initially Open) - -To toggle the sidebar for **Shrinking content (initially open)**, follow these steps: - -1. Click **Run Locally** to run your app. -2. In your browser, click the toggle button: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.2_toggleshrinkingcontentopenoption.gif" width="350" class="no-border" >}} - -### Set the Toggled Sidebar to Shrinking Content (Initially Closed) - -To configure the toggled sidebar to **Shrinking content (initially closed)**, follow these steps: - -1. Open the page properties of the **Home_Web** page: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.3_pageproperties.png" width="350" class="no-border" >}} - -2. In the **General** tab, select **Atlas_Default** as the layout: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.3_layoutselection.png" width="350" class="no-border" >}} - -3. Then in the breadcrumb, navigate to the **Atlas_Default** navigation layout: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.3_breadcrumb.png" width="350" class="no-border" >}} - -4. Open the region properties of the left sidebar: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.3_regionproperties.png" width="350" class="no-border" >}} - -5. In the tab **General**, select **Shrinking content (initially closed)** as the toggle mode: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.3_shrinkcontentclosed.png" width="350" class="no-border" >}} - -### Toggling the Sidebar for Shrinking Content (Initially Closed) - -1. Click **Run Locally** to run your app. -2. In your browser, click the toggle button: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.4_toggleshrinkingcontentclosedoption.gif" width="350" class="no-border" >}} - -### Set the Toggled Sidebar to Pushing Content Aside - -To configure the toggled sidebar to **Push content aside**, follow these steps: - -1. Open the page properties of the Home_Web page: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.5_pageproperties.png" width="350" class="no-border" >}} - -2. In the **General** tab, select **Atlas_Topbar** as the layout: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.5_layoutselection.png" width="350" class="no-border" >}} - -3. In the breadcrumb, navigate to the **Atlas_Topbar** navigation layout: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.5_breadcrumb.png" width="350" class="no-border" >}} - -4. Open the region properties of the left sidebar: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.5_regionproperties.png" width="350" class="no-border" >}} - -5. In the **General** tab, select **Push content aside** as the toggle mode: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.5_pushcontentaside.png" width="350" class="no-border" >}} - -6. Optionally, you can change the **Width to Percentage** and enter *80* as the **Width value**: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.7_changewidth.png" width="350" class="no-border" >}} - -### Toggling the Sidebar for Pushing Content Aside - -To toggle the sidebar for Pushing content aside, follow these steps: - -1. Click **Run Locally** to run your app. -2. In your browser, right-click your web page and click **Inspect**: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.6_inspector.png" width="350" class="no-border" >}} - -3. Click the toggle device toolbar: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.6_toggledevicetoolbar.png" width="350" class="no-border" >}} - -4. Change the emulated device to an **iPhoneX** or an equivalent mobile device: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.6_selectdevicesize.png" width="350" class="no-border" >}} - -5. In your emulated device's browser window, click the toggle button: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.2_pushingcontentaside.gif" width="350" class="no-border" >}} - -### Set the Toggled Sidebar to Slide Over Content - -To configure the toggled sidebar to **Slide over content**, follow these steps: - -1. Open the page properties of the **Home_Web** page: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.7_pageproperties.png" width="350" class="no-border" >}} - -2. In the **General** tab, select **Atlas_Topbar** as the layout: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.7_layoutselection.png" width="350" class="no-border" >}} - -3. In the breadcrumb, navigate to the **Atlas_Topbar** navigation layout: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.5_breadcrumb.png" width="350" class="no-border" >}} - -4. Open the region properties of the left sidebar: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.7_regionproperties.png" width="350" class="no-border" >}} - -5. In the **General** tab, select **Slide over content** as the toggle mode: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.7_slideovercontent.png" width="350" class="no-border" >}} - -6. Optionally, change the **Width** to **Percentage** and enter *80* as the **Width value**: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.7_changewidth.png" width="350" class="no-border" >}} - -### Toggling the Sidebar for Slide Over Content - -To toggle the sidebar for **Slide over content**, follow these steps: - -1. Click **Run Locally** to run your app. -2. In your browser, right-click your web page and click **Inspect**: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.8_inspector.png" width="350" class="no-border" >}} - -3. Click the toggle device toolbar: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.8_toggledevicetoolbar.png" width="350" class="no-border" >}} - -4. Change the emulated device to an **iPhoneX** or an equivalent mobile device: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/3.8_selectdevicesize.png" width="350" class="no-border" >}} - -5. In your emulated device's browser window, click the toggle button: - - {{< figure src="/attachments/howto8/front-end/use-navigation-layouts/2.2_slidingovercontent.gif" width="350" class="no-border" >}} - -## Read More - -* Check the [Atlas UI](https://atlas2.mendix.com/) page for more information on the Atlas UI framework -* See the [Layout Examples](/howto8/front-end/layouts-and-snippets/#layout-examples) section of *How to Use Layouts and Snippets* for more information on creating your own navigation layouts diff --git a/content/en/docs/howto8/front-end/ux-best-practices.md b/content/en/docs/howto8/front-end/ux-best-practices.md deleted file mode 100644 index 9a4f97a4b79..00000000000 --- a/content/en/docs/howto8/front-end/ux-best-practices.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: "Implement Best Practices for UX Design" -url: /howto8/front-end/ux-best-practices/ -weight: 10 ---- - -## Introduction - -{{% alert color="info" %}} -This how-to is based on the blog post [Common UX Mistakes Made by Business Developers](https://blog.prototypr.io/common-ux-mistakes-made-by-business-developers-e837d0b31379) by Jason Teunissen, UX Consultant at [Appronto](https://developer.mendixcloud.com/link/partnerprofile/8870), a Mendix partner company. -{{% /alert %}} - -In a Mendix team, the UX Designer's job is to improve the user experience of applications in as many ways as possible. However, sometimes logical solutions from a development perspective are not the best solutions from a UX perspective. - -This set of best practices is for UX Designers to think carefully about what they can add to app development process. - -## Do Not Put Everything in a Single Screen - -Putting all of the application's menus, features, and buttons in a single screen is a bad UX practice, but one that is commonly seen. In this scenario, UX Designers and Developers start with a tight interface, but over time they add features that result in a screen full of buttons. - -The arguments for putting everything onto a single screen include the following: - -* "Fewer clicks are needed" -* "An overview is created" -* "Users hate scrolling" - -To a UX Designer, this kind of app looks like a Swiss Army knife with all the tools unfolded, but the only one being used is the bottle opener. - -{{< figure src="/attachments/howto8/front-end/ux-best-practices/single-screen.png" class="no-border" >}} - -### Avoid Overwhelming Design - -Packing all the options for your app into one screen may seem like it creates overview, but your brain can only understand nine options at a time at best. And let's be honest, the end-user may not use 90% of your app's buttons that often, so there is no need to overwhelm them. - -### Prioritize Visual Proximity - -Buttons should be close to the data that they influence. This means that when you have fewer buttons on one screen, you gain visual proximity. - -### Remember, Users Do Not Hate Scrolling! - -The “users hate scrolling argument” is often a side-effect of being unable to provide an end-user with the right context at the right time. The workaround is then forcing as much information as possible into a single screen to help create context. - -The issue here is not the need to scroll, but the amount of information on the screen. Placing more information higher on the page does not mean the end-user will necessarily absorb that information. It may make them tire of your app more quickly and even leave. - -For more information, see [Miller's Law](https://lawsofux.com/millers-law) and the [Law of Proximity](https://lawsofux.com/law-of-proximity). - -## Do Not Put Everything in Drop-Down Menus - -The arguments for using drop-down menus and packing them full of options often include the following: - -* "There will be more focus and less clutter" -* "It will be easier for the end-user to find what they need" - -The guidelines below address what you really need to consider when designing drop-down menus. - -{{< figure src="/attachments/howto8/front-end/ux-best-practices/drop-down.png" class="no-border" >}} - -### Emphasize Balance - -Think about your interface as a physical space. Consider the following scenario: an object you need is in a set of drawers, so you need to start opening the drawers until you find what you are looking for. If the drawers are in the right place and organized logically, you can find what you need more quickly. But if the drawers hold random objects that do not correspond to the context of what you need, you will spend a lot of time looking for the right object. - -Good balance goes a long way. How often an object is used determines where it should go in a drawer, which translates to: How often a button is needed determines where it should go in a drop-down menu. - -If you only have five buttons, they might not need to go in a drop-down menu at all. But if you have six buttons, that’s a different story. - -## Let the User Know Where They Are in the App - -When your app has a consistent design system and brand style, all the pages may start to feel the same to the end-user. Soon enough, the end-user may feel like they are walking through a forest of pages, unable to recall if they have seen a particular page before, or if they are actually on a different page with a similar state. - -The arguments for using a very consistent design system and brand style may include the following: - -* "The visual style must be entirely consistent and fully branded" -* "Design systems drive design" -* "We want efficient use of screen real-estate" - -The guidelines below address how to let the user know where they are in your app. - -{{< figure src="/attachments/howto8/front-end/ux-best-practices/where-am-i.png" class="no-border" >}} - -### Design for Distracted Users - -Picture an end-user on a Friday afternoon, bouncing between social media, chats with colleagues, some private messages, and actually doing some work. The last thing on their mind is what link they just clicked and where they are in the flow of your app. - -Create every screen for this user by following these guidelines: - -* Give pages clear headers and page names -* Implement breadcrumbs if you design more than one level deep -* If the page flow has multiple steps, show those steps - -## Avoid Long Lines and Tiny Text - -Writing long lines of text and implementing tiny font sizes is another example of wanting to get the most out of your screen. Arguments for designing like this are some we have seen already: - -* "Users hate scrolling" -* "We want efficient use of screen real-estate" - -The rule of thumb for web typography is to write no more than nine words per line. When the end-user is finished reading a line, their eyes need to be able to find the next line. So, if a line is too long, it is harder for their eyes to move on. - -{{< figure src="/attachments/howto8/front-end/ux-best-practices/long-lines.png" class="no-border" >}} - -### Whitespace Is Not Wasted Space - -Consider the popular blogging platform [Medium.com](https://blog.prototypr.io/common-ux-mistakes-made-by-business-developers-e837d0b31379). Have you ever noticed how much screen real estate they "waste"? That is because what may be called "waste" is actually an investment. It presents the impression that if you can afford to invest that much space into a page, the text must be important (and if the text is not important, you should get rid of it anyway). - -For more information, see [A Typographic Approach to Email](https://blog.weare1910.com/post/78113100010/a-typographic-approach-to-email). - -## Do Not Double Up the Pop-Ups - -Have you ever pressed a button in a mobile app that opens a notification pop-up window, and in that notification there is another button leading to another pop-up window? - -The main argument for a UX Designer implementing something like this is the following: - -* "The user will have more context awareness" - -However, the problem with such a design is that the end-user will lose the mental model of where they are in the flow of app pages or the process. They will be more distracted, no matter if they close the second pop-up window and return to the first pop-up window or return to the original screen. - -{{< figure src="/attachments/howto8/front-end/ux-best-practices/pop-up.png" class="no-border" >}} - -### Avoid One Too Many Pop-Up Windows - -The best practice here is to implement one of the following solutions: - -* Turn the first pop-up window into a page itself, or -* Convert the second pop-up window into an inline message in the first pop-up window - -## Lay Your Cards on the Table - -Cards are trending in the UX world at the moment. Single cards are nice, but what about a series of cards in another card? - -An argument for implementing such a design would be the following: - -* "The cards are nested in order to create visual hierarchy” - -UX Designers often talk about visual hierarchy, which is the way elements are organized on a screen to communicate their importance to the end-user. Physical symbolism—such as cards—was introduced into the visual hierarchy to present information in a certain way. Because playing cards are of equal size in a traditional card deck, digital cards placed on, under, or next to other cards can communicate certain states and relationships between information. However, when you nest a card inside another card, the end-user's mental model of what you can do with the cards starts to break down. This end-user may even start to question the relationships of other objects in the UI, thus further compromising the design hierarchy in your app. - -{{< figure src="/attachments/howto8/front-end/ux-best-practices/cards.png" class="no-border" >}} - -### Do Not Nest Cards - -Instead of nesting cards in your design, place them next to each other (or at least close to each other). Or, place them in a ribbon spread (like how playing cards are spread on a casino table). - -## Plan Your Forms Carefully - -A UX Designer has to make a lot of decisions about forms. For example, should there be a long list of form inputs? Should the form be broken up in to multiple steps? Or maybe there should be three columns of form inputs, so that they all fit into a single screen? - -The main argument for including a lot of form fields in one page is an argument we have seen before: - -* “Users hate scrolling” - -Again, the issue here is not the need to scroll, but the amount of information on the screen (meaning, how many form fields are visible on the screen at a single time). Like buttons, the number of form fields should be reduced to the minimal number possible that can still provide context and ease-of-use. - -{{< figure src="/attachments/howto8/front-end/ux-best-practices/forms.png" class="no-border" >}} - -### Always Use a Single Column - -The best practice for designing forms is to put input fields in a single column. This will make it easier for the end-user to continue their flow down the page and check off each section. - -### Think About the Story You Are Telling - -Sometimes your app's form fields reflect the journey the end-user is embarking on (for example, onboarding) or have important consequences (for example, a tax questionnaire). When you think about the story you are telling, look for the best points to break up your forms into multiple pages. Doing so will give you visual space to create breathing room for the end-user and explain to them what they are doing and why it is important. - -### Consider What Should Go in Drop-Down Menus - -If there are only 2–5 form field items to choose from, do not put them in a drop-down menu. This might seem like an elegant solution, but it will not be worth the user's effort and clicks. Placing radio buttons is a friendlier approach. - -### Read More - -For more information on planning form design, see the following: - -* [Design Better Forms](https://uxdesign.cc/design-better-forms-96fadca0f49c?epik=0KSYeE_IWH4Bw) - -* [Single Page or Multi-Page Forms?](https://ux.stackexchange.com/questions/36956/single-page-or-multi-page-forms) - -## Make the Purpose of Each Button Clear - -When designing a series of app pages, a UX Designer should employ certain elements on each page that will help an end-user get oriented. As a parallel, you may think that buttons do not need to be consistent, because the end-user only needs to understand the button in the context of a particular page. - -An argument for designing buttons inconsistently may be something like this: - -* "That's the way Apple and Google do it” - -However, consistency in button design is important for enabling the user to progress through your app smoothly. - -{{< figure src="/attachments/howto8/front-end/ux-best-practices/buttons.png" class="no-border" >}} - -### Plan the Position, Color, and Label - -The most common button examples that raise questions are "Accept" and "Cancel." As a UX Designer, you must decide which one you put on the left and the right, in order to establish a relationship between them that the end-user can easily understand. You also need to consider the button colors and labels. - -The rule of thumb for button design is that, when the end-user moves forward in an app flow, that button should be designed in the following way: - -* It should be on the right -* It should have the color green -* It should have a label that explains what it does (for example, “Accept,” “Proceed,” or “Order"). - -However, this can get confusing with “destructive tasks,” such as when the end-user wants to cancel a subscription. In this scenario, you would need to consider whether the button label should be “Cancel” or “Cancel subscription." - -For more information, see [The Microcopyist: Cancellation, Confirmation, Conflagration](https://uxdesign.cc/the-microcopyist-cancellation-confirmation-conflagration-8a6047a4cf9). - -## Quick Summary - -These are the basic UX best practices outlined in this document: - -* Do not use more than nine buttons on a page -* Do not write more than nine words per line in the UI -* Only use drop-down menus as a last resort to present options to the end-user -* Give every page a header -* When a page is more than one level deep, give it breadcrumb -* When the end-user has to perform multiple steps, show the steps -* Do not place pop-up window in another pop-up window -* Do not nest a card in a card -* Keep form fields in a single column -* Give descriptive names to buttons - -## Read More - -* [Common UX Mistakes Made by Business Developers](https://blog.prototypr.io/common-ux-mistakes-made-by-business-developers-e837d0b31379) diff --git a/content/en/docs/howto8/general/_index.md b/content/en/docs/howto8/general/_index.md deleted file mode 100644 index 8c16a72ce53..00000000000 --- a/content/en/docs/howto8/general/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "General Info" -url: /howto8/general/ -description: "These introductory how-tos describe Mendix Studio Pro basics and best practices." -no_list: false -description_list: true ---- - -## Introduction - -Learn some basics about starting to model a Mendix app with the introductory how-tos in this category. - -## Documents in This Category diff --git a/content/en/docs/howto8/general/community-best-practices-for-app-performance.md b/content/en/docs/howto8/general/community-best-practices-for-app-performance.md deleted file mode 100644 index 426bb513064..00000000000 --- a/content/en/docs/howto8/general/community-best-practices-for-app-performance.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "Implement Community Best Practices for App Performance" -linktitle: "Best Practices for App Performance" -url: /howto8/general/community-best-practices-for-app-performance/ -weight: 8 ---- - -## Introduction - -{{% alert color="info" %}} - -This document is created by and for the Mendix community. It collects performance best practices in the form of dos and don'ts. - -{{% /alert %}} - -A must-have for your app is that it performs well. Your users will not accept anything else, and they will choose alternatives if the performance is not good. This document describes some best practices to apply during development to in order to get a better performing app. - -To put the best practices in perspective, let us quote some of the giants. First, Einstein's "Everything should be made as simple as possible, but no simpler." And next, programming giant Donald Knuth's "Premature optimization is the root of all evil." Both of these quotes suggest refraining from difficult constructs for the sake of performance unless you really need them and have already investigated simpler alternatives. You might need a load test and good measurement tooling, but that is out of the scope of this document. - -Other best practices might conflict with performance best practices. For example, security might require event handlers, and performance requires minimizing them. Good architecture is often a trade-off between different quality aspects. So, make motivated choices. - -This document contains sections covering parts of Mendix Studio Pro where you can consider performance for domain models (with a special section on indexes), microflows, and pages. Other sections cover parts of the infrastructure for special performance considerations in Mendix domain-specific languages, such as XPath, expressions, and OQL. - -## Domain Model Best Practices - -If you made a simple and sound design of the app's domain models, consider the following points so that the app performs well: - -* Create indexes on entities that will get more than 100 records and that will be searched by anything besides Mendix references/IDs. -* Minimize the use of calculated attributes, as they fire on every retrieve and per row for a list retrieve. You seldom need these for conditional visibility. -* Minimize the use and work of event handlers, because they fire on every event (for example, commit). -* Minimize the use of reference set associations. Mendix retrieves the IDs (per row for a list retrieve) on every query. So, many references—and especially reference sets—cause extra queries and thus extra load on the database. -* Consider archiving data if your volume grows too large and you do not need all the data all the time. You can even consider creating two identical entities, one with the data currently being used, and the other with all the data that is only used for reporting or other historic reasons. -* Consider denormalizing the data, which means copying attribute values to other entities. This is so the data is not retrieved every time from the source. If data does not change a lot, this can save a lot of queries. However, you need to build the logic to keep the copied attributes in sync! -* Do not use multiple levels of inheritance and too many specializations on entities that will contain a substantial amount of data, especially when you are using domain model XPath access on entities. This will generate complex queries adding XPaths for every specialization's security rules and, on a large dataset, will lead to slow queries. Consider the following alternatives: - * Combine attributes in one entity and add an enumeration to determine its specialization. - * Add separate entities for specializations with a one-to-one relation. Depending on UI needs, this one-to-one relation might be a normal reference from specialization to generalization to save prefetching time. - * Add a non-persistable layer with inheritance that is populated by your business logic. -* Do not use temporary associations on persistable entities. Use a non-persistable entity for your screen/UI logic here. - -## Index Best Practices - -Indexes is a topic with a long history of best practices from the database world. For Mendix apps, the following best practices apply: - -* Create as many indexes as needed. Although every index takes up space and the `insert`, `update`, and `delete` statements will be a bit slower, your queries will benefit a lot. -* Since Mendix will retrieve the object for you with all of its columns, your index is needed for two reasons. The first reason is to get the unique internal Mendix IDs fast. The second reason is for sorting. -* You only need to cover your search clauses and sort clauses, preferably in one index. -* Don't create different indexes that start with the same attributes. -* As a rule of thumb, try to minimize the number of index columns. Stay below three, or use a maximum of five. -* Start with the most selective attribute, although you need to consider that searches on single attribute can only use indexes that start with that attribute. -* Indexes can be used best for equal searches, ranges searches for dates and numbers, and leading/`startsWith` searches on strings. -* Index scans can be done to match more difficult clauses like `contains` or `endsWith`. These are still faster then full table scans. - -## Microflow Best Practices - -* Minimize the work in loops: - * Do commits after the loop in a list commit. - * If needed, create a list named `_CommitList` before the loop and collect the items to be committed there. - * For retrieves in a loop, consider retrieving all the data before the loop, and do finds on that list inside the loop. - * If loops contain decisions, consider if the decision logic can be a query before the loop to minimize iterations. -* Prevent unnecessary retrieves if objects or lists can be passed as parameters. -* Know and use the retrieve + aggregate optimization. If you retrieve a list and count the list, Mendix will optimize this to one query. If you need the list later in the microflow, after some decisions, it is wise to retrieve the list again so that you only retrieve the data when needed. This also works in batches where you can retrieve the total count optimized and retrieve chunks in a separate query. -* Use the retrieve over association if possible. This uses caching, it is more readable, and it uses an index. If business logic requires the database value (because the value over association might be changed), then of course a database retrieve is needed. -* Commit as late as possible. A commit locks that record (or list of records). This means that any other user/logic that wants to commit the same object has to wait until the first transaction is finished. -* To prevent locking, do scheduled events that commit data in small chunks. This is so the data does not get locked over a longer period of time. - -## Page Best Practices - -* Keep it simple. If possible, split up into multiple pages. Think of mobile app logic and not of all-in-one-screen logic. -* Minimize the data sent by using, for example, chunking or security to prevent data sent to the client. -* Try to prevent multiple identical data sources, since they load the object multiple times. -* Minimize conditional visibility. -* Give the user feedback. If this takes more than a few seconds, provide a progress indication. -* Do work asynchronously if the user does not have to wait for the result. For example, sending mails or updating other apps over an interface should never be something the user is waiting on in the UI. For running work asynchronously, there are options in the [Community Commons Function Library](/appstore/modules/community-commons-function-library/) in the Mendix Marketplace to run microflows in the background or have a process queue to control the load and prevent peaks in background work. - -## Infrastructure Best Practices - -* Get better infrastructure (for example, more App Engines in the [Mendix Cloud](/developerportal/deploy/mendix-cloud-deploy/)). -* When on premises, make sure a proxying web server is placed in front of Mendix to serve static content and compress data. - -## XPath Best Practices - -* Avoid "unequal" and "not" clauses in XPath. Often they can be rewritten to positive statements, like `=false()`, ` = valueA`, ` = valueB`, `integer>valueA`, or `integer}} - -## Project Setup - -### The Application Development Language - -The language that will be used to develop the application should be determined upfront. This way you have one language for modules, entities, microflows, pages, etc. The preferred language for development is English. - -There are some reasons why certain parts of an application may use another language. The main reason to make an exception would be within the domain model of an integration module. For example, when the source data model is in another language already. - -For more information, see [How to Translate Your App Content](/howto8/collaboration-requirements-management/translate-your-app-content/). - -### Project Name - -Every project is named when it is created. Make sure you use a logical name that allows you to easily identify the application. You will probably create more projects in the future, and will want to be able to recognize this project. Mendix recommends leaving out dates or Mendix version numbers in the project name, since that information can be captured and extracted in a different way. - -### Configurations - -Every project has at least one configuration, but it may have many. Every project starts with a single configuration called **default**. When you work with multiple people on an application it is beneficial to create multiple configurations. When doing so, Mendix recommends using relevant names for those configurations, like the name of the developer or the app's purpose, like **Test** or **Acceptance**. Beware that the database passwords defined in the configuration will be visible to other team members, so be careful with using personal passwords you'd like to keep secret. - -### User Roles - -The [user roles](/refguide8/user-roles/) should have logical names that reflect the different types of users that will use the application. The user roles are singular and use an UpperCamelCase notation, like **FunctionalAdministrator**. User roles are mostly defined in English, but there is an option to name these in a different language, since the user role is visible in the front end. - -Each user role should correspond to only one module role per module. In other words, a user role should not map to multiple module roles within the same module. This helps to keep the number of applicable module roles for a user to a minimum, which reduces complexity in understanding the security model and reduces the performance impact of complex security rules. - -### Passwords and Other Secrets - -Always store secret information in a safe place. A safe place is the database. Use the [Encryption](https://marketplace.mendix.com/link/component/1011) module to encrypt and store and to retrieve and decrypt the information. - -Using either the default value of a constant or the project's configuration setting is unsafe. Both these places are readable by others and visible in the version management copies made by SVN. - -## Naming Conventions - -### Modules - -#### Module Names - -Modules should be treated like standalone replaceable services; for example, the customer module should function as a standalone customer management system as much as possible, replaceable by a different customer management system. Module names should have UpperCamelCase names that identify the responsibility of the module, for example, **CustomerManagement** or **SharePointIntegration**. - -#### Module Roles - -The [module roles](/refguide8/module-security/#module-role) should have logical names that reflect the access they should have within a module. In contrast to the user role, the module role should always be in English, for instance **Administrator** or **Employee**. - -### Domain Model - -#### Entity Names - -Most of the time, an [entity](/refguide8/entities/) reflects a real-world object that people can relate to. Therefore, the entity name should also reflect that object and identify its purpose. There are sometimes project-specific exceptions that lead to creating other types of entity, but that is up to you. The name of an entity is singular since an object is a single instance of the entity. A good example is using **Customer** and not **Customers**. Furthermore, we advise avoiding abbreviations, underscores, mathematical characters or any other special characters in the names of entities. Entity names also use UpperCamelCase, for example, **HousekeepingRecord** or **LogEntry**. - -{{% alert color="info" %}} -Following these entity naming conventions will prevent issues with naming conflicts between modules and entities. For example, if a module named **Customer** contains an entity named **customer** (note the lower-case "c"), there will be a Java compilation error and the app will not run. Renaming the entity to **Customer** will solve the problem. -{{% /alert %}} - -#### Entity Attributes - -The entity [attribute](/refguide8/attributes/) should reflect a property of a real-world object that people can relate to and fits the purpose of that property. We advise avoiding abbreviations, underscores (except in the case described in the next paragraph), mathematical characters or any other special characters in the names. Entity attributes should use UpperCamelCase, for example, **FirstName** or **TelephoneNumber**. - -Attributes that do not reflect business-related data, but are only necessary for technical reasons, should start with an underscore (`_`). - -{{% alert color="info" %}} -A strong indicator for determining whether or not an attribute is business-related is whether you would still capture it if you were using a paper-only process. If you would, it is likely that the attribute will deliver business value. -{{% /alert %}} - -#### Associations - -##### Naming Multiple Associations Between Entities - -[Association](/refguide8/associations/) names in the domain model are automatically generated by Mendix. The auto-generated names follow the best practice and should be used by default. - -If you have multiple associations between the same entities Mendix recommends extending the association name. Extending this name with a recognizable purpose clarifies where you should use the association. For example, you can have a relationship between **Person** and **Address**. A person can have multiple addresses but you want to specify what their postal address is and what their delivery address is. An implementation choice could be that you create two associations for that purpose and adjust the names of the associations accordingly. For example, **Person_Address_Delivery**. - -##### Renaming Entities - -When an association already exists between entities and you change the name on one or both of the entities, Mendix will rename the association automatically. - -With models built in lower versions of Mendix, however, you will need to manually rename the association to keep your model consistent and up-to-date. - -### Folders - -The structure for your documents starts with a clear separation of folders. By using a good folder structure you will improve the maintainability of your application; you will be able to find required documents faster and therefore will be able to develop and fix faster. - -The optimal grouping of your documents into folders depends on the circumstances and on the functionality of your application. Mendix recommends combining the guidelines below in a way that fits your project. - -#### Process-Related Sources - -Every project consists of processes. Structure your documents for these processes into folders that reflect individual processes and their steps. - -#### Entity-Related Sources - -Every project has documents that are needed for specific entities. Think of overview pages for maintenance, validation microflows that prevent commits, or other event triggers. These types of document should be structured into one folder that is named after the entity. Optionally, sub-folders could be used to organize, for example, **events** and **pages**. - -### Microflows - -Generally, [microflow](/refguide8/microflows/) names should include the type of event which triggers them, the name of the main entity being processed, and the operation being performed: **{Prefix}\_{Entity}\_{Operation}**. For example, **Act_Vendor_StartWorkflow**. - -There are exceptions, such as where there is no main entity, or there is another reason to use a different name to improve understandability. The important thing is to make sure the name of the microflow clearly indicates its purpose. - -To easily find and recognize the purpose of a microflow, you can use standard prefixes. Common purposes or events and their standard prefixes are listed below. If a microflow is triggered by several events, consider using more than one prefix. If a microflow does not comply to any of the patterns listed below, it should not have a prefix. - -#### Entity Event Microflows - -For some entities you use entity [events](/refguide8/events/) that are always triggered when a specific operation is executed on the entity. - -For example, an attribute **TotalOrderAmount** is automatically filled based on the amount values of the order-related order lines. You can define an after-commit event that ensures that **TotalOrderAmount** is updated when a related order line is saved: *ACo_Order_CalculateTotalOrderAmount*. - -The microflows related to such an event handler should have the following prefixes: - -| Event Type | Prefix | -|-----------------|----------------------| -| Before commit | BCo\_{Entity name} | -| After commit | ACo\_{Entity name} | -| Before create | BCr\_{Entity name} | -| After create | ACr\_{Entity name} | -| Before delete | BDe\_{Entity name} | -| After delete | ADe\_{Entity name} | -| Before rollback | BRo\_{Entity name} | -| After rollback | ARo\_{Entity name} | - -#### Calculated Attribute Microflows - -For attributes, you can choose to store the value in the database or to calculate the value based on a microflow. For the microflow which does the calculation you should use **Cal_** as a prefix, and refer to the entity and attribute which is being calculated. The calculation is triggered when you show the entity on a page or use it in a microflow. On a page, the object's calculation attribute refreshes if you navigate away from the object and back to it in any way (via pagination buttons or tabs or by re-entering the page). - -| Event Type | Prefix | -|-----------------|----------------------| -| Calculation | Cal\_{Entity name}\_{Attribute name} | - -#### Page-Based Microflows - -[Pages](/refguide8/pages/) have a number of events that can trigger a microflow. See the following list for the examples and prefixes: - -| Event Type | Prefix | Used In | -|---------------------------|--------------------|---- | -| On enter event | OEn\_{Purpose} | Input widgets | -| On change event | OCh\_{Purpose} | Input widgets | -| On leave event | OLe\_{Purpose} | Input widgets | -| Data source | DS\_{Purpose} | Data view, list view, data grid, template grid | -| Action button | Act\_{Purpose} | Menu item, navigation item, microflow and action button, drop-down button
(“IVK\_” is used historically) | - -#### Validation Microflows - -Microflows that are used for [data validation](/howto8/data-models/setting-up-data-validation/) use the prefix **Val_**. - -| Event Type | Prefix | -|-----------------|----------------------| -| Validation | Val\_ | - -#### Scheduled Event Microflows - -For the microflow that you use in your [scheduled events](/refguide8/scheduled-events/), use the prefix **ScE_**. The event itself should have a descriptive name since it will be shown in the cloud configuration portal. The scheduled event and the microflow should have the same name. - -| Event Type | Prefix | -|-----------------|----------------------| -| Scheduled Event | ScE\_ | - -#### Project Microflows - -Your [project settings](/refguide8/project-settings/) provide three events that can trigger a microflow. In these cases we advise writing out the purpose as a microflow name. These microflows are defined only once per project and should preferably call sub-microflows to do the actual processing. These sub-microflows should have a prefix indicated below: - -| Event Type | Microflow Name | Sub-microflow Prefix | -|-----------------|----------------|----------------------| -| After startup | AfterStartUp | ASu\_ | -| Before shutdown | BeforeShutDown | BSd\_ | -| Health check | HealthCheck | HCh\_ | - -#### Unit Test Microflows - -Microflows containing [unit tests](/howto8/testing/testing-microflows-using-the-unittesting-module/) should have the prefix **Test_**. - -| Event Type | Prefix | -|-----------------|----------------------| -| Unit Test | Test\_ | - -#### Integration Microflows - -For integrations, you have the following types of microflow: - -| Event Type | Prefix | -|-------------------------------------------|--------| -| Consumed web service operation microflow | CWS\_ | -| Published web service operation microflow | PWS\_ | -| Published app service operation microflow | PAS\_ | -| Published REST service operation microflow | PRS\_ | - -### Other Document Types - -#### Layouts and Snippets - -[Layouts](/refguide8/layout/) and [snippets](/refguide8/snippet/) should be identified with prefixes. - -| Document Type | Prefix | -|-------------------------------------------|-----------| -| Layout | Lay\_ | -| Snippet | Snip\_ | - -#### Enumerations - -[Enumerations](/refguide8/enumerations/) should be identified with a prefix. - -| Document Type | Prefix | -|-------------------------------------------|-----------| -| Enumeration | Enum\_ | - -#### Pages - -Pages use a **suffix** to indicate their use. - -Pages that show an [overview](/howto8/front-end/create-your-first-two-overview-and-detail-pages/) of a single entity should have a suffix of **_Overview**. - -Pages that are to create, edit, or view entity data, and that are not part of a process, should have the suffix **_New**, **_Edit**, **_NewEdit**, or **_View**. - -Pages that are used to make a selection of one object have a suffix of **_Select** where the multi-object selection pages should have the suffix **_MultiSelect**. - -Pages that are used as a tooltip page should have the suffix **_Tooltip**. - -| Page Purpose | Suffix | -|-------------------------------------------|--------| -| List objects of a single entity type | \_Overview | -| Create an object | \_New | -| Update an object | \_Edit | -| Create *or* Update an object | \_NewEdit | -| View an object (read-only) | \_View | -| Select a single object | \_Select | -| Select multiple objects | \_MultiSelect | -| Tooltip | \_Tooltip | - -#### Integration Documents - -Documents used to support integration should have the prefixes listed below. - -| Document Type | Prefix | -|-------------------------------------------|--------| -| Import mapping | ImM\_ | -| Export mapping | ExM\_ | -| XML schema definition | XSD\_ | -| JSON structure | JSON\_ | -| Deeplink | Dl\_ | - -### Home Pages - -You can define the [home pages](/refguide8/show-home-page/) per device and role in your navigation. The recommended page names are listed below: - -| Event Type | Device | Page Name | -|----------------------|---------|-----------------------------| -| Default home page | Desktop | Home_Desktop\_Default | -| Default home page | Tablet | Home_Tablet\_Default | -| Default home page | Mobile | Home_Phone\_Default | -| Role based home page | Desktop | Home_Desktop\_{Userrole} | -| Role based home page | Tablet | Home_Tablet\_{Userrole} | -| Role based home page | Mobile | Home_Phone\_{Userrole} | - -## General Guidelines and Best Practices - -### Domain Models - -#### Attributes {#attributes} - -Using calculated (virtual) attributes is discouraged. These introduce a performance risk since they need to be calculated every time the object is used, regardless of whether the attribute itself is used. - -#### Inheritance {#inheritance} - -When using inheritance (specialization/generalization), it is recommended to use no more than two levels for performance reasons. - -#### Delete Behavior - -[Delete behavior](/howto8/data-models/create-a-basic-data-layer/#delete-behavior) must be specified where possible. Delete behavior must, however, never be relied upon when deleting large amounts of data. For performance reasons it is better to explicitly delete dependent objects when doing batch deletes. - -#### Event Handlers - -[Event handlers](/refguide8/event-handlers/) on domain entities must be used with a lot of caution. They can quickly result in complex and possibly unexpected behavior when several of them are applied to a single entity. It is often best to make the execution of microflows more explicit by using sub-microflows that are called manually, for example, just before committing an object. - -### Microflows - -#### Size {#size} - -The size of a microflow should not exceed 25 elements. An element is any block that Studio Pro allows in a microflow (loops, action activities, decisions, etc.). In some cases exceeding this limit is acceptable; this can occur, for instance, for validation or data copying flows. - -Split microflows up into logical, functional elements. If a microflow has more than twenty-five elements, split the microflow up by creating a sub-microflow for a part of it. For example, by separating presentation logic from business logic. - -Certain cases (such as validation checks) may require this rule to be ignored to produce an understandable result. - -#### Documentation and Annotations {#documentation-and-annotations} - -All complex microflows (more than ten activities or more than two decisions) should have an [annotation](/refguide8/annotations/) describing the purpose of the microflow, expected parameters, and return values. This annotation should be placed at the start, so it is visible when the microflow is opened. This will assist other developers in quickly understanding the general purpose of a microflow, without having to read through it entirely. - -Complex, non-standard or integration-related sections in microflows should also have an accompanying annotation. Examples of these are web service calls, custom loops, and Java calls. - -#### Readability - -The normal flow in a microflow should be aligned from left to right to ensure readability. Exceptions to the normal flow may branch out vertically: downwards is preferred, upwards if the downwards direction is already used. - -Avoid crossing of lines of the links between the microflow elements. - -If you decide to color code the different activities in your project, be sure to align within your team on their meaning. - -#### Complexity - -Nested `IF` statements in a single microflow expression are not recommended. If multiple checks depend on one another, this should be represented by multiple decisions in the microflow, so that the complexity is not hidden away in the expressions. You can use `AND` and `OR` operators to produce complex expressions if necessary. - -Event triggers on input fields must be kept as simple as possible, since they are potentially executed very often, depending on user behavior. Complex operations here will reduce performance. - -The number of parameters for a microflow should be kept to a minimum to facilitate reusability. The more parameters a microflow has, the more difficult it is to determine what should be put into the parameters to make the microflow run correctly. - -#### Error Handling and Logging - -Use microflow [error handling](/howto8/logic-business-rules/set-up-error-handling/) for all integration and Java calls. Make sure to determine the correct rollback behavior. Always log the error that occurred, even if the process can continue, this is essential for later analysis of the error. - -Complex processes and important business logic (like workflow processing or validations) must include debug and trace [logging](/refguide8/logging/). Logging actions must write the current state and progress of the process and must include a request ID or other identifying information. The log node should be the name of the module. This will greatly assist error analysis. - -#### Validating Inputs in Microflows - -When microflows are invoked from the client side, it is important to validate the inputs. By having validations, you prevent incorrect, inappropriate, or potentially harmful data from being used in your microflows. This protects your application against security vulnerabilities. The following presents the best practices regarding the integrity and validation of inputs in your microflows. - -##### Implementing Validation Checks - -Adding validation checks is vital for ensuring that input data conforms to the expected data type, format, range, or other application-specific constraints. For instance, if a numeric input is expected within a defined range, validation checks should confirm that the input is indeed numeric and falls within the specified range. - -##### Managing Unexpected Values - -When building microflows, it is important to account for the potential occurrence of unexpected values. These could be empty values, or values outside the expected range or format. It is also important to ensure that read-only attributes only contain expected values. - -{{% alert color="warning" %}} -We strongly recommend adding validation checks to all microflows inputs, including read-only attributes. - -We also recommend avoiding storing intermediary values in attributes (such as, *TotalPrice*). Instead, calculate these values when needed to ensure you have the correct values. -{{% /alert %}} - -Microflows should incorporate mechanisms to detect unexpected values and respond suitably – this might involve returning an error message to the end-user or executing a fallback operation. - -##### Updating Validation Logic Regularly - -As the application evolves, the validation logic within microflows should be updated accordingly to reflect changes in business logic or data models. This regular review and update of validation checks ensures that microflows remain secure and function correctly over time. - -By prioritizing the validation of inputs in microflows, you not only enhance the security of your application, but also ensure a more predictable and stable user experience. This practice underscores the development of reliable and robust applications. - -### Warnings and Studio Pro Feedback - -No warnings should be visible in Studio Pro, unless explicitly documented with a reason. Warnings can indicate many issues, including maintainability and security risks, which must be resolved. - -Unused and excluded items should be removed from the model when they are no longer needed. When a version of the application is prepared for a release, all these items should be cleaned up. Make sure to check whether items that appear unused are not actually called from a Java action before removing them. Studio Pro provides the possibility to mark such items as used to override warnings about this. - -### XPath - -[XPath](/refguide8/xpath/) constraints in any part of the model should be kept as simple as possible. As a general rule, XPaths must not appear when the **Find advanced > XPath** option in Studio Pro is used with all options enabled. - -### Security - -The [security](/howto8/security/) overview in Studio Pro must not show any incomplete (yellow) parts. All entity, microflow, and page access must be configured completely. - -Assigning default rights to new members when defining entity access is NOT recommended. This will ensure that access is only granted after a conscious decision. - -### Mendix Version - -Apps should keep up with new Mendix releases as much as possible. - -### Marketplace Content - -When introducing a new [Mendix Marketplace](https://marketplace.mendix.com/) component to a project, carefully consider the support level of the component. Using components that are community supported introduces a maintainability and upgrade risk. - -Marketplace modules should NOT be modified. If a Marketplace module is modified, updating to a new version becomes much harder, because the changes will be overwritten when a new version is downloaded from the Marketplace. If changing an Marketplace module is unavoidable, you have two options: - -* Mark any changes you make explicitly and clearly, and perform them again when the module is updated -* Copy the contents of the Marketplace module to another module in your app and use that module instead (remember that your app will no longer reflect updates to the original Marketplace module) - -To minimize the number of changes in the actual Marketplace module, it is advisable to combine them in a separate extension module wherever possible. diff --git a/content/en/docs/howto8/general/install.md b/content/en/docs/howto8/general/install.md deleted file mode 100644 index b9be088e633..00000000000 --- a/content/en/docs/howto8/general/install.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "Install Mendix Studio Pro" -url: /howto8/general/install/ -weight: 10 -description: "Follow this how-to to learn how to install Mendix Studio Pro." ---- - -## Introduction - -Mendix Studio Pro enables you to build apps on the Mendix Platform. This how-to will guide you through the steps of installing the latest version of Mendix Studio Pro. If you use a Mac device, see [Configure Parallels](/howto8/general/using-mendix-studio-pro-on-a-mac/) to configure your Windows virtual machine. - -For a deep-dive demonstration of how to install Studio Pro, follow along in this video: - -{{< vidyard id="WUp2tLi68nXFQd7xhPbDtt" >}} - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* A Windows environment to install Studio Pro (For the full list of supported systems and required frameworks, see [System Requirements](/refguide8/system-requirements/)) - -## Downloading Mendix Studio Pro - -Mendix Studio Pro can be installed on your machine with a Windows executable file. This executable file can be downloaded from the Mendix Marketplace. Follow these steps to download Mendix Studio Pro: - -1. Go to the Studio Pro download page in the [Mendix Marketplace](https://marketplace.mendix.com/link/studiopro/). -2. Click the **Download** button in the upper-right corner to download the latest Mendix Studio Pro. - -## Installing Mendix Studio Pro {#install} - -Mendix Studio Pro needs to be installed on your computer before you can start building apps. Follow these steps to install Mendix Studio Pro: - -1. Open the downloaded Mendix Studio Pro executable. It is named like this: *Mendix-8.X.X-Setup*. Then click **Next**: - - {{< figure src="/attachments/howto8/general/install/setup-wizard.png" class="no-border" >}} - -2. Select **I accept the terms in the License Agreement** and click **Next**: - - {{< figure src="/attachments/howto8/general/install/terms-of-use.png" class="no-border" >}} - -3. Select the folder in which you want to install Studio Pro and click **Next**: - - {{< figure src="/attachments/howto8/general/install/select-folder.png" class="no-border" >}} - -4. Enter the start menu shortcuts folder you want to use and click **Next**: - - {{< figure src="/attachments/howto8/general/install/shortcut-folder.png" class="no-border" >}} - -5. Check the **Desktop** option to create a shortcut to Studio Pro on your desktop and click **Next**: - - {{< figure src="/attachments/howto8/general/install/location.png" class="no-border" >}} - -6. Click **Install** to install Studio Pro on your computer: - - {{< figure src="/attachments/howto8/general/install/ready-to-install.png" class="no-border" >}} - -7. Check **Launch Mendix 8.X.X** and click **Finish** to finish the installation and launch Studio Pro: - - {{< figure src="/attachments/howto8/general/install/completing-setup.png" class="no-border" >}} - -## Troubleshooting {#troubleshooting} - -Sometimes you can run into problems when installing Studio Pro. One work-around is to restart your system and install the prerequisites separately if they are not installed yet. - -The prerequisites are the following: - -* [Microsoft .NET Framework 4.7.2](https://dotnet.microsoft.com/en-us/download/dotnet-framework/net472) -* Java JDK - * For Mendix Studio Pro 8.18.29 and above [Eclipse Temurin JDK 17](https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.10%2B7/OpenJDK17U-jdk_x64_windows_hotspot_17.0.10_7.msi) - * For Mendix Studio Pro 8.18.28 and below [AdoptOpenJDK 11](https://cdn.mendix.com/installer/AdoptOpenJDK/OpenJDK11U-jdk_x64_windows_hotspot_11.0.3_7.msi) -* [Microsoft Visual C++ 2010 SP1 Redistributable Package](https://download.microsoft.com/download/1/6/5/165255E7-1014-4D0A-B094-B6A430A6BFFC/vcredist_x64.exe) -* [Microsoft Visual C++ 2015 Redistributable Package](https://download.microsoft.com/download/6/A/A/6AA4EDFF-645B-48C5-81CC-ED5963AEAD48/vc_redist.x64.exe) -* [Mendix Native Mobile Builder one-click Installer](https://artifacts.rnd.mendix.com/native-builders/latest.exe) - -Based on the error message you get from the installer you can decide to install a single prerequisite, or you can try to manually install them all. - -After that you can retry installing Studio Pro. - -## Installing Mendix Studio Pro Offline {#offline} - -The Mendix Studio Pro installation experience includes all the tools and frameworks required to run the application. If any of the prerequisites are not found at the moment of installation, the Studio Pro setup process will attempt to download and install the missing elements automatically. The Mendix Studio Pro installer does not include all dependencies and relies on internet connectivity to obtain them if any of the required pieces of software are missing. - -It is possible to prepare the prerequisite installers beforehand, so that the Mendix Studio Pro setup process can pick them up instead of downloading from the remote location. Follow these steps to prepare the installers: - -1. Create a folder for the Mendix Studio Pro installer. -2. Download the latest [Mendix Studio Pro installer](https://marketplace.mendix.com/link/studiopro/) and move it into folder you created. -3. Create a folder with the name **Dependencies** in the same location where the Mendix Studio Pro installer was placed. -4. Download the prerequisites listed in the [Troubleshooting](#troubleshooting) section above and move them into the **Dependencies** folder. -5. Rename the following dependencies: - * The `.NET Framework 4.7.2` executable to `dotnetfx472.exe` - * The Java Development Kit 11 or 17 (x64) *msi* (for example, *OpenJDK17U-jdk_x64_windows_hotspot_17.0.10_7.msi*) to one of the following, depending on the Studio Pro version: - * *adoptiumjdk_17_x64.msi* – for versions 8.18.29 and above - * *adoptopenjdk_11_x64.msi* – for versions 8.18.28 and below - * The `Visual C++ 2010 SP1 Redistributable (x64)` executable to `vcredist2010_x64.exe` - * The `Visual C++ Redistributable for Visual Studio 2015 (x64)` executable to `vcredist2015_x64.exe` - * The `latest` executable to `mendix_native_mobile_builder.exe` -6. Run the installer as described in the [Installing Mendix Studio Pro](#install) section above. - -## Read More - -* [Studio Pro Overview](/refguide8/studio-pro-overview/) -* [App Modeling](/refguide8/modeling/) diff --git a/content/en/docs/howto8/general/minimize-number.md b/content/en/docs/howto8/general/minimize-number.md deleted file mode 100644 index a310b45f799..00000000000 --- a/content/en/docs/howto8/general/minimize-number.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: "Minimize the Number of In-Use Objects in Your Session" -linktitle: "Minimize Objects in Session" -url: /howto8/general/minimize-number/ -weight: 6 ---- - -## Introduction - -Mendix has a completely stateless architecture. All the application state that was kept in the Mendix Runtime in earlier versions is now kept by the Mendix Client in the browser. By *state* we mean non-persistable entities (NPEs) and persistable entities that have not yet been committed to the database. - -This new approach has important advantages, such as the ability to easily scale the app horizontally. However, there are also some new things to keep in mind when developing for this new architecture, in order to prevent performance degradation of the Mendix Client. - -## Overview - -The stateless architecture means that all temporary objects are stored in the Mendix Client (browser) instead of the Mendix Runtime. However, since the objects are used in microflows, the Mendix Runtime will need them to be able to execute a microflow. For this reason, the state is transferred by the browser to the server when a request is sent. - -The Mendix Client that runs in the browser determines which objects are relevant for the current page and microflows you want to execute. It does this based on the possibility of retrieving objects from the microflow parameters by following the relations from that object. Only objects that can be retrieved are transferred to the server to optimize performance. However, since there are many flexible ways to retrieve objects, Mendix must be conservative in this. There will often be more objects sent than are strictly necessary to be able to execute a microflow. - -After a microflow has run, any new objects or updates to existing objects that were made are returned to the Mendix Client. The Mendix Client can then update its state and refresh any objects on the current page if necessary. This is only done for NPEs and for persistable objects that are on the current page. - -The following diagram shows the flow of objects in detail: - -{{< figure src="/attachments/howto8/general/minimize-number/object_flow.png" class="no-border" >}} - -## Minimizing the Number of In-Use Objects in Your Session - -Because all the objects necessary for a microflow are transferred between the Mendix Client and server for each request, the network traffic will grow when more objects are used at the same time. This can become a bottleneck, especially on mobile devices. - -That is why the primary best practice for app performance is to minimize the number of in-use objects in your session. By *in-use objects* we mean non-persistable objects and uncommitted persistable objects. - -It is not possible to eliminate the need for in-use objects entirely, unless you want your app to be completely read-only. However, there are several common ways to inadvertently create more objects than necessary. The rest of this document presents ways to reduce the number of in-use objects. - -## Changed Objects - -### Scenario - -To the Mendix Runtime there is very little difference between a non-persistable object and a persistable object that is changed but not committed. Any changes that are not committed at the end of a browser request will be sent to the Mendix Client for use in future requests. - -### Tip - -To minimize the number of objects for which this is the case, committing or rolling back the changes to persistable objects before the end of the main microflow is recommended. - -Any changes that are not committed when a main microflow ends will be sent to the Mendix Client and become part of the Mendix Client state which is stored there. In that case, they will also contribute to the size of future requests where they need to be sent back to the Mendix Runtime. - -If you make sure to commit any changes to persistable objects, they do not need to be sent to the Mendix Client if they are not shown on a page. When they are subsequently needed in a microflow, they do not need to be sent by the Mendix Client, because the Mendix Runtime can just retrieve them from the database. - -In other words, by reducing the number of requests during which objects are not committed, you reduce the network traffic necessary to use the app. - -## Workflow Objects - -### Scenario - -If an object is used during a flow that spans multiple pages but is not displayed on every one of those pages, the Mendix Client could incorrectly determine that the object is not necessary anymore. This situation can also happen if you allow users to navigate backwards through a flow using the **Close** button or a browser's **Back** button. In that case, the objects on the page that was previously displayed might have been removed already. - -### Tip - -To prevent this from occurring, you can link non-persistable objects that have long life spans to the current session object. - -To do this, first create a reference between your entity and the **Session** entity in the **System** module: - -{{< figure src="/attachments/howto8/general/minimize-number/domain_model_npe.png" class="no-border" >}} - -Then link the object to the current session when you create it in a microflow: - -{{< figure src="/attachments/howto8/general/minimize-number/create_object_dialog.png" class="no-border" >}} - -Because it is always possible to look at the current **Session** object, any objects related to the current session can also always be retrieved. The Mendix Client must then always keep these objects around; they will never be removed. - -{{% alert color="info" %}} -There is a drawback here as well: since the objects will never be removed, they will be in memory indefinitely. It is very important to remove these objects as soon as they are not necessary anymore. -{{% /alert %}} - -## Integrations - -### Scenario - -When dealing with web or app-service integrations, you will often use non-persistable entities to model requests and responses. For more complex integrations, this can quickly become a complex domain model with a lot of entities. When calling the service, many objects can be created. There are often cases where developers map an entire web service response to a large domain model, only to use a small part of the message in a microflow. - -Building an integration as described above will cause all objects that are created to be sent to the Mendix Client as well. - -### Tip 1 - -To deal with the above scenario, map only those parts of a web service integration that are necessary. - -By minimizing the number and size of the objects that are created, you reduce the amount of objects that are necessary for the Mendix Client. - -### Tip 2 - -In some cases, there will be objects that are necessary for a microflow to function, but that are not shown on any page in the app. In that case, they will still be sent to the Mendix Client, since Mendix cannot always determine if they will not be used by widgets and such. For that reason, you should delete non-persistable objects as soon as they are no longer necessary. - -This goes especially for microflows related to integrations: as soon as the message has been sent, or the response has been processed, you should remove the objects related to the call. Of course, you should keep the objects that are subsequently displayed on a page. A useful way to easily remove everything related to a service call is to apply delete behavior in your domain model. - -## Layouts - -### Scenario - -Be careful when using non-persistable objects in layouts. Since layouts can be used for many pages in your app, objects in layouts can be on the screen for a long time. If you use non-persistable objects here, they will be sent back and forth between the Mendix Client and Mendix Runtime very often, since they are always available. - -### Tip - -To deal with the above scenario, do not use non-persistable objects in layouts. - -This will reduce the number of in-use objects. The same goes for non-persistable objects that are not directly used in a layout, but have a reference to objects in a layout. Since they can be retrieved via the object in the layout, they will live as long as that object. This should be avoided too. - -## Summary - -In the Mendix stateless architecture, the application is kept by the Mendix Client in the browser. All temporary objects are stored in the browser instead of the Mendix Runtime. State is transferred by the browser to the server when a request is sent, and back when the request finishes. - -We have identified some tips for Mendix developers to take advantage of this architecture: - -* Minimize the number of in-use objects in your session -* Commit or roll back all changes to persistable objects before the end of the main microflow -* Link non-persistable objects that have long life spans to the current **Session** object -* Map only those parts of a web service integration that are necessary -* Delete any non-persistable objects as soon as they are no longer necessary -* Do not use non-persistable objects in layouts diff --git a/content/en/docs/howto8/general/setting-up-the-navigation-structure.md b/content/en/docs/howto8/general/setting-up-the-navigation-structure.md deleted file mode 100644 index 127ff7745be..00000000000 --- a/content/en/docs/howto8/general/setting-up-the-navigation-structure.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: "Set Up the Navigation Structure" -url: /howto8/general/setting-up-the-navigation-structure/ -weight: 3 ---- -## Introduction - -Once you created some pages, it is important that your users can access them. For this, you need to create a navigation menu. The navigation editor of Studio Pro allows you define the navigation menu for different type of apps and devices for example, for responsive, tablet browser, hybrid phone, or native mobile apps. It also allows you to define which page is shown as a default home page depending on the user role. - -## Prerequisites - -Before starting this how-to make sure you have completed the following prerequisites: - -* [Create a basic data layer](/howto8/data-models/create-a-basic-data-layer/) -* [Create your first two Overview and Detail pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/) - -## Setting a Default Home Page {#home} - -This section will explain how to set the default home page. - -{{% alert color="info" %}} - -Note that the **Default home page** setting is overridden by a **Role-based home page** if you configure it. For more information, see the [Setting a Role-Based Home Page](#role-based-home-page). - -{{% /alert %}} - -Do the following: - -1. Open **Project** > **Navigation**. - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/open-navigation.jpg" class="no-border" >}} - -2. Some navigation profiles are open in a tab by default, for example, the **Responsive** one. To open other navigation profiles, do the following: - - 1. Click **Add navigation profile**, select the profile type depending on the type of the interface you are working on: - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/add-navigation-profile.jpg" class="no-border" >}} - - 2. Click **OK**. - -3. In **Home pages** > **Default home page**, click **Select**. -4. Select the page you want to use as the default home page. The example below uses *_Web*: - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/select-home-page.jpg" class="no-border" >}} - -5. Click **Select**. - -{{% alert color="info" %}} - -You can also select a microflow as a default home page. Make sure that the microflow contains a *Show Form* activity, otherwise the user will not see anything. - -{{% /alert %}} - -Now every time a user signs in to the application, the selected page/microflow is shown/triggered. - -## Setting a Role-Based Home Page {#role-based-home-page} - -In many cases you would like users with different roles to see different home pages. You can use role-based home pages for this. You do not need to configure home pages for every role, because the default home page works as a fall-back mechanism. - -Follow the steps below: - -1. Open the **Navigation** editor. -2. Open the profile type depending on the interface type you are working on. -3. In **Home pages** > **Role-based home pages**, click **Edit**. -4. In the **Role-based home pages** dialog box, click **New**. -5. Select a user role to create a new setting, for example, select the **Administrator** role: - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/select-user-role.png" class="no-border" >}} - -6. Click **Select**. -7. After you have selected the user role, click the **Select target** button. - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/select-target.png" class="no-border" >}} - -8. Select the home page for selected user role, for example, the **Account_Overview** page: - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/select-page.png" class="no-border" >}} - -9. Click **Select**. - -Now every time a user with the **Administrator** user signs in to the application, the **Account_Overview** page is shown. Users with other roles will be redirected to the default home page. - -## Creating Menu Items - -You can create menu items for your navigation. Do the following: - -1. Open the **Navigation** editor. -2. Open the profile type depending on the interface type you are working on. -3. In the **Menu** section, click **New item** to create a top level menu item. -4. Enter a **Caption** for your menu item. In the example below, the menu item is named *Customer Overview* after a page this menu item will open. -5. Select a page or microflow as a target: - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/new-menu-item.png" class="no-border" >}} - -6. Click **OK** to save the menu item. - -In the overview of menu items you can see the name of the menu item, the target page/microflow, and the user role are the necessary settings to be configured for the menu item. The user roles are derived from the [page and microflow access settings](/refguide8/module-security/). - -You can restructure the menu by dragging and dropping menu items. - -## Adding Navigation Menu to Pages - -Now that you have created a menu structure it is time to start using it on pages. Do the following: - -1. Open a page. -2. Click **Add widget** and select **Menu bar**: - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/select-menu-bar.png" class="no-border" >}} - -3. Select a place on the page to add the widget. - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/add-widget.png" class="no-border" >}} - -4. Open the **Properties** pane. -5. In **General** > **Menu source**, select **Project navigation**. This is the navigation structure defined in the navigation editor. (You can also add additional menu structures using menu documents.) - - {{< figure src="/attachments/howto8/general/setting-up-the-navigation-structure/menu-bar-properties.jpg" class="no-border" >}} - -6. In **Profile**, select the profile type depending on the device type. **Responsive** is selected by default. - -The menu widget is now showing the navigation items created in the navigation editor. - -To avoid adding the menu widget on every page in your project, you can use a layout. With layouts you can define a structure for pages in your project. You can define where the menu should be rendered and you can simply reuse that layout for all or several pages. For more information on how to use layouts, see [How to Use Layouts and Snippets](/howto8/front-end/layouts-and-snippets/). - -## Read More - -* [Atlas UI](/howto8/front-end/atlas-ui/) -* [Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/) -* [Use Layouts and Snippets](/howto8/front-end/layouts-and-snippets/) -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) diff --git a/content/en/docs/howto8/general/using-mendix-studio-pro-on-a-mac.md b/content/en/docs/howto8/general/using-mendix-studio-pro-on-a-mac.md deleted file mode 100644 index ca9821ab205..00000000000 --- a/content/en/docs/howto8/general/using-mendix-studio-pro-on-a-mac.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: "Configure Parallels" -url: /howto8/general/using-mendix-studio-pro-on-a-mac/ -weight: 2 -description: "This how-to will allow you to start making Mendix native mobile apps on your Mac device." ---- - -## Introduction - -Using Parallels, you can run Mendix Studio Pro on your Mac device using a Windows virtual machine. - -{{% alert color="warning" %}} -To run Studio Pro on Apple Silicon Macs, such as the M1(X), an LTS version starting from Mendix Studio Pro 8.18.14 is required. For more information, see [System Requirements](/refguide8/system-requirements/). -{{% /alert %}} - -To start making Mendix native mobile apps on your Mac, follow this how-to. - -This how-to teaches you how to do the following: - -* Configure your Windows virtual machine for Mendix Studio Pro -* Run a Mendix app on a test device using your Windows virtual machine -* Make changes to your app, then view those changes on your test device - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install [Parallels Desktop Pro Edition](https://www.parallels.com/products/desktop/pro/), install Windows when prompted by Parallels, and create a Windows virtual machine (Parallels Desktop Pro Edition is necessary for Mendix's network features to work) -* Install Mendix Studio Pro on your Windows virtual machine - -## Configuring Your Windows Virtual Machine for Mendix Studio Pro - -To configure your Windows virtual machine to work with Mendix Studio Pro, follow these steps: - -1. Open your Parallels **Control Center**: - - {{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/windows-control-center.png" alt="parallels control center" width="450" class="no-border" >}} - -2. Click **Configuration** ({{% icon name="cog" %}}) to open the **Configuration Panel**. -3. Navigate to the **Hardware** tab, and select **Network** from the left panel: - - {{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/windows-configuration.png" alt="network in configuration" width="450" class="no-border" >}} - -4. Make sure **Source** is set to **Shared Network**. -5. Make sure that both the **Inbound** bandwidth and **Outbound** bandwidth show **unlimited**. - - If this is not the case, either enable **Network Conditioner** and set it to a profile that does not limit bandwidth, or click the **Options** tab then the **Optimization** pane and set **Resource usage** to **No limit**. -6. In the Parallels drop-down menu, select **Preferences**: - - {{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/preferences-dropdown.png" alt="preferences in parallels" width="400" class="no-border" >}} - -7. Navigate to the **Network** tab, and select **Shared** from the left panel: - - {{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/parallels-preferences-no-ports.png" alt="network tab" width="450" class="no-border" >}} - -8. Click the {{% icon name="add" %}} button and add two ports: one for 8080 and one for 8083, both forwarded to your Windows virtual machine (the 8083 port is only necessary for developing native mobile apps): - - {{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/port-setup.png" alt="plus button" width="450" class="no-border" >}} - - After adding those two ports, your **Port forwarding rules** should look like this: - - {{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/parallels-preferences-ports.png" alt="finished ports" width="450" class="no-border" >}} - -Congratulations! You have successfully configured port forwarding to enable testing Mendix apps with your Mac. - -## Checking Network Drive - -{{% alert color="warning" %}} -Whenever you create or open a Mendix app in Mendix Studio Pro, be sure to do so from a mapped drive instead of a network drive. -{{% /alert %}} - -Read the tips below to check the network drive before viewing your app on your testing device: - -* Correct mapped drives will always have a letter at the start of their file location: - - {{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/mapped-drive.png" alt="mapped drive" width="450" class="no-border" >}} - -* Incorrect network drives will always have **\\** at the start of their file location: - - {{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/network-drive.png" alt="network drive" width="450" class="no-border" >}} - -## Viewing Your App on Your Testing Device - -When running your app on your test device, you cannot use the QR code within Mendix Studio Pro's **View Mobile App** dialog box: - -{{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/view-mobile-app.png" alt="view mobile app" width="400" class="no-border" >}} - -Instead, you must enter your Mac's IP address into your Make It Native app. To run your app on your test device, follow the steps below: - -1. Make sure your test device and Mac are on the same Wi-Fi network. - -2. Place your cursor over your Wi-Fi symbol in your system tray, then and click while holding Option to see your Mac's advanced network information. You will see your **IP Address** in this drop-down menu. - -3. In your Make It Native app's **Host** field, type `{your IP address}:8080` like this: - - {{< figure src="/attachments/howto8/general/using-mendix-studio-pro-on-a-mac/ip-in-dev-app.png" alt="ip in dev app" width="300" class="no-border" >}} - -4. Tap **Launch** to view your app. - -Congratulations! You have successfully viewed your app on a test device. - -## Viewing Changes to Your App on Your Testing Device - -For information on how to change to your app and then see that change on your device, see the [Viewing Changes to Your App on Your Testing Device](/howto8/mobile/getting-started-with-native-mobile/#viewingchanges) section in *Get Started with Native Mobile*. - -## Improving Performance - -To improve the performance, you can do the following: - -* Run Parallels in a window, instead of Coherence mode -* Store apps on disk C:\ - -### Increasing Network Speed - -Some users experience slow network speed. You try the following approach, which can increase the upload speed significantly: - -1. In Windows 10/11, navigate to **Start** > **Control Panel**> **Device Manager** > **Network adapters** > **Parallels VirtIO Ethernet Adapter**. - -2. Right-click **Parallels VirtIO Ethernet Adapter** and select **Properties** in the drop-down list. -3. On the **Advance** tab, find the **Large Send Offload** **(IPv4)** property and change its value to **Disabled**. -4. Click **OK**. - -Now the upload speed becomes faster! For more information, see [Parallels Forum](https://forum.parallels.com/threads/horribly-slow-upload-download-speeds.264819/). - -## Read More - -* [Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) -* [Style Your Mendix Native Mobile App](/howto8/mobile/how-to-use-native-styling/) diff --git a/content/en/docs/howto8/integration/_index.md b/content/en/docs/howto8/integration/_index.md deleted file mode 100644 index 9ecc08d6598..00000000000 --- a/content/en/docs/howto8/integration/_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Integration" -url: /howto8/integration/ -weight: 70 -no_list: false -description_list: true -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -Do you want to connect your app to the internet? Learn how to do this by following these how-tos. - -We want to create a large network of Mendix apps, so let's start integrating! - -## Documents in This Category diff --git a/content/en/docs/howto8/integration/access-a-samba-share-from-the-mxcloud.md b/content/en/docs/howto8/integration/access-a-samba-share-from-the-mxcloud.md deleted file mode 100644 index f7dc64d7db9..00000000000 --- a/content/en/docs/howto8/integration/access-a-samba-share-from-the-mxcloud.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Access a Samba Share" -url: /howto8/integration/access-a-samba-share-from-the-mxcloud/ -weight: 11 ---- - -## Introduction - -You can use a Samba connection to pull or push files to a Windows share. When doing this, you need to use a static IP address in the connection string. The library could support the usage of a servername, but that requires extensive configuration to specify the DNS server location, DFS address, etc. It is far more efficient to use the IP address. - -This how-to teaches you how to do the following: - -* Access a Samba share from the MxCloud -* Use a servername instead of an IP address - -## Code Example - -When connecting to a Samba share using a regular username, password, and IP address, the code below with the NTLMFileHandler is sufficient. Based on the SMB configuration and the name of the FileDocument, the FileHandler will connect to the Samba share and pull the document with the same file name. - -```java -public ReadFileFromSMBDrive(SMBConfiguration SMBConfig, FileDocument DocumentParameter1) -{ - super(); - this.SMBConfig = SMBConfig; - this.DocumentParameter1 = DocumentParameter1; -} - -@Override -public Boolean executeAction() throws Exception -{ - // BEGIN USER CODE - - NTLMFileHandler fileHandler = new NTLMFileHandler(getContext(), this.SMBConfig.getDomainName(), this.SMBConfig.getUsername(), this.SMBConfig.getPassword()); - fileHandler.getSingleFile(this.SMBConfig.getImportFolder(), this.DocumentParameter1.getName(getContext()), this.DocumentParameter1.getMendixObject(), this.DocumentParameter1.getDeleteAfterDownload());; - - return true; - // END USER CODE -} -``` - -## Using a Servername Instead of an IP Address - -If you choose to connect to a server based on the server name instead of the IP address, you will have to enable all the properties related to this option. For details on the different WINS properties that need to be specified in order for the library to resolve the domain and the server, see this page: [https://jcifs.samba.org/src/docs/resolver.html](https://jcifs.samba.org/src/docs/resolver.html). - -| Name | Resolution Properties | -| --- | --- | -| **jcifs.netbios.wins** | The IP address of the WINS server (or, more formally, NBNS). This is only required when accessing hosts on different subnets, although it is recomended if a WINS server is being used. | -| **jcifs.netbios.baddr** | The local network's broadcast address. It may be necessary to set this for certain network configurations, because the default 255.255.255.255 may otherwise throw a "Network is unreachable" `IOException`. For example, if the local host's IP address is 192.168.1.15, the broadcast address would likely be 192.168.1.255. | -| **jcifs.resolveOrder** | A comma-separated list of name resolution method identifiers that specify which methods will be used and in what order to resolve hostnames. The possible identifiers are `LMHOSTS`, `WINS`, `BCAST`, and `DNS`. | -| **jcifs.netbios.lmhosts** | The path to an LMHOSTS (LAN Manager Hosts) file containing a map of the IP addresses to hostnames. The format of this file is identical to that of the Windows LMHOSTS file format (with a few exceptions noted below.) | -| **jcifs.netbios.scope** | This is rare, but NetBIOS provides for a "scope ID" to be used in an attempt to conceal groups of machines on the same network. Ask your network administrator if a scope ID is used. If so, it must be set using this property, or the name queries will fail. | - -However, the cloud edit library requires an additional property override. The DFS property is not supposed to be enabled in Mendix Cloud since Mendix Cloud cannot resolve the DFS server by default. If you choose to enable the DFS, you will need to make sure that the server will be able to resolve the DFS based on the domain name and DNS location. - -| Name | Resolution Properties | -| --- | --- | -| **jcifs.smb.client.dfs.disabled** | If this property is true, the domain-based DFS referrals will be disabled. The default value is false, but the cloud-edit version has a default value of true. This property can be important in non-domain environments where domain-based DFS referrals that normally run when JCIFS first tries to resolve a path would timeout, causing a long startup delay (for example, running JCIFS only on a local machine without a network, like on a laptop). | -| **jcifs.smb.client.dfs.ttl** | The time in seconds that DFS topology information should be cached. The default value is 300 seconds (although the trusted domains list is cached for 10: timesjcifs.smb.client.dfs.ttl). | -| **jcifs.smb.client.dfs.strictView** | This property controls how JCIFS behaves if it fails to enumerate DFS roots but succeeds in enumerating shares. By default, this value is false in order to indicate that JCIFS should return the list of shares even if the DFS root enumeration fails. If this value is set to true, an exception will be thrown if the DFS information cannot be successfully retrieved (for example, an SmbAuthException due to insufficient access). | - -The cloud does not allow the properties to be specified using the system properties. Therefore, you will need to specify these through Java, and before initializing any of the JCIFS classes, you will need to specify the exact `Config` options. This can be done by using the following line of code: - -```text -jcifs.Config.setProperty("jcifs.smb.client.dfs.disabled","false"); -``` - -For more details on all the properties, see here: [Setting Client Properties](https://www.jcifs.org/src/docs/api/overview-summary.html#scp). - -## Further Documentation - -* [The Java CIFS Client Library](https://www.jcifs.org) diff --git a/content/en/docs/howto8/integration/consume-a-complex-web-service.md b/content/en/docs/howto8/integration/consume-a-complex-web-service.md deleted file mode 100644 index 4da6518d4e0..00000000000 --- a/content/en/docs/howto8/integration/consume-a-complex-web-service.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: "Consume a Complex Web Service" -url: /howto8/integration/consume-a-complex-web-service/ -weight: 8 ---- - -## Introduction - -This how-to explains how to consume a (third-party) web service with which you can integrate your Mendix application and re-use functionality and data from other applications. Web services are the preferred way of integrating a Mendix application with external systems. They can be used to retrieve data, send updates, and perform operations. In Mendix, calling a web service is done in a microflow using the call web service action. - -This how-to teaches you how to do the following: - -* Import a web service using the **Import Web Service** wizard -* Directly import a web service document into your project -* Configure a web service call - -## Importing a Web Service Using the Wizard - -This section describes the powerful wizard that enables integrating—in just a few clicks—the creation of an imported web service, the related data entities, the XML-mapping, and a microflow to trigger the web service. - -### The Configuration - -To import a web service using the wizard, follow these steps: - -1. Open your domain model and click **Import web service/XML file** in the toolbar. - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581788.png" class="no-border" >}} - - This opens the **Import Web Service or XML Schema** wizard that will guide you through importing the result of a web service (or an XML file). As a result, it will generate the following: - * Domain model entities to store the results - * An XML-to-domain mapping that maps the incoming XML to Mendix objects - * An imported web service (or XML schema) document - * A microflow that calls the web service (or imports an XML file) (optional) -2. On the **Import Web Service or XML Scheme** dialog box, select **Web service operation** and click **Next**: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581787.png" class="no-border" >}} - -3. On the **Import Web Service** dialog box, select **Create new imported web service** and click **Next**. -4. For **WSDL source** in the **Web service Description** section of the **New Web Service Operation** dialog box, specify the WSDL to be used for this imported web service. For the **WSDL source** you can either provide a **URL** (for example, http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL) or load a **File** from your computer. - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581785.png" class="no-border" >}} - -5. Click **Next** to fetch the services and operations in the WSDL. -6. In the **Select Ports** pop-up window select a web service port and click **OK**. Studio Pro now imports the operations. - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/port.png" class="no-border" >}} - -7. On the **New Web Service Operation** dialog box, you can review the services and operations that are available to the imported web service. If you click on any of the operations, information about the operation will be displayed in the right pane. Select a web service operation and click **Next**. - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581784.png" class="no-border" >}} - -8. On the **Select Elements** dialog box, you can optionally select individual elements to map as return values of the web service. Click **Next**. - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581783.png" class="no-border" >}} - -9. In the final step of this wizard you can select icons that will be attached to the generated entities and create a microflow in which the imported web service is called: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581782.png" class="no-border" >}} - -10. Click **Finish** to create the web service. - -### The Outcome - -When finished the wizard will add the following to your model based on the options selected: - -* The imported service -* An XML to domain mapping -* A microflow in which the web service operation is called -* Domain model entities (by default, Studio Pro creates non-persistable entities) - -{{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581781.png" class="no-border" >}} - -## Importing a Web Service Directly - -An alternative to using the wizard described above is to import a web service document directly into your project. For further information, see [Consumed Web Services](/refguide8/consumed-web-services/) in the *Studio Pro Guide*. - -To import a web service directly, follow these steps: - -1. Right-click a module and select **Add Other** > **Consumed web service**. -2. Specify a name for the new consumed web service and click **OK**. -3. In the **Consumed Web Service** box, specify the **WSDL Source** to be used for this consumed web service. You can specify a **URL** or load a **File** from your computer. - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/enter-wsdl-url.png" class="no-border" >}} - -4. Click **Import** to fetch the services and operations in the WSDL. If prompted, in the **WSDL Source** dialog box, select the ports you want to use and click **OK**. - -5. In the **Consumed Web Services** box, review the **Services** and **Operations** available to the imported web service. If you click on any of the **Operations**, information about the operation will be displayed in the right pane. You can select individual web service operations from the list otherwise the whole service and operation will be imported: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581779.png" class="no-border" >}} -6. Click **OK**. The web service will be added to the model. - -## Configuring the Web Service Call - -To configure the web service call, follow these steps: - -1. If you did not use the web service wizard or did not use the option in the wizard to automatically create a microflow, you have to create a microflow that will call the imported web service: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581778.png" class="no-border" >}} - - {{% alert color="info" %}}Make sure the microflow either creates the variables required as arguments for the web service call or has them passed to it.{{% /alert %}} - -2. If you are creating your own microflow, add the call web service activity to the microflow. For details on how to add activities to a microflow, see [Activities](/refguide8/activities/) in the *Studio Pro Guide*. -3. Double-click the activity to open the **Call Web Service** properties editor and in the **Operation** section, click **Select** for **Operation**. -4. In the **Select Web Service Operation** dialog box, you can select the operation for this web service call: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581777.png" class="no-border" >}} - -5. In the **SOAP Request Body** tab of the **Call Web Service** properties editor, you can configure the SOAP body. This contains the parameters needed to execute the web service request. The **Simple**, **Export Mapping**, and **Custom** options enable you to select the type of SOAP body to use. Click **Edit value** and use one of the following to change the domain-to-XML mapping or the variables from the microflow used as input arguments: - * **Simple expressions for each request parameter** — if the imported web service requires only primitive arguments: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581791.png" class="no-border" >}} - - * **Export mappings for each request parameter** or **Export mapping for the entire request** — if the domain model entities need to be mapped to XML elements - * **Custom request template** — for the definition of a custom XML body with parameters: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581792.png" class="no-border" >}} - -6. In the **HTTP Headers** tab, if the Mendix Runtime should HTTP authentication before calling the web service, check **Use HTTP authentication** and enter the **User name** and **Password** using the **Edit** buttons: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581793.png" class="no-border" >}} - -7. In the **SOAP Response** tab, you can configure the handling of the return from the web service call as follows: - * If the return is a complex XML structure, select **Mapping** and use an XML-to-domain mapping to map the XML elements to the domain model entities: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581790.png" class="no-border" >}} - - * If the return is a primitive, you can store it in a variable by selecting **Store in variable** — **Yes** and provide the **Type** and **Variable**: - - {{< figure src="/attachments/howto8/integration/consume-a-complex-web-service/18581789.png" class="no-border" >}} - - * If you want to ignore the return, select **Ignore** -8. Your imported web service is now ready to be used in your application. - -## Read More - -* [Consume a Simple Web Service](/howto8/integration/consume-a-simple-web-service/) -* [Export XML Documents](/howto8/integration/export-xml-documents/) -* [Import Excel Documents](/howto8/integration/importing-excel-documents/) -* [Expose a Web Service](/howto8/integration/expose-a-web-service/) -* [Use Selenium Support](/howto8/integration/selenium-support/) -* [Import XML Documents](/howto8/integration/importing-xml-documents/) -* [Consume a REST Service](/howto8/integration/consume-a-rest-service/) -* [Expose Data to BI tools Using OData](/howto8/integration/exposing-data-to-bi-tools-using-odata/) diff --git a/content/en/docs/howto8/integration/consume-a-rest-service.md b/content/en/docs/howto8/integration/consume-a-rest-service.md deleted file mode 100644 index 954da49315b..00000000000 --- a/content/en/docs/howto8/integration/consume-a-rest-service.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: "Consume a REST Service" -url: /howto8/integration/consume-a-rest-service/ -weight: 9 -description: "Describes how to get information from a REST service." ---- - -## Introduction - -Mendix applications frequently need to communicate with existing systems. Whether you are creating an app to replace an older platform or a legacy system or want to integrate an existing database, the ability to integrate with existing systems is a necessary feature. In your Mendix app, you can use published REST services for this integration. - -This how-to shows you how to do this using an example in which you create an app that retrieves Wikipedia pages from a REST service. The resulting app is [available for download](/attachments/howto8/integration/consume-a-rest-service/WikipediaApi.mpk). - -This how-to teaches you how to do the following: - -* Integrate with an existing system using a REST service -* Call the REST service in a microflow - -{{% alert color="info" %}} -Creating a published REST service on top of the system you want to integrate with is outside the scope of this how-to; for instructions on how to do this, refer to the configuration of your non-Mendix Platform. -{{% /alert %}} - -## Creating a JSON Structure - -If the system you want to integrate into your app has the functionality for exposing its data to REST services, you can integrate it easily into your Mendix app using consume REST service. Each system has a different JSON structure based on internal data models. - -You are going to use the Wikipedia REST service as an example in this how-to. It allows you to retrieve the summary of a Wikipedia page – in this case information about a country. This service can be reached at `https://en.wikipedia.org/api/rest_v1/page/summary/{title}`, where `{title}` is the title of a page. - -We will start by providing to Studio Pro an example of what the REST service returns: - -1. Open your browser and go to [https://en.wikipedia.org/api/rest_v1/page/summary/Tahiti](https://en.wikipedia.org/api/rest_v1/page/summary/Tahiti). This calls the REST service with a GET request – the result is the summary of the [Tahiti page on Wikipedia](https://en.wikipedia.org/wiki/Tahiti) in the JSON format. -2. Copy the whole JSON snippet. -3. Create a module and name it *RESTconsume*. To add a new [JSON structure](/refguide8/json-structures/) to your module with the sample JSON that you can use in the app, right-click the module in the **Project Explorer** and select **Add other** > **JSON structure**. -4. Enter a **Name** for the structure: *JSON_structure* and click **OK**. -5. In the **JSON Structure** dialog box, paste the JSON snippet in the **General** tab and click **Refresh**. This analyzes the structure of the JSON snippet that we can use later. - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/json-structure.png" class="no-border" >}} - -6. Click **OK**. - -## Creating an Import Mapping - -An [import mapping](/refguide8/import-mappings/) specifies how the JSON relates to [entities](/refguide8/entities/). You can map the JSON to any entity you like. The following steps describe how to generate the entities and create an import mapping: - -1. Right-click the module in the **Project Explorer** and select **Add other** > **Import Mapping**. -2. Enter a **Name** for the import mapping: *Import_mapping* and click **OK**. -3. In the **Select schema elements for import mapping** dialog box, click the radio button for **JSON structure** and then click **Select**. -4. Double-click **JSON_structure** in the **Select JSON Structure** dialog box. -5. Click **Expand all** and then click **Check all**. - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/import-mapping.png" class="no-border" >}} - -6. Click **OK**. The **Import_mapping** document is displayed and the JSON structure is on the right. -7. Click **Map automatically** in the editor toolbar. -8. A pop-up box is displayed informing you that can **See the details for the changes that have been applied**. You can click **Details** to see details of the mapping to the entities that are generated to match the JSON structure. -9. Click **Close** to see the entities corresponding to the JSON structure. - -## Adding an Input Entity to the Domain Model - -The service takes the title of the page as an input and it returns the summary of the page from Wikipedia. - -In this section, you will create an entity that represents this input and associate it with its summary. - -To add an input entity to the domain model, follow these steps: - -1. In the **Project Explorer**, double-click the **Domain Model**. -2. Rename **Root** to **Summary**. -3. From the **Toolbox**, drag an **Entity** into the domain model. -4. Double-click the entity and enter *Input* for the **Name**. -5. For **Persistable**, select **No**. -6. On the **Attributes** tab, click **New** to add a string attribute and name it *Title*. -7. Click **OK**. -8. Drag an association from **Input** to **Summary**. - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/domain-model.png" class="no-border" >}} - -9. Go to the **Import_mapping** and from the **Connector** pane drag **Input** as the input parameter for the input mapping. -10. Double-click **Summary**. -11. In the **Map entity 'Summary from the object element 'Summary** dialog box, **Set association** to **Yes** and select the **RESTconsume_input_Summary** for the **Association** to have the import mapping set the association: - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/map-entity-from-input-mapping.png" class="no-border" >}} - -12. Click **OK**. - -## Calling the REST Service in a Microflow - -You will now call the REST service in a [microflow](/refguide8/microflows/) to build the integration with Wikipedia. The microflow takes **Input** as the input parameter and sets the associated **Summary**. - -To call the REST service in a microflow, follow these steps: - -1. Right-click the module and select **Add** > **Microflow** and accept the default **Name** *Microflow* for the name of the microflow and click **OK**. -2. From the tool bar, drag a **Parameter** object to the microflow document. -3. Click **Select** for the **Data type** and select the **Input** entity as the input parameter. Click **OK**. -4. Right-click the mouse and select **Insert** > **Activity** to insert an activity to the microflow. Double-click the activity and select the **Call REST service** to change the activity. -5. In the **Call REST** dialog box, click **Edit** for the **Location** and add the following to **Template**: `https://en.wikipedia.org/api/rest_v1/page/summary/{1}`, with the parameter being the Title attribute from the **Input** parameter `$Input/Title`. Click **OK**. - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/location.png" class="no-border" >}} - -6. In the **Response** tab, the response has to be mapped using the import mapping. For **Response handling** select **Apply import mapping**. -7. For **Mapping**, click **Select** and double-click **Import_mapping**. For the **Parameter**, select **Input**. -8. For **Output** select **Yes** for **Store in variable** and specify *Summary* for the **Variable name**. - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/response.png" class="no-border" >}} - -9. Click **OK**. -10. Right-click after the **Call REST service** object and select **Insert** > **Activity** and double-click it and change it to a **Change object**. -11. For the **Input Object**, select **Input (RESTconsume.Input)**. -12. For **Refresh in client**, select **Yes**. This ensures that the summary is displayed on the screen. -13. Click **New**. -14. On the **Edit Change Item** dialog box, for **Member**, select **RESTconsume.Input_Summary (RESTconsume.Summary)**. -15. Under **Value**, enter `$Summary`. - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/set-association.png" class="no-border" >}} - -16. Click **OK**. - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/change-object.png" class="no-border" >}} - -17. Click **OK**. You have created microflow that takes the title of an article as input and associates it with its summary. - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/microflow.png" class="no-border" >}} - -You have successfully consumed a REST service and created a microflow to show the results. The rest of this how-to describes how to use this microflow in an app so that you can see the REST call in action. - -## Creating a Page - -To create a page for this app, follow these steps: - -1. Open the **** and add a **Data view**. -2. Right-click the **[Unknown]** bar and click, **Select entity**. Select the **Input** entity. -3. For the **Data source – Type**, select **Microflow**. -4. For the **Name**, enter *CreateInput*. Note that when this page loads, it needs a new **Input** object – you will define the **CreateInput** microflow that creates this object in [Filling In the Create Input Microflow](#createinput). -5. Click **OK**. -6. From **Container widgets**, add a new **Table** with one row and two columns. -7. Drag the **Title** field onto the left column. -8. From the **Project Explorer**, drag **Microflow** into the right column. -9. Double-click the **Microflow** button and in the **Edit Action Button** dialog box, enter *Get summary* for the caption of the button. -10. Add a **Data view** below the table (inside the other data view). -11. From the **Connector**, drag the **Summary** entity onto the **[Unknown]** bar. -12. Click **OK**. -13. From this data view, delete all the fields except **Extract**. -14. Double-click **Extract**. -15. For **Show label**, select **No**. -16. Click **OK**. -17. Delete the **Save** and **Cancel** buttons. - - {{< figure src="/attachments/howto8/integration/consume-a-rest-service/page.png" class="no-border" >}} - -## Filling In the Create Input Microflow{#createinput} - -Now all that is left is to have the **CreateInput** microflow create a new **Input** object. - -To fill in the CreateInput microflow, follow these steps: - -1. In the **Project Explorer**, double-click **CreateInput**. -2. From the **Toolbox**, drag a **Create object** activity to the microflow. -3. Double-click the activity. -4. For **Entity**, click **Select** and double-click **Input**, then click **OK**. -5. Double-click the red **End event**. -6. Under **Return value**, enter `$NewInput`, then click **OK** - -Congratulations! You can now start your app and get summaries from Wikipedia. - -## Example - -**How to consume REST with Mendix Studio Pro 8** - -{{% alert color="info" %}} -For Studio Pro v 8.15 and above, the **Call REST** dialog box has changed from what is shown in the video. You have to ensure that for **Output** you select **Yes** for **Store in variable** and then specify the **Variable name**. -{{% /alert %}} - -{{< figure src="/attachments/howto8/integration/consume-a-rest-service/response.png" class="no-border" >}} - -{{< youtube OhzWTa1kZ00 >}} - -## Read More - -* [Consume a Complex Web Service](/howto8/integration/consume-a-complex-web-service/) -* [Consume a Simple Web Service](/howto8/integration/consume-a-simple-web-service/) -* [Export XML Documents](/howto8/integration/export-xml-documents/) -* [Import XML Documents](/howto8/integration/importing-xml-documents/) -* [Import Excel Documents](/howto8/integration/importing-excel-documents/) -* [Expose a Web Service](/howto8/integration/expose-a-web-service/) -* [Expose Data to BI Tools Using OData](/howto8/integration/exposing-data-to-bi-tools-using-odata/) diff --git a/content/en/docs/howto8/integration/consume-a-simple-web-service.md b/content/en/docs/howto8/integration/consume-a-simple-web-service.md deleted file mode 100644 index 6b7694debaf..00000000000 --- a/content/en/docs/howto8/integration/consume-a-simple-web-service.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "Consume a Simple Web Service" -url: /howto8/integration/consume-a-simple-web-service/ -weight: 7 ---- - -## Introduction - -Mendix is the app platform for the enterprise, and in enterprise software it is not likely that you work in a [greenfield project](https://en.wikipedia.org/wiki/Greenfield_project). In almost every situation, you will need to integrate with existing systems. Mendix supports many ways of integration, and this how-to focuses on how you can consume web services with Mendix. - -In this how-to, you will be using an example web service of [W3Schools](https://www.w3schools.com/). This is a very simple web service that converts temperatures from Celsius to Fahrenheit and vice versa. The converted temperature will be returned as a string value that can be stored in a variable directly. If you want to invoke a web service that returns a complex XML message, you can use the XML-to-domain mappings described in [How to Import XML Documents](/howto8/integration/importing-xml-documents/). - -This how-to teaches you how to do the following: - -* Import a WSDL -* Create logic to call the web service - -## Importing a WSDL - -A WSDL describes the operations of a web service and can be imported in Studio Pro. After importing the WSDL, you can invoke the operations of the web service instantly within the microflow editor. - -To import a WSDL, follow these steps: - -1. Right-click your module in the **Project Explorer** and select **Add other** > **Consumed web service**: - -2. Enter a name for the new consumed web service (for example, *TemperatureConverter*): - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582086.png" class="no-border" >}} - -3. Click **OK**. You will now see the **Consumed Web Service** screen. Click **Edit**. Enter `https://www.w3schools.com/xml/tempconvert.asmx?wsdl` as the **URL** and click **Import**. - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/wsdl-source.png" class="no-border" >}} - -4. The **Select Ports** dialog box is displayed for selecting a web service port: - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582065.png" class="no-border" >}} - -5. Click **OK** to select the default, and click **OK** to close the **WSDL Source** dialog. The operations **CelsiusToFahrenheit** and **FahrenheitToCelsius** will now be imported into the project. - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582084.png" class="no-border" >}} - -## Creating Logic to Call the Web Service - -To create logic to call the web service, follow these steps: - -1. Right-click your module in the **Project Explorer** and select **Add microflow** from the menu: -2. Enter a name for the new microflow (for example, *ConvertCelsiusToFahrenheit*) and click **OK**. - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582083.png" class="no-border" >}} - -3. An empty microflow will be displayed: - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582081.png" class="no-border" >}} - -4. Open the **Toolbox** and drag a **Create variable** activity to the line between the start and end event. - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/8946802.png" class="no-border" >}} - -5. Double-click the new activity to open the **Create Variable** properties editor. - -6. For the **Data Type**, select **Integer/Long** and enter *100* as the value. For the **Output Variable Name** enter *TemperatureInCelsius*: - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582080.png" class="no-border" >}} - -7. Click **OK.** The microflow will look like this: - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582079.png" class="no-border" >}} - -8. Drag a **Call web service** activity from the toolbox and add it to the microflow just before the end event. - -9. Double-click this activity to open the **Call Web Service** properties editor. For the **Operation** of your consumed web service, click **Select**. Expand the **TemperatureConverter** web service and under **TempConvert** click **CelsiusToFahrenheit** and click **Select**: - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582076.png" class="no-border" >}} - -10. In the **Location** section for this operation, check the **Override location** box to override the location and use the secure location of the web service. -11. Click **Edit** and change `http` to `https` for the URL in the **Location** editor and click **OK**. -12. In the **SOAP Request Body** tab of the **Call Web Service** properties editor, double-click the **Celsius (optional)** input parameter and enter `toString($TemperatureInCelsius)` for the expression. The web service operation expects a string value, which is why you need to use the `toString` function. Then click **OK**. - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582075.png" class="no-border" >}} - -13. In the **SOAP Response** tab, select **Yes** for the **Store in variable** option. Enter *TemperatureInFahrenheit* for the **Variable name**: - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/call-web-serv-SOAP-resp.png" class="no-border" >}} - -14. Click **OK**. The microflow will look like this: - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582073.png" class="no-border" >}} - -15. Drag a **Show message** activity from the **Toolbox** to the line before the end event. -16. Double-click the new activity to open the **Show Message** dialog box. -17. Select **Information** as the **Type**, and enter *The temperature in Fahrenheit is: {1}* for the **Template**. The *{1}* functions as a placeholder for the parameters. - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582071.png" class="no-border" >}} - -18. Create a new parameter and enter `$TemperatureInFahrenheit` for the expression (this is the return value of the web service operation) and click **OK**: - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582072.png" class="no-border" >}} - -19. Click **OK** again to save the show message activity values. The microflow now looks like this: - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/18582070.png" class="no-border" >}} - -20. Create a menu item that triggers this microflow. For details on how to create a menu item, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/). - -21. Deploy the application and trigger the microflow to call the web service operation. You should see a message with the converted temperature. - -## Read More - -* [Create a Secure App](/howto8/security/create-a-secure-app/) -* [Consume a Complex Web Service](/howto8/integration/consume-a-complex-web-service/) -* [Export XML Documents](/howto8/integration/export-xml-documents/) -* [Import Excel Documents](/howto8/integration/importing-excel-documents/) -* [Expose a Web Service](/howto8/integration/expose-a-web-service/) -* [Use Selenium Support](/howto8/integration/selenium-support/) -* [Security How-tos](/howto8/security/) diff --git a/content/en/docs/howto8/integration/execute-an-sql-statement-on-an-external-database.md b/content/en/docs/howto8/integration/execute-an-sql-statement-on-an-external-database.md deleted file mode 100644 index 78ed300cf2a..00000000000 --- a/content/en/docs/howto8/integration/execute-an-sql-statement-on-an-external-database.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Execute an SQL Statement on an External Database" -linktitle: "Execute SQL on External Database" -url: /howto8/integration/execute-an-sql-statement-on-an-external-database/ -weight: 17 ---- - -## Introduction - -The Mendix Platform offers many ways to integrate with external data, but integrating with external databases has not been a seamless experience until now. The [Database Connector](/appstore/modules/database-connector/) can be used to seamlessly connect to external databases without limiting you in your choice of database or SQL dialect, thus enabling you to incorporate external data directly in your Mendix application. Two actions are available via the connector: [Execute statement](#statement) and **Execute query**. - -The **Execute statement** action provides a consistent environment for Mendix apps to perform an arbitrary SQL statement on relational external databases. A Java database connectivity (JDBC) API is used when this Java action attempts to connect with a relational database for which a JDBC driver exists. - -The Database Connector can be used for the following SQL statements: - -* `CREATE` -* `INSERT` -* `UPDATE` -* `STORED PROCEDURE` -* `DELETE` -* `DDL` -* `SELECT` (only with the **Execute query** action, not with **Execute statement**) - -{{% alert color="info" %}} -Automatic mapping is currently not possible. -{{% /alert %}} - -This document will focus on executing an SQL on relational external databases. - -This how-to teaches you how to do the following: - -* Execute SQL statements on relational external databases with the help of the Database Connector -* Configure the **Execute statement** action - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Download the Database Connector from the Mendix Marketplace into your app -* Have a database **URL** address that points to your database -* Have the **username** and **password** for signing into the database (relative to the database URL address) -* Have the SQL statement to execute (relative to the database type; note that the SQL dialect differs for different databases) -* Have the JDBC driver *.jar* for the database to which you want to connect - -## Preparation - -You must place the JDBC driver *.jar* files for the databases to which you want to connect inside the **userlib** directory of your Mendix app. - -For example, if you want to connect to an Amazon RDS PostgreSQL database (for example, `jdbc:postgresql://xyz-rds-instance.ccnapcvoeosh.eu-west-1.rds.amazonaws.com:5432/postgres`), you need to place the PostgreSQL Jdbc driver *.jar* file inside the userlib folder. - -## Using the Execute Statement Action in a Microflow {#statement} - -To use an ExecuteStatement action in a microflow, follow these steps: - -1. Find the **Database Connector** in the **Toolbox**. - - {{< figure src="/attachments/howto8/integration/execute-an-sql-statement-on-an-external-database/19399122.png" class="no-border" >}} - -2. Drag the **Execute statement** action into your microflow: - - {{< figure src="/attachments/howto8/integration/execute-an-sql-statement-on-an-external-database/19399123.png" class="no-border" >}} - -3. Configure the statement: - * Provide all the valid arguments to the statement action - * The **Jdbc url** argument must specify a database URL that points to your relational database and is dependent upon the particular database and JDBC driver - * It will always begin with `jdbc:` protocol text, but the rest is up to the particular vendor (for example, the `jdbc:mysql://hostname/databaseName'` JDBC URL format can be used for MySQL databases) - * Specify the **Output Variable name** - * In the example below, the variable is **amountOfUpdatedRows**, which is the output of the SQL statement; this is also the output of the SQL statement provided for the **Sql** argument within the connector - - {{< figure src="/attachments/howto8/integration/execute-an-sql-statement-on-an-external-database/19399146.png" class="no-border" >}} - - The statement action's result is either an **Integer** or a **Long** value, which usually represents the amount of affected rows. - -{{% alert color="warning" %}} -It is your responsibility to apply the proper security, as this action can allow for SQL injection into your Mendix application. Among others things, do not use user-supplied or environment-supplied variables in your SQL statement; if possible, you should prefer them to be static. -{{% /alert %}} diff --git a/content/en/docs/howto8/integration/export-xml-documents.md b/content/en/docs/howto8/integration/export-xml-documents.md deleted file mode 100644 index 0e9e9e76158..00000000000 --- a/content/en/docs/howto8/integration/export-xml-documents.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: "Export XML Documents" -url: /howto8/integration/export-xml-documents/ -weight: 4 ---- - -## Introduction - -In enterprise software, it is not likely that you work in a [greenfield](https://en.wikipedia.org/wiki/Greenfield_project). In almost every situation, you will need to integrate with existing systems. Mendix supports many ways of integration, but this how-to focuses on how you can export XML documents. - -This how-to teaches you how to do the following: - -* Add an XML schema -* Create domain-to-XML mapping and export logic - -## Prerequisites - -Before you can start exporting XML documents, you need data in your application that is used during the export. You first need to set up the data structure and GUI to maintain the customer data. Then you'll create the actual export logic and the corresponding export mapping. So, you need to know how to do the following: - -* Create a domain model (for more information, see [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/)) -* Create a custom file document (for more information, see [How to Work with Images and Files](/howto8/data-models/working-with-images-and-files/)) -* Create overview and detail pages (for more information, see [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/)) -* Create menu items, (for more information, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/)) - -Before starting this how-to, make sure you have completed the following prerequisites: - -1. Create the following **Customer** entity in your domain model: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581816.png" class="no-border" >}} - -2. Create overview and detail pages to manage the Customer objects. -3. Create a menu item to access the customer overview page. -4. Create the **XMLDocument** entity that inherits all the properties from *System.FileDocument*: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581650.png" class="no-border" >}} - -5. Create a reference set (multiplicity **[*-*]**) between XMLDocument and Customer: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581814.png" class="no-border" >}} - -## Adding an XML Schema (XSD) - -Whether you plan to import documents or export documents, working with XML means that your application must contain an XML schema (also called XSD). An XSD describes the possible contents of an XML file. Based on this XSD, your application knows how to read or write an XML file. If you don't have an XSD file, there are a couple of online XSD generators that accept an XML document as input. For this how-to, you can use [Customers.xsd](/attachments/howto8/integration/18448731/18581813.xsd). - -1. Right-click your module in the **Project Explorer** and select **Add other** > **XML schema**. -2. Enter *CustomersXSD* for the **Name** and click **OK**: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581696.png" class="no-border" >}} - -3. In the **XML Schema** editor, click **Select** for **XML Schema** and select the XSD file that you downloaded earlier: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581812.png" class="no-border" >}} - -4. Click **OK** to save the XML Schema. We'll be using this schema in the following steps. - -## Creating Domain-to-XML mapping - -The XML schema describes what the contents of an XML document should be. We need to create domain-to-XML mapping to define how the data in our application is transformed into a XML document. - -1. Right-click your module in the **Project Explorer** and select **Add other** > **Export mapping**. - -2. Enter *ExportCustomersMapping* for the **Name**: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581849.png" class="no-border" >}} - -3. Click **OK**, and the **Select schema elements for export mapping** dialog box will automatically open. Now do the following:
- 1. For **Schema source**, select **XML schema**.
- 2. For the schema, select the previously added **CustomersXSD**.
- 3. In the **Schema elements** section of the dialog box, click the **Expand all** and **Check all** buttons. This automatically selects the **Customer** element and its child elements. Your screen should now look like this: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581811.png" class="no-border" >}} - -4. Click **OK**. You should now see the first part of the import mappings: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581810.png" class="no-border" >}} - -5. Open the **Connector** pane, which should be in the lower-right corner of Studio Pro: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581817.png" class="no-border" >}} - -6. Drag the **XMLDocument** entity from the **Connector** into the placeholder: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581809.png" class="no-border" >}} - - The mapping editor for this element will pop up, you can close that by clicking **OK**. - -7. Drag the **Customer** entity from the **Connector** into the placeholder: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581808.png" class="no-border" >}} - - The mapping editor for this element will open up: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581806.png" class="no-border" >}} - -8. In the mapping editor, verify the following:
- 1. **Method** is set to **By association**
- 2. **Association to parent** is set to **XMLDocument_Customer**
-9. Select attributes for all five **Attribute to value element mapping** instances (or click **Map attributes by name** to accomplish this). You should have the following mapping: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581807.png" class="no-border" >}} - -10. Click **OK** to save the mapping. - -## Creating the Export Logic - -This section explains how you can create logic to export the customers stored in your application to an XML document. - -To create the export logic, follow these steps: - -1. Open the **Customer** overview page, right-click the toolbar of the data grid widget, and select **Add button** > **Action** to add a new Action button: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581804.png" class="no-border" >}} - -2. Double-click the new button to open the properties editor and do the following: - * For **Caption**, enter *Export as XML* - * For **On click**, select **Call a microflow** - * In the **Select Microflow** dialog box, click **New** to create a new microflow and enter *Customers_Export* for its **Name** - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581803.png" class="no-border" >}} - -3. Click **OK** to save the button properties. -4. Right-click the new action button and click **Go to microflow** in the context menu. You should see an empty microflow with one input parameter: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581802.png" class="no-border" >}} - -5. Select the input parameter and delete it. -6. Open the **Toolbox**, which should be on the lower-right side of Studio Pro (you can also open it from the **View** menu). -7. Drag a **Retrieve** activity from the **Toolbox** to the line between the start event and end event. -8. Double-click the activity to open the **Retrieve Objects** properties editor and do the following: - * For **Source**, select **From database** - * For **Entity**, click **Select...** and select the customer entity - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581830.png" class="no-border" >}} - -9. Click **OK**. The microflow should now look like this: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581827.png" class="no-border" >}} - -10. Drag a **Create object** activity from the **Toolbox** to the line between the start event and end event. -11. Double-click the activity to open the **Create Object** editor and do the following: - * For **Entity**, select **XMLDocument** - * Click **New** to add a change item - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581801.png" class="no-border" >}} - -12. In the **Edit Change Item** editor, do the following: - * For the **Member** for the change item, select the **XMLDocument_Customer** reference: - * For the **Value**, enter *$CustomerList* - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581825.png" class="no-border" >}} - -13. Click **OK** to save the change item. -14. Create a change item to set the **Name** attribute to: *'customers.xml'* (including the single quotation marks [']). The **Create Object** dialog box should now look like this: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/create-object.png" class="no-border" >}} - -15. Click **OK** to save the action properties. The microflow should look like this: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581823.png" class="no-border" >}} - -16. Drag an **Export with mapping** activity from the **Toolbox** to the line between the start event and end event. This inserts a new export XML activity. -17. Double-click the new activity to open the properties editor and do the following: - * For **Mapping**, select the previously created **ExportCustomersMapping** XML-to-domain mapping - * For **Parameter type**, verify that the entity **XMLDocument** is automatically selected - * For the **Parameter**, select the created **NewXMLDocument** - * For the output **Name**, select the created **NewXMLDocument** - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581822.png" class="no-border" >}} - -18. Click **OK** to save the properties. The microflow should look like this: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581821.png" class="no-border" >}} - -19. Drag a **Download file** activity from the **Toolbox** to the line between the start event and end event. -20. Double-click the actvity to open the **Download File** dialog box and select **NewXMLDocument** as the **File document**: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581818.png" class="no-border" >}} - -21. Click **OK**. The microflow should now look like this: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581819.png" class="no-border" >}} - -22. Deploy the application and open the customer overview page. -23. Click the **Export as XML** button and download the generated XML document. - -## Read More - -* [Consume a Complex Web Service](/howto8/integration/consume-a-complex-web-service/) -* [Consume a Simple Web Service](/howto8/integration/consume-a-simple-web-service/) -* [Import Excel Documents](/howto8/integration/importing-excel-documents/) -* [Expose a Web Service](/howto8/integration/expose-a-web-service/) -* [Enable Selenium Support](/howto8/integration/selenium-support/) -* [Import XML Documents](/howto8/integration/importing-xml-documents/) -* [Consume a REST Service](/howto8/integration/consume-a-rest-service/) -* [Expose Data to BI Tools Using OData](/howto8/integration/exposing-data-to-bi-tools-using-odata/) diff --git a/content/en/docs/howto8/integration/expose-a-web-service.md b/content/en/docs/howto8/integration/expose-a-web-service.md deleted file mode 100644 index 641aa956044..00000000000 --- a/content/en/docs/howto8/integration/expose-a-web-service.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "Expose a Web Service" -url: /howto8/integration/expose-a-web-service/ -weight: 12 -description: "Describes how Mendix supports exposing the functionality and data of your app using web services." ---- - -## Introduction - -Mendix supports many ways to expose the functionality and data of your application to others. The easiest way is to use web services. A web service can contain multiple operations. - -This how-to teaches you how to do the following: - -* Create a web service -* Publish a microflow as web service operation - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Download the latest version of [Mendix Studio Pro](https://marketplace.mendix.com/) - -{{% alert color="warning" %}} - -This how-to was written based on Studio Pro 5.20. All the images, names, and steps in this how-to are based on this version. When using other versions, the images and/or names on your screen may be different than the images and names used in this how-to. - -{{% /alert %}} - -## Data Structure and GUI - -1. Create the following **Customer** entity in your domain model (for details on how to create an entity, see [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/)): - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/8945665.png" class="no-border" >}} - -2. Create overview and detail pages to manage objects of the **Customer** type (for details on how to create overview and detail pages, see [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/). -3. Create a menu item to access the customer overview page (for details on how to create menu items, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/). -4. Run the application and add some data to expose in the web service. - -## Creating a Published Web Service {#4} - -To create a published web service, follow these steps: - -1. Right-click the module in which you want to store the published web service and select **Add** > **Published services** > **Published web service**: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581715.png" class="no-border" >}} - -2. In the **Add Published Web Service** window, enter *CustomerWebservice* for the **Name** and then click **OK**: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581728.png" class="no-border" >}} - -3. You should now see the **Published Web Service** properties window. Take note of the following tab details: - * On the **Operations** tab, you can see the available operations of the web service (currently the list is empty, so we'll add an operation in section [6 Publishing a Microflow](#6)): - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581713.png" class="no-border" >}} - - * On the **Settings** tab, you can configure the other settings. Do change them before publishing your web service, especially the **Target namespace** (for details on these settings, see [Published Web Service](/refguide8/published-web-service/) in the *Studio Pro Guide*): - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581712.png" class="no-border" >}} - - * On the **Documentation** tab, you can change the documentation: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581710.png" class="no-border" >}} - -4. Click **OK.** - -## Creating the Functionality to Expose - -To create the functionality to expose, follow these steps: - -1. Create a microflow that retrieves and returns a list of customers from the database (for details on how to create a microflow, see [How to Trigger a Microflow From a Menu Item](/howto8/logic-business-rules/trigger-microflow-from-menu-item/)). -2. To make the microflow more exciting, add two input parameters to dynamically set the range settings of the retrieve action. Configure the range options of the retrieve action like this: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581709.png" class="no-border" >}} - - Reference this microflow: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/model.jpg" class="no-border" >}} - -## Publishing a Microflow {#6} - -To publish a microflow, follow these steps: - -1. Right-click somewhere in the background of the microflow and select **Publish as Web service operation**: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581708.png" class="no-border" >}} - -2. Locate the web service created in [4 Creating a Published Web Service](#4) and click **Select**: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581723.png" class="no-border" >}} - -3. You should now see the **Operation Operation** properties editor. Take note of the following tab details: - - * On the **General** tab, you can change the **Name** and **Documentation**: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581705.png" class="no-border" >}} - - * On the **Parameters** tab, you can mark the input parameters as **Optional** and **Nillable**: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581707.png" class="no-border" >}} - - * On the **Return type** tab you can configure the return type: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581706.png" class="no-border" >}} - -4. Click **Select...** to select which attributes and associations of the return object **Customer** you want to expose: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581704.png" class="no-border" >}} - -5. Select the members you want to expose and click **OK**. Only the selected members will be returned by the web service. -6. Click **OK** to save the operation. - -## Getting a WSDL - -You need a Web Services Description Language (WSDL) to allow others to interact with the web service you just created. The WSDL describes how to call the operations in the web service. - -To get a WSDL, follow these steps: - -1. Run the application locally or in a Free App environment. -2. View the application in your browser: - * If you run the application locally, the application URL should look like this: `http://localhost:8080/index.html` - * If you run the application in a Free App environment, the application URL should look like this: `https://myfirstapp.mendixcloud.com/index.html` -3. In both of the above cases, you can replace `/index.html` with `/ws-doc/` to open the web service documentation page: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581703.png" class="no-border" >}} - - You should see the name of your web service in the list. -4. Click the "WSDL schema" URL to open the WSDL. This WSDL can be given to others so that they can interact with your web service. - -## Authentication and Users - -To change the user authentication, follow these steps: - -1. Double-click the published web service in the **Project Explorer** to open it. -2. In the **Published Web Service** properties window, open the **Settings** tab. Because **No Authentication** is set, currently users of the web service do not need to authenticate: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581702.png" class="no-border" >}} - -3. Change **Authentication** to **Username and password**: - - {{< figure src="/attachments/howto8/integration/expose-a-web-service/18581701.png" class="no-border" >}} - -4. Click **OK** and re-run the application. Users now need to authenticate before they can use the web service. - -Mendix enables creating your own user management functionality as long as your own user object inherits from `System.User`. The `User` entity in the `System` module contains the `WebServiceUser` Boolean attribute. This attribute determines if an user is able to interact with web services. If you want a certain user to be able to interact with web services, the value of this attribute must be *true*. - -## Considerations - -When exposing a web service, consider the following things: - -* In Studio Pro some words are reserved for Mendix use (for example, type, Enumeration) -* Because you may not want to publish a "_type" attribute with an underscore ("`_`") in front of it, you can change the WSDL name by changing the last column in the selected attribute window -* If an attribute is renamed after it is published, the name in the WSDL does not automatically change (because that would break the customer's implementation) - -## Read More - -* [Consume a Complex Web Service](/howto8/integration/consume-a-complex-web-service/) -* [Consume a Simple Web Service](/howto8/integration/consume-a-simple-web-service/) -* [Export XML Documents](/howto8/integration/export-xml-documents/) -* [Import Excel Documents](/howto8/integration/importing-excel-documents/) -* [Enable Selenium Support](/howto8/integration/selenium-support/) -* [Import XML Documents](/howto8/integration/importing-xml-documents/) -* [Consume a REST Service](/howto8/integration/consume-a-rest-service/) -* [Expose Data to BI Tools Using OData](/howto8/integration/exposing-data-to-bi-tools-using-odata/) diff --git a/content/en/docs/howto8/integration/exposing-data-to-bi-tools-using-odata.md b/content/en/docs/howto8/integration/exposing-data-to-bi-tools-using-odata.md deleted file mode 100644 index ab1d863a85b..00000000000 --- a/content/en/docs/howto8/integration/exposing-data-to-bi-tools-using-odata.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: "Expose Data to BI Tools Using OData" -url: /howto8/integration/exposing-data-to-bi-tools-using-odata/ -weight: 13 -description: "Presents how to create a published OData service with resources, add the OData server to Tableau and Excel, combine resources in Tableau, and create custom queries." ---- - -## Introduction - -Mendix apps encourage the application of a services-oriented architecture, with multiple smaller services providing APIs and user interfaces for a specific set of data and logic. Enterprises build up complete solutions by assembling these services. - -One important aspect of services is that all access to data and logic is handled by the service operations. Direct access to databases used for storing the service data is discouraged, because this would bypass the business rules and security handled by the service. This creates a challenge for generic reporting, data warehousing, and ETL tooling. - -The OData standard is being adopted because it enables generic data access within a services-oriented architecture. [OData](https://www.odata.org) is “an open protocol to allow the creation and consumption of queryable and interoperable Restful APIs in a simple and standard way.". In other words, it enables tools to use any REST/OData service by providing metadata that describes the data being provided, and by standardizing the messages exchanged with the OData services. - -A reporting tool like Excel or Tableau can discover what data and functionality is available in an OData service, and provide a generic way for users to build new queries for the data. - -**This guide will outline how to do the following:** - -* Create a published OData service with resources -* Add the OData server to Tableau and Excel -* Combine resources in Tableau -* Create custom queries - -## Prerequisites - -Before checking out this guide, make sure you do the following: - -* Create an app that includes data you want to expose. You can either have published OData services already, or follow the steps in the [Creating a Published OData Service](#create-service) section below. For detailed steps to publishing an OData service, see [Share Data Between Apps](/howto/integration/share-data/). -* Install Excel (we will use Excel for Office 365). -* Download and install the public version of [Tableau](https://public.tableau.com). - -## Creating a Published OData Service {#create-service} - -A published OData service can be used by third-party applications to read data from a Mendix application. The basic steps are as follows: - -1. Open Studio Pro and add a folder named *OData Services* to **MyFirstModule**. -2. Right-click the new folder and select **Add other** > **Published OData service**. -3. Enter a descriptive name for the service and click **OK**. -4. Under **Entities**, click **Add**: -5. In the **Select Persistable Entity** window, select the entity you want to expose and click **Select**. - {{% alert color="info" %}}Security in OData is managed by the **App Security** settings and the entity-level access rules; therefore, if you have already configured access rules in your app, you do not have to configure security separately for OData.{{% /alert %}} -6. On the **Settings** tab, choose **As an associated id** for **Associations**. Excel can handle the setting **As a link**, but Tableau does not support it. -7. Start the application. - -The OData service is now ready to be consumed. - -## Working with Mendix Data in Excel for Office 365 - -1. Open Excel. -2. Open the **DATA** tab and select **Get Data** > **From Other Sources** > **From OData Feed**. -3. Return to Studio Pro, and double-click the published OData service. Copy the link in the **Location** field to the clipboard. -4. Back in Excel, on the **OData Feed** dialog box, enter the copied link for the **URL** and Click **OK**: -5. Select the name of the published entity in the Navigator and click **Load**. - -The data of the Mendix application is now available in Excel. - -## Working with Mendix Data in Tableau - -In this section, we will outline the steps for adding more than one published entity so you can compare data from different data sources. - -### Use Case - -Imagine that you have an app that helps with asset management. You have a Published OData Service with persistable entities called **SmartTask** and **Employee** that expose information. The domain model looks like this: - -{{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/asset-manager-domain-model.png" class="no-border" >}} - -To visualize data from your app in Tableau, follow these steps: - -1. Open **Tableau** and select **Connect** > **To a Server** > **OData**: -2. Return to Studio Pro, and double-click the published OData service. Copy the link the **Location** field to the clipboard. -3. On the **Server Connection** dialog box, enter the copied OData service **Location** link for the **Server** address: - - {{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/18582020.png" class="no-border" >}} - - Include authentication credentials if you set them up. - -4. Click **Sign In** to save the server connection. You should now see the data source details. -5. Click the name of the server connection and change it to a name related to your entity (in this case, **SmartTasks**) for readability. -6. Click **Data** > **New Data Source** and repeat step 1–5 to add a server connection for other published OData services. -7. Open **Sheet1**. Under **Data**, click the first entity and drag a desired entity **Attribute** from **Measures** to **Dimensions**. In this case, click **Engineers** and drag **ID** from **Measures** to **Dimensions**: - - {{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/18582012.png" class="no-border" >}} - -8. Similarly, click and drag an attribute from the second entity from **Measures** to **Dimensions**. In this case, click **SmartTasks** and drag **SmartTask_Engineer** from **Measures** to **Dimensions**. -9. Go to **Data** > **Edit Relationships...** to define the relationship between the different data sources. -10. On the **Relationships** window, do the following:
- 1. Select your first entity for the **Primary data source**. In our imagined scenario, that is **SmartTasks**.
- 1. Select your second entity for the **Secondary data source**. In our imagined scenario, that is **Engineers**.
- 1. Switch to **Custom** mapping.
- 1. Remove any default mappings.
- 1. Click **Add...** to configure a field mapping. - - {{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/18582013.png" class="no-border" >}} - -11. In the **Add/Edit Field Mapping** window, select the attribute for the first entity for the **Primary data source field** and **Entity1_Entity2** for the **Secondary data source field**, then click **OK** to save the field mapping. In this case, select **ID** for the **Primary data source field** and **SmartTask_Engineer** for the **Secondary data source field**: - - {{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/18582011.png" class="no-border" >}} - -12. In the **Relationships** window, click **OK** to save the relationships: - - {{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/18582007.png" class="no-border" >}} - -13. Select the second entity for the data source (in this case, **Engineers**) and drag the **Name** attribute from the **Dimensions** section to **Rows**: - - {{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/18582006.png" class="no-border" >}} - -14. Select your first published entity (in this case, **SmartTasks**) for the data source and do the following:
- 1. Click the **SmartTask_Engineer** attribute to use it as the linking field.
- 1. Drag **Number of Records** from the **Measures** section to **Columns**. - - {{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/18582005.png" class="no-border" >}} - -You should now see a bar chart of the data. - -## Filtering Data With Query Parameters - -By default, all data is retrieved by Tableau, but Mendix allows you to add filters to the query so only the desired data is being retrieved. - -To filter data with query parameters, follow these steps: - -1. Right-click a data source and select **Edit Data Source...**. -2. Click the OData URL to change the connection settings. -3. Add *?$top=2* to the server URL (in order to only retrieve the first two values, engineers in this case) and click **Sign In**: - - {{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/18581998.png" class="no-border" >}} - -4. On the warning indicating that the data being used was refreshed, click **OK**. -5. Open **Sheet1** and drag **Name** to **Rows** again. Now you should now see a bar chart with only the data of the two engineers: - - {{< figure src="/attachments/howto8/integration/exposing-data-to-bi-tools-using-odata/18581997.png" class="no-border" >}} - -6. You can combine filters by using the `&` character. Repeat steps 1–4, but now use `http://localhost:8080/odata/Expenses/Expenses?$skip=1` as the server URL. You should now see a bar chart showing the data of 2 and 3. - -These are some other query examples: - -* `http://localhost:8080/odata/publishedservicename/v1/Engineers(7881299347898469)` -* `http://localhost:8080/odata/publishedservicename/v1/Engineers/$count` -* `http://localhost:8080/odata/publishedservicename/v1/Engineers?$filter=Name+eq+'Kim'` -* `http://localhost:8080/odata/publishedservicename/v1/Engineers?$filter=Name+ne+'Kim'` -* `http://localhost:8080/odata/publishedservicename/v1/SmartTasks?$filter=DueDate+gt+datetime'1995-01-01T00:00:00'` -* `http://localhost:8080/odata/publishedservicename/v1/SmartTasks?$filter=Created+gt+datetime'2005-01-01T00:00:00'&$orderby=DueDate` - -## Read More - -* [Consume a Complex Web Service](/howto8/integration/consume-a-complex-web-service/) -* [Consume a Simple Web Service](/howto8/integration/consume-a-simple-web-service/) -* [Export XML Documents](/howto8/integration/export-xml-documents/) -* [Import Excel Documents](/howto8/integration/importing-excel-documents/) -* [Expose a Web Service](/howto8/integration/expose-a-web-service/) diff --git a/content/en/docs/howto8/integration/implement-cicd-pipeline.md b/content/en/docs/howto8/integration/implement-cicd-pipeline.md deleted file mode 100644 index fab751a6f23..00000000000 --- a/content/en/docs/howto8/integration/implement-cicd-pipeline.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: "Implement a Simple CI/CD Pipeline with Mendix APIs" -linktitle: "Implement CI/CD Pipeline" -url: /howto8/integration/implement-cicd-pipeline/ ---- - -## Introduction - -This how-to describes how you can use the available Mendix APIs with any mainline orchestrators (Jenkins, Visual Studio Team Services, etc.) to build a simple CICD pipeline. - -This is not meant to be a step-by-step guide. It will simply show you which APIs to use and provide some examples on how to use them. The tool used in the examples is [postman](https://www.getpostman.com/). - -## Prerequisites - -Before starting this how-to, make sure you are familiar with the following: - -* CICD -* Using REST services -* [Unit Testing](/appstore/modules/unit-testing/) (only if used in your application) -* [Application Test Suite](/appstore/partner-solutions/ats/) (only if used in your application) - -## The Pipeline - -### API Rights and Keys - -#### User API Key - -To get access to Mendix Cloud environments, an authorized user is needed when executing the APIs. With Mendix APIs, API keys are used to achieve this. To create a Mendix API key, follow the steps in [Authentication](/apidocs-mxsdk/apidocs/authentication/). - -#### Mendix API Rights - -To be able to use the Mendix APIs to access your environment, you will need to grant API rights to the user that is going to be used to access the APIs. To grant API rights to that user, open your app in [Apps](https://sprintr.home.mendix.com/), then go to **Security** > **Node Permissions**, and check the **API RIGHTS** option for the user you created an API key for in the previous step. - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/01APIRightsCloudPortal.png" class="no-border" >}} - -### Building the Deployment Package - -To build the deployment package, use the [App Repository API](/apidocs-mxsdk/apidocs/app-repository-api/) and the [Build API](/apidocs-mxsdk/apidocs/build-api/). In this scenario, a package will be built for the latest revision, but you can use whatever version you wish. - -#### Getting the Latest Revision - -To get the latest revision, use the [Retrieve Branch](/apidocs-mxsdk/apidocs/app-repository-api/#retrieve-branch) API call to get the `latestCommit.id` from the output. - -#### Building the Package{#BuildPackage} - -After getting the version you want to build the package for, you need to build the package. To do this, use the [Start Building a Deployment Package API call](/apidocs-mxsdk/apidocs/build-api/#start-building-deployment-package). - -This is a POST call, so you will need to pass the relevant fields in the body (follow the link above to know what to use). - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/03StartBuildingPackage.png" class="no-border" >}} - -Before proceeding to the next step, you need to wait for the build of the deployment package to be successful. To do this, use the [Retrieve Package API call](/apidocs-mxsdk/apidocs/build-api/#retrieve-package). This scenario needs to use the `PackageId` (output from the previous call) and check if the status is `Succeeded` (the other possible statuses are Queued, Building, Uploading, and Failed). - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/04RetrievePackageStatus.png" class="no-border" >}} - -### Deploying to the Next Environment {#deploying-to-the-next-environment} - -After building the deployment package, you can now deploy the new package to the next (Test, Acceptance, etc.) environment. To do this, use the [Deploy API](/apidocs-mxsdk/apidocs/deploy-api/). - -#### Getting the Environment Status - -First, you need to check if the environment to which you want to deploy is running. You need to know if you need to stop it before deploying the new deployment package to it. To do this, use the [Retrieve Environment API call](/apidocs-mxsdk/apidocs/deploy-api/#retrieve-environment) and check the status. - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/05GetEnvironment.png" class="no-border" >}} - -#### Stopping the Environment - -If the environment is running, you need to stop it. To do this, use the [Stop Environment API call](/apidocs-mxsdk/apidocs/deploy-api/#stop-environment). - -#### Deploying/Transporting the Package - -To deploy/transport a package to the environment, use the [Transport a Deployment Package to an Environment API call](/apidocs-mxsdk/apidocs/deploy-api/#transport-deployment-package). - -For this action, you need the `PackageId` from section [3.2.2 Building the Package](#BuildPackage). - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/06TransportDeploymentPackageToEnvironment.png" class="no-border" >}} - -#### Starting the Environment - -After a successful deployment, you must start the environment. To do that, use the [Start Environment API call](/apidocs-mxsdk/apidocs/deploy-api/#start-environment). - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/07StartEnvironment.png" class="no-border" >}} - -Before proceeding to the next steps (although you might not have any, if all you want to automate is the transport to another environment), you must make sure the environment has started. To do that, use the [Get Environment Status API call](/apidocs-mxsdk/apidocs/deploy-api/#get-start-environment-status) with the `JobId` (output of the previous call). The environment will be ready when the status is **Started**. - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/08StartEnvironmentStatusStarting.png" class="no-border" >}} - -### Running Tests - -After deploying the package to the environment and starting it, you are ready to run tests. This is not a mandatory step in a CICD pipeline, but it is usually part of it. - -The sections below show you how to execute unit and ATS (UI) tests remotely. There can also be other tests (for example, load tests), but these are not covered in this how-to. - -#### Unit Tests - -One way of doing unit tests in a Mendix app is by using the [Unit Testing](/appstore/modules/unit-testing/) module available from the Mendix Marketplace. This module already exposes an API to execute remote calls. - -First, you need to start the tests. - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/10StartUnitTests.png" class="no-border" >}} - -When the tests are completed (check the status for when completed is `true`), you can see how many tests ran, how long they took to run, how many failed, which ones failed, and what the reasons were for failing. - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/11UnitTestsStatus.png" class="no-border" >}} - -{{% alert color="info" %}} - -You can also (manually) create a web service that exposes the standard unit structure from the data available in the Unit Testing module. - -{{% /alert %}} - -#### Mendix Application Test Suite (ATS) Tests - -ATS has its own [API for CICD](/appstore/partner-solutions/ats/rg-two-cicd-api/#api). To use this, follow the steps in the **ATS and CI/CD** section of [How to Use ATS in Combination with CI/CD](/appstore/partner-solutions/ats/ht-two-ats-and-ci-cd/#ats-and-ci-cd). - -### Next Steps - -If you need to promote to another environment, repeat the steps in [Deploying to the Next Environment](#deploying-to-the-next-environment) section. - -## Jenkins/VSTS Examples - -The sections below present examples of how to call a Mendix API with Jenkins (using a groovy script) and Visual Studio Team Services (VSTS). - -### Jenkins - -To call a REST service with Jenkins (using a groovy script), install the [HTTP Request Plugin](https://wiki.jenkins.io/display/JENKINS/HTTP+Request+Plugin). If you also want to bind credentials to variables (see `withCredentials` in the code snippet below), install the [Credentials Binding Plugin](https://jenkins.io/doc/pipeline/steps/credentials-binding/). The `Mendix-Username` and `Mendix-ApiKey` will be set in a `customHeaders` array. - -This code snippet example gets the latest revision number so it can be used when building the deployment package: - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/12Jenkins.png" class="no-border" >}} - -### VSTS - -To call a REST service with VSTS, use the [Invoke REST API task](https://docs.microsoft.com/en-us/vsts/build-release/tasks/utility/http-rest-api). This should be used in an agentless phase, and you will need to set up a **Generic endpoint** first. The `Mendix-Username` and `Mendix-ApiKey` will go in the **Headers** section. You can set **Success criteria** (under the **Advanced** section) to define what makes the task successful. - -The example below checks the status of the acceptance environment. The task will be successful if the environment is running. - -{{< figure src="/attachments/howto8/integration/implement-cicd-pipeline/13RestExampleVSTS_cut.png" class="no-border" >}} diff --git a/content/en/docs/howto8/integration/importing-and-exporting-objects.md b/content/en/docs/howto8/integration/importing-and-exporting-objects.md deleted file mode 100644 index 87efd73f1b6..00000000000 --- a/content/en/docs/howto8/integration/importing-and-exporting-objects.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: "Import and Export Objects" -url: /howto8/integration/importing-and-exporting-objects/ -weight: 2 ---- - -## Introduction - -In Mendix, you don't need to reinvent the wheel. You can save time by importing modules others have created and by exporting new modules for others to use. The Marketplace provides this functionality on a macro level. You can also use 's built-in import and export functions to share content between your own apps, import unofficial modules, and share entire projects. - -{{% alert color="warning" %}} -Please note throughout this how-to that Mendix packages are stored as Mendix package (*.mpk*) files. These are not compatible with each other; you cannot, for example, import individual *modules* from a *project* package. -{{% /alert %}} - -This how-to teaches you how to do the following: - -* Import and export the following Studio Pro objects: - * projects - * modules - * widgets - * module documents such as pages or microflows - -## Importing Objects - -{{% alert color="warning" %}} -Be careful when importing objects, as you can overwrite your existing work. Pay attention to prompts and warnings along the way! -{{% /alert %}} - -### Importing Project Packages - -A Mendix package (*.mpk*) file can store a complete Mendix project. - -To import a complete Mendix project package, follow these steps: - -1. Click the **File** menu in and select **Import Project Package...**: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582103.png" class="no-border" >}} - -2. Select your Mendix project package file and click **Open**. The **Import Project Package** dialog box will appear: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582101.png" class="no-border" >}} - - You have the following options in this dialog box: - - * Decide whether to store your app in a **New Mendix Team Server** (recommended), an **Existing Mendix Team Server**, or **Locally on disk** - * Provide an **App name** (by default, it will be named as it was in the Mendix package file) - * Determine the local folder where you would like to store your project in **Project directory** - -3. Click **OK**, and your project will be loaded in . - -### Importing Module Packages - -A Mendix package (*.mpk*) file can store a Mendix project module. - -To import module packages, follow these steps: - -1. Right-click your project in the **Project Explorer** and select **Import Module Package**. - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/import-package.png" class="no-border" >}} - -2. Select your Mendix module package file and click **Open**. The **Import Module** dialog box will open. -3. In the dialog box, choose a name for your module and select whether to create a new module or replace an existing one: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582113.png" class="no-border" >}} - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582112.png" class="no-border" >}} - - {{% alert color="info" %}}If you replace the module with a new version, the existing user data will be retained based on the names of entities, attributes, and associations. If you delete a module and then add a newer version of it, all user data will be lost.{{% /alert %}} - -4. Click **Import**. You may see a **Warning** pop-up window that will inform you of any included module dependencies that will be overwritten in your project. - -5. Click **OK**. You will see your new or replaced module in the **Project Explorer**. - - You will also see your changes in the **Changes** section of . In this example, the existing module has been deleted and replaced by the newly imported module: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582109.png" class="no-border" >}} - -### Importing Module Documents - -A Mendix package (*.mpk*) file can store a Mendix module document. - -The package can contain a single example of one of the following: - -* Page -* Microflow -* Nanoflow -* Image -* Layout -* Menu -* Snippet -* Building block -* Page template -* Java Action -* Rule -* Enumeration -* Data Set -* Constant -* Regular Expression -* Scheduled Event -* Document Template -* Message Definition -* JSON structure -* XML schema -* Export mapping -* Import mapping -* Consumed app service (deprecated) -* Consumed web service -* Published REST service -* Published web service -* Published OData service -* Published app service (deprecated) - -To import module objects, follow these steps: - -1. Right-click a module in the **Project Explorer** and select **Import document from file...**: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582100.png" class="no-border" >}} - - The **Import Document from File** dialog box will appear. - -2. Select your Mendix package file containing the document you want to import, and click **Open**. - - {{% alert color="info" %}}If a document with the same name already exists, you will see the **Warning** pop-up window. In that case, you can either select **Rename** to rename the object or **Cancel**.{{% /alert %}} - -3. Click **OK** to import the object into your module: - - {{% alert color="info" %}}You may need to update the new object's permissions, depending on where it was originally exported from. For consistency, be sure to check the permissions on any objects imported.{{% /alert %}} - -### Importing Widgets - -A Mendix package (*.mpk*) file can store one or more widgets. You need to place the Mendix package file in your project directory to import it. - -To import widgets, follow these steps: - -1. Click the **Project** menu and select **Show Project Directory in Explorer**: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582108.png" class="no-border" >}} - -2. Open the **widgets** folder in your project directory and put your Mendix package file there. - -3. Open the **Project** menu and select **Synchronize Project Directory** to synchronize the changes in the project directory: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582106.png" class="no-border" >}} - - {{% alert color="info" %}}You can also press F4 to synchronize your project directory.{{% /alert %}} - -4. Add your newly imported widget from the **Toolbox** or the **Add Widget** context menu. - -### Importing Content from the Marketplace - -To learn more about importing content from the Marketplace, see [How to Use Marketplace Content](/appstore/use-content/). - -## Exporting Objects - -### Exporting Complete Project Packages - -To export a project, follow these steps: - -1. Click the **File** menu in and select **Export Project Package...** - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582091.png" class="no-border" >}} - -2. The **Export Project Package** dialog box will appear, which enables you to set the export location and select data to export (if required): - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582090.png" class="no-border" >}} - - The **Existing snapshot** option will only be available when a data snapshot was created earlier using the **Add snapshot of data** menu option from the **Team** menu. It is also possible to include a new snapshot based on the current state of the local database. This option is only available after the project has been started at least once. - -3. Click **Export** to create the package. - -### Exporting Modules - -To export a module, follow these steps: - -1. Right-click a module in the **Project Explorer**, and select **Export module package...**: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582095.png" class="no-border" >}} - - If your module refers to other modules in the project (that is, it is not self-contained), you will see a pop-up window warning you of this. - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582094.png" class="no-border" >}} - - Select **Find usages of other user modules** to view the references, or click **Continue exporting** and you will see the **Select Dependencies** dialog box: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582093.png" class="no-border" >}} - - Here you can select files you would like to include in your package. This list includes any files in the **userlib** or **resources** folders in your project directory. If you don't want to include these files, you can uncheck the boxes. - - {{% alert color="info" %}}To uncheck all the files quickly, press Ctrl + A to select all of the items then press Space to uncheck all the objects.{{% /alert %}} - -### Exporting Widgets - -Widgets are automatically available in the **widgets** folder in your project directory as *.mpk* files. - -### Exporting Module Documents - -Mendix module documents can be exported as a Mendix package (*.mpk*) file. - -1. Right-click the document you want to export and select **Export document to file...**: - - {{< figure src="/attachments/howto8/integration/importing-and-exporting-objects/18582092.png" class="no-border" >}} - - The **Export Page to File** dialog box will open. - -2. Enter the **Name** for your package and click **Save**. - -## Read More - -* [Consume a Complex Web Service](/howto8/integration/consume-a-complex-web-service/) -* [Consume a Simple Web Service](/howto8/integration/consume-a-simple-web-service/) -* [Export XML Documents](/howto8/integration/export-xml-documents/) -* [Import Excel Documents](/howto8/integration/importing-excel-documents/) -* [Expose a Web Service](/howto8/integration/expose-a-web-service/) -* [Configure Selenium Support](/howto8/integration/selenium-support/) -* [Import XML Documents](/howto8/integration/importing-xml-documents/) -* [Consume a REST Service](/howto8/integration/consume-a-rest-service/) -* [Expose Data to BI Tools Using OData](/howto8/integration/exposing-data-to-bi-tools-using-odata/) -* [Modules](/refguide8/modules/) -* [Project](/refguide8/project/) -* [Common Widgets](/refguide8/common-widgets/) diff --git a/content/en/docs/howto8/integration/importing-excel-documents/_index.md b/content/en/docs/howto8/integration/importing-excel-documents/_index.md deleted file mode 100644 index d4adce2e71d..00000000000 --- a/content/en/docs/howto8/integration/importing-excel-documents/_index.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: "Import Excel Documents" -url: /howto8/integration/importing-excel-documents/ -weight: 5 -description: "Describes how to set up import templates and import data into your app using the Excel Importer module." ---- - -## Introduction - -Adding large amounts of data to your application (for example, reference data or data from an external application) can be very time-consuming. In order to save time and effort, this process can be automated using the [Excel Importer](/appstore/modules/excel-importer/) from the Mendix Marketplace. In this how-to, you will set up import templates and import data into your app using this module. - -## Prerequisites - -Before starting this how-to, make sure you know how to do the following: - -* Create domain models (see [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/)) -* Create overview and detail pages (see [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/)) -* Create menu items (see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/)) -* Create microflows (see [How to Trigger a Microflow From a Menu Item](/howto8/logic-business-rules/trigger-microflow-from-menu-item/) -* Add Marketplace content to your app (see [How to Use Marketplace Content](/appstore/use-content/)) -* Secure your applications (see [How to Create a Secure App](/howto8/security/create-a-secure-app/)) - -## Preparing the Data Structure, GUI and Modules - -Before you can start importing data into your application, you first need to set up the data structure and GUI by following these these steps: - -1. Create the following domain model: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581969.png" class="no-border" >}} - - Create an enumeration for the **OrderStatus** attribute with the values of **Open**, **Processing**, and **Complete**. - - Configure the **XLSFile** object to inherit from the **FileDocument** object (for more information, see [How to Work with Images and Files](/howto8/data-models/working-with-images-and-files/)). -2. Create **Overview** and **Detail** pages to manage objects of the **Customer** and **Order** types. -3. Create menu items to access the **Order** and the **Customer** overview pages. -4. Download the **Excel Importer** and **Mx Model Reflection** modules from the Mendix Marketplace (available by clicking the shopping-cart icon in the upper right of Studio Pro). -5. Create menu items for the **ExcelImportOverview** and the **MxObjects_Overview** pages (these pages already exist in the **_USE_ME** folders of the downloaded modules). -6. Configure the **Administrator** user role to have the **Configurator** module role for the **ExcelImporter** module, and the **ModelAdministrator** module role for the **Mx Model Reflection** module. - -## Preparing the Logic for Data Import {#preparing} - -Because an enumeration is used for the **OrderStatus** attribute, you need to create a microflow to determine the enumeration value of the attribute based on the input from the Excel file. - -1. Create the following microflow and name it **IVK_ParseStatus**. - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581968.png" class="no-border" >}} - -2. Set the **Return value** as follows: - - ```text - if $Unformatted = 'open' then MyFirstModule.OrderStatus.Open - else if $Unformatted = 'processing' then MyFirstModule.OrderStatus.Processing - else if $Unformatted = 'complete' then MyFirstModule.OrderStatus.Complete - else MyFirstModule.OrderStatus.Complete - ``` - -3. **Save** the microflow. - -## Using Application Model Metadata in the Client - -In order to set up import templates for importing data, your application model metadata should be reflected in the client. This can be achieved by using the [Mx Model Reflection](/appstore/modules/model-reflection/) module. In this section, you will learn how to do this by following these steps: - -1. Click **Run Locally** to start your application. -2. Click **View** to open your application in the browser. -3. **Log in** as an Administrator. -4. Click on the menu item for the **MxObjects_Overview** in your navigation. -5. Select the module that contains the objects you want to use in your client by checking the box to the left of it – which in this case is **MyFirstModule**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581937.png" class="no-border" >}} - -6. Click the button next to **Synchronize all entities and microflows of checked modules on the left**. Now the two objects and the parse microflow from the **MyFirstModule** module can be seen and used in the client. - -## Manually Creating an Import Template {#creating} - -Before you can import data from an Excel File into your application, you have to set up an import template. In this template, you will configure the objects to which the data should be mapped, if an object is associated to another object, from which row of the Excel file the import should start, and which columns should be imported. - -In this section, you will import data from a simple Excel file example, which can be downloaded here: - -{{< figure src="/attachments/howto8/integration/importing-excel-documents/18581938.png" link="/attachments/howto8/integration/18448735/18581949.xlsx" class="no-border" >}} - -Based on the structure of the file you want to import, you need to manually set up your template by following these steps: - -1. Click the menu item for **ExcelImportOverview** in the navigation of your app's home page. -2. Click **New Template**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581971.png" class="no-border" >}} - -3. Give a name to the template. -4. Click the arrow next to the **Mendix object** box. -5. Double-click the **Customer** object: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581966.png" class="no-border" >}} - -6. Click the arrow next to the **Reference to import objects** box. -7. Select the **MyFirstModule.Customer_XLSFile** association. By setting the association to the XLS file, the XLS file is saved on disk and the imported data is linked to the source file. -8. Make sure **Import Action** is set to **Synchronize objects**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581965.png" class="no-border" >}} - - {{% alert color="info" %}}For this example you will be using a simple Excel file that has just one sheet and column headers on the first row. If a more comprehensive Excel file is used, you can change these values via the **Sheet nr**, **Header row nr**, and **Import from row nr** fields.{{% /alert %}} - -9. In the **Connect columns to attributes** section, click **New** to create a mapping from the Excel sheet column to the proper Mendix attribute. -10. Add the column number that corresponds to the column number from the Excel file you want to map. - - {{% alert color="info" %}}The number of the first column in Excel is 0, the second is 1, etc.{{% /alert %}} - -11. Define the Excel column header as the **Caption** value. -12. Select **Attribute** for the **Type**. -13. Click the arrow next to the **Attribute** box: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581963.png" class="no-border" >}} - -14. Double-click the **Attribute** to which you want to map the Excel value: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581962.png" class="no-border" >}} - -15. Repeat steps 9 to 14 above for each attribute of the **Customer** object. - - * For the mapping of attribute **Name**, set the **Key** value to **Yes** to prevent a customer from being duplicated. - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581961.png" class="no-border" >}} - - {{% alert color="info" %}}If the mapping is set up right, a green check appears in front of the row.{{% /alert %}} - -16. You now need to create mappings for the **Order** object attributes. However, because the **Order** object is associated to the **Customer** object, the mapping setup will be slightly different. Follow these steps for each attribute of the **Order** object:
- 1. Add the column number that corresponds to the column number from the Excel file you want to map.
- 1. Define the Excel column header as the **Caption** value.
- 1. Choose **Reference** for the type.
- 1. Click the arrow next to the **Reference** box, where you can select the association over which the order is linked to the customer – which in this case should **Order_Customer**.
- 1. Click the arrow next to the **Attribute** box and double-click the **Attribute** to which you want to map the Excel value.
- 1. For the mapping of attribute **Number**, set the **Key** value to **Yes, only for the associated object** in order to prevent orders being duplicated.
- 1. Click **Save**. - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581956.png" class="no-border" >}} - -17. For the mapping of the **OrderStatus** attribute, the Excel file value needs to be parsed to an enumeration value. To achieve this, you can use the **IVK_ParseStatus** microflow (created in the [Preparing the Logic for Data Import](#preparing) section above). Click the arrow next to the **Parse with** box and select the **IVK_ParseStatus** microflow: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581953.png" class="no-border" >}} - -18. Save the import template. - -### Importing an Excel File - -Now that the template is set up, you can start importing data from an Excel file into your application. You can use the example file you downloaded in the [Creating the Import Template](#creating) section above. - -Follow these steps to import the Excel file: - -1. Click the menu item for **ExcelImportOverview** in the navigation of your app's home page. -2. Go to the **Import files** tab and click **New**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581952.png" class="no-border" >}} - -3. Select the template you just created. -4. Click **Browse**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581951.png" class="no-border" >}} - -5. Select the example Excel file you downloaded and click **Save**. -6. Click the Excel file under **Filename** to select it, then click **Import file**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581950.png" class="no-border" >}} - -7. Click **OK** when the import has finished. - -## Automatically Creating an Import Template via an Excel File - -In the previous steps, you manually added all the columns to your import template. In this section, you will create the same Excel template in an automated way, which you can do this via the specific **New template by excelfile** button. You can use this same Excel file example: - -{{< figure src="/attachments/howto8/integration/importing-excel-documents/18581938.png" link="/attachments/howto8/integration/18448735/18581949.xlsx" class="no-border" >}} - -Follow these steps to create the import template via the Excel file: - -1. Click the menu item for **ExcelImportOverview** in the navigation of your app's home page. -2. Click **New template by excelfile**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581948.png" class="no-border" >}} - -3. Select the example Excel file you downloaded. -4. Define the **Sheet nr**, **Header row nr**, and **Import from row nr**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581947.png" class="no-border" >}} - -5. Click **Save & next**. This will automatically create a row for every header of the Excel file: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581936.png" class="no-border" >}} - -6. Back in the top section of the page, click the arrow next to **Mendix object** and select the **Customer** object type: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581935.png" class="no-border" >}} - -7. Under **Connect columns to attributes**, click **Connect matching attributes**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581934.png" class="no-border" >}} - - This will automatically match attributes of the selected Mendix object that have the same name as the **Caption**. - -8. Complete the template as you did in the [Creating the Import Template](#creating) section above. - - {{% alert color="info" %}}Remember that you have to set a key attribute for the **Customer** object as well as the **Order** object.{{% /alert %}} - -## Exporting and Importing a Template - -Once you have completed an Excel template, you can export the template (for example, from a test environment) and import it (for example, into an acceptance environment). When exporting and importing a template, the exact template will be uploaded, which means that columns are generated, the Mendix object is selected, the attributes are connected, and the parse microflows are selected. - -Follow these steps to export and import your template: - -1. Click the menu item for **ExcelImportOverview** in the navigation of your app's home page. -2. Click the Excel template you created in the [Creating the Import Template](#creating) section above to select it, then click **Export template** and save the file on your computer: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581933.png" class="no-border" >}} - -3. Import the file you just downloaded by clicking **Import template**, selecting the file, and clicking **Import**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/18581932.png" class="no-border" >}} - -You have now imported a complete import template. - -{{% alert color="info" %}}You will have a duplicate import template in your app, but in a working scenario, you would import this template in a different environment/database where the template had not already been created.{{% /alert %}} - -## Read More - -* [Export XML Documents](/howto8/integration/export-xml-documents/) -* [Import XML Documents](/howto8/integration/importing-xml-documents/) -* [Expose a Web Service](/howto8/integration/expose-a-web-service/) diff --git a/content/en/docs/howto8/integration/importing-excel-documents/import-a-large-excel-file.md b/content/en/docs/howto8/integration/importing-excel-documents/import-a-large-excel-file.md deleted file mode 100644 index 8630ea0e7e7..00000000000 --- a/content/en/docs/howto8/integration/importing-excel-documents/import-a-large-excel-file.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: "Import a Large Excel File" -url: /howto8/integration/import-a-large-excel-file/ ---- - -## Introduction - -Every now and then a client asks you to import some data. It doesn’t look like a lot of effort at first glance, so you add it as a task and plan to pick it up at the end of the day. - -Looking at the sheet later, you realize that there are more than hundred columns that need to be imported into the application. This means manual labor, a lot of it. As every column represents an attribute, creating 100+ new attributes in an import entity would take ages if you did it manually. - -The trick is to use XML-to-domain mapping. - -We will use XML-to-domain mapping to create a new import entity from an Excel sheet quickly in a semi-automated way. - -This how-to teaches you how to do the following: - -* Quickly import a large Excel file with a lot of columns - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisite: - -* Have an app with the [MxModel Reflection](/appstore/modules/model-reflection/) and [Excel Importer](/appstore/modules/excel-importer/) modules installed and configured from the Mendix Marketplace - -## Modifying Your Excel Sheet - -The Excel sheet you receive in this scenario contains almost every country in the world, and for every country, some data is stored. This data has to be imported into your application. - -You can find the Excel sheet here: [Countries](/attachments/howto8/integration/Excel/Countries.xlsx). - -You are going to make an XSD schema from the headers in the Excel sheet so that you can import this later into the model. - -To modify your Excel sheet, follow these steps: - -1. Select the header row with all the country names. -2. Copy and paste them in a new sheet using the transpose function: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/import-a-large-excel-file/19398888.png" class="no-border" >}} - - Your headers should be listed vertically and your sheet should look like this: [Countries Transposed](/attachments/howto8/integration/Excel/CountriesTransposed.xlsx). - - We are now ready to add some tags around the column. - -3. Add one column to the left. -4. Place the following string in cell **A1**: - - ```text - }} - -6. In cell **C1**, enter the following string: - - ```text - "/> - ``` - -7. Like you did with the previous string, drag it down to the last country. The Excel sheet should now look like this: [Countries with Tags](/attachments/howto8/integration/Excel/CountriesWithTags.xlsx). - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/import-a-large-excel-file/19398890.png" class="no-border" >}} - - Now you have to get the three different columns into one column. This is necessary because later on, you want to copy the whole column into an XSD file. - -8. Select cell **D1** and type in the following into the formula box: - - ```text - =(A1&B1&C1) - ``` - -9. Drag the cells down like you’ve done with column **A1** and **C1**. Now your column **D** should have the columns **A**, **B**, and **C** combined into one, and your sheet should look like this: [Countries with Tags and Column D](/attachments/howto8/integration/Excel/CountriesWithTagsAndColumnD.xlsx). - -## Preparing Your XSD File - -We have used some of the basic functionalities of Excel to help us out creating the first part of our XSD structure. For a proper XSD file, we still need to have a header and a footer. This is where your favorite text editor comes in (for example, Brackets). - -To prepare your XSD file, follow these steps: - -1. Open a new file and call it *CountriesImport.xsd*. -2. Place this text as the header of your XSD file: - - ```xsd - - - - - - ``` - -3. Go back to your sheet, copy the content from column **D**, and paste it underneath the header. -4. Now it’s time to place the footer, which will complete the XSD file. Place this text as for footer: - - ```xsd - - - - - ``` - - Your file should look like this: [Country Import](/attachments/howto8/integration/Excel/CountryImport.xsd). - -5. Don’t forget to save it! - -## Importing into Your Application Project - -The XSD file is ready to be imported into . To import it, follow these steps: - -1. Open your app and create a new XSD schema: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/import-a-large-excel-file/19398893.png" class="no-border" >}} - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/import-a-large-excel-file/create.png" class="no-border" >}} - -2. With the new XSD schema created, it’s time to create the XML-to-domain mapping that will perform the trick for you and make your life a bit easier. - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/import-a-large-excel-file/19398895.png" class="no-border" >}} - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/import-a-large-excel-file/19398896.png" class="no-border" >}} - -3. Be sure to check all the attributes! After clicking **OK**, you should see a mapping entity with all your countries. - -4. You will now generate a real entity from it that you can use as an import table for your Excel sheet. Click **Map automatically**: - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/import-a-large-excel-file/19398897.png" class="no-border" >}} - - There’s your entity! - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/import-a-large-excel-file/19398898.png" class="no-border" >}} - -5. Go to your domain model, set the entity’s **Persistable** property to **Yes**, and the job is done! - - {{< figure src="/attachments/howto8/integration/importing-excel-documents/import-a-large-excel-file/19398899.png" class="no-border" >}} - -6. To keep your application clean, you can delete the XSD schema and XML-to-domain files from your project. - -Happy modeling! diff --git a/content/en/docs/howto8/integration/importing-xml-documents.md b/content/en/docs/howto8/integration/importing-xml-documents.md deleted file mode 100644 index 3560e4e9366..00000000000 --- a/content/en/docs/howto8/integration/importing-xml-documents.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: "Import XML Documents" -url: /howto8/integration/importing-xml-documents/ -weight: 3 ---- - -## Introduction - -Mendix is the app platform for the enterprise organization, and in enterprise software, you likely do not work in a [green field](https://en.wikipedia.org/wiki/Greenfield_project). In almost every situation, you will need to integrate with existing systems. Mendix supports many ways of integration, but this how-to focuses on how you can import XML documents with Mendix. - -This how-to teaches you how to do the following: - -* Prepare the data structure and GUI -* Add an XML schema -* Create XML-to-domain mapping - -## Prerequisites - -Before you continue, make sure that you know how to create: - -* Domain models (see [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/)) -* A custom file document (see [How to Work with Images and Files](/howto8/data-models/working-with-images-and-files/)) -* Overview and detail pages (see [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/)) -* Menu items (see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/)) - -## Preparing the Data Structure and GUI - -The XML document used in this how-to contains customers. To be able to see the imported data, you first need to set up the data structure and GUI to maintain the customer data. Then, you need to facilitate the uploading and downloading of XML documents. Finally, you will create the actual import logic and the corresponding import mapping. - -To prepare the data structure and the GUI, follow these steps: - -1. Create the following **Customer** entity in your domain model: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581649.png" class="no-border" >}} - -2. Create the overview and detail pages to manage objects of the **Customer** type. -3. Create a menu item to access the customer overview page. -4. Create an entity called **XMLDocument** that inherits all the properties from **System.FileDocument**: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581650.png" class="no-border" >}} - -5. Create the overview and detail pages to manage objects of the **XMLDocument** type. -6. Create a menu item to access the XML document overview page (for more information, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/). - -## Adding an XML Schema (XSD) - -Whether you plan to import or export documents, working with XML means that your application must contain an XML schema, which is also called an XSD. An XSD describes the possible contents of an XML file. Based on the XSD, your application knows how to read or write an XML file. If you don't have an XSD file, there are some online XSD generators that accept an XML document as input. For this how-to, you can use [Customers.xsd](/attachments/howto8/integration/18448727/18581652.xsd). - -To add an XML schema (XSD), follow these steps: - -1. Right-click a module in the **Project Explorer** and select **Add Other** > **XML schema** from the menu. -2. Enter **CustomersXSD** as the **Name** and click **OK**: - - {{< figure src="/attachments/howto8/integration/export-xml-documents/18581696.png" class="no-border" >}} - -3. In the **XML Schema** editor, click **Select** and select the XSD file that you downloaded earlier: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581657.png" class="no-border" >}} - -4. Click **OK** to save the XML schema, which you will be using in the following steps. - -## Create XML-to-Domain Mapping - -The XML schema describes what the possible contents of an XML file are, but we need to create an XML-to-domain mapping to define how the data in the XML document is imported into the application. - -To create the XML-to-domain mapping, follow these steps: - -1. Right-click a module in the **Project Explorer** and select **Add Other** > **Import mapping**. -2. Enter **ImportCustomersMapping** as the **Name** and click **OK.** The new mapping will open automatically and the elements will be shown. - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581689.png" class="no-border" >}} - -3. On the **Select schema elements** dialog box, make sure **XML schema** is selected as the **Schema source**, and select **CustomerXSD** as the schema. Then, click **Expand all** to see the tree with elements. -4. Select the following elements: **Customer**, **ID**, **CompanyName**, **Address**, **City**, and **PostalCode**: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581656.png" class="no-border" >}} - -5. Click **OK**. The first part of the import mapping should look like this: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581655.png" class="no-border" >}} - -6. Open the connector (from the lower-right side of Studio Pro or from the **View** menu). -7. Drag the entity **Customer** from the connector into the place-holder in the mapping editor: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581681.png" class="no-border" >}} - - The **Map entity** editor for this element will open automatically: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581654.png" class="no-border" >}} - -8. In the **Map entity** editor, do the following: - * Select **Find an object (by key)** for the **Method** (to be able to search for an object, you need to define one or more keys in the value-to-attribute mappings) - * Select **Create** for **If no object was found** - * Select attributes for all five value-to-attribute mappings - * Set **CustomerID** as the **Key** - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581653.png" class="no-border" >}} - -9. Click **OK** to save the mapping. - -## Creating the Import Logic - -In this section, you will create the logic to import the customers stored in an [XML document](/attachments/howto8/integration/18448727/18581651.xml) in your application. - -To create the import logic, follow these steps: - -1. Open the **XMLDocument** overview page. It should look this, using a default layout: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581648.png" class="no-border" >}} - -2. Right-click the toolbar of the data grid widget and select **Add button** > **Action** to add a new action button: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581647.png" class="no-border" >}} - -3. Double-click the new button to open the **Edit Action Button** editor and do the following:
- 1. Change the caption to *Import XML Document*
- 1. For the **On click** event, select **Call a microflow**, then click **Select** for the microflow, create a new microflow, and name it **XMLDocument_Import**.
- 1. Click **OK** to save the properties.
- - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581646.png" class="no-border" >}} - -4. Right-click the new **Import XML Document** button and select **Go to on click microflow** in the context menu. You should see an empty microflow with **XMLDocument** as the input parameter: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581669.png" class="no-border" >}} - -5. Open the **Toolbox** and drag an **Import with mapping** activity to the line between the start and end event. This inserts a new import XML activity. -6. Double-click the new activity to open the **Import With Mapping** dialog box and do the following:
- 1. Select the input parameter **XMLDocument** as the **Variable**.
- 1. Select the previously created XML-to-domain mapping **ImportCustomersMapping** as the mapping.
- 1. Click **OK** to save the properties.
- - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581668.png" class="no-border" >}} - - The microflow should look like this: - - {{< figure src="/attachments/howto8/integration/importing-xml-documents/18581667.png" class="no-border" >}} - -## Importing an XML File - -To import the XML file, follow these steps: - -1. Deploy the application, upload [Customers.xml](/attachments/howto8/integration/18448727/18581651.xml), and trigger the import microflow. -2. Open the customer overview page and check if the customer data has been imported into your application. - -## Read More - -* [How to Consume a Complex Web Service](/howto8/integration/consume-a-complex-web-service/) -* [How to Consume a Simple Web Service](/howto8/integration/consume-a-simple-web-service/) -* [How to Export XML Documents](/howto8/integration/export-xml-documents/) -* [How to Expose a Web Service](/howto8/integration/expose-a-web-service/) -* [How to Handle Selenium Support](/howto8/integration/selenium-support/) -* [How to Consume a REST Service](/howto8/integration/consume-a-rest-service/) -* [How to Expose Data to BI Tools Using OData](/howto8/integration/exposing-data-to-bi-tools-using-odata/) diff --git a/content/en/docs/howto8/integration/publish-data-to-other-mendix-apps-using-an-app-service.md b/content/en/docs/howto8/integration/publish-data-to-other-mendix-apps-using-an-app-service.md deleted file mode 100644 index 10df3ea4234..00000000000 --- a/content/en/docs/howto8/integration/publish-data-to-other-mendix-apps-using-an-app-service.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Publish Data to Other Mendix Apps Using an App Service (Deprecated)" -url: /howto8/integration/publish-data-to-other-mendix-apps-using-an-app-service/ -weight: 14 -description: "Describes how to use an app service to publish data to other Mendix apps." ---- - -{{% alert color="info" %}} -App services are deprecated marked for removal. Use a [published web service](/refguide8/published-web-services/) or a [published REST service](/refguide8/published-rest-services/) instead. -{{% /alert %}} - -## Introduction - -In this how-to, you will create an app in which you keep track of the inventory of a shop. This app makes the inventory available for use in other Mendix apps via an app service. - -## Creating the Domain Model - -The domain model defines the products that you want the save and how you want to expose them. - -To create the domain model, follow these steps: - -1. In the domain model, create a persistable entity called **Product** with two attributes: **Name** (String) and **Stock** (Integer). -2. Create a non-persistable entity called **PublishedProduct** with the same attributes. - - {{< figure src="/attachments/howto8/integration/publish-data-to-other-mendix-apps-using-an-app-service/domain-model.png" class="no-border" >}} - -## Creating Pages - -To create pages that allows users to create, edit, and delete products, follow these steps: - -1. Add a new page called **EditUser**. -2. Add a data view. -3. From the **Connector**, drag the **Product** entity onto to yellow **[Unknown]** bar. -4. On the dialog box that appears, click **OK**. - - {{< figure src="/attachments/howto8/integration/publish-data-to-other-mendix-apps-using-an-app-service/edit-product-page.png" class="no-border" >}} - -5. Open the **Home page** and add a data grid. -6. From the **Connector**, drag the **Product** entity onto to yellow **[Unknown]** bar. -7. On the dialog box that appears, click **OK**. -8. From the **Project Explorer**, drag the **EditUser** page onto the **New** button. -9. From the **Project Explorer**, drag the **EditUser** page onto the **Edit [default]** button. - - {{< figure src="/attachments/howto8/integration/publish-data-to-other-mendix-apps-using-an-app-service/homepage.png" class="no-border" >}} - -## Creating a Microflow - -We will now create a microflow that retrieves all the products from the database and converts them to published products. - -To create this microflow, follow these steps: - -1. Add a microflow called **PublishProducts**. -2. From the **Toolbox**, drag a **Retrieve** activity into the microflow. -3. Double-click the **Retrieve** activity and select **From database**. -4. For **Entity**, select **Product**, then click **OK**. -5. From the **Toolbox**, drag a **Create list** activity into the microflow. -6. Double-click the **Create list** activity. -7. For **Entity**, select **PublishedProduct**, then click **OK**. -8. From the **Toolbox** (under **Other**), drag a **Loop** activity into the microflow. -9. Double-click the loop and for **Iterate over**, select **ProductList**, then click **OK**. -10. From the **Toolbox**, drag a **Create** activity onto the loop. -11. Double-click the **Create** activity and for **Entity**, select **PublishedProduct**. -12. Click **New**, and for **Member**, select **Name**. -13. For **Value**, enter *$IteratorProduct/Name*, then click **OK**. -14. Click **New**, and for **Member**, choose **Stock**. -15. For **Value**, enter *$IteratorProduct/Stock*, then click **OK**. -16. From the **Toolbox**, drag a **Change list** activity onto the loop -17. Connect the **Create PublishedProduct** activity to the **Add to list** activity. -18. Double-click the **Add to list** activity and for **List**, select **PublishedProductList**. -19. For **Value**, enter *$NewPublishedProduct*, then click **OK**. -20. Double-click the red end event and for **Type**, select **List**. -21. For **Entity**, select **PublishedProduct**. -22. For **Return value**, enter *$PublishedProductList*, then click **OK**. - - {{< figure src="/attachments/howto8/integration/publish-data-to-other-mendix-apps-using-an-app-service/microflow.png" class="no-border" >}} - -## Creating an App Service - -You will use the microflow to create an app service that exposes the products to other apps. To accomplish this, follow these steps: - -1. In **Project Explorer**, right-click a module and choose **Add** > **Published services** > **Published app service**. -2. For **Name**, enter *Shop*. -3. Click **Create version**. -4. Go to the **Actions** tab and click **New**. -5. For **Name**, enter *Products*. -6. For **Microflow**, select **PublishProducts**, then click **OK**. -7. Go to the **Settings** tab and for **Authentication**, select **Username and password**. -8. Go to the **General** tab and for **Status**, select **Consumable**, then click **OK**. -9. A dialog box will ask whether you want to make this version available. Click **OK**. - -## Securing the App - -Before you publish our app, you need to make sure it is protected with a username and password. To accomplish this, follow these steps: - -1. In **Project explorer**, double-click **Project** > **Security**. -2. For **Security level**, select **Prototype/demo**. -3. Click **Edit module security**. -4. Go to the **Page access** tab and check all the checkboxes. -5. Go to the **Microflow access** tab and check all the checkboxes, then click **OK**. -6. Go to the **Administrator** tab. -7. Type a password, and then click **OK**. - -## Publishing the App Service - -You can now go ahead and deploy the app. This will publish your app service. - -## Read More - -* [Expose a Web Service](/howto8/integration/expose-a-web-service/) -* [Expose Data to BI Tools Using OData](/howto8/integration/exposing-data-to-bi-tools-using-odata/) diff --git a/content/en/docs/howto8/integration/publish-rest-service.md b/content/en/docs/howto8/integration/publish-rest-service.md deleted file mode 100644 index 5a5ccb57639..00000000000 --- a/content/en/docs/howto8/integration/publish-rest-service.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: "Publish a REST Service" -url: /howto8/integration/publish-rest-service/ -weight: 10 -description: "Describes how to publish REST web services natively from ." ---- - -## Introduction - -Mendix allows you to publish REST web services natively from Studio Pro. This how-to will show you how to publish a REST service in an example project. This example will demonstrate the GET operation for a published REST service. - -This how-to teaches you how to do the following: - -* Create a published REST service and return the results in JSON or XML - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install [Studio Pro](https://marketplace.mendix.com/link/studiopro/) - -## Setting Up the Example Project - -To create the example project you will use in the next sections for publishing your REST service, follow these steps: - -1. Create a new app and rename the **MyFirstModule** module to **RESTExample**. -2. Open the domain model of the RESTExample module. -3. Create entities with an association like this: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/domainmodel.png" class="no-border" >}} - -4. You need pages for entering order data, so create an overview page for the **Order** entity In the RESTExample module. -5. Create a **NewEdit** page for the orders, then add a data grid to the **Order_NewEdit** page that displays the **OrderItems** over an association. - -Your page should now look like this: - -{{< figure src="/attachments/howto8/integration/publish-rest-service/order_NewEdit_Page.png" class="no-border" >}} - -Add the overview page to your project navigation and run the application. Create a couple of orders and order lines by filling in the appropriate fields. - -## Publishing the Service - -To be able to use the data from your model in the REST service, you need to create a message definition. - -### Creating the Mapping - -1. In the **Project Explorer**, right-click the **RESTExample** module and select **Add** > **Mappings** > **Message Definitions**: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/message_definition.png" class="no-border" >}} - -2. In the **Add Message Definition** dialog box, enter *MD_Orders* as the name for this definition. -3. The message definition is now opened and you need to select the entity to use for the MD_Orders definition. To do this, select **Add** and in the dialog box, click **Select**, then choose the **Order** entity from the list. - - {{< figure src="/attachments/howto8/integration/publish-rest-service/MD_AddEntity.png" class="no-border" >}} - -4. After selecting the **Order** entity, the **Structure** part of the dialog box is filled with only the **Order** object selected. -5. Select the **OrderID** and **Customer** attributes -6. Expand the **OrderItem_Order** association and select the **Product** and **Quantity** attributes: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/MD_SelectedAttributes.png" class="no-border" >}} - -7. Click **OK** to close the dialog box. -8. Close the message definition, and make sure to save the definition if asked! - -### Configuring the REST Service - -1. In the **Project Explorer**, right-click the **RESTExample** module and select **Add** > **Published Services** > **Published REST Service**: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/AddRestService.png" class="no-border" >}} - -2. Enter *PRS_OrderService* for the **Name** of your REST service. The REST service is now opened -3. Add a new resource to your service by clicking **Add**, and enter *GetOrderByID* for the **Resource name**: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/AddRestResource.png" class="no-border" >}} - - Click **OK** to close the dialog box. - -4. Add an operation to your resource by clicking **Add** in the **Operations for resource** section. -5. In the **Operation** dialog box, enter`{OrderID}` in the **Operation path** field (make sure to include the braces). This will allow the REST service to be invoked with the OrderID in the URL shown in the **Example location** field of this same dialog box. - - {{< figure src="/attachments/howto8/integration/publish-rest-service/AddOperation.png" class="no-border" >}} - -6. In the same dialog box, click **Select** next to the **Microflow** field. As you do not have a microflow for this operation, select the **RESTExample** module in the dialog box and then click **New** to create a new microflow. Enter *PRS_GetGetOrderByID* for the **Name** of this new microflow: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/AddOperationMicroflow.png" class="no-border" >}} - -7. Click **Show** to start editing the newly created microflow. -8. Add two parameters: **httpRequest** and **OrderID**. -9. Add an action to the microflow to convert the **OrderID** variable (string) to an integer variable. This is needed to be able to search for the OrderID (autonumber). - - {{< figure src="/attachments/howto8/integration/publish-rest-service/ConvertOrderID.png" class="no-border" >}} - -10. Add a second activity to the microflow to retrieve the **Order** based on the **OrderID**. This retrieve action from the database returns 1 order. - - {{< figure src="/attachments/howto8/integration/publish-rest-service/RetrieveOrder.png" class="no-border" >}} - -11. From the Project Explorer, right-click the RESTExample module and select **Add** > **Mappings** > **Export Mapping** to add a new mapping named **EM_ExportOrder**: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/AddExportMapping.png" class="no-border" >}} - -12. In the **Select schema elements for export mapping** dialog box, select the **Message definition** option, and then select the **MD_Orders** mapping created earlier via the **Select** button: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/SelectSchemaForExport.png" class="no-border" >}} - - Make sure to select all the attributes a shown above, then click **OK**. - -13. In the export mapping that is shown, map the objects to the same objects from the domain model (either by double-clicking or dragging from the **Connector** pane). Make sure to map the attributes with the same names. Your mapping should look like this: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/ExportMappingResult.png" class="no-border" >}} - -14. Now go back to the **PRS_GetGetOrderByID** microflow and add an **Export with mapping** activity. -15. In the **Mapping** field of the dialog box, select the mapping created above in [step 11](#eleven). For the **Parameter** field, select the **Order** object retrieved with the database retrieve action in the microflow. -16. Select **JSON** for the result, and store the output in a **String variable**. Enter *Order_JSON* for the variable's **Name**. - - {{< figure src="/attachments/howto8/integration/publish-rest-service/MFExportWithMapping.png" class="no-border" >}} - -17. Add an activity to the microflow to create an object of the type **HttpResponse**: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/httpResponse.png" class="no-border" >}} - - The **StatusCode** will return "OK" as a 200 message. The content of the message is mapped to the exported JSON from [step 16](#sixteen). And add the **HttpVersion** that you will be using (in this case, `HTTP/1.1`). - -18. Add an activity to the microflow for adding a header to the response: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/httpResponseHeader.png" class="no-border" >}} - - Set the member **Key** to `'Content-Type'` and the **Value** to `'application/json'`(or `'application/xml'` if your response contains XML rather than JSON). Set the **System.HttpHeaders** association to your HTTP response. -19. Open the end activity in your microflow and select **$NewHttpResponse** as the return value. You should have no errors, and your microflow should look like this: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/CompleteMFNoErrorHandling.png" class="no-border" >}} - -### Viewing the App{#viewing} - -To view and try out your app, follow these steps: - -1. Run your app and open it in the browser via this URL: `http://localhost:8080/rest-doc/`. -2. You will see a page with the documentation of all your published REST services: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/RESTTestOverview.png" class="no-border" >}} - -3. Click the **PRS_OrderService** link to view the details: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/RESTTestDetails.png" class="no-border" >}} - -4. Click **GET** followed by **Try it out**. -5. Fill in a **OrderID** and click **Execute**: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/RESTTestExceute.png" class="no-border" >}} - - This will execute the request and return the result in the **Response body**: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/RESTTestResponse.png" class="no-border" >}} - -Cool! You have published your first REST service from Mendix. - -## Error Handling - -In this new service, no error handling has been implemented. For example, if you now execute your service and enter a string in the **OrderID** parameter (or leave it out), you will see a 500 or a 404 generic error. So, error handling should be implemented to publish a robust service. - -### Adding Error Handling - -1. Open the **PRS_GetGetOrderByID** microflow, right-click the first activity, then select the option to **Set Error Handling** to **Custom with rollback**. -2. After the first activity, add an activity that creates a new HttpResponse object. Enter *NewHttpErrorResponse* for the **Name**, and map the attributes like this: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/ParsingErrorResponse.png" class="no-border" >}} - - For the **Content** member, the value is this JSON string: `'{"Error": "The OrderID can only be an integer"}'`. - -3. Set the new activity as the custom error handler. -4. Below this activity, add a **Create object** activity that creates a new httpHeader object: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/ParsingErrorResponseHeader.png" class="no-border" >}} - - Make sure to associate the header to the **NewHttpErrorResponse**. - -5. Add a new endpoint for the microflow and set **NewHttpErrorResponse** as the return value. Your microflow should now look like this: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/ParsingErrorMicroflow.png" class="no-border" >}} - -6. Test your error handler as you did with the app in section [4.3 Viewing the App](#viewing). Enter some characters in the **OrderID** parameter and observe the response of the request, like this: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/ParsingErrorRESTResult.png" class="no-border" >}} - -### Additional Error Handling - -Now that you covered the error handling of the parameter parsing, it's time to handle empty responses. This is not really an error, but an indication of what happened when nothing was returned is always a good idea. - -To add the error handling for those situations when the OrderID parameter is filled but no result is found, follow these steps: - -1. After the activity for retrieving from the database, add a decision activity with the following statement: `$Order != empty`. The true exit is connected to the activity for exporting to JSON. For the false exit, add new create object activities that create a **NewhttpErrorNotFoundResponse** and a **NewhttpErrorNotFoundHeader**: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/OrderNotFoundResponse.png" class="no-border" >}} - - The **Content** is filled with the following string: `'{"Error": "No Order available for ID:'+$OrderID+'"}'`. - - {{< figure src="/attachments/howto8/integration/publish-rest-service/OrderNotFoundHeader.png" class="no-border" >}} - -2. Configure the end activity to return the **NewHttpResponse**. The microflow should now look like this: - - {{< figure src="/attachments/howto8/integration/publish-rest-service/CompleteMFWithErrorHandling.png" class="no-border" >}} - -3. Test your new error responses as you did with the app in section [4.3 Viewing the App](#viewing). - -## Example - -**How to publish REST in Studio Pro 8** - -{{< youtube Ff_P84NOcZk >}} - -## Read More - -* For more information on creating published REST services in Mendix (including GET, POST, and DELETE operations), see [Published REST Services](/refguide8/published-rest-services/) diff --git a/content/en/docs/howto8/integration/selenium-support.md b/content/en/docs/howto8/integration/selenium-support.md deleted file mode 100644 index 1d7c1988a4f..00000000000 --- a/content/en/docs/howto8/integration/selenium-support.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Configure Selenium Support" -url: /howto8/integration/selenium-support/ -weight: 16 ---- - -## Introduction - -Mendix uses CSS classes to identify page content like widgets and pop-up windows. You can use these classes in Selenium to manipulate pages and verify data. - -This how-to teaches you how to do the following: - -* Use naming conventions -* Avoid pitfalls - -## Naming Conventions - -Widgets can be given a name in Mendix Studio Pro. These names appear in the HTML document as class names prefixed by `mx-name-`. For instance, a grid named `ArtistGrid` will get the `mx-name-ArtistGrid` a CSS class. This is true for all widgets. - -More complex widgets, like a grid, can set more specific CSS classes to sub-elements, like columns or the paging bar buttons. - -Some widgets, like grids or list views, can show multiple items. Every item has the `mx-name-index-` CSS class followed by an index number, starting at 0. - -The easiest way to discover these names is to use a browser's developer tool. - -## Pitfalls - -### Nested Widgets - -Every widget has a unique class name, which means that you can use the name on its own as a selector in Selenium. This makes them robust against changes in your page, like moving a button from one container to another. However, not all sub-elements in widgets are unique, like the buttons in a grid's paging bar. To select such an element, use a descendant selector like `.mx-name-artist-grid .mx-name-next`. This first selects the artist grid and then searches for the next page button on that grid. - -### Timing Issues - -Some actions done by Selenium take time to complete, for example, animations or requesting data for a pop-up window. When clicking a search button in a grid, the search bar appears using an animation. This means that after clicking the button, the test needs to wait for the animation to complete before continuing. - -For more information, see the WebDriver documentation on [Waiting Strategies](https://www.selenium.dev/documentation/webdriver/waits/). - -## Examples - -Select a Microflow button named `Execute` in a page: - -```javascript -$('.mx-name-Execute') - -``` - -Select the fourth row a grid named `ArtistGrid`: - -```javascript -$('.mx-name-ArtistGrid .mx-name-index-3') - -``` - -Note that the fourth row in a grid has an index of `3`. - -## Read More - -* [Create Automated Tests with TestNG](/howto8/testing/create-automated-tests-with-testng/) -* [Test Mendix Applications Using Selenium IDE](/howto8/testing/testing-mendix-applications-using-selenium-ide/) -* [Consume a Complex Web Service](/howto8/integration/consume-a-complex-web-service/) -* [Consume a Simple Web Service](/howto8/integration/consume-a-simple-web-service/) -* [Import Excel Documents](/howto8/integration/importing-excel-documents/) -* [Export XML Documents](/howto8/integration/export-xml-documents/) -* [Expose a Web Service](/howto8/integration/expose-a-web-service/) -* [Import XML Documents](/howto8/integration/importing-xml-documents/) diff --git a/content/en/docs/howto8/integration/testing-web-services-using-soapui.md b/content/en/docs/howto8/integration/testing-web-services-using-soapui.md deleted file mode 100644 index e1561ff7a81..00000000000 --- a/content/en/docs/howto8/integration/testing-web-services-using-soapui.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: "Test Web Services Using SoapUI" -url: /howto8/integration/testing-web-services-using-soapui/ -weight: 30 -aliases: - - /howto8/integration/testing-web-services-using-soapui/ ---- - -## Introduction - -You can publish your own webservices in a Mendix application. These webservices consist of operations. Other applications can then call operations of this webservice and you can return a result. This result is based on a microflow that will be executed when the webservice is called. With SoapUI you can create (automated) tests for these webservices. - -This how-to teaches you how to do the following: - -* Create a SOAP project with SoapUI -* Create assertions in SoapUI -* Build an automated test using SoapUI - -## Preparation - -Before you can start with this how-to, make sure you have completed the following prerequisites. - -* Download and install [SoapUI](https://www.soapui.org/downloads/soapui.html) -* Complete the how-to [Exposing a web service](/howto8/integration/expose-a-web-service/) - -| Software | Version used in this how-to | -| --- | --- | -| SoapUI | 5.2.0 | - -{{% alert color="warning" %}} - -All images, names and steps in this how-to are based on these versions. When using other versions the images and/or names on your screen may be different than the images or names used in this how-to. - -{{% /alert %}} - -## Publishing More Microflows as Web Service Operation - -In the how-to [Exposing a web service](/howto8/integration/expose-a-web-service/) you already published the microflow *GetCustomers* as web service operation. In this chapter you will create two more microflow and publish them as web service operation. - -1. Open Studio Pro. -2. Open the project you created in the how-to [Exposing a web service](/howto8/integration/expose-a-web-service/). -3. Create a **Microflow** that creates a customer and returns a Boolean. - - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/model1.jpg" class="no-border" >}} - -4. Create a **Microflow** that deletes a customer and returns a Boolean. - - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/model2.jpg" class="no-border" >}} - -5. Publish both microflows as web service operation of the **CustomerWebservice** as described in chapter 4 of the how-to [Exposing a web service](/howto8/integration/expose-a-web-service/). - -## Creating a new SOAP Project - -In this chapter you will create a new SOAP project. - -1. Open **SoapUI**. -2. Press Ctrl + N to create a new SOAP project. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580339.png" class="no-border" >}} -3. Run the project locally in Studio Pro. -4. Go to `http://localhost:8080/ws-doc/`. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580314.png" class="no-border" >}} -5. Enter the URL of the WSDL schema in the **Initial WSDL** field in SoapUI. - The Project Name field will automatically be filled with the name of the webservice following by *?wsdl*. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580334.png" class="no-border" >}} -6. Click**OK**. This will create a new SOAP project in SoapUI. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580313.png" class="no-border" >}} - -## Building a TestSuite, TestCase, and TestStep - -In this chapter you will build a testsuite. A testsuite contains one or more testcases. Every testcase contains one ore more teststeps. - -1. In SoapUI, press Ctrl + T to create a new TestSuite. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580332.png" class="no-border" >}} -2. Click **OK**. -3. Select TestSuite 1 and press Ctrl + N to create a new TestCase. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580331.png" class="no-border" >}} -4. Click **OK**. -5. Expand TestSuite 1 and TestCase 1. -6. Right-click **Test Steps(0)** and select **SOAP Request**. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580312.png" class="no-border" >}} -7. Enter *Retrieve Customers* in the name field. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580329.png" class="no-border" >}} -8. Click **OK**. -9. Select **CustomerWebserviceSoap -> GetCustomers**. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580328.png" class="no-border" >}} -10. Click **OK**. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580327.png" class="no-border" >}} -11. Click **OK**. -12. Open SOAP request **Retrieve Customers**. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580326.png" class="no-border" >}} -13. Change the follow value: - - ```java - ? - ? - ``` - - into - - ```java - 0 - 10 - ``` - -14. Press Alt + Enter to submit the request. The customers you created in the previous how-to will be shown in the response. The response will look like the code below: - - ```xml - - - - - Jessica D. Rogers -
2118 Collins Street
- PA 16646 - Hastings - - - Jamie S. Wentz -
3269 Village View Drive
- MD 20872 - Damascus - - - Blake G. Race -
4437 Sunny Glen Lane
- OH 44115 - Cleveland - - - Angela L. Dolly -
3718 Alpha Avenue
- TX 75439 - Ector - - - - - ``` - -## Assertions - -Assertions are used to validate the message received by a TestStep during execution, usually by comparing parts of the message (or the entire message) to some expected value. In this chapter you will create an assertion that validates the number of customers. - -1. Click **Assertions (1)**. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580307.png" class="no-border" >}} - In chapter 3 step 9 the *Add SOAP Response Assertion* checkbox was checked. That is the first assertion you see in the list, *SOAP Response - VALID*. -2. Click the add assertion icon. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580324.png" class="no-border" >}} -3. Click **Property Content**. -4. Click **XPath Match**. -5. Enter *count(//Customer)* in the XPath Expression field. -6. In step 1.4 of the previous how-to you have added some data. Enter the number of created customers in the **Expected Result** field. In this example four customers were created. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580323.png" class="no-border" >}} -7. Click **Save**. - -## Extending Your Test Case - -In this chapter you will extend your test case with multiple test steps and assertions. - -1. Add a new SOAP request to the existing test case with the following details: - - | Field | Value | - | --- | --- | - | Specify name for step | Create Customer | - | Select operation to invoke for request | CustomerWebServiceSoap -> CreateCustomer | - -2. Change the request into the following value: - - ```xml - - - - - Donald A. Hylton -
784 Better Street
- Kansas City - KS 66102 - - - - ``` - -3. Add a **Contains Assertion** and enter *true* in the content field. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580322.png" class="no-border" >}} -4. Right-click test step **Retrieve Customers**. - -5. Select **Clone TestStep**. - -6. Change **TestStep Name** to *Retrieve Customers 2*. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580320.png" class="no-border" >}} -7. Click **OK**. -8. Open teststep **Retrieve Customers 2**. -9. Click **Assertions (2)**. -10. Open **XPath Match - Unknown**. -11. Change **Expected result** to *1 + [the number you entered in step 5.6]*. -12. Click **Save**. -13. Add a new SOAP request to the existing test case with the following details: - * In the **Specify name for step**, enter *Delete Customer*. - * In the **Select operation to invoke for request** field, enter *CustomerWebServiceSoap -> DeleteCustomer*. - -14. Change the request into the following value: - - ```text - - - - - Donald A. Hylton - - - - ``` - -## Running the Test Case - -In this chapter you will learn how to run the testcase you created in previous chapters. - -1. Open testcase **TestCase 1**. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580310.png" class="no-border" >}} -2. Click the run this testcase icon. - {{< figure src="/attachments/howto8/integration/testing-web-services-using-soapui/18580309.png" class="no-border" >}} - -Congratulations! You have just created your first automated test with SoapUI. - -## Read More - -* [Finding the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clearing Warning Messages in Mendix](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Testing web services using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitoring Mendix using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debugging Java actions remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Debugging Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [Debugging Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debugging Microflows Remotely](/howto8/monitoring-troubleshooting/debug-microflows-remotely/) - -Learn more about this topic using the following helpful links: - -* [10 tips for the SoapUI beginner](https://www.soapui.org/getting-started/10-tips-for-the-soapui-beginner.html) diff --git a/content/en/docs/howto8/integration/use-a-client-certificate.md b/content/en/docs/howto8/integration/use-a-client-certificate.md deleted file mode 100644 index 6f2d6c80e1a..00000000000 --- a/content/en/docs/howto8/integration/use-a-client-certificate.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Use a Client Certificate" -url: /howto8/integration/use-a-client-certificate/ ---- - -## Introduction - -Some services require you to authenticate using a client certificate. This how-to describes how to configure your app to do this. - -Let's assume that you already have an app that calls a service. For details on how to configure this, have a look at [How to Consume a REST Service](/howto8/integration/consume-a-rest-service/) or [How to Consume a Simple Web Service](/howto8/integration/consume-a-simple-web-service/). - -This how-to teaches you how to do the following: - -* Configure to run locally -* Configure in Mendix Cloud - -## Prerequisites - -* A PKCS12 certificate file that contains a private key — these files typically have the *.pfx* or *.p12* file extension -* The password to open that file - -## Running Locally - -To configure the custom settings that are only used when you run your app locally, follow these steps: - -1. Open your app in the Modeler and go to **Project** > **Settings**. -2. Click **Edit** to open the **Edit Configuration** dialog box, and select the **Custom** tab. -3. Add two custom settings to specify the paths to the certificates (ClientCertificates) and matching passwords (ClientCertificatePasswords). Also, add a third setting (ClientCertificateUsages) to specify which service should use which certificate if you use more than one certificate in your app. - - Name | Value | Notes - --- | --- | --- - ClientCertificates | The paths to the certificate files. | Separate with commas if you have more than one file. Backslashes in the paths should not be doubled. - ClientCertificatePasswords | The password for each certificate file. | In the same order as the **ClientCertificates**. - ClientCertificateUsages **(Optional)** | The description of which files to use for which service, in the format `"ModuleName.WebserviceName": "path"` (for web services) or `"www.server-to-contact.com": "path"` (for REST services). | If you have more than one service to configure, you can separate them with commas. Enclose the whole setting value in braces (`{ }`). Backslashes in the paths must be doubled. In addition, the paths you specify here should all appear in **ClientCertificates**. - -This is an example: - -```text -{ "Module.WebService1": "D:\\App\\Mx1.pfx", "www.server-to-contact.com": "D:\\App\\Mx2.pfx" } -``` - -A complete configuration may look like this: - -{{< figure src="/attachments/howto8/integration/use-a-client-certificate/example-custom-settings.png" class="no-border" >}} - -You can use an empty path for `ClientCertificateUsages` to specify that you do not want to use a client certificate, even when the server accepts one. To do this, you need to add the **Value** `{"":""}` (replace `` with the actual endpoint). - -{{% alert color="info" %}} - -Be sure to drop `https://` from a URL endpoint. - -{{% /alert %}} - -The following sample uses client certificate `Mx1.pfx` for `WebService1` and no client certificate for `WebService2`: - -```text -{ "Module.WebService1": "D:\\App\\Mx1.pfx", "Module.WebService2": "" } -``` - -## Running in the Cloud - -{{% alert color="info" %}} - -You will only be able to follow the steps below if you have the correct access rights for the client certificates. - -{{% /alert %}} - -To configure client certificates in Mendix Cloud, follow these steps: - -1. Go to [Apps](https://sprintr.home.mendix.com/) and go to the **Environments** page for your app. -2. Each environment has its own configuration. Click **Details** next one of the environments. -3. Click **Network** and scroll down to **Certificates for outgoing connections**. -4. Click **Add client certificate**. Upload the certificate files. -5. Only follow these steps if you are using more than one client certificate in your app:
- 1. After the files have been uploaded, they appear in the list. Double-click an item in the list.
- 1. In the **Pin Client Certificate to Web Services** section of the **Details** screen, you can specify which client certificate belongs to which service:
- * For web services, enter the name of the web service (for example,*ModuleName.WebServiceName*)
- * For REST services, enter the host name of the endpoint (for example, *example.com*)
- 1. Close the **Details** screen.
- -6. Click **Stop application** and then **Start application**. diff --git a/content/en/docs/howto8/integration/using-the-excel-exporter.md b/content/en/docs/howto8/integration/using-the-excel-exporter.md deleted file mode 100644 index 3bba0c37630..00000000000 --- a/content/en/docs/howto8/integration/using-the-excel-exporter.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: "Export to Excel" -url: /howto8/integration/using-the-excel-exporter/ -weight: 6 ---- - -## Introduction - -Exporting items from a data grid in a Mendix application in Excel format via an **Export to Excel** button, is standard Mendix functionality. However, in instances where more customized Excel documents are required, your app can leverage Mendix Marketplace content to create custom Excel documents based on configurable templates. To achieve this, your app will require you to download and configure two Mendix Marketplace modules. - -This how-to explains how to do the following: - -* Download the Marketplace modules -* Configure your app to export the required data in the correct format - -## Downloading the Required Marketplace Modules - -In this section, you will learn how to download the necessary modules from the Mendix Marketplace. The modules required for this process are [Mx Model Reflection](/appstore/modules/model-reflection/) and [Excel Exporter](/appstore/modules/excel-exporter/). - -{{% alert color="info" %}} -The Mx Model Reflection module enables your app to obtain information about its domain model (entities and attributes) and microflow definitions at runtime. -{{% /alert %}} - -To download the modules, follow these steps: - -1. Open the **Mendix Marketplace** from within Studio Pro. -2. Search for the keyword *reflection* and select **Mx Model reflection**: - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/18581166.png" class="no-border" >}} - -3. Click **Download** to include the module in your app. It will be imported into **Project** > **App Store modules** in the **Project Explorer**. -4. Search for the keyword *Excel*, select **Excel exporter**, and download that module into your app: - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/exporter.png" class="no-border" >}} - -{{% alert color="warning" %}} -Depending on the layout selected when the project was created, errors in Studio Pro may arise due to the new module's default layouts. To correct this, open each page that has an error and update the layout to the desired layout within the app. -{{% /alert %}} - -## Adding Navigation Items to Allow Users to Configure Settings - -In this section, you will learn how to add the required pages in the app's **Navigation** that are needed to configure both the Mx Model Reflection and the Excel Export templates that will be used within the app. - -1. In Studio Pro, open **Project** > **Navigation**. -2. Add a new item to the Navigation to open the page **MxModelReflection.MxObjects_Overview**: - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/18581165.png" class="no-border" >}} - -3. Add a new item to the Navigation to open the page **XLSReport.Excel_Document_Overview**: - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/18581909.png" class="no-border" >}} - -4. Open **Project Security** and assign these two modules to the Administrator user role: - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/security.png" class="no-border" >}} - -## Creating an Input Object Entity - -In this section, you will create an entity which will be used to export the Excel workbook. This will be associated with the entity holding the data with which you want to fill the Excel spreadsheet. This how to will use a **Policy** entity to hold the data. - -1. Open the domain model for your app and add an entity to serve as a "primary export" entity that is a specialization of **FileDocument**. -2. Create an association between the newly created entity and the entity (or entities) that you will want to serve as a base for the Excel export. - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/18581908.png" class="no-border" >}} - -## Configuring Mx Model Reflection - -In this section, you will learn how to run the Mx Model Reflection synchronization so the app can leverage the output from that process to create highly customizable Excel export templates. - -To run the MxModelReflection sync follow these steps: - -1. Run your app. -2. View the app. -3. Click the **MxReflection** navigation item to open the MxReflection overview page. -4. Select each module the app needs to synchronize and click **Click to refresh**. -5. Under **Synchronize all entities and microflows of checked modules on the left**, click **Click to refresh** . - -## Creating Excel Export Templates - -In this section, you will learn how to create a basic Excel export template within your app. This section will cover an overview of the various configuration items to enable you to start building the desired templates. - -{{% alert color="info" %}} -The Excel Exporter has many options that allow the configurations to be as simple or complex as the user desires. This how-to will go over the basics to get you started, but building the desired template will vary according to your requirements. -{{% /alert %}} - -### Configuring the Basic Template Setup - -To set up a template, follow these steps: - -1. Run your app. -2. View the app. -3. Click **Excel Exporter** to open the exporter overview page. -4. Click the **New** to create a new template. -5. Configure the **Filename** (without extension) to be the default file name when the template is used. This is the **Name** by which the template can be identified. - - {{% alert color="info" %}}The file name can always be changed when the template is used within a microflow.{{% /alert %}} - -6. Configure the **Input Object** to be the file document entity that is associated to your entity to be exported. -7. Provide a **Description** for identifying and documenting what this template is for: - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/new-excel-template.png" class="no-border" >}} - -8. Specify the **Date time export format** which defines how the dates and times should appear in the Excel file once exported. - -### Creating the Worksheet Layout - -To create the worksheet layout, follow these steps: - -1. Under the **Worksheets** section for the template, select **New** to create a new sheet template: - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/18581907.png" class="no-border" >}} - -2. Specify the **Name** that will be given to the sheet when the file is exported. -3. Configure the **Row Object** that you want to export and set the reference to the template input object (if input object is used). Each object of this entity type will be saved as a row in the worksheet. -4. Configure the **Start retrieved data at row** to set the ordinal number in which the data should be exported. - - {{% alert color="info" %}}This setting will possibly trim the result set being exported, as the export will go from this value to the end of the list of data{{% /alert %}} - -5. Select if the export should export distinct only or allow duplicate data -6. Specify the **Column default width** and **Row default height** (or leave them as defaults). -7. Specify if the extract will **Use Static Data** or not: - - {{% alert color="info" %}}If static data is used, that will be configured below.{{% /alert %}} - -8. Specify if the **Default text style** that will denote the pre-defined style to be applied to the exported data. -9. Specify if the **Default header text style** that will denote the pre-defined style to be applied to the header data: - - {{% alert color="info" %}}Specifying styles are addressed in the section below.{{% /alert %}} - -### Configuring the Dynamic Column Data - -To configure the dynamic column data, follow these steps: - -1. On the **Column Data tab**, select **New** to create a new export column: - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/18581905.png" class="no-border" >}} - -2. The **Column number** will be set automatically, but can be overwritten to the desired ordinal number. -3. Define a **Name** for the column and specify if that **Name** should be the **Column Header** as well when exported. -4. Specify the **Retrieve type** to identify if this column will be an attribute or a reference. -5. Specify the **Select attribute** to identify the attribute of the row object which will be stored in this column. -6. Specify if the column should result in an aggregate. Note that only types of decimal, integer, and long can be aggregated. - -### Configuring Static Data in the Sheet - -To configure the static data in the sheet, follow these steps: - -1. Open the **Static Data tab** and select **New** to create a new export column. - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/18581903.png" class="no-border" >}} - -2. Specify the **Row** and **Column** that the static value should be placed. -3. Enter a name for the cell in the **Name** field. -4. Specify the **Type** by selecting if the cell is **Static Text, Object Data, or Aggregate Function.** This example uses **Static Text** (which changes the **Name** field into **Excel Text** upon selection). -5. Specify the **Style** that should be applied to the cell. - -### Configuring Custom Cell Formatting and Styling - -To configure the custom formatting and styling for the cells, follow these steps: - -1. Back on the main page for your new template, click **New** in the **Styles** section to create a new style that can be applied to any of the data in the Excel export: - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/18581900.png" class="no-border" >}} - -2. Specify the properties of the style that will be applied to the cells. -3. Click **Save** to make the style available for dynamic columns, static columns, and headers. - -## Calling the Excel Export Module via Microflow - -In this section, you will learn how to call the newly created Excel export template in your application. To retrieve the template and generate the document, follow these steps: - -1. Create a microflow that either takes an inbound parameter of the object that needs to be exported, or retrieve that object into your microflow. -2. In the microflow, retrieve a single object which is the template you set up earlier to use for the export. - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/retrieve-template.png" class="no-border" >}} - -3. In your microflow, call the **XLSReport.GenerateExcelDoc** Java action (available from the module's **JavaActions** folder) to pass the required objects to the module. - - {{< figure src="/attachments/howto8/integration/using-the-excel-exporter/java-action.png" class="no-border" >}} - -4. In your microflow, download the resulting FileDocument object. - -Your microflow should look similar to this: - -{{< figure src="/attachments/howto8/integration/using-the-excel-exporter/microflow-for-generate.png" class="no-border" >}} - -## Running the Microflow - -There are two things missing now from the app: - -* There is no data to download -* There is no way to run the microflow - -See the sections below to add these missing things. - -### Creating Data - -To allow you to enter some data, you will need to generate some pages and then enter some data into them by following these steps: - -1. Right-click on the **Policy** entity in the domain model and select **Generate overview pages…**. -2. Select **Policy** and click **OK**. -3. Link the generated overview page into the app, either through the home page or the app navigation. -4. Run the app and enter some data to create **Policy** objects. - -### Running the microflow - -To run the microflow you created above, you will need to create another microflow which is added to the navigation. This microflow should create a **PolicyDoc** object and associate it with existing **Policy** objects, making sure that all the associations are committed, and pass this PolicyDoc as the parameter to the microflow. This will export all the Policy objects you associated with the PolicyDoc. - -{{% alert color="info" %}} -If you create a **PolicyDoc** with *no* associations to **Policy** objects, you will export an empty spreadsheet with the structure defined in the template. -{{% /alert %}} - -## Read More - -* [Import Excel Documents](/howto8/integration/importing-excel-documents/) diff --git a/content/en/docs/howto8/integration/version-rest-service.md b/content/en/docs/howto8/integration/version-rest-service.md deleted file mode 100644 index 5ac9dcea51b..00000000000 --- a/content/en/docs/howto8/integration/version-rest-service.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "Version a REST Service" -url: /howto8/integration/version-rest-service/ -weight: 11 -description: "Describes the best practices for versioning REST services in Mendix" ---- - -## Introduction - -You can have different versions of the same REST service published at the same time. - -This how-to teaches you how to do the following: - -* Utilize best practices on when and how to use different versions of the same REST service published at the same time -* Deprecate old versions - -## Numbering the Versions - -Give each service a version number following the `MAJOR.MINOR.PATCH` format: - -* A service must get a new `MAJOR` version when you make incompatible API changes (such as removing an operation) -* A service should get a new `MINOR` version when you add functionality that is backwards-compatible (such as adding an operation) -* A service may get a new `PATCH` version when you make a bug fix that is backwards compatible - -To make versioning more explicit in your model, Mendix suggests creating a folder for each service. Call it *ServiceName_Version*. Store all microflows, mappings, and message definitions that are used in the service in that folder. - -After you have published a service and users are using it, it is not advisable to change it anymore. - -If you were to change it in a way that requires the user to change, you would introduce a "breaking change." The user would start getting errors without doing anything different. - -Instead of changing a published service, you should duplicate the service and give it a new major version. If you want to change a microflow, a mapping, or a message definition, duplicate that as well, and change the duplicate. - -Change the location of the new version to include the new version, for example, **rest/myservice/v1.1**. It is customary to omit the **.0** or **.0.0** in the URL. - -The new version of the service reuses all microflows, mappings, and message definitions from the previous version that did not change in the new version. - -The rest of this how-to gives some examples of typical changes that occur and how to handle the versioning of your service in those cases. - -## Examples - -### Fixing a Bug in a Microflow - -#### Scenario - -You have a REST service in Petstore version 1.0.0 in production. You find out that you need a small change to the GetPet microflow. When the incoming `pet_id` is empty, it is giving an error that results in "500 Internal Server Error," but it should be "400 Bad Request." - -#### Solution - -Since this is a non-breaking change, there are two solutions to this problem. One is to create a separate patch version, and the other is to just fix the bug in the current version. - -To create a patch version, do the following: - -1. Create a new folder called **PetStore_1_0_1**. -2. Duplicate the PetStore service. Call it **PetStore_1_0_1** and move it to the **PetStore_1_0_1** folder. -3. Duplicate the GetPet microflow. Call it **GetPet_1_0_1** and move it to the **PetStore_1_0_1** folder. -4. Update the **PetStore_1_0_1** service, making the GET operation refer to **GetPet_1_0_1**. -5. Change the **GetPet_1_0_1** microflow to fix the behavior. - -### Adding an Operation to a Resource - -#### Scenario - -You have a REST service in Petstore version 1.0.0 in production. You want to add an operation to retrieve pets by status. - -#### Solution - -Since this change is backwards-compatible, there are two solutions to this problem. One is to create a new minor version, and the other is to just add the operation to the current version. - -To create a new minor version, do the following: - -1. Create a new folder called **PetStore_1_1_0**. -2. Duplicate the PetStore service. Call it **PetStore_1_1_0** and move it to the **PetStore_1_1_0** folder. -3. Add the **GetPetByStatus** operation to the **PetStore_1_1_0** service. - -### Changing the Type of an Attribute - -#### Scenario - -You have a REST service in Petstore version 1.0.0 in production. The **GET /pet** operation returns a pet's year of birth of as an integer. You have a message definition called **Pet** that is based on the **Pet** entity. The **ExportPet** export mapping maps the entity to the message definition. - -You want to change the year of birth to date of birth. - -#### Solution - -Note that this is a breaking change (because it is not backwards compatible), so you must create a new version if you do not want to get complaints from existing users of your service. - -1. Add a new attribute **DateOfBirth** to the **Pet** entity. -2. Create a new folder called **PetStore_2_0_0**. -3. Duplicate the new message definitions. Call it **PetStoreMessages_2_0_0** and move it to the **PetStore_2_0_0** folder. Remove any message definitions that you do not want to change. -4. Create a new export mapping called **ExportPet_2_0_0** in the **PetStore_2_0_0** folder. Base it on the **Pet** entity, selecting the same attributes as before, but choosing **DateOfBirth** instead of **YearOfBirth**. -5. Duplicate the **PetStore** service. Call it **PetStore_2_0_0** and move it to the **PetStore_2_0_0** folder. -6. Update the **GET /pet** operation in the **PetStore_2_0_0** service, choosing the **ExportPet_2_0_0** export mapping. - -## Deprecation - -After you have created a new version of your service, you should mark the old version as deprecated. - -You do that by adding **(deprecated)** to the service name. Write a description of why it was deprecated and what the new version number is in the **Public documentation** of the service. You should also mark all the operations that changed as deprecated. This way, the user can see which operations have changed from one version to the next. - -You should let users know that the this version is deprecated (for instance, by publishing release notes). - -After a version has been deprecated for a sufficiently long time, you can remove it. All users should have moved to the new version in the meantime. diff --git a/content/en/docs/howto8/logic-business-rules/_index.md b/content/en/docs/howto8/logic-business-rules/_index.md deleted file mode 100644 index 97084cd13f7..00000000000 --- a/content/en/docs/howto8/logic-business-rules/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Logic and Business Rules" -url: /howto8/logic-business-rules/ -weight: 60 -no_list: false -description_list: true ---- - -## Introduction - -Application logic is created in Mendix in the form of microflows. A microflow allows you to express the logic of your application. This is a visual way of expressing what traditionally ends up in textual program code. In other words, microflows allow you to easily add complex business logic to the processes in your application without having to write code. - -Mendix is all about collaboration between business and IT, and microflows help to give business-minded people insight into how the application is designed. - -With these how-tos, you can learn how to translate your business logic into microflows and build and debug them from the beginner to the expert level. - -## Documents in This Category diff --git a/content/en/docs/howto8/logic-business-rules/create-a-custom-save-button.md b/content/en/docs/howto8/logic-business-rules/create-a-custom-save-button.md deleted file mode 100644 index 8d9590dfb43..00000000000 --- a/content/en/docs/howto8/logic-business-rules/create-a-custom-save-button.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "Create a Custom Save Button" -url: /howto8/logic-business-rules/create-a-custom-save-button/ -weight: 3 ---- -## Introduction - -Mendix uses visual models called microflows to define the logic of your application. A microflow is a visual way of expressing what traditionally would be written in code. This how-to explains how you can create a custom save button on a detail page using a microflow. You will replace a default save button with the save button that shows a message to end-users after they click it. - -This how-to teaches you how to do the following: - -* Recreate the logic of the default **Save** button -* Create a custom **Save** button - -## Prerequisites - -Before starting with this how-to, make sure you have completed the following prerequisites: - -* Create a basic data layer (for details, see [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/)) -* Create overview and detail pages for the customer object (for details, see [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/)) -* Create a menu item to access the customer overview page (for details, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/)) - -## Replacing the Default Save Button with a Custom One - -To replace the default **Save** button with a custom one, follow these steps: - -1. Open the **Customer_Detail** page: - - {{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/customer-detail.png" class="no-border" >}} - -2. Select the **Save** button press Delete to remove it. - -3. Right-click the drop-zone under the **Cancel** button, select **Add widget**, and then select **Call microflow button**. - -4. In the **Select Microflow** dialog box, click **New** to create a new microflow called **Customer_Save**. - - {{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/customer-save.png" class="no-border" >}} - -5. After the button is created, open its **Properties** pane. - -6. Change the **Caption** property to *Save*: - - {{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/button-properties.png" class="no-border" >}} - -7. Set a floppy disk as the **Icon**: - - {{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/18580987.png" class="no-border" >}} - -You have created a button that calls a microflow. - -## Recreating the Default Save Behavior - -You need to recreate the default Save behavior to customize it afterwards. Do the following: - -1. Right-click the new **Microflow** button and select **Go to microflow** to open the new microflow. The microflow should look like the one below: - - {{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/created-microflow.png" class="no-border" >}} - -2. Open the **Toolbox** and select the **Commit object(s)** activity there: - - {{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/8946802.png" class="no-border" >}} - -3. Drag a **Commit object(s)** action from the **Toolbox** to the flow between the start and end events. -4. Double-click the **Commit object(s)** activity to open its properties. - -5. In the **Input** section, select **Customer** for **Object or List**, and click **OK**: - - {{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/commit-object-properties.png" class="no-border" >}} - -6. Open the **Toolbox**, find the **Close page** activity there, and drag it into the flow after the **Commit object(s)** activity: - - {{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/close-page-activity.png" class="no-border" >}} - -You have recreated the default **Save** button logic. - -## Extending the Microflow with Your Own Functionality - -To extend the logic with a custom message that will be shown when end-users click the button, do the following: - -1. Open **Toolbox**, find the **Show message** activity, and drag it after the **Close page** activity. - -2. Double-click the new activity to open its properties. - -3. In the **Template** property enter a text that will be displayed in the message. Type in *Customer is saved!* - - {{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/show-message-properties.png" class="no-border" >}} - -4. Click **OK** to save the changes. - -Congratulations! You have created a microflow and customized the **Save** button: - -{{< figure src="/attachments/howto8/logic-business-rules/create-a-custom-save-button/microflow.png" class="no-border" >}} - -## Read More - -* [Define Access Rules Using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Work With Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) -* [Configure Error Handling](/howto8/logic-business-rules/set-up-error-handling/) -* [Optimize Microflow Aggregates](/howto8/logic-business-rules/optimizing-microflow-aggregates/) -* [Extract and Use Sub-Microflows](/howto8/logic-business-rules/extract-and-use-sub-microflows/) -* [Microflow Activities](/refguide8/activities/) diff --git a/content/en/docs/howto8/logic-business-rules/define-access-rules-using-xpath.md b/content/en/docs/howto8/logic-business-rules/define-access-rules-using-xpath.md deleted file mode 100644 index 82dfcae38dc..00000000000 --- a/content/en/docs/howto8/logic-business-rules/define-access-rules-using-xpath.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "Define Access Rules Using XPath" -url: /howto8/logic-business-rules/define-access-rules-using-xpath/ -weight: 10 ---- - -## Introduction - -The access rules of an entity define what a user is allowed to do with the objects of the entity. Users can be allowed to create and/or delete objects and to view and/or edit member values. A member is an attribute or an association of an entity. Furthermore, the set of objects available for viewing, editing, and removing can be limited by means of an XPath constraint (for details, see [XPath Constraints](/refguide8/xpath-constraints/) in the *Studio Pro Guide*). For more information on access rules, see [Access Rules](/refguide8/access-rules/) in the *Studio Pro Guide*. - -In this how-to, you will prepare a data structure (including security), a GUI, and some example data for customers, orders, and a financial administrator account. After this preparation, you will define the access rules for the Order entity using XPath on the payment status. The XPath will constrain the order so it can only be seen by a financial administrator when the payment status of the order is set to "paid." - -This how-to teaches you how to do the following: - -* Define access rules for an entity using XPath - -## Preparing the Data Structure, GUI, and Example Data - -The access rules used in this how-to contain customer and order data. To define the access rules, you first need to set up the data structure, user roles, and GUI to maintain customer and order data. - -To prepare the data structure, GUI, and example data, follow these steps: - -1. Create the following domain model: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581378.png" class="no-border" >}} - - For more information on creating a domain model, see [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/). -2. Create overview and detail pages to manage the Customer and Order objects (for more information on creating these pages, see [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/)). -3. Create menu items to access the Order and Customer overview pages (for more information on creating menu items, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/)). -4. Set the **Security level** of you application to **Production** (for more information, see [How to Create a Secure App](/howto8/security/create-a-secure-app/)). - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581008.png" class="no-border" >}} - -5. Enter *FinancialAdministrator* for the **Name** of the new user role on the **User roles** tab (for more information on adding roles, see [How to Create a Secure App](/howto8/security/create-a-secure-app/): - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581005.png" class="no-border" >}} -6. Give both module roles access to all your created pages, and create separate read and write access rights to all your created entities (for more information on how to set the entity access, see [How to Create a Secure App](/howto8/security/create-a-secure-app/)): - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18580997.png" class="no-border" >}} - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581003.png" class="no-border" >}} - -7. Add the following customer data to your app: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581374.png" class="no-border" >}} -8. Add the following order data to your app: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581373.png" class="no-border" >}} -9. Add an account to your application with the user role *FinancialAdministrator*: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581002.png" class="no-border" >}} - -## Defining the Access Rules on the Order Entity Using XPath - -In the previous section, you set up a basic data structure and created some sample data. In this section, you will define the access rules on the Order entity so that orders can only be viewed by a financial administrator if the payment status of the order is set to "Complete." You will do this by adding an XPath constraint to the Order entity for the FinancialAdministrator module role. - -To define the access rules on the Order entity using XPath, follow these steps: - -1. Open the **Access rules** tab for the **Order** entity: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18580996.png" class="no-border" >}} - -2. Double-click the **FinancialAdministrator** module role to open its properties and go to the **XPath constraint** tab: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581000.png" class="no-border" >}} - -3. To constrain the access of the financial administrator to only "Complete" orders, add the following **XPath**: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18580995.png" class="no-border" >}} - -4. Click **OK** and re-deploy your application. -5. When you sign in with the **Financial Administrator** account, you will see that only completed orders are shown in the orders overview: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18580994.png" class="no-border" >}} - -## Read More - -* [Create a Custom Save Button](/howto8/logic-business-rules/create-a-custom-save-button/) -* [Extend Your Application with Custom Java](/howto8/logic-business-rules/extending-your-application-with-custom-java/) -* [Work with Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) -* [Optimize Retrieve Activities](/howto8/logic-business-rules/optimizing-retrieve-activities/) -* [Configure Error Handling](/howto8/logic-business-rules/set-up-error-handling/) -* [Optimize Microflow Aggregates](/howto8/logic-business-rules/optimizing-microflow-aggregates/) -* [Extract and Use Sub-Microflows](/howto8/logic-business-rules/extract-and-use-sub-microflows/) diff --git a/content/en/docs/howto8/logic-business-rules/extending-your-application-with-custom-java.md b/content/en/docs/howto8/logic-business-rules/extending-your-application-with-custom-java.md deleted file mode 100644 index ee3f66fa4d2..00000000000 --- a/content/en/docs/howto8/logic-business-rules/extending-your-application-with-custom-java.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: "Extend Your Application with Custom Java" -linktitle: "Extend App with Custom Java" -url: /howto8/logic-business-rules/extending-your-application-with-custom-java/ -weight: 12 ---- - -## Introduction - -Most application logic can be developed using microflows. Microflows are very powerful and contain a lot of the features that you need in every application. To prevent you from getting stuck due to a missing feature, Mendix microflows are extendable. So, whenever you feel something is missing, you can add it yourself with the use of Java actions. - -This how-to teaches you how to do the following: - -* Extend your application with custom Java code - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisite: - -* Have Eclipse installed (download it [here](https://eclipse.org/)) - - {{% alert color="info" %}}You can use any text editor to create custom Java actions, but we highly recommend using Eclipse. Studio Pro contains a **Deploy for Eclipse** feature verifying that everything that needs to be configured in Eclipse is done automatically. All you have to do is import the app into your Eclipse working environment.{{% /alert %}} - -* Have an app ready using the [Asset Manager App](https://marketplace.mendix.com/link/component/69674) template. - -## Adding a Java Action in Studio Pro - -1. Right-click the **AssetManager** module and select **Add other** > **Java action**. -2. Enter *ReverseAssetName* for the **Name** of the new Java action and click **OK**. -3. In the **Java Action** wizard, click **Add** to add a parameter and do the following:
- - 1. Enter *inputAssets* for the **Name** of the new parameter.
- 2. Select **Object** for the **Type**.
- 3. Click **Select** for **Entity** and select **AssetManager.Asset** as the object type.
- 4. Click **OK**.
- - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/add.png" width="500" class="no-border" >}} - -4. Back on the **Java Action** wizard, change the **Return type** of the Java action to **String** and click **OK** to save the Java action. - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/return.png" width="500" class="no-border" >}} - -5. Select **App** > **Deploy for Eclipse** from the top Studio Pro toolbar. - -## Editing the Java Action in Eclipse - -To edit the Java action in Eclipse, follow these steps: - -1. Open Eclipse, right-click in the **Package Explorer** window, and select **Import**. -2. In the **Import** window, select **Existing Projects into Workspace** and click **Next**. -3. Set the app directory as the root directory for this app and click **Finish**. - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/import3.png" width="400" class="no-border" >}} - - {{% alert color="info" %}}If you don't know what the app directory is, select **App** > **Show App Directory in Explorer** in Studio Pro.{{% /alert %}} - -4. Double-click **ReverseAssetName.java** in the **Package Explorer** of Eclipse. - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/package-explorer.png" width="300" class="no-border" >}} - - In the Java code, there is a placeholder marked with `//BEGIN USER CODE` and `//END USER CODE` comment statements. This is where you can add your own Java code. Studio Pro will never overwrite the code between those two statements. - - ```java - @java.lang.Override - public java.lang.String executeAction() throws Exception - { - this.inputAssets = __inputAssets == null ? null : assetmanager.proxies.Asset.initialize(getContext(), __inputAssets); - - // BEGIN USER CODE - throw new com.mendix.systemideinterfaces.MendixRuntimeException("Java action was not implemented"); - // END USER CODE - } - ``` - - Studio Pro generates a variable for `inputAssets`. You can use that variable to get the name of the asset and reverse it. - -5. Replace the existing line: - - ```java - throw new com.mendix.systemideinterfaces.MendixRuntimeException("Java action was not implemented"); - ``` - - between `//BEGIN USER CODE` and `//END USER CODE`, with the code: - - ```java - String assetsAssetName = this.inputAssets.getAssetName(this.getContext()); - return new StringBuilder(assetsAssetName).reverse().toString(); - ``` - -6. Select **File** > **Save** to save the Java action in Eclipse. - -## Calling the Java Action from a Microflow - -1. Back in Studio Pro, locate the **Home** page via **App Explorer**. -2. Under **{AssetName}**, right-click and select **Add widget**. - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/add-widget.png" width="300" class="no-border" >}} - -3. In the **Select widget** dialog box that appears, select **Button widgets** > **Call microflow button**. -4. In the **Select Microflow** dialog box, click **New** to create a new microflow. -5. Enter *ReverseName* for the **Name** of the new microflow and click **OK**. -6. Right-click the **Reverse name** button you just created and select **Go to on click microflow** to open the new microflow. -7. Drag the **ReverseAssetName** Java action from the **App Explorer** onto the line between the green start event and red end event. This generates a Java action activity. - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/microflow2.png" width="500" class="no-border" >}} - -8. Double-click the generated activity to open the **Call Java Action** properties editor, and then click **Edit** for the first input to open the argument editor. - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/call1.png" width="500" class="no-border" >}} - -9. Press and hold the Ctrl key and then press Space to open the code completion editor. -10. Select **$Asset (AssetManager.Asset)**. - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/argument.png" width="500" class="no-border" >}} - -11. Click **OK** to save the expression. -12. In the **Call Java Action** properties editor, change the output **Variable** to *ReversedName*. - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/call2.png" width="500" class="no-border" >}} - -13. Click **OK** to save the properties. The microflow should now look like this: - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/microflow3.png" width="500" class="no-border" >}} - -14. From the **Toolbox** (select **View** > **Toolbox** to open it, if necessary), drag a **Show message** activity into the microflow. -15. Double-click the activity to open the **Show Message** properties editor and enter *Reversed name: {1}* for **Template**. -16. In the **Parameters** section, click **New** to open the expression editor. -17. Select **$ReversedName (String)**, which is the output variable of the Java action. -18. Click **OK** to save the parameter. The **Show Message** properties should now look like this: - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/show-message.png" width="500" class="no-border" >}} - -19. Click **OK** to save the show message activity. The microflow should now look like this: - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/microflow4.png" width="500" class="no-border" >}} - -## Deploying and Seeing the Results - -1. Click **Run Locally** to deploy the application locally, and click **View** to open the application in your browser. -2. Select **Add asset** from the top right. -3. In the new window input *Asset to Reverse* in the **Name** field. -4. Select **Save**. -5. Select the new asset from the app's **Dashboard**. -6. On the **Home** page, click **Reverse name** for the newly created asset: - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/app1.png" width="200" class="no-border" >}} - -7. The reversed name of the asset appears in a dialog box. - - {{< figure src="/attachments/howto8/logic-business-rules/extending-your-application-with-custom-java/app2.png" width="400" class="no-border" >}} - -## Troubleshooting {#troubleshooting} - -If you get an `UnsupportedClassVersionError` when running your app, follow these steps: - -1. Clean your app's **deployment** folder by selecting **App** > **Clean Deployment Directory**. - -2. Add the same JDK version to Eclipse as that which you are using in Studio Pro (this is the recommended version correlation). For details on JDK requirements, see the [Mendix Studio Pro](/refguide8/system-requirements/#sp) section of *System Requirements*. - -## Read More - -* [Define Access Rules Using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Create a Custom Save Button](/howto8/logic-business-rules/create-a-custom-save-button/) -* [Work with Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) -* [Optimize Retrieve Activities](/howto8/logic-business-rules/optimizing-retrieve-activities/) -* [Set Up Error Handling](/howto8/logic-business-rules/set-up-error-handling/) -* [Optimize Microflow Aggregates](/howto8/logic-business-rules/optimizing-microflow-aggregates/) -* [Extract and Use Sub-Microflows](/howto8/logic-business-rules/extract-and-use-sub-microflows/) diff --git a/content/en/docs/howto8/logic-business-rules/extract-and-use-sub-microflows.md b/content/en/docs/howto8/logic-business-rules/extract-and-use-sub-microflows.md deleted file mode 100644 index e9ee5c0045f..00000000000 --- a/content/en/docs/howto8/logic-business-rules/extract-and-use-sub-microflows.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "Extract and Use Sub-Microflows" -url: /howto8/logic-business-rules/extract-and-use-sub-microflows/ -weight: 5 ---- - -## Introduction - -When you are building large microflows that span multiple functions, the best practice is to break down the large microflow into more manageable parts based on those functions. To better manage your logic, you can create sub-microflows. - -This how-to teaches you how to do the following: - -* Extract sub-microflows -* Use sub-microflows -* Troubleshoot extractions of sub-microflows - -## When to Use Sub-Microflows - -### First Example - -The first example of using sub-microflows is when you are doing a large data import. If you are creating a microflow that imports data into the system, there are usually different parts to the process. The first part can be data validation. An example of data validation is checking if the values are empty. If the values are empty, then you might not want to import the data, or you might want the application to throw an error. - -Once the data is validated, you import and map it into your Mendix domain model. This is a separate action within the data import. It is ideal to do all the validations at the beginning of the imported microflow and to do all the mapping at the end. - -You can break down the validation and mapping into sub-microflows to better manage the logic. Furthermore, if you need to reuse the validation during the import at other steps in the application, you can reuse the sub-microflow. - -### Second Example - -The second example of using sub-microflows is when you are doing data validation and saving an object to the database. The example in the section [How to Use Sub-Microflows](#HowtoUseSubMicroflows) below will cover in detail how to use a sub-microflow for validation. - -### Other Examples - -There are many other examples of when it is useful to create sub-microflows. The goal is to reuse sub-microflows to condense your logic. Feel free to use sub-microflows whenever you see the need for it. - -### Dragging a Microflow into a Microflow - -Instead of creating a new sub-microflow action, it may be easier to drag an existing microflow into the current one: - -{{< figure src="/attachments/howto8/logic-business-rules/extract-and-use-sub-microflows/18580991.gif" class="no-border" >}} - -## How to Use Sub-Microflows {#HowtoUseSubMicroflows} - -The following example microflow checks to see if a registration has a trainee assigned and a registration date. If the registration passes both of these checks, the registration is committed to the database. - -{{< figure src="/attachments/howto8/logic-business-rules/extract-and-use-sub-microflows/18581021.png" class="no-border" >}} - -In this scenario, it makes sense to create a sub-microflow for the validation steps. If you do this, you can reuse this sub-microflow in other microflows where you need to validate a registration again. - -To create a sub-microflow for the validation steps, follow these steps: - -1. Select the area you want to capture and use as a sub-microflow: - - {{< figure src="/attachments/howto8/logic-business-rules/extract-and-use-sub-microflows/18581020.png" class="no-border" >}} - -2. Right-click an item in the selection and select **Extract submicroflow...**: - - {{< figure src="/attachments/howto8/logic-business-rules/extract-and-use-sub-microflows/18581018.png" class="no-border" >}} - -3. Enter a name for the sub-microflow: - - {{< figure src="/attachments/howto8/logic-business-rules/extract-and-use-sub-microflows/18581017.png" class="no-border" >}} - - {{% alert color="warning" %}} The best practice is to identify sub-microflows by their name. You can use "Sub_MicroflowDescriptionHere", "Subflow_MicroflowDescriptionHere", or any other notation you feel works best. The key is to be consistent when you name your microflows so that it is easy for other team members to understand and find the microflows they need.{{% /alert %}} -4. Click **OK** to create your first sub-microflow: - - {{< figure src="/attachments/howto8/logic-business-rules/extract-and-use-sub-microflows/18581016.png" class="no-border" >}} - -5. Open the sub-microflow by right-clicking the **Sub_RegistrationValidation** microflow and selecting **Go to microflow**: - - {{< figure src="/attachments/howto8/logic-business-rules/extract-and-use-sub-microflows/18581015.png" class="no-border" >}} - -The new sub-microflow will do the registration validation. You can reuse this sub-microflow whenever you need to do a registration validation. - -{{% alert color="info" %}} -Because this sub-microflow does not return anything, the sub-microflow call cannot be used in the **Is Valid?** check that immediately follows it. To stop or continue your microflow based on the sub-microflow's outcome, right-click the **Create Boolean Variable** activity and select **Set $isValid as return value**. -{{% /alert %}} - -## Troubleshooting Extractions of Sub-Microflows - -If you get errors, this usually means you have not provided the right input or output parameters. Check your parameters and make sure that they are configured properly. - -In addition, make sure you have highlighted the correct activities that you want to turn into a sub-microflow. - -## Conclusion - -The extra sub-microflow option is based on the Mendix reusability principle. You can reuse any sub-microflows in other parts in the application. Furthermore, when you have very large and complex microflows, using sub-microflows can help you break down and better manage your logic and business processes. - -## Read More - -* [Define Access Rules Using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Create a Custom Save Button](/howto8/logic-business-rules/create-a-custom-save-button/) -* [Extend Your Application with Custom Java](/howto8/logic-business-rules/extending-your-application-with-custom-java/) -* [Work with Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) -* [Optimize Retrieve Activities](/howto8/logic-business-rules/optimizing-retrieve-activities/) -* [Set Up Error Handling](/howto8/logic-business-rules/set-up-error-handling/) -* [Optimize Microflow Aggregates](/howto8/logic-business-rules/optimizing-microflow-aggregates/) -* [Microflows](/refguide8/microflows/) diff --git a/content/en/docs/howto8/logic-business-rules/filtering-data-on-an-overview-page.md b/content/en/docs/howto8/logic-business-rules/filtering-data-on-an-overview-page.md deleted file mode 100644 index 0bc8940b862..00000000000 --- a/content/en/docs/howto8/logic-business-rules/filtering-data-on-an-overview-page.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: "Filter Data on an Overview Page Using XPath" -linktitle: "Filter Data Using XPath" -url: /howto8/logic-business-rules/filtering-data-on-an-overview-page/ ---- - -## Introduction - -To filter data on your page, you can use the search bar functionality, or you can add an XPath constraint to your data grid. The search bar contains search fields that allow the end-user to quickly find the information they need. XPath is a hard-coded constraint on your data grid that filters the data. - -This how-to will start with preparing a data structure and some example data. After this setup, you will filter your data with a search bar. Then you will filter your data using different XPath constraints. - -This how-to serves as a comparison for filtering data and emphasizes how to use XPath for the filtering. - -This how-to teaches you how to do the following: - -* Prepare the data structure -* Prepare the GUI -* Prepare the data -* Filter a list using the search bar -* Filter a list using XPath - -## Prerequisites - Preparing the Data Structure, GUI, and Example Data - -To see the results of this how-to, it is necessary that you set up a test project with test data. - -Before you continue, make sure that you know how to create the following: - -* Domain models (for more information, see [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/)) -* Overview and detail pages (for more information, see [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/)) -* Menu items (for more information, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/)) - -1. Create the following domain model: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581378.png" class="no-border" >}} - -2. Create **overview** and **detail** pages to manage objects of type **Customer** and **Order**. -3. Create **menu items** to access the **Order** and the **Customer** overview pages. -4. Add the following customer data to your app: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581374.png" class="no-border" >}} - -5. Add the following order data to your app: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581373.png" class="no-border" >}} - -## Filtering a List of Orders Using the Search Bar - -In the previous section you set up a basic data structure and created some sample data. In this section you will add search fields to the search bar to allow the user to filter data on your overview page. In the examples you will filter on the order status and on a minimum price. - -1. Open your **orders overview** and right click the (empty) section above the **Search** button. - - {{% alert color="warning" %}} The search bar section might be already populated if you automatically filled the contents of your data grid. {{% /alert %}} - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581359.png" class="no-border" >}} - -2. Right click the search bar section and select **Add search field** > **Drop-down**. -3. Add the **OrderStatus** attribute to the search field and define the name. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581355.png" class="no-border" >}} - -4. Redeploy your application and click the **Search** button on your orders overview. The new search field appears. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581354.png" class="no-border" >}} - -5. Use the **Order status** search field to filter your list on a specific order status and click the 'Search' button on the right side. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581353.png" class="no-border" >}} - -6. To filter on a minimum price, add another search field by selecting **Add search field** > **Comparison**. -7. Select the **TotalPrice** attribute, name the search field **Minimum total price** and change the **Comparison** from **Contains** to **Greater or equal.** - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581351.png" class="no-border" >}} - -8. Redeploy your application and enter 50 in your newly added search field. Your list will be filtered to only show orders with a minimum value of 50. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581350.png" class="no-border" >}} - -## Filtering a List of Orders with the "Open" Status Using XPath - -In the previous section you used the search bar to filter data on your overview page. Now you will add an XPath constraint on the Orders data grid. With an XPath constraint on a data grid you can (hard coded) filter the objects shown in the list. Mendix XPath is one of the Mendix query languages designed to retrieve data. XPath uses path expressions to select data of Mendix objects and their attributes or associations. To learn more about XPath, see [XPath Constraints](/refguide8/xpath-constraints/). In this section you will constrain the data grid so it will only display orders with status 'Open'. - -1. Select the **Order** data grid and in the **Properties** pane on the right, change **Data source** > **Type** to **XPath**, and then click the **XPath Constraint** field: - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581372.png" class="no-border" >}} - -2. Enter the following expression in the **XPath Constraint** editor: `[OrderStatus = ‘Open’]`. The data grid will now only show orders with status ‘Open’. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581371.png" class="no-border" >}} - -3. Run your application to see the following result set: - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581370.png" class="no-border" >}} - -## Filtering a List of Orders on the Minimum Total Price Using XPath - -In the previous section you have constraint the data grid on status 'Open'. In this section we will change the constraint to ensure that the data grid will only show orders with a minimum value of 50.00. - -1. Select the **Order** data grid and in the **Properties** pane on the right, click the **XPath Constraint** field and enter the following expression: `[TotalPrice >= 50]`. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581367.png" class="no-border" >}} - -2. If you run your application you will see the following result set. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581368.png" class="no-border" >}} - -## Combining Constraints Using XPath - -In the previous two sections you used single constraints to filter the data grid on status and minimum total price. In this section you will combine those two constraints. Combination can be made with logical operator **AND** and **OR**. - -1. To constrain the results in the order overview to only the **Open** orders *or* orders with a minimum price of 50.00, you have to insert an `or` statement in the XPath constraint: `[OrderStatus = 'Open'] or [TotalPrice >= 50]`. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581366.png" class="no-border" >}} - -2. Run your application to see all the orders with the order status 'Open' or with a total price higher or equal to 50. - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581373.png" class="no-border" >}} - -3. To constrain the results in the order overview to only the **Open** orders *and* orders with a minimum price of 50.00, you have to insert an `and` statement in the XPath constraint: `[OrderStatus = 'Open'] and [TotalPrice >= 50]`. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581365.png" class="no-border" >}} - -4. Run your application to see orders which are 'Open' and have a minimum total price of 50. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581364.png" class="no-border" >}} - -## Filtering the Order List with Attributes of Associated Customers Using XPath - -In the previous section you have constrained the data grid on attributes of the same entity as the data grid entity. In this section you will constrain on attributes over an associated object. In the example of this section you will filter the orders by their associated customers based on the city letter of the customer. - -1. To constrain the results in the order overview to only orders from customers in Rotterdam, enter the following XPath into the **XPath Constraint** editor: `[Sales.Order_Customer/Sales.Customer/City = 'Rotterdam']`. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581363.png" class="no-border" >}} - -2. Run your application to only see the orders of customers in Rotterdam. - - {{< figure src="/attachments/howto8/logic-business-rules/filtering-data-on-an-overview-page/18581362.png" class="no-border" >}} - -## Read More - -* [XPath Constraints](/refguide8/xpath-constraints/) diff --git a/content/en/docs/howto8/logic-business-rules/java-api-tutorial.md b/content/en/docs/howto8/logic-business-rules/java-api-tutorial.md deleted file mode 100644 index b95145f5f01..00000000000 --- a/content/en/docs/howto8/logic-business-rules/java-api-tutorial.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: "Use the Java API" -url: /howto8/logic-business-rules/java-api-tutorial/ -weight: 13 ---- - -## Introduction - -This tutorial contains some examples of how to use the Java API provided by the Mendix Runtime. The tutorial assumes you have basic Java knowledge as well as basic Mendix modeling knowledge. - -To avoid cluttering the tutorial, only the relevant code will be shown, not the entire code generated by Studio Pro itself. Recreating the cases yourself and then trying to execute the actions is recommended. - -When you look at these examples, often an IContext will be used. This is the context in which something can be done. For example, it holds access rights to objects. If you do something with an object that requires access rights, the context in which you're working will determine if you have these rights and can perform that action. - -This how-to teaches you how to do the following: - -* Execute microflows and commit objects -* Copy FileDocuments - -## Executing Microflows and Committing Objects - -There are cases in which you'd like to execute a microflow in a Java Action. This case will explain how to do this, including how to pass parameters and obtain the return value. Additionally, the result will be saved in an object and the object will be committed. - -First, we will introduce a helper method that we will place in the section `BEGIN EXTRA CODE` and `END EXTRA CODE`. The method will execute a microflow that is called FormatString and is part of the MyFirstModule module. It has an input parameter called inputString, which is a string. Its return value is also a string, which contains the formatted string. - -```java -private static String formatString(String inputString, IContext context) throws CoreException -{ - Map parameters = new HashMap(); - parameters.put("inputString", inputString); - String formattedString = (String) Core.execute(context, "MyFirstModule.FormatString", parameters); - return formattedString; -} -``` - -| Line | Description | -| --- | --- | -| 1 | In this line, the method is defined. We'll need the input string, and we'll also need the context in which this microflow is executed. | -| 3 | To pass parameters to a microflow, a map is used. A `HashMap` is being used here. The map consists of a string key, which holds the name of the parameter in the microflow, and an object value, which holds the value of the parameter. | -| 4 | An entry is put in the `HashMap` containing the name of the parameter (`inputString`) and the value of the string. | -| 5 | The core method executed is called. This executes the microflow. It has the following parameters: the context, the module name and microflow name, and the parameter map. The method always returns an object which can be cast to the type that the microflow returns, in this case a string. | -| 6 | The microflow return value is returned by our helper method. | - -Once we have the value of the formatted string, we are going to store this in an object. This is the code between `BEGIN USER CODE` and `END USER CODE`. - -```java -String formattedString = formatString("this is an unformatted string", context); -testObject.setTestString(context, formattedString); -Core.commit(context, testObject.getMendixObject()); -``` - -## Copying FileDocuments - -A FileDocument is a system module entity that holds the content of a file (for example, a text file or Excel sheet). For this case, we assume we have an entity called `GenericObject` that has a relation with an `Attachment` entity. The `Attachment` entity inherits from `FileDocument`. One `GenericObject` can have multiple `Attachments`. We'd like to copy the `Attachments` from one `GenericObject` to another so that they can be independently modified later. - -In the Java Action, we pass two `GenericObjects` as parameters, a `sourceObject`, and a `destinationObject`. We are going to copy all the `Attachments` from the `sourceObject` to the `destinationObject`. - -To be able to copy `Attachments`, we will first need to retrieve them. For this purpose we introduce the extra method called `getAttachments`, which returns a list of `IMendixObjects`. This code is put between `BEGIN EXTRA CODE` and `END EXTRA CODE` in the Java action. - -```java -public static List getAttachments(GenericObject object, IContext context) throws CoreException -{ - String attachmentEntityName = Attachment.entityName; - String relationName = Attachment.MemberNames.Attachment_GenericObject.toString(); - String currentObjectID = object.getGUID(); - String query = String.format("//%s[%s=$currentid]", attachmentEntityName, relationName); - return Core.createXPathQuery(query) - .setVariable("currentid", currentObjectID) - .execute(context); -} -``` - -| Line | Description | -| --- | --- | -| 1 | The help method is defined here. Its parameters are the `GenericObject` proxy object and the context in which we are performing the query. | -| 3 | The name of the `Attachment` entity is defined in a `String` by copying the `entityName` from the `Attachment` proxy class. | -| 4 | The name of the relation between the `Attachment` entity and `GenericObject` entity is defined in a `String` by getting it from the `MemberNames` enumeration of the `Attachment` proxy class and calling `toString()` on it. | -| 5 | The ID of the `currentObject` is retrieved from the `GenericObject` proxy object method `getGUID();`. | -| 6 | We construct a query on the `Attachment` entity that is related to the object with `currentid`. The prefix `$` denotes that this is a variable, which can later be safely inserted using the `Core.createXPathQuery` API. -| 7 | The `Core` method `createXPathQuery` is used to create a query. This query fill the variable `currentid` with the ID of the current object. We pass the context in which we want the query to be executed. After this its result (a list of `IMendixObjects`) is immediately returned. - -Using the createXPathQuery API, you can also enter conditions, such as a sorting mechanism and a maximum number of objects returned. After executing, these are taken into account. View the JavaDoc for more information. - -Now that we have a way to get all the `Attachments` from a certain `GenericObject`, we can start copying them. - -This is the code between `BEGIN USER CODE` and `END USER CODE`: - -```java -Attachment newAttachment; -InputStream inputStream; -for (IMendixObject iMendixObject: getAttachments(sourceObject, context)) -{ - inputStream = Core.getFileDocumentContent(iMendixObject); - newAttachment = Attachment.create(context); - newAttachment.setAttachment_GenericObject(destinationObject); - Core.storeFileDocumentContent(context, newAttachment.getMendixObject(), (String) iMendixObject.getValue(system.proxies.Document.MemberNames.Name.toString()), inputStream); -} -``` - -| Line | Description | -| --- | --- | -| 1 | Declaring an `Attachment` variable named `newAttachment`. | -| 2 | Declaring an `InputStream` variable named `inputStream`. | -| 3 | Starting to loop through a list of `IMendixObjects` returned by our helper method. | -| 5 | Here the `Core` method `getFileDocumentContent()` is used, passing the retrieved `Attachment` object to retrieve the `InputStream` of the actual file. | -| 6 | A new `Attachment` is instanced. | -| 7 | The relation to the destination object is set on our new `Attachment`. | -| 8 | The content of the retrieved `InputStream` is stored in our new `Attachment` using the `Core` method `storeFileDocumentContent()`. This method takes a number of parameters: the context in which you are performing this store; the `IMendixObject` of the `Attachment` proxy, which is retrieved by calling `getMendixObject()` on the `Attachment` proxy; the file name of the `FileDocument` in string format, which is copied from the attachment you're copying from by using the `getValue()` method passing the member name you wish to know the value of; and the `InputStream` containing the actual file. | - -After this, all `Attachments` belonging to one `GenericObject` have been copied to another. - -## Read More - -* [Create a Custom Save Button](/howto8/logic-business-rules/create-a-custom-save-button/) -* [Trigger a Microflow From a Menu Item](/howto8/logic-business-rules/trigger-microflow-from-menu-item/) -* [Define Access Rules Using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Extend Your Application with Custom Java](/howto8/logic-business-rules/extending-your-application-with-custom-java/) -* [Extract and Use Sub-Microflows](/howto8/logic-business-rules/extract-and-use-sub-microflows/) -* [Optimize Microflow Aggregates](/howto8/logic-business-rules/optimizing-microflow-aggregates/) -* [Optimize Retrieve Activities](/howto8/logic-business-rules/optimizing-retrieve-activities/) -* [Set Up Error Handling](/howto8/logic-business-rules/set-up-error-handling/) -* [Work with Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) diff --git a/content/en/docs/howto8/logic-business-rules/optimizing-microflow-aggregates.md b/content/en/docs/howto8/logic-business-rules/optimizing-microflow-aggregates.md deleted file mode 100644 index 7066eec807f..00000000000 --- a/content/en/docs/howto8/logic-business-rules/optimizing-microflow-aggregates.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: "Optimize Microflow Aggregates" -url: /howto8/logic-business-rules/optimizing-microflow-aggregates/ -weight: 7 -#To update screenshots of these microflows in , use the Microflow Screenshots app. ---- - -## Optimization - -In some projects, it is necessary to evaluate large datasets in a microflow (for example, for reporting purposes). If all those microflows do a lot of retrieves and aggregates on large datasets, it is easy to run into performance or memory problems. - -When a database retrieve activity is only used in list aggregate activities and a custom range is not configured, the platform can automatically merge these two activities into a single action. This executes a single aggregate query on the database. So, if you retrieve all 100k log lines from a database and only do a count on the list, you will not receive a heap space. This is because the microflow will never place all 100k records in memory. However, if you reuse the same list for multiple list aggregates, this does not apply. - -The Mendix Platform only creates an optimized SQL query if the list is not used in the microflow afterwards and a custom range is not configured. If you use the list later (for example, to iterate over) or a custom range is configured, the query will not be optimized. - -If you do want to use the list but you also want the optimized query, do two separate retrieves. This will do the optimized query, and you can use the second retrieve in your microflow. - -{{< figure src="/attachments/howto8/logic-business-rules/optimizing-microflow-aggregates/18580944.png" class="no-border" >}} - -## Read More - -* [Define Access Rules Using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Extend Your Application with Custom Java](/howto8/logic-business-rules/extending-your-application-with-custom-java/) -* [Work with Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) -* [Create a Custom Save Button](/howto8/logic-business-rules/create-a-custom-save-button/) -* [Optimize Retrieve Activities](/howto8/logic-business-rules/optimizing-retrieve-activities/) -* [Configure Error Handling](/howto8/logic-business-rules/set-up-error-handling/) -* [Optimize Microflow Aggregates](/howto8/logic-business-rules/optimizing-microflow-aggregates/) -* [Extract and Use Sub-Microflows](/howto8/logic-business-rules/extract-and-use-sub-microflows/) diff --git a/content/en/docs/howto8/logic-business-rules/optimizing-retrieve-activities.md b/content/en/docs/howto8/logic-business-rules/optimizing-retrieve-activities.md deleted file mode 100644 index 427e9ad57a2..00000000000 --- a/content/en/docs/howto8/logic-business-rules/optimizing-retrieve-activities.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: "Optimize Retrieve Activities" -url: /howto8/logic-business-rules/optimizing-retrieve-activities/ -weight: 9 -#To update screenshots of these microflows in , use the Microflow Screenshots app. ---- - -## Introduction - -Often in processes you need to retrieve objects in order to complete the process. But what if those objects cannot be found? Usually additional actions are required, but since the objects you retrieve and create are assigned different names, sometimes you cannot merge them back into a single flow. - -This how-to teaches you how to do the following: - -* Find and create objects to continue your process -* Retrieve an instance of an object - -## Finding and Creating Objects to Continue Your Process - -A common example is shown below in which creating an order needs to be associated with the customer and its primary address. This example ends up in three different flows and cannot be merged back into the main flow, because that causes the **OtherAddress** or **NewPrimaryAddress** to be unreachable. - -Preventing the creation of the same objects multiple times on different places causes a lot of unnecessary maintenance. One solution for this is to copy the logic (partially) into a sub-microflow (as shown in the example), but this doesn't make it easier to read. - -{{< figure src="/attachments/howto8/logic-business-rules/optimizing-retrieve-activities/18581014.png" class="no-border" >}} - -You can easily work around this by using a sub-microflow at a different place. In order to avoid making exceptions in your microflow for the default behavior, do not put the standard logic in a sub microflow that is difficult to read (because of one exception earlier in the process). Since we got to this point because of an exception, it makes the most sense to solve this problem by altering the exception and changing it so that it fits in our standard flow. - -The easiest way to implement this is to move all the logic for acquiring the primary address into a sub-microflow. This way, all the logic acquired after getting the address only needs to be specified once, and the microflow is still easily readable. - -{{< figure src="/attachments/howto8/logic-business-rules/optimizing-retrieve-activities/18581013.png" class="no-border" >}} - -The **GetCustomerPrimaryAddress** sub-microflow contains the same logic as the original example, except this way there is only one result: the correct primary address. - -{{< figure src="/attachments/howto8/logic-business-rules/optimizing-retrieve-activities/18581012.png" class="no-border" >}} - -## Retrieving an Instance of an Object - -Sometimes you need to have a specific instance of an object, and building a sub-flow for just one retrieve-and-create seems like too much work. An alternative is to build your own loop, which allows you to have one main flow but still be able to find and create objects during this process. - -However, there is the risk of creating an infinite loop if the retrieve applies a constraint that is not set correctly during the create. So, always be sure to print a log message so that you can easily identify any problems in your design. - -{{< figure src="/attachments/howto8/logic-business-rules/optimizing-retrieve-activities/18581011.png" class="no-border" >}} - -## Read More - -* [Define Access Rules Using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Extend Your Application with Custom Java](/howto8/logic-business-rules/extending-your-application-with-custom-java/) -* [Work with Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) -* [Create a Custom Save Button](/howto8/logic-business-rules/create-a-custom-save-button/) -* [Optimize Retrieve Activities](/howto8/logic-business-rules/optimizing-retrieve-activities/) -* [Configure Error Handling](/howto8/logic-business-rules/set-up-error-handling/) -* [Optimize Microflow Aggregates](/howto8/logic-business-rules/optimizing-microflow-aggregates/) -* [Extract and Use Sub-Microflows](/howto8/logic-business-rules/extract-and-use-sub-microflows/) diff --git a/content/en/docs/howto8/logic-business-rules/server-side-paging.md b/content/en/docs/howto8/logic-business-rules/server-side-paging.md deleted file mode 100644 index eb08a2a8167..00000000000 --- a/content/en/docs/howto8/logic-business-rules/server-side-paging.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: "Set Up Server-Side Paging and Sorting for a Microflow Data Source" -linktitle: "Server-Side Paging and Sorting" -url: /howto8/logic-business-rules/server-side-paging/ -description: "This how-to teaches you how to create a data grid with a microflow data source which retrieves data from a REST service, and then add server-side paging and sorting to it." ---- - -## Introduction - -Using server-side paging and sorting for a microflow data source you can model out how you retrieve data to a single page and ensure it ends up in the correct sorting order. With this approach you do not need to return all the data to the client — you can just return a single page. This can be helpful for getting data from external sources like a REST service, but can also be useful for a regular retrieve action in a microflow. To do this however, you must model the logic for getting the correct data in the microflow itself. - -This how-to teaches you how to do the following: - -* Create a data grid with a microflow data source which retrieves data from a REST service -* Add server-side paging and sorting to that data grid - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* If you are not familiar with using data from REST services, read [Consume a REST Service](/howto8/integration/consume-a-rest-service/) -* Mendix 8.2 and above - -## Creating a Microflow Data Source - -In this section you will create a JSON structure and import mapping for a REST service. To do this, complete the first four sections of [Consume a REST Service](/howto8/integration/consume-a-rest-service/) — (until **Adding an Input Entity to the Domain Model** is done). - -You must complete these steps with *one crucial change*: you must use this REST service URL for your JSON snippet: `https://my-json-server.typicode.com/mendix/howto-api-data/airports`. - -Once successful, your project should have the following elements: - -* A JSON structure based on the airport data: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/json-structure.png" alt="json structure" width="500" class="no-border" >}} - -* Import mapping: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/import-mapping.png" alt="import mapping" width="500" class="no-border" >}} - -* An input entity added to the domain model: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/input-entity.png" alt="input entity" width="500" class="no-border" >}} - -Now you can start calling the REST service from your microflow data source. To create a microflow data source which returns a list of characters, do the following: - -1. Right-click your module, click **Add Microflow**, and create a new microflow named *Call_REST*. -2. From the **Toolbox**, drag a **Call REST service** activity into the microflow. -3. Double-click your **Call REST service** activity. -4. Click the **Location** > **Edit** button: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/edit-call-rest.png" alt="edit call rest" width="500" class="no-border" >}} - -5. In the **Template** field, add `https://my-json-server.typicode.com/mendix/howto-api-data/airports` then click the **OK** button: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/add-airport-url.png" alt="airport template" width="500" class="no-border" >}} - -6. Click the **Response** tab: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/response-tab.png" alt="response tab" width="500" class="no-border" >}} - -7. Select **Apply import mapping** from the **Response handling** drop-down menu. -8. Click **Mapping** > **Select** and select the import mapping you created. -9. For **Variable Name**, type *Result.* Click **OK** to accept the changes: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/call-rest-response.png" alt="variable result" width="500" class="no-border" >}} - -10. From the **Toolbox** drag the **Retrieve** activity into the microflow and double-click it. -11. Click **Association** > **Select**, click **Expand All**, and select **JsonObject_Summary (List of NativeMobile.JsonObject)**. -12. Click **OK** to accept this association. -13. Right-click the **Retrieve** activity and select **Set $JsonObjectList as return value**: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/call-rest-returned.png" alt="set return value" width="500" class="no-border" >}} - -## Creating a Data Grid with a Microflow Data Source - -In previous section you created a microflow which return a list of characters. Next you will use this microflow as a data source for a data grid: - -1. From the **Toolbox**, drag a **Data grid** onto a page. -2. Double-click the blue header of the newly-placed data grid. -3. Click the **Data source** tab: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/data-source.png" alt="data source tab" class="no-border" >}} - -4. Select **Type** > **Microflow**. -5. Click **Microflow** > **Select** and select the **Call_REST** microflow. -6. Click **OK** to accept the changes to the data source. -7. When you see the **“Do you want to automatically fill the contents of the data grid?”** pop-up window, click **Yes**: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/auto-fill.png" alt="click yes" width="500" class="no-border" >}} - -8. When you see the **“Do you want to generate controls for microflow source parameters of the data grid? This will enable server-side paging sorting and searching for the grid.”** pop-up window, click **Yes**: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/question-dialog.png" alt="click yes again" width="500" class="no-border" >}} - -This generates a data view around your data grid, creates the necessary widgets and nanoflows, and adds the **Paging** object as an input to your microflow: - -{{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/paging.png" alt="paging object" width="500" class="no-border" >}} - -## Adding Paging Support to the Microflow Data Source - -In the previous section you added the **Paging** input parameter to your microflow. This parameter contains the **PageNumber** attribute which is updated when you navigate through the pages with the paging bar in the client. In this section you will use the **PageNumber** attribute to retrieve a specified page from your REST service: - -1. Open the **CallREST** microflow. -2. Double-click the **Call REST service** activity. -3. Click **Location** > **Edit**. -4. Change **Template** to `https://my-json-server.typicode.com/mendix/howto-api-data/airports?_limit=5&_page={1}`: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/template-param-one.png" alt="add page bit to template" width="500" class="no-border" >}} - -5. Click **Parameters** > **New** for a new parameter and enter the following expression `toString($Paging/PageNumber)` for this parameter: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/page-parameter.png" alt="add page number parameter" width="500" class="no-border" >}} - -6. Click **OK** to accept this expression. -7. Click **OK** to accept the changes for the location, and click **OK** once more to accept the changes for the **Call REST service** activity. You are now back at your microflow. - -Deploy your app and navigate to the page where you added your data grid. You can now use your newly added server-side paging by using the paging bar buttons above the data grid. - -## Adding Server-Side Sorting Support to the Microflow Data Source - -Now you have service-side paging for your data grid. Next, add server-side sorting to it. - -Clicking the header on the data grid in the client will update the **Paging** entity by setting the attribute **SortAttribute** to the attribute which is associated to the header you clicked, and the **SortAscending** is set to **true** for ascending and **false** for a descending sort order. - -Use these attributes when calling your REST service: - -1. Open your **Call_REST** microflow. -2. Double-click the **Call REST service** activity. -3. Click **Location** > **Edit**. -4. Add `&_sort={2}&_order={3}` to the end of your current **Template** address: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/appended-template.png" alt="add sort and order bits to template" width="500" class="no-border" >}} - -5. Click **Parameters** > **New** to add the second parameter and enter the following expression `toLowerCase($Paging/SortAttribute)`: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/second-param.png" alt="add second parameter" width="500" class="no-border" >}} - -6. Click **OK** to accept this expression. -7. Click **Parameters** > **New** to add the third parameter and enter the following expression `if $Paging/SortAscending then 'asc' else 'desc'`: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/third-param.png" alt="add third parameter" width="500" class="no-border" >}} - -8. Click **OK** to accept this expression. -9. Click **OK** to accept the changes in the location. -10. Click **OK** once more to accept the changes in the **Call REST service** activity. - -Deploy your app again and navigate to the page with your data grid. Click the column headers to see your server-side sorting in action! - -{{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/header-sorting-smaller2.gif" alt="click headers to sort" class="no-border" >}} - -### Setting a Default Sort Order - -You can set a default sort order for data. When a user has not clicked a header, the data will be ordered in the default sort order: - -1. Open the page containing your data grid. -2. Right-click the data view surrounding the data grid. -3. Select **Go to data source nanoflow**. -4. Double-click the **Create object** activity: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/create-nano.png" alt="create object activity one" width="500" class="no-border" >}} - -5. Click **New** to set the value for a member of the **Paging** entity. -6. Click the **Member** drop-down menu and select **SortAttribute (String (200))**. -7. Set **Value** to `'Name'`: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/name-value.png" alt="name value" width="500" class="no-border" >}} - -8. Click **OK** to accept the changes to the member, and click **OK** once more to accept the changes to the **Create object** activity. - -Deploy your app again and navigate to the page with your data grid. The data will be shown ordered by **Name**. - -{{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/data-by-name.png" alt="sorted by name" width="500" class="no-border" >}} - -### Disabling Server-Side Sorting - -Apps that use a REST service which does not support sorting, or apps which do not enable users to change sorting order, require special functionality. In these cases, disable sorting so that clicking the header has no effect: - -1. Open the page containing the data grid. -2. Right-click the data view surrounding the data grid and select **Go to data source nanoflow**. -3. Double-click the **Create object** activity. -4. Click **New** to set the value for another member of the **Paging** entity. -5. Select **Member** > **IsSortable (Boolean)** from the drop-down menu. -6. Type *false* into **Value**: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/disable-sort.png" alt="value false" class="no-border" >}} - -7. Click **OK** to accept the changes to the member, and click **OK** once more to accept the changes to the **Create object** activity. - -Deploy your app again and navigate to the page with your data grid. The data will still be shown ordered by **Name**, but you can no longer change the sorting by clicking the header. Note the lack of an arrow above the **Name** header. - -{{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/sorting-disabled.png" alt="sorted but not clickable" class="no-border" >}} - -## Add Server-Side Searching - -If you are using Mendix 8.3 or above, generating controls also generates input fields for all your attributes of the entity the microflow returns. These inputs can be used by your user to enter search criteria, which can be used to filter the data set on the server. Any data entered in the input fields by the user is set in the **Paging** entity which is passed to the data source microflow. - -You only need to use this data in your microflow and pass the search criteria to your REST call to get a filtered set of data. As an example, follow the instructions below to filter the **Name** attribute: - -1. Open your **Call_REST** microflow. -2. Double-click the **Call REST service** activity. -3. Click **Location** > **Edit**. -4. Add `&name_like={4}` to the end of your current **Template** address: - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/template-add-search.png" alt="add search bits to template" width="500" class="no-border" >}} - -5. Click **Parameters** > **New** to add the fourth parameter and enter the following expression: - - ```text - if $Paging/Name = empty then '' else $Paging/Name - ``` - - {{< figure src="/attachments/howto8/logic-business-rules/server-side-paging/fourth-param.png" alt="add fourth parameter" width="500" class="no-border" >}} - -6. Click **OK** to accept this expression. -7. Click **OK** to accept the changes in the location. -8. Click **OK** once more to accept the changes in the **Call REST service** activity. - -Deploy your app again and navigate to the page with your data grid. Enter a value for a part of the name, for example *International*, and click **Search** to see your server-side searching in action! - -## Read More - -* [Consume a REST Service](/howto8/integration/consume-a-rest-service/) -* [JSON Structures Guide](/refguide8/json-structures/) -* [Consumed REST Services Guide](/refguide8/consumed-rest-services/) diff --git a/content/en/docs/howto8/logic-business-rules/set-up-error-handling.md b/content/en/docs/howto8/logic-business-rules/set-up-error-handling.md deleted file mode 100644 index c63bab2e986..00000000000 --- a/content/en/docs/howto8/logic-business-rules/set-up-error-handling.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: "Set Up Error Handling" -url: /howto8/logic-business-rules/set-up-error-handling/ -weight: 8 -#To update screenshots of these microflows in , use the Microflow Screenshots app. ---- - -## Introduction - -When working with microflows, it is important to realize that there are always transactions. These transactions help in achieving the correct result, and in case something goes wrong, they also help us to keep all the information in our application consistent. - -This how-to teaches you how to do the following: - -* Set up the various error handling components - -## Transactions - -### Transactions Keep Your Data Consistent - -Everything that happens in the platform happens in a transaction. What is more, unless otherwise specified, everything is executed, or nothing is executed. Accordingly, if you don't specify any error handling and the microflow you are trying to execute gives you an error, nothing will be executed. That means that all the objects you created or changed will be reverted, you will not get the text feedback, and the platform will not show the new page. Either every single step in the microflow is successfully executed, or nothing is executed. That is the only way to keep processes and data consistent. - -### Transactions Keep the Changes Isolated - -While updating or creating your objects, you do not want users to see temporary information or empty records because a microflow hasn't finished executing yet. - -To ensure that every user or process can only see persisted data, all the data changed in a transaction is only available within that specific transaction. None of the changes made inside that microflow will be available outside the microflow, not even to the user that initiated the microflow. The information will only be available to the whole application once the microflow has successfully completed all the actions. - -### Transactions Prevent Two processes from Using the Same Object at the Same Time - -When an object is updated, the platform will place a lock on that object for the duration of the transaction. That means that while the transaction is running, no other transactions are allowed to read or write in that same object. As soon as the transaction has finished, the lock will be released automatically and any waiting processes will continue normally. - -Please note that this isn't the same as preventing two users from editing the same object. It is still possible for two users to open the same object and change it 1 milliseconds after each other. The latest change will still be applied. - -## Error Handling Components - -| Type | Image | Description | -| --- | --- | --- | -| **Error Handling – Custom With Rollback** | {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580964.png" class="no-border" >}} | Everything that happened up to the error will be rolled back in the database, and a new transaction will be initiated. It will neither change nor roll back the state of the objects that are still in memory. As a result of that, recommitting the same objects will not cause a change as the runtime no longer knows which members are changed or whether the object was created or not. If you want to change the data in the database again you should copy the changes into another/new version of the same object.| -| **Error Handling – Custom Without Rollback** | {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580965.png" class="no-border" >}} | Any action taken inside the microflow can be reverted, but everything that happened before the error will be kept. The microflow will continue over the custom error handler flow. The transaction in the database will not be rolled back, meaning that all successfully committed changes in objects within activities of the microflow preceding the current failing activity will stay in the database.| -| **Continue** | {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580952.png" class="no-border" >}} | Any action taken inside the microflow can be reverted, but everything that happened before the error will be kept. The microflow will continue as if nothing happened. Avoid using this option – you should only use this in the more complicated combinations of multiple error handlers. You want to make sure that you at least log the error message. If it breaks, you need to know about it.| -| **End Event** | {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580962.png" class="no-border" >}} | This is the end of the microflow transaction and all actions are executed at the end of the main microflow.| -| **Error End Event** | {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580963.png" class="no-border" >}} | This re-throws the error to all parent microflows after executing the custom activities. For more details, see [Error Event](/refguide8/error-event/) in the *Studio Pro Guide*.| - -## Error Handling Transactions - -There are many different combinations of error handling and transactions that you can configure, and below you will find the descriptions of several combinations. These sections should present some of the possibilities and help you understand how the different configurations behave. - -### Default Error Handling - -With default error handling, there is always a transaction running. But since there is no custom error handling specified, the platform will create one transaction for all the actions executed in the microflow. All subflows will be executed in the same transaction. The changed order and customer information is only available inside the transaction until the microflow transaction has completed. - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580961.png" class="no-border" >}} - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580951.png" class="no-border" >}} - -| Order | | -| ------------ | -------- | -| ID | 1234 | -| Date | 1/1/2018 | - -| Customer | | -| -------- | ---- | -| ID | 1234 | -| Status | Gold | - -### Error Handling – Custom with Rollback - -Any submicroflow initiated with error handling set to **Custom with Rollback** will NOT initiate a new transaction. The original transaction will be re-used in the subflow. If an error occurs, the transaction will be completely reverted and a new transaction will be initiated so the custom error flow can continue using that new transaction. - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580956.png" class="no-border" >}} - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580950.png" class="no-border" >}} - -**For 1:** - -| Order | | -| ------------ | ------ | -| ... | | -| ... | | - -| Customer | | -| ------------ | ------ | -| ID | 1234 | -| Status | Silver| - -**For 2:** - -| Order | | -| ------------ | -------- | -| ID | 1234 | -| Date | 1/1/2018 | - -| Customer | | -| ------------ | -------- | -| ID | 1234 | -| Status | Gold | - -**For 3:** - -| Order | | -| ------------ | -------- | -| ID | 1234 | -| Date | 1/1/2018 | - -| Customer | | -| ------------ | ------ | -| ID | 1234 | -| Status | Silver | - -Because you are switching transactions, merging back to the original process is not recommended, as this will result in inconsistent data. If you use error handling with rollback in a subflow, you should make sure that all parent microflows are configured to use error handling continuously. It is preferable that you re-throw the exception after running your custom actions. - -### Error Handling – Custom without Rollback - -A submicroflow with error handling set to **Custom without Rollback** will always create a sub-transaction. All actions within the parent microflow will be persisted, and what happens inside the sub-microflow is determined by the sub-microflow. If no custom error handling is specified in the submicroflow, only the changes in the submicroflow can be reverted in case of an error. - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580960.png" class="no-border" >}} - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580949.png" class="no-border" >}} - -**For 1:** - -| Order | | -| ------------ | ------ | -| ... | | -| ... | | - -| Customer | | -| ------------ | ------ | -| ID | 1234 | -| Status | Silver| - -**For 2:** - -| Order | | -| ------------ | -------- | -| ID | 1234 | -| Date | 1/1/2018 | - -| Customer | | -| ------------ | -------- | -| ID | 1234 | -| Status | Gold | - -**For 3:** - -| Order | | -| ------------ | ------ | -| ... | | -| ... | | - -| Customer | | -| ------------ | ------ | -| ID | 1234 | -| Status | Silver | - -## Combinations of Different Types of Error Handling - -Most of the time you will be using a single activity with custom error handling. However, if you are developing more complicated processes where you are sending data outside of the application, it is important to realize what happens when an error occurs later in the process. For example, you don't want to send out notifications about a status change if an error occurs and therefore reverts the change. - -Especially when interacting with other systems, you need to think about how you want to process the errors. The best solution depends on what you want to do: continue, skip/revert the record you are working on, or keep the changes you have made so far but stop the process. All of these options can be done as long as you know what you want to achieve. The instructions below will show you a couple of examples of how you can use different combinations of the error handling options. - -### Rollback in the Parent Flow, Rollback in the Subflow - -| Color | Description | -| --- | --- | -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/orange.png" class="no-border" >}} | *Initial transaction* – this transaction is initiated when the microflow started. Custom error handling with rollback does not initiate any transactions. Therefore, the microflow is executed, but all the actions in both the parent and the subflow will be reverted. None of the changes made anywhere in this transaction will be applied. | -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/blue.png" class="no-border" >}} | *Transaction initiated by custom with rollback activity* – after catching the exception, a new transaction is initiated to execute the remainder of the microflow activities. | - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580948.png" class="no-border" >}} - -### Rollback in the Parent Flow, Continuing in the Subflow - -| Color | Description | -| --- | --- | -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/orange.png" class="no-border" >}} | *Initial transaction* – this transaction is initiated when the microflow starts. This transaction will be completely reverted, because the subflow re-throws the exception. None of the changes made during this transaction will be persisted. (If the subflow wasn't rethrowing the exception, all changes except 'SendEmail' would have been persisted in the database.) | -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/blue.png" class="no-border" >}} | *Transaction initiated by custom with rollback activity* – after catching the exception, a new transaction is initiated to execute the remainder of the microflow activities. | -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/green.png" class="no-border" >}} | *Transaction initiated by subflow* – at the start of the subflow, a new transaction is initiated. Any changes made in this transaction will be reverted because the activities in the 'SendEmail' subflow use default error handling. | - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580945.png" class="no-border" >}} - -### Continuing in the Parent Flow, Rollback in the Subflow - -| Color | Description | -| --- | --- | -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/orange.png" class="no-border" >}} | *Initial transaction* – this transaction is initiated when the microflow starts. This transaction will complete successfully and any changes made during this transaction will be persisted. | -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/blue.png" class="no-border" >}} | *Transaction initiated by subflow* – at the start of the subflow, a new transaction is initiated. All changes in this transaction will be reverted because of the custom error handler "with rollback." As a result, the change on the customer will not be applied. | -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/green.png" class="no-border" >}} | *Transaction initiated after the exception was caught by the error handler* – when this transaction is initiated, after executing some actions, it will re-throw the original exception. These changes will be persisted because of the error handling on the initial sub-microflow call. | - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580947.png" class="no-border" >}} - -### Continuing in the Parent Flow, Continuing in the Subflow - -| Color | Description | -| --- | --- | -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/orange.png" class="no-border" >}} | *Initial transaction* – nothing will be reverted. The only difference compared to successful execution is that no email will be sent, and the process will finish using the error flow instead of the normal process flow. -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/blue.png" class="no-border" >}} | *Transaction initiated by subflow* – at the start of the subflow, a new transaction is initiated. All the changes in this transaction will be kept, because the 'SendEmail' subflow is configured to continue without rollback. Even though the exception is re-thrown, the initial microflow call is configured for custom without rollback; therefore, none of the changes will be reverted. The process will just take the error flow instead of the default flow. -| {{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/green.png" class="no-border" >}} | *Transaction initiated by subflow* – at the start of the subflow, a new transaction is initiated. Any changes made in this transaction will be reverted, because the activities in the 'SendEmail' subflow use default error handling. - -{{< figure src="/attachments/howto8/logic-business-rules/set-up-error-handling/18580946.png" class="no-border" >}} - -## Best Practices - -Consider the following best practices for error handling: - -* Always use a log activity to print the error message and stack trace -* Never use the continue option, since that doesn't give you the option to print any info (the platform will just ignore the error) -* Always add custom error handling on integration or email activities -* Don’t over-do it – you can specify a lot of complicated error handling combinations, but this makes it more difficult (and slower) for the platform to evaluate the microflow, and it also makes it more difficult to predict the exact behavior in case of an exception - -## Read More - -* [Define Access Rules Using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Create a Custom Save Button](/howto8/logic-business-rules/create-a-custom-save-button/) -* [Extend Your Application with Custom Java](/howto8/logic-business-rules/extending-your-application-with-custom-java/) -* [Work with Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) -* [Optimize Retrieve Activities](/howto8/logic-business-rules/optimizing-retrieve-activities/) -* [Optimize Microflow Aggregates](/howto8/logic-business-rules/optimizing-microflow-aggregates/) -* [Extract and Use Submicroflows](/howto8/logic-business-rules/extract-and-use-sub-microflows/) diff --git a/content/en/docs/howto8/logic-business-rules/string-concatenation.md b/content/en/docs/howto8/logic-business-rules/string-concatenation.md deleted file mode 100644 index a8284fd44b7..00000000000 --- a/content/en/docs/howto8/logic-business-rules/string-concatenation.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: "Configure String Concatenation" -url: /howto8/logic-business-rules/string-concatenation/ -weight: 11 ---- - -## Introduction - -In every project, you will need to concatenate some text together. Common cases are when you want to assemble the full name of a person based on the first and last name. - -Whenever you want to paste multiple strings attributes together you want to make sure that the text looks good in all cases. For example you do not want a firstname + middlename + lastname to be printed as "John null Doe" because the middle name is empty. - -To understand what to look out for when concatenating strings it is important to be aware of the three states a string can be in: - -* Populated – there is text written in the attribute, and when you inspect the value in the microflow, you see something like: `'John'` -* Empty – the attribute never contained a value, and when inspecting the value in the microflow, you see `empty` -* Blank – the attribute previously contained a value, but has been reset by a user or system, so in the microflow, you see `''` - -Every string attribute will start out as an empty field, whenever the users or the system enters a value in the attribute it will be populated with that value. When the user removes that value from the UI the users makes the field blank and the attribute will contain the value: `''` - -Whenever you want to check if a string contains text it won't be sufficient to execute the expression: `$Account/Firstname != empty` nor will `$Account/Firstname != ''` cover all cases. Every string needs to be checked for both values to be sure that a field really is empty. - -## Breaking Down into Separate Decisions - -An inefficient example on how to check for text and create a combined messages based on the outcome. Building out all combinations is a lot of work, and if something need to change it will be a lot of work to change and it is prone to errors. - -Reference this microflow: - -{{< figure src="/attachments/howto8/logic-business-rules/string-concatenation/bco_contactperson_createfullname_inefficient.jpg" class="no-border" >}} - -## A Single Expression - -This example contains a single expression which can become difficult to read if the expression becomes larger and more complicated. As long as you are just combining 2 or 3 fields this is a good workable solution. But keep in mind when you are concatenating more fields it is better to use the best practices below. - -When looking at the example below it is important to note a couple of things. The white space is only added after a field if it is populated. If a person only has a first and last name, you don't want to end up with two white spaces between the two words. -Also the entire expression is surrounded with a trim, in case we only have a single field populated all unnecessary white spaces will be removed from the outcome of this expression. - -```text -trim( -( if $ContactPerson/Firstname != empty and $ContactPerson/Firstname != '' -then $ContactPerson/Firstname + ' ' else '' ) + -( if $ContactPerson/Middlename != empty and $ContactPerson/Middlename != '' -then $ContactPerson/Middlename + ' ' else '' ) + -( if $ContactPerson/Lastname != empty and $ContactPerson/Lastname != '' -then $ContactPerson/Lastname + ' ' else '' ) + -( if $ContactPerson/Suffix != empty -then getCaption( $ContactPerson/Suffix ) -else '') -) -``` - -Reference this microflow: - -{{< figure src="/attachments/howto8/logic-business-rules/string-concatenation/bco_contactperson_createfullname_hardtoread.jpg" class="no-border" >}} - -## Best Practices for Expression Breakdown - -The most flexible solution is to break the string concatenate down into separate activities. This allows to easily add or remove text from the concatenate function. It should not create an additional level of complexity either, simply create a subflow to combine the string values and use that in your microflow. - -In this example we went even one step further in the stability of the expression. By adding an additional trim to the attribute we prevent adding additional white spaces that might have been added by the user. Using the microflow below we are absolutely sure never to get any white spaces or null values in our text. - -```text -trim( $ContactPerson/Fullname + ' ' + trim( $ContactPerson/Firstname ) ) -``` - -Reference this microflow: - -{{< figure src="/attachments/howto8/logic-business-rules/string-concatenation/bco_contactperson_createfullname.jpg" class="no-border" >}} diff --git a/content/en/docs/howto8/logic-business-rules/translatable-validation-messages.md b/content/en/docs/howto8/logic-business-rules/translatable-validation-messages.md deleted file mode 100644 index 839d3d4fe51..00000000000 --- a/content/en/docs/howto8/logic-business-rules/translatable-validation-messages.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Use Translatable Validation Messages" -url: /howto8/logic-business-rules/translatable-validation-messages/ -weight: 14 ---- - -## Introduction - -Setting up validation rules should be relatively straightforward. Per object or per process step you want to have a single microflow that is in charge of the validation. That microflow has the required input parameters, validates all values. If a value is invalid the microflow will execute the validation feedback activity. When completing the microflow it will return a Boolean true/false whether or not the object has been successfully validated. - -These types of validation actions should be used throughout your project. - -{{< figure src="/attachments/howto8/logic-business-rules/translatable-validation-messages/18581628.png" class="no-border" >}} - -However you will often run into situations where you need to be able to show or process your validation rules in a different way than just as validation feedback. On option that gives you more control is building one large string message variable. The validation microflow should return that message. If anything has been returned, the object is invalid. - -Or if you need to differentiate between the different validation messages you can also build a list of (non-)persistable objects, instead of appending a message you should create an object and add the object to a list. Also take a look at the validation best practices. - -{{< figure src="/attachments/howto8/logic-business-rules/translatable-validation-messages/18581627.png" class="no-border" >}} - -## Simple Alternative for Translating Messages - -There is one big problem with this second solution, you loose the ability to translate your validation message. String variables or attributes can not be translated by the platform. If you only have a hand full of these types of validation rules you might want to consider modeling out all language combinations. For each validation message you have to add decisions and activities per language. This could become a lot of work, but as long as you only have to do this one a couple of places it might not be worth to use the more complicated solution described below. - -{{< figure src="/attachments/howto8/logic-business-rules/translatable-validation-messages/18581626.png" class="no-border" >}} - -## Translating Validation Rules - -If you have to translate multiple validation rules, it will be worth it to develop a more advanced validation module which supports you in your maintenance of all these rules and messages. - -Prepare a validation entity in the domain model - -{{< figure src="/attachments/howto8/logic-business-rules/translatable-validation-messages/18581625.png" class="no-border" >}} - -Create an enumeration containing all validation messages - -{{< figure src="/attachments/howto8/logic-business-rules/translatable-validation-messages/18581624.png" class="no-border" >}} - -Reference the model below for messages you should store in the entity: - -{{< figure src="/attachments/howto8/logic-business-rules/translatable-validation-messages/model1.jpg" class="no-border" >}} - -{{< figure src="/attachments/howto8/logic-business-rules/translatable-validation-messages/model2.jpg" class="no-border" >}} - -The GetI18NText microflow validates and acquires the text like this. This is done to prevent any nullpointers in case of incorrect modeling. - -{{< figure src="/attachments/howto8/logic-business-rules/translatable-validation-messages/model3.jpg" class="no-border" >}} - -The text is replaced by this microflow, the input is the translated text, the variable (parameter) text you want to add to the text, and the token number to indicate the position (as in, {1}, {2}, {3}) - -{{< figure src="/attachments/howto8/logic-business-rules/translatable-validation-messages/model4.jpg" class="no-border" >}} diff --git a/content/en/docs/howto8/logic-business-rules/trigger-microflow-from-menu-item.md b/content/en/docs/howto8/logic-business-rules/trigger-microflow-from-menu-item.md deleted file mode 100644 index 51f01ecf54c..00000000000 --- a/content/en/docs/howto8/logic-business-rules/trigger-microflow-from-menu-item.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Trigger a Microflow From a Menu Item" -url: /howto8/logic-business-rules/trigger-microflow-from-menu-item/ -weight: 1 ---- - -## Introduction - -Mendix uses visual models called microflows to define the logic of your application. Microflows are visual ways of expressing what traditionally would be written in code. This how-to explains how you can create a very simple "Hello World" microflow. - -This how-to teaches you how to do the following: - -* Create a menu item -* Create and edit a microflow - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Familiarize yourself with microflow terms. For more information, see [Microflows](/refguide8/microflows/). - -## Creating a Menu Item {#creating-menu-item} - -You will create a menu item that will trigger a microflow and show the **Hello World** message to the end-users. - -Microflows can be triggered in many different ways. For this how-to, you will use a menu item to trigger the new microflow. - -To create a menu item, follow these steps: - -1. Open the **Navigation** editor. -2. In the **Responsive** tab > the **Menu** section, click **New Item**: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/new-menu-item.jpg" class="no-border" >}} - -3. In the **New Menu Item** dialog box, set the **Caption** to *Hello World*: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/caption.png" class="no-border" >}} - -4. For **On click**, select **Call a microflow**: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/call-microflow.png" class="no-border" >}} - -5. In the **Select Microflow** dialog box, select a microflow and then click **New**: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/new-microflow.png" class="no-border" >}} - -6. Enter *HelloWorld* for the **Name** of the new microflow. -7. Save the new menu item by clicking **OK**. - -You have created the menu item that will trigger the **Hello World** microflow. - -## Editing the New Microflow - -The new microflow is now empty and needs to be configured to show the message to the end-users. - -To edit the new microflow, follow these steps: - -1. Open the **Hello World** microflow by right-clicking the new menu item created in the [Creating a Menu Item](#creating-menu-item) section above and selecting **Go to target** from the context menu: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/go-to-target.png" class="no-border" >}} - - You will see an empty microflow like this: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/created-microflow.png" class="no-border" >}} - -2. Open the **Toolbox** and search for the **Show message** activity: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/toolbox.png" class="no-border" >}} - -3. Drag the **Show message** activity from the **Toolbox** into the flow between the start event and end event, which will insert a show message activity: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/show-message-activity.png" class="no-border" >}} - -4. Double-click the message activity to open the **Show Message** properties. -5. Enter *Hello World* for the **Template** value and click **OK**: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/show-message-properties.png" class="no-border" >}} - -6. Click **Run Locally** and then **View** to see the application in your default browser. -7. Click the **Hello World** menu item in the menu bar to see the message: - - {{< figure src="/attachments/howto8/logic-business-rules/trigger-microflow-from-menu-item/hello-world-message.png" class="no-border" >}} - -Congratulations! You have created the menu item that triggers the microflow and shows the **Hello World** message to your end-users! - -## Read More - -* [Define Access Rules Using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Create a Custom Save Button](/howto8/logic-business-rules/create-a-custom-save-button/) -* [Extend Your Application with Custom Java](/howto8/logic-business-rules/extending-your-application-with-custom-java/) -* [Work with Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) -* [Optimize the Retrieve Activities](/howto8/logic-business-rules/optimizing-retrieve-activities/) -* [Configure Error Handling](/howto8/logic-business-rules/set-up-error-handling/) -* [Optimize Microflow Aggregates](/howto8/logic-business-rules/optimizing-microflow-aggregates/) -* [Extract and Use Sub-Microflows](/howto8/logic-business-rules/extract-and-use-sub-microflows/) diff --git a/content/en/docs/howto8/logic-business-rules/working-with-lists-in-a-microflow.md b/content/en/docs/howto8/logic-business-rules/working-with-lists-in-a-microflow.md deleted file mode 100644 index 4d98011c520..00000000000 --- a/content/en/docs/howto8/logic-business-rules/working-with-lists-in-a-microflow.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: "Work with Lists in a Microflow" -url: /howto8/logic-business-rules/working-with-lists-in-a-microflow/ -weight: 6 -description: "Teaches you how to work with a list of objects in a microflow as well retrieve a filtered list of objects from the database." ---- - -## Introduction - -In this how-to, you will learn how to work with a list of objects in a microflow. To manage this list you will first retrieve a filtered list of objects from the database. Mendix utilizes XPath constraints to apply filters. To learn more about XPath, see [XPath Contains](/refguide8/xpath-contains/) in the *Studio Pro Guide*. Secondly, you will iterate over the retrieved list of objects and calculate the total price of all the orders in a [Loop](/refguide8/loop/). You will end this how-to with an alternative to calculating aggregated values over a list of objects. - -## Preparing the Data Structure, GUI and Example Data - -To see the results of this how-to it is necessary that you set up a test project with test data. - -Before you continue, make sure that you know how to create the following: - -* Domain models – if you need more information, see [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/) -* Overview and detail pages – if you need more information, see [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/) -* Menu items – if you need more information, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/) - -1. Create the following domain model: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581378.png" class="no-border" >}} - -2. Create **overview** and **detail** pages to manage objects of type **Customer** and **Order**. -3. Create **menu items** to access the **Order** and the **Customer** overview pages. -4. Add the following customer data to your app: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581374.png" class="no-border" >}} - -5. Add the following order data to your app: - - {{< figure src="/attachments/howto8/logic-business-rules/define-access-rules-using-xpath/18581373.png" class="no-border" >}} - -## Retrieving a Filtered List of Objects from the Database - -In the previous section you have set up a basic data structure and created some sample data. In this section you will retrieve all the 'Processing' orders. To achieve this you will add a microflow button to the 'Orders' overview. In this microflow you will add a 'Retrieve from database' 'Action activity' with an XPath constraint. The XPath constraint will filter the retrieved list to only the 'Invoiced' orders. - -1. Create a new microflow by right-clicking the module and selecting **Add** > **Microflow**. -2. Name the Microflow *IVK_SetOrderToComplete*. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581093.png" class="no-border" >}} - -3. Save the new menu item by clicking **OK**. You should see an empty Microflow like this: - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/8946316.png" class="no-border" >}} - -4. Add an **Action** button to the toolbar of the orders overview: - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581118.png" class="no-border" >}} - -5. Double-click the action button and in its properties, enter *Set Processing to Complete* for the **Caption**. -6. For **On click**, select **Call a microflow**, and then select the **IVK_SetOrderToComplete** microflow. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581054.png" class="no-border" >}} - -7. Open the **IVK_SetOrderToComplete** microflow by right-clicking the new button and selecting **Go to microflow**. -8. Open the **Toolbox**. It should be on the bottom right of . - - {{< figure src="/attachments/howto8/integration/consume-a-simple-web-service/8946802.png" class="no-border" >}} - -9. Drag a **Retrieve** action from the toolbox to the line between the green start and red end event. This inserts a retrieve action activity. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581091.png" class="no-border" >}} - -10. Double-click the retrieve activity to open its properties. -11. Select **From database** for the **Source** option. -12. Set the following properties:
- 1. For **Entity**, select **Order**_
- 1. For **List**, enter **OrderList**
- - {{% alert color="info" %}}With the currents settings your retrieve action gets every order in the database, using the XPath expression in the following steps you will filter the results that come back from the database.{{% /alert %}} - -13. Add the following XPath expression in the XPath constraint field: `[OrderStatus = 'Processing']`. This expression will filter the list to only orders with the status **Processing**. -14. Your properties screen should look like this: - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581088.png" class="no-border" >}} - - {{% alert color="info" %}}With the currents settings your retrieve action gets all the 'Processing' orders in the database. In the next section you will edit this list of orders.{{% /alert %}} - -You should see a microflow like this: - -{{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581087.png" class="no-border" >}} - -## Iterate Over a List of Objects - -In the previous section you retrieved a list of orders with the status 'Processing'. In this section you will iterate over this list and change the status of each object individually to 'Complete'. To do so you will use a 'Loop' to iterate over the 'OrderProcessingList' and use the change object activity to change the status of the order object. - -1. Open the **IVK_SetOrderToComplete** microflow created in the previous section. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581087.png" class="no-border" >}} - -2. Drag a **Loop** action from the **Toolbox** to the line behind the **OrderProcessingList** action activity. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581086.png" class="no-border" >}} - - {{% alert color="info" %}}A loop is used to iterate over a list of objects. For each object the flow inside the loop is executed. For each object the flow inside the loop is executed. The flow starts at the element that has no incoming sequence flows. A loop can contain all elements used in microflows, with the exception of start and stop events. Additionally, a loop (and only a loop) can contain break events and continue events. The iterator, which looks the same as a parameter, represents the current object in the list for each iteration. Beneath it the name of the object is shown in black and the entity type of the object in blue. For more information, see [Loop](/refguide8/loop/).{{% /alert %}} - -3. Double-click the loop activity and select the **OrderList** to iterate over. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581085.png" class="no-border" >}} - -4. Drag a **Change object** activity inside the loop: - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581084.png" class="no-border" >}} - -5. Double-click the **change activity** to open its properties. -6. Select the **IteratorOrder** at the **Object** drop-down menu and click the **New** button. This will open the **Edit Change Item** editor. -7. Set the following properties:
- 1. For **Member** select **OrderStatus**.
- 1. For **Value** enter `MyFirstModule.OrderStatus.Complete`.
- - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581080.png" class="no-border" >}} - -8. Click **OK**. Your properties screen should look like this: - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581078.png" class="no-border" >}} - -9. Set **Commit** and **Refresh in Client** to **Yes** to commit your changes to the database and refresh your list in the client so your changes will be visible, then click **OK**. Your microflow should look like this: - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581076.png" class="no-border" >}} - - Or, to optimize the number of commits, you can perform the commit outside of the loop. This way, there will be a single commit to the database instead of one per order: - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/working-with-lists-optimization.jpg" class="no-border" >}} - -10. **Re-deploy** your application. -11. Click the **Set Processing to Complete** button. The orders with status 'Processing' will now be changed to 'Complete'. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581113.png" class="no-border" >}} - -## Calculating a Total List Value Using a Variable and a Loop - -In the previous section you iterated over a filtered list of objects using a 'Loop'. In this section you will use a loop to calculate the total sum of all your orders. To calculate this sum you will create a variable, which will be changed for every iteration in the loop. - -1. Add a new microflow button to your order data grid with the following details:
- 1. **Caption** of the button: Calculate Total Order Price - 1. **Name** of the microflow: IVK_CalculateTotalPriceOrders -2. In the new microflow, add a **Retrieve** activity for **Orders** and a loop for this list to the microflow. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581106.png" class="no-border" >}} - -3. Drag a **Create variable** before Retrieve0 OrdersList. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581073.png" class="no-border" >}} - -4. Double-click the **Create … variable** to open its properties and configure it as follows:
- 1. For **Data type** select **Decimal**.
- 1. In the value editor, enter `0`.
- 1. For **Variable** enter *CalculatedTotalPrice*.
- - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/variable.png" class="no-border" >}} - -5. Add a **Change variable** activity inside the loop. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581069.png" class="no-border" >}} - -6. Double-click the **Change variable** activity to open its **Properties** and set the following properties:
- 1. For **Variable** select **CalculatedTotalPrice**.
- 1. For **Value** enter `$CalculatedTotalPrice + $IteratorOrder/TotalPrice`.
- - {{% alert color="info" %}}By iterating over the list, the price of every order will be added one by one to the 'CalculatedTotalPrice' variable{{% /alert %}} - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581067.png" class="no-border" >}} - -7. Drag a **Show Message** action from the toolbox to the end of the microflow. -8. Double-click the **message** activity to open its properties and set the following properties:
- 1. For **Template** enter *Total calculated price: {1}*.
- 1. For **Parameters** add `toString($CalculatedTotalPrice)`.
- - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581064.png" class="no-border" >}} - -9. Click **OK**. You should see a Microflow like this: - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581063.png" class="no-border" >}} - -10. **Re-deploy** your application. -11. Click the **Calculate total order price** button and you will see the price of all the orders added up. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581103.png" class="no-border" >}} - -## Calculate a Total List Value Using an Aggregate Function - -In the previous section you iterated over a list to add the value of single object to a total price variable. In this section you will use the 'aggregate list' function to calculate the total price instead of using a loop. The aggregate list can be used to calculate aggregated values such as the maximum, minimum, sum, average and total amount of objects over a list of objects. - -1. Open the **IVK_CalculateTotalPriceOrders** microflow and remove the loop and the **CalculatedTotalPrice** variable. -2. Add an **Aggregate list** activity after the **OrderList**. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581061.png" class="no-border" >}} - -3. Double-click the aggregate list activity to open its properties and set the following properties:
- 1. For **List** select **OrderList**.
- 1. For **Function** select **Sum** (see the [documentation](/refguide8/aggregate-list/) for the description of the other functions).
- 1. For **Attribute** select **TotalPrice**.
- 1. For **Variable** enter a descriptive name like *SumTotalPrice*.
- - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581059.png" class="no-border" >}} - -4. Click **OK**. -5. Double-click the message activity and replace the `$CalculatedTotalPrice` variable in the **Parameters** expression with the `$SumTotalPrice` variable. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581055.png" class="no-border" >}} - -6. Click **OK**. Your microflow should look like this: - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581058.png" class="no-border" >}} - -7. Re-deploy your application. - -8. Click the **Calculate total order price** button and you will see the same price of all the orders added up. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581103.png" class="no-border" >}} - -## Filter List of Orders on the City of the Associated Customers - -In the previous sections you filtered the list of orders from database on attributes of the order entity itself. In this section you will constrain on attributes over the associated customer object. In the example of this section you will set the order status of all customers in Rotterdam to the status 'Complete'. - -1. Open the microflow **IVK_SetOrderToComplete**. -2. Open the **OrderList** retrieve activity. -3. Add an **XPath constraint** over the association to customer, constraining on the city (Rotterdam) of this customer. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581111.png" class="no-border" >}} - -4. Click **OK** and **re-deploy** your application. -5. Open the application in the browser. -6. Click the **Set Processing to Complete** button. All the orders from customers in Rotterdam are set to **Complete**. - - {{< figure src="/attachments/howto8/logic-business-rules/working-with-lists-in-a-microflow/18581110.png" class="no-border" >}} - -## Read More - -* [Defining access rules using XPath](/howto8/logic-business-rules/define-access-rules-using-xpath/) -* [Extending Your Application with Custom Java](/howto8/logic-business-rules/extending-your-application-with-custom-java/) -* [Working With Lists in a Microflow](/howto8/logic-business-rules/working-with-lists-in-a-microflow/) -* [Creating a Custom Save Button](/howto8/logic-business-rules/create-a-custom-save-button/) -* [Optimizing Retrieve Activities](/howto8/logic-business-rules/optimizing-retrieve-activities/) diff --git a/content/en/docs/howto8/mobile/_MAPPING.txt b/content/en/docs/howto8/mobile/_MAPPING.txt deleted file mode 100644 index 1eaedad50e8..00000000000 --- a/content/en/docs/howto8/mobile/_MAPPING.txt +++ /dev/null @@ -1 +0,0 @@ -There are document files in this folder that are mapped to the product. Refer to Mapping to Products for the names of these files and how to proceed. \ No newline at end of file diff --git a/content/en/docs/howto8/mobile/_index.md b/content/en/docs/howto8/mobile/_index.md deleted file mode 100644 index 68213528aaf..00000000000 --- a/content/en/docs/howto8/mobile/_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Mobile" -url: /howto8/mobile/ -weight: 40 -no_list: false -description_list: true -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -The Mendix vision for mobile app development is that enterprises can greatly benefit from a single platform that supports the various styles of mobile app development (web, native, and hybrid) for multiple devices and provides common mobile back-end services. - -The rapid evolution of standards like HTML and the wide adoption of frameworks to bridge native device functions provide an ever-richer user experience for cross-platform apps. From a logic perspective, JavaScript is powerful as a platform-independent, back-end technology even in native clients. There is a shift occurring from native languages towards JavaScript, where JavaScript is being embedded more and more in native programming languages to raise the level of code reusability across platforms. - -## Documents in This Category diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/_index.md b/content/en/docs/howto8/mobile/hybrid-mobile/_index.md deleted file mode 100644 index 07ac66cd558..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Hybrid Mobile" -url: /howto8/mobile/hybrid-mobile/ -weight: 2 -no_list: false -description_list: true ---- - -## Introduction - -A Mendix hybrid app is a web application which runs inside a container that can be installed as a native app on your device. Hybrid apps can be deployed using the Mendix Platform, their containers enable native capabilities like camera and GPS app functions, and they can be published to the Apple App Store and Google Play. - -{{% alert color="warning" %}} -Building hybrid apps in the cloud uses the PhoneGap Build service from Adobe. Unfortunately, Adobe no longer maintains this service. PhoneGap does not allow you to create iOS 13 builds, but the Apple App Store requires builds be iOS 13 or higher. As a result, as of April 30 2020, hybrid iOS apps built using the PhoneGap Build service are not being accepted on Apple's App Store. -{{% /alert %}} - -## Documents in This Section diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/_index.md b/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/_index.md deleted file mode 100644 index 7ebbfadb512..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/_index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Build Hybrid Apps " -url: /howto8/mobile/build-hybrid-apps/ -weight: 2 -no_list: false -description_list: true ---- - -## Introduction - -{{% alert color="warning" %}} -Building hybrid apps in the cloud uses the PhoneGap Build service from Adobe. Unfortunately, Adobe no longer maintains this service. PhoneGap does not allow you to create iOS 13 builds, but the Apple App Store requires builds be iOS 13 or higher. As a result, as of April 30 2020, hybrid iOS apps built using the PhoneGap Build service are not being accepted on Apple's App Store. -{{% /alert %}} - -Hybrid apps are built by using PhoneGap to wrap a web app in a native wrapper. However, because PhoneGap has ceased supporting iOS builds 13 and higher Mendix recommends building native iOS apps instead. For more information, see [How to Build Native Apps](/howto8/mobile/build-native-apps/). - -The documents in this section focus on publishing hybrid apps in the Apple and Google app stores. For more details on platform-specific installation packages see [Mobile App](/developerportal/deploy/mobileapp/). - -## Documents in This Section diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally.md b/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally.md deleted file mode 100644 index a06f8c50e33..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: "Build a Mendix Hybrid App Locally" -url: /howto8/mobile/build-hybrid-locally/ -weight: 9 ---- - -{{% alert color="warning" %}} -Hybrid mobile packages require Node.js v18. Versions above those fail to install and compile dependencies. We are working to update hybrid mobile packages to support later versions. - -To support multiple node or npm versions on Windows, use the [Node Version Switcher (NVM)](https://github.com/coreybutler/nvm-windows) utility. -{{% /alert %}} - -## Introduction - -This document describes how to build your hybrid apps locally. - -## Building Your iOS App Locally {#building-ios-locally} - -**Prerequisites:** - -* A Mac OSX machine -* Install [Node.js 18](https://nodejs.org/download/release/latest-v18.x/) using the all-in-one installation option -* Download your [local build package](/developerportal/deploy/mobileapp/#doing-it-yourself) from Cloud Portal and unzip it in a known location -* Register for an [Apple Developer Account](https://developer.apple.com/register/index.action) -* Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) and its command-line tools - -### Prepare Your App for Building - -To prepare your app for building, follow these instructions: - -1. Open a terminal window and change directory into the unzipped package folder, for example **cd /Downloads/localbuild** if it is in your Downloads folder. -1. Run `npm i && npm run package && npm run platform:ios`. This combination of commands does the following: - * Installs all required dependencies. - * Packages the Cordova app for deployment. - * Adds the iOS platform to Cordova. - -#### Customizing a DTAP Endpoint - -Optionally, you can set various environments in the **config/environments.json** file. This can help if you are trying to make your build from your own specific test or acceptance environment. - -To target a specific DTAP endpoint with your app, you can specify it as a parameter to `npm run package` or `npm run package:x86`. Such code could, for example, look like this: - -```shell -npm run package -- --env target=test # target the test endpoint for ARM architecture -``` - -Possible targets are `development`, `test`, `acceptance`, `production` (default), and `sandbox`. For convenience you can shorten these to their first letters. Note that if no `--env target` parameter is provided, the hybrid app endpoint will default to the production environment. - -### Building Your Prepared Project - -There are two possible ways to build your apps: the Cordova CLI or Xcode. The Cordova CLI is faster and allows Cordova to fully control the your app's configuration. Xcode is more involved, but Xcode's UI makes it easier to detect problems in the app. You can use whichever works best for your case. - -#### Building iOS Using the Cordova CLI - -**Prerequisites:** - -* Your Apple Developer team's id, which can be found [here](https://developer.apple.com/account/#/membership/) - -This process is shorter than using Xcode but might require more work to understand why a build fails. To build using the Cordova CLI, do the following: - -1. Run `npm run build -- ios --release --device --codeSignIdentity="iPhone Developer" --developmentTeam=""`. This combination of commands does the following: - * Starts a release build that will create binaries for a physical device - * Uses the code sign identity "iPhone Developer" for signing - * Looks up the provisioning files and certificates using the provided Apple Developer's team id - * Optionally, if you wish to build for an emulator and do a debug build use the following command instead: `npm run build -- ios --debug --emulator`. -1. When the build succeeds the generated *IPA* file can be found in */build/platforms/ios/build*. That folder should have the following file structure(if you did a build for an emulator an *.app* file will be available): - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/folder-final.png" alt="Signing screen correctly configured" class="no-border" >}} - -1. The IPA generated can be now uploaded to Testflight for further testing. If you wish to do so, continue with the [Upload tools](https://help.apple.com/app-store-connect/#/dev82a6a9d79) section in the Apple App Store documentation. - -#### Building iOS using Xcode - -Using Xcode can be easier than the Cordova CLI due to Xcode's friendly visual interface. To build your app using Xcode do the following: - -1. Under **/build/platforms/ios/** open the `.xcworkspace` file by double-clicking it. Xcode should open with the app loaded: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/xc-workspace.png" alt="Opening XCWorkspace" width="400" class="no-border" >}} - -1. Select the root element from the tree view in the left-side panel: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/root-element.png" alt="Selecting the root element" width="400" class="no-border" >}} - -1. The screen should change to the following view. If it does not, select the item under **Targets** on the left panel not the item under **App** and select the tab **Signing & Certificates**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/setup-signing-wrong.png" alt="Signing screen with errors" width="400" class="no-border" >}} - -1. Both **Debug** and **Release** might have been configured for **Automatically manage signing**. Clear both checkboxes to switch to manual signing. The screen should change to the following: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/setup-signing-correct.png" alt="Signing screen correctly configured" width="400" class="no-border" >}} - -1. Enable **Automatically manage signing** again. -1. Select a **Team** using the drop-down menu. If you have not yet signed in with your credentials, Xcode will prompt you to do so. -1. When configured correctly all errors should be gone. -1. Make sure you select the target to be your app's build target and designate **Generic iOS Device** as a device: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/target-device.png" alt="Signing screen correctly configured" width="400" class="no-border" >}} - -1. Select **Product** and then **Archive** from the menu bar: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/archiving.png" alt="Archiving" width="400" class="no-border" >}} - -1. After the process finishes successfully the **Organizer** view will come up. Your app should be selected and your latest **Archive** visible. You can always open the organizer yourself through Xcode's **Window** menu: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/organizer.png" alt="Organizer" width="400" class="no-border" >}} - -1. You can now use the **Distribute App** button to distribute your app to the appstore or archive it for local distribution: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/distribute-options.png" alt="Distribute Options" width="400" class="no-border" >}} - -## Building Your Android App Locally {#building-android-locally} - -**Prerequisites:** - -* Install [AndroidStudio](https://developer.android.com/studio) -* Install [Node.js 18](https://nodejs.org/download/release/latest-v18.x/) using the all-in-one installation option -* Install JDK 1.8 -* Create a keystore using [Generating a Keystore](/refguide8/managing-app-signing-keys/#generating-a-keystore) -* Download the [local build package](/howto8/mobile/customizing-phonegap-build-packages/#download-local-package) from Cloud Portal and unzip it in a known location - -### Prepare Your App for Building - -To prepare your app for building, follow these instructions: - -1. Open a terminal window and change directory into the unzipped package folder, for example **cd /Downloads/localbuild** if it is in your **Downloads** folder. -1. Run `npm i && npm run package && npm run platform:android`. This combination of commands does the following: - * Installs all required dependencies - * Packages the Cordova app for deployment - * Adds the Android platform to Cordova - -### Set Up Environmental Variables - -To be able to run the commands to build locally, you will need to set up some required environmental variables for your system. These can be set to temporary for the current command line session or globally for your system. The variables are the following: - -* **ANDROID_SDK_ROOT**, pointing to the installation folder of the Android *SDK* -* **JAVA_HOME**, pointing to the *JDK* 1.8 root directory -* **GRADLE_HOME**, pointing to a valid Gradle distribution directory - -During this guide you will set the commands to temporary for each of the commands. - -### Building Your Prepared Project - -There are two possible ways to build your apps: the Cordova CLI or Android Studio. The Cordova CLI is faster and allows Cordova to fully control the your app's configuration. Android Studio is more involved, but Android Studio's UI makes it easier to detect problems in the app. You can use whichever works best for your case. - -#### Building Android Using the Cordova CLI - -The command to build your app locally for release is `npm run build -- android --release`. - -1. Run the following command: - - 1. **On Mac OSX, as a single command run:**
- - ```shell - PATH="\$PATH:/Users//.gradle/wrapper/dists/gradle-5.1.1-all/97z1ksx6lirer3kbvdnh7jtjg/gradle-5.1.1/bin" JAVA_HOME=`/usr/libexec/java_home -v 1.8\` npm run build -- android --release -- --keystore= --storePassword= --alias= --password= - ``` - - 1. **On Windows, in a command line as separate commands run:**
- - ```shell - set PATH=%PATH%;C:\path-to-gradle-distribution - - set JAVA_HOME=C:\path-to-jdk-1.8-directory - - npm run build -- android --release -- --keystore= --storePassword= --alias= --password= - ``` - - This command adds the gradle binary to the path, switches the JAVA *JDK* to be 1.8, and runs the build release command to generate a signed *APK*. - -1. When the build succeeds the generated *APK* file can be found in **/build/platform/android/app/release**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/folder-final-android.png" alt="Final folder structure" width="400" class="no-border" >}} - -#### Building Android Using Android Studio - -Using Android Studio can be easier than the Cordova CLI due to Android Studio's friendly visual interface. To build your app using Android Studio do the following: - -1. Start Android Studio: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/android-studio-welcome.png" alt="Android Studio Welcome Screen" width="400" class="no-border" >}} - -1. Open an existing Android Studio project and select your app's Android folder, for example **/Downloads/localbuild/build/platform/android**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/android-studio-open-folder.png" alt="Android Studio Open Folder" width="400" class="no-border" >}} - -1. Wait for Android Studio to finish syncing your app. -1. Click the **Build** > **Generate Signed Bundle / APK**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/android-studio-build-menu.png" alt="Android Studio Build Menu" width="400" class="no-border" >}} - -1. Select the *APK* checkbox: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/android-studio-sign-wizard-1.png" alt="Android Studio Sign Wizard Step 1" width="400" class="no-border" >}} - -1. Select your Android keystore and complete the form with the correct keystore password, alias, and password: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/android-studio-sign-wizard-2.png" alt="Android Studio Sign Wizard Step 2" width="400" class="no-border" >}} - -1. Select the destination folder for the *APK*, **Build Variant** release, and **V1 and V2 Signature** versions: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/build-hybrid-locally/android-studio-sign-wizard-3.png" alt="Android Studio Sign Wizard Step 3" width="400" class="no-border" >}} - -1. Click **Finish**. - -You *APK* should now be generated and signed using Android Studio. The resulting *APK* can be found in the output folder selected and can be uploaded via the Google Play Console for further processing. - -## Read More - -* [Deploying Apps](/deployment/) -* [Offline Reference Guide](/refguide8/offline-first/) -* [How to Publish a Mendix Hybrid Mobile App in App Stores](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/) -* [Apache Cordova Reference Config.xml](https://cordova.apache.org/docs/en/latest/config_ref/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/customizing-phonegap-build-packages.md b/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/customizing-phonegap-build-packages.md deleted file mode 100644 index 2b65f443bb8..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/customizing-phonegap-build-packages.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Customizing Local Build Packages" -url: /howto8/mobile/customizing-phonegap-build-packages/ -weight: 30 -aliases: - - /refguide8/customizing-phonegap-build-packages.html - - /refguide8/customizing-phonegap-build-packages -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -{{% alert color="warning" %}} -Building hybrid apps in the cloud uses the PhoneGap Build service from Adobe. Because Adobe no longer maintains this service, building hybrid apps in the cloud and publishing them to app stores is no longer possible. - -To build a hybrid app and publish it, see [How to Build a Mendix Hybrid App Locally](/howto8/mobile/build-hybrid-locally/) for information on local building. - -To publish your app in an app store, Mendix recommends building native iOS apps instead. For more information, see [How to Build Native Apps](/howto8/mobile/build-native-apps/). -{{% /alert %}} - -## Downloading the Local Build Package {#download-local-package} - -To download the local build package, publish your app for mobile app stores through the Mendix Portal. At the **Build Mobile App Store Packages** page, under **How should the device packages be built?**, choose the non-default option **I will manage the build process manually myself**. Click the green button to download the local build package. - -## Customizing the Local Build Package - -You can customize the local build package to suit your use case. Once you have customized your app according to your needs, you can build your app locally using the Cordova CLI or Xcode by following [How to Build a Mendix Hybrid App Locally](/howto8/mobile/build-hybrid-locally/). diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores.md b/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores.md deleted file mode 100644 index da3d72b4ba4..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: "Publish a Mendix Hybrid Mobile App in Mobile App Stores" -linktitle: "Publish Hybrid Mobile App in App Stores" -url: /howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/ -weight: 20 -aliases: - - /refguide8/publish-packages-to-mobile-stores.html - - /refguide8/publish-packages-to-mobile-stores ---- -## Introduction - -{{% alert color="warning" %}} -Building hybrid apps in the cloud uses the PhoneGap Build service from Adobe. Because Adobe no longer maintains this service, building hybrid apps in the cloud and publishing them to app stores is no longer possible. - -To build a hybrid app and publish it, see [How to Build a Mendix Hybrid App Locally](/howto8/mobile/build-hybrid-locally/) for information on local building. - -To publish your app in an app store, Mendix recommends building native iOS apps instead. For more information, see [How to Build Native Apps](/howto8/mobile/build-native-apps/). -{{% /alert %}} - -Once you have finished developing a Mendix hybrid mobile application, you will want to make it available as an app for mobile platforms such as Apple iOS and Google Android. We make it possible to produce platform-specific installation packages. For more details on deploying platform-specific installation packages, see [Mobile App](/developerportal/deploy/mobileapp/). - -This how-to teaches you how to do the following: - -* Set up app signing keys -* Complete the app-packaging process -* Install an iOS or Android app on a mobile test device -* Upload your app to the Apple App Store or Google Play Store - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Have a Mendix app with mobile support running in Mendix Cloud, either as a Free App or on a licensed cloud node -* Have an account for Adobe PhoneGap Build (you can create one for free [here](https://helpx.adobe.com/experience-manager/kb/adobe-phonegap-end-of-service.html)) - -To publish your app in the Apple App Store, do the following: - -* Register for an [Apple Developer Account](https://developer.apple.com/register/index.action) -* Have an iOS device (iPhone or iPad) for testing the iOS package that will be produced -* Have an iOS deployment certificate and a provisioning file for which your mobile test device is activated -* Have Apple iTunes installed on your computer for deploying the iOS package that will be produced on your mobile test device - -To publish your app in the Google Play store, do the following: - -* Have an Android device for testing the APK package that will be produced - -## Starting the Packaging Process{#starting-the-packaging-process} - -To start the packaging process, follow these steps: - -1. Open [Apps](https://sprintr.home.mendix.com/). -2. Go to the app of the Mendix app that you want to publish. -3. Go to the **Deploy > Mobile app** entry in the side menu of the app. -4. You will be shown the **Publish App for Mobile App Stores** page, where you need to set up some options for your hybrid mobile app. - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/mobile-app-page.png" alt="mobile app page" class="no-border" >}} - -5. On the **App Info** tab set up the following settings for your app:
- 1. Fill in the name that your app will have in the app stores and on the device. The **Name** should correspond to the name set up in your Apple certificate.
- 1. Set the unique **App Identifier** for your app. The **App Identifier** should correspond to the ones set up in your Apple certificate.
- 1. If your app does not employ push notifications, disable the **Push Notifications** permission by clearing its checkbox. - -6. Select the platforms that you want to support. -7. Optionally, upload custom-branded app icons and splash screens under the tabs for the different platforms. You can find those tabs next to the **App Info** tab. - - {{% alert color="info" %}}If you do not upload any images, the default Mendix-branded images that are shown will continue to be used.{{% /alert %}} - -8. Click the green **Publish for Mobile App Stores** button. You will be presented with the **Build Mobile App Store Packages** page: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/build-mobile-packages.png" alt="build mobile app store packages" class="no-border" >}} - -9. Select where you want to publish: - - * For Free Apps, the only option is **Sandbox** - * For apps running on a licensed cloud node, you can choose from **Test**, **Acceptance**, and **Production** (depending on what is available on your cloud node) - * For apps using [Flexible Environments](/developerportal/deploy/mendix-cloud-deploy/#flexible-environments) you will be able to select the environment from a drop-down list of environments. - -10. Leave the default choice of how to build the package **Build Mobile App Store packages for me by sending the build configuration to Adobe PhoneGap Build** selected. - You can use the alternate option to manually download a PhoneGap Build package, which you can then inspect, modify, and upload manually to Adobe PhoneGap Build (for more information, see [Customizing Local Build Packages](/howto8/mobile/customizing-phonegap-build-packages/)). This is unnecessary in most scenarios. - -You can freely customize the generated package to enable, for example, additional PhoneGap/Cordova plugins or add additional resources to your app. For more information, see [Customizing Local Build Packages](/howto8/mobile/customizing-phonegap-build-packages/). - -For detailed instructions, see the [hybrid-app-template GitHub repository](https://github.com/mendix/hybrid-app-template). - -For more context on building hybrid apps in the cloud, as well as other options for iOS apps, see [How to Build Hybrid Apps](/howto8/mobile/build-hybrid-apps/). - -## Setting Up App Signing Keys - -The **PhoneGap Build: Signing Key Required** page asks you to go to the PhoneGap Build website and set up the app signing keys. To set up the app signing keys, follow these steps: - -1. Click **Log in to PhoneGap Build**. A new page will be opened on PhoneGap's [apps tab](https://helpx.adobe.com/experience-manager/kb/adobe-phonegap-end-of-service.html). Here you can see the PhoneGap Build app that was created by the Mendix Portal for your app. The app is named as you defined it in the **App Info** in the [Starting the Packaging Process](#starting-the-packaging-process) section above. -2. Set up the app signing key for your app in your account. -3. Click the avatar icon on the upper-right side of the page, and then click **Edit account** to configure how your app will build: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/edit-account.png" alt="edit account" class="no-border" >}} - -## Preparing and Publishing Your App - -For publishing to a specific platform, see the subsequent sections of this how-to: - -* [Preparing and Publishing for iOS](#publishing-for-ios) -* [Preparing and Publishing for Android](#publishing-for-android) - -## Preparing and Publishing for iOS{#publishing-for-ios} - -Apple provides general information on [publishing an iOS app in the Apple App Store](https://developer.apple.com/programs/ios/distribute.html). Before uploading your app, make sure to check the [App Review Guidelines](https://developer.apple.com/app-store/review/) to make sure your app will be accepted. An Apple Developer Account is required. If you do not have one, [register as an Apple Developer](https://developer.apple.com/register/index.action). - -1. In PhoneGap Build, click your avatar icon, then click **Edit account**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/edit-account.png" alt="edit account" class="no-border" >}} - -2. Click the **Signing Keys** tab, and under **iOS**, click **add a key**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/add-a-key.png" alt="add a key" class="no-border" >}} - -3. A dialog box will prompt you to upload a certificate file and a provisioning profile file. You can get those files from Apple. The certificate is the *.p12* file, and the provisioning profile is the *.mobileprovision* file. For more information, see the [Managing App Signing Keys Reference Guide](/refguide8/managing-app-signing-keys/). -4. Give the key a title that you can easily recognize, and upload the files. -5. Click the lock with the yellow background on the same row as your key and enter a passphrase. The key can now be used for builds for the period of an hour. After an hour, the passphrase needs to be entered again: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/yellow-lock.png" alt="yellow lock" class="no-border" >}} - -6. Click **Apps** at the top of the page to go to an overview showing your apps. Click your app's name or logo to see the app's details. -7. Select the correct key for your app. Next to the text **iOS**, there is a drop-down menu with the **No key selected** option. From the drop-down menu, select the newly uploaded key which should be listed under **unlocked**. - -Your PhoneGap Build account is now ready and you can continue the packaging process. - -### Completing the Packaging Process - -To complete the building process in the Mendix Portal, follow these steps: - -1. Close your **Adobe PhoneGap Build** page and navigate back to your original **Mendix Developer Platform** page. -2. Click **Restart build job** to restart the packaging process.
- * You will see a **Building Mobile App Store Packages** page, which will display a **Building** status while PhoneGap Build is building your app. Once your app is ready, the page's status will show **Done**. -3. Click the **Download iOS package** button, and save the package (the *.ipa* file) to your computer. - -### Installing the iOS App on Your Mobile Test Device - -You can now deploy your app to your mobile test device. You must use a Mac mobile test device for this step. An easy way to do this is with Apple iTunes. - -To install the iOS app on your mobile test device, follow these steps: - -1. Connect your Apple mobile test device to your computer. Both will show dialog boxes which ask you to confirm that you trust the devices. Click **Continue** on your device, and **Trust This Computer?** on your mobile device to proceed. - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/appletrust.png" alt="trust dialog" class="no-border" >}} - -2. Open iTunes and connect your iOS mobile test device to your computer. -3. Select the *.ipa* package file that you downloaded earlier, and drag it into your mobile test device's **Devices** section on iTunes' left menu. Drop the *.ipa* file there to install it on your mobile test device. -4. If there is an existing version, iTunes will ask if you want to replace that existing version of the app. If there is one, do so. -5. Your app will show up in the list of apps. Click the **Install** button next to your app. -6. Click **Apply** at the bottom of the screen to execute the actual installation. - -The app will now be visible on your device. Open it and sign in to the app with a regular user account. You can set one up in the Mendix app in your desktop browser if you have not done so yet. - -### Uploading the iOS App to the App Store - -1. Follow Apple's [Add an app to your account](https://help.apple.com/app-store-connect/#/dev2cd126805) tutorial to add an app entry to your account. -2. After adding a new app to your account, follow Apple's [View and edit app information](https://help.apple.com/app-store-connect/#/dev97865727c) tutorial to describe your new app entry. Consult the other pages under the left menu's **Enter app information** category should they apply to your app: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/ios-enter-app-info.png" alt="enter app information" class="no-border" >}} - -3. Follow Apple's [Uploading builds overview](https://help.apple.com/app-store-connect/#/dev82a6a9d79) to upload a build of your app to App Store Connect. -4. Use Apple's [Choose the build before you submit to review](https://help.apple.com/app-store-connect/#/dev7cbda8c55) to select the build which you will submit to App Review. - -### Testing - -Test your app per the [TestFlight beta testing overview](https://help.apple.com/app-store-connect/#/devdc42b26b8) documentation to ensure your app works the way it should. TestFlight beta testing allows you to control which users can test your app, and then collect feedback from them. - -### Publishing - -Publish your app by following Apple's [Overview of publishing an app](https://help.apple.com/app-store-connect/#/dev34e9bbb5a) and the subsequent documents in the left menu's **Publish on the App Store** category: - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/build-hybrid-apps/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/ios-publishing-an-app.png" alt="publish on the app store" class="no-border" >}} - -## Preparing and Publishing for Android{#publishing-for-android} - -If you plan on publishing an Android app, read Google's overview of [the Android app publishing process](https://developer.android.com/tools/publishing/publishing_overview.html). Before submitting your app to an app store, [review the launch checklist](https://developer.android.com/distribute/tools/launch-checklist.html). - -If you are just testing your app, you do not need to create a keystore. You can continue with the next section [Enabling your Mobile Test Device for an Android Binary (APK)](#download-apk) below. - -If you want to publish your Android app, you must first complete the [Android](/refguide8/managing-app-signing-keys/#android) section of *Managing App Signing Keys*. This section explains how to generate a keystore and upload that keystore to PhoneGap Build. - -### Enabling your Mobile Test Device for an Android Binary (APK){#download-apk} - -After you create your build you can download the resulting APK using a download link or a QR code. To enable APK installations: - -1. Open your device's **Settings**. -2. Open **Apps and notifications,** or on a Samsung Galaxy **Biometrics and Security**. -3. Tap **Install unknown apps** (on certain devices you may have to tap **Special access** first). -4. Select the browser you wish to use when downloading APK files. -5. Enable the **Allow from this source** switch or checkbox. -6. Tap the **OK** button if prompted. - -### Installing Your APK - -To install your APK, you can either download the APK file using your mobile device's web browser, or transfer the APK file to your Android device using a USB cord. - -#### Option 1: Using Your Device's Browser - -Go to the PhoneGap install page using your mobile test device's browser to continue installation, then follow these instructions: - -1. Tap the Android link to get the APK. -2. Navigate to your browser’s **Downloads** folder, open it, and tap your downloaded app. -3. On the next screen, tap the **Install** button to install it. - -To install an APK file directly from your Android's **Download** folder: - -1. Tap the **Back** button to see your list of apps. -2. Tap the file manager app you will use to install the APK file. -3. Tap the **Allow** switch or checkbox. -4. Tap the **OK** button if prompted. - -#### Option 2: Using a USB Cord - -The second way to install your app is by connecting your device to a machine via USB. To Install an APK from your device's file manager app this way: - -1. Follow the instructions on Google’s [Transfer files between your computer & Android device](https://support.google.com/android/answer/9064445?hl=en) to get the APK onto your device. Remember which folder you transfer the APK into. -2. Open your phone’s file manager, navigate to the folder you transferred your APK to, then tap the APK file to open it. -3. Tap the **Install** button. -4. Tap the **Done** button when prompted. You should now be able to access your installed app via your **App Drawer**, as well as by tapping the **Open** button after the installation completes. - -### Testing Your App - -Using your new app, ensure all pages, buttons, and functionality work the way you intended them to. You can test your app using automatic software, such as [BrowserStack](https://www.browserstack.com/), or test your app manually. - -### Upload to Play Console - -Upload your Mendix app to the Play Console by following the instructions on Google's [Upload your app to the Play Console](https://developer.android.com/studio/publish/upload-bundle) site. Before uploading to the Play Console you will have to complete the [signup steps](https://play.google.com/apps/publish/signup/) of signing-in with your Google account, accepting the developer agreement, paying the registration fee, and completing your account details. Once you have satisfied those requirements, you can [upload your app](https://support.google.com/googleplay/android-developer/answer/7159011) to the Play Console. - -### Create, Review, and Roll Out a Release - -Follow the steps in Google's [Prepare and roll out a release](https://support.google.com/googleplay/android-developer/answer/7159011) to create, prepare, review, and roll out your app release. You can also consult Google's [Run apps on a hardware device](https://developer.android.com/studio/run/device) for detailed instructions on testing your app using a physical Android device instead of an emulator. - -## Read More - -* [Deploy your First Hybrid Mobile App](/howto8/mobile/deploy-your-first-hybrid-mobile-app/) -* [Debug a Hybrid Mobile App](/howto8/mobile/debug-a-mobile-app/) -* [Include Push Notifications](/howto8/mobile/push-notifications/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/debug-a-mobile-app.md b/content/en/docs/howto8/mobile/hybrid-mobile/debug-a-mobile-app.md deleted file mode 100644 index 22fb55d10aa..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/debug-a-mobile-app.md +++ /dev/null @@ -1,413 +0,0 @@ ---- -title: "Debug a Hybrid Mobile App" -url: /howto8/mobile/debug-a-mobile-app/ -weight: 40 -description: "How to set up a mobile app to run from your local machine and debug using Mendix's tools" ---- - -## Introduction - -Mendix has great tools for debugging web applications, including the offline and online debugger, but many people do not know that these tools can also be used to debug and test mobile applications. - -{{% alert color="warning" %}} -Building hybrid apps in the cloud uses the PhoneGap Build service from Adobe. Because Adobe no longer maintains this service, building hybrid apps in the cloud and publishing them to app stores is no longer possible. - -To build a hybrid app and publish it, see [How to Build a Mendix Hybrid App Locally](/howto8/mobile/build-hybrid-locally/) for information on local building. - -To publish your app in an app store, Mendix recommends building native iOS apps instead. For more information, see [How to Build Native Apps](/howto8/mobile/build-native-apps/). -{{% /alert %}} - -This how-to teaches you how to do the following: - -* Build and run a hybrid Mendix mobile app that connects to your local development machine -* Debug the mobile app using Mendix debugging tools, Chrome DevTools and the Safari Web Inspector - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Ensure that you have a network utilities tool on your mobile device (I use [PingTools](https://play.google.com/store/apps/details?id=ua.com.streamsoft.pingtools) on Android, and [NetworkPing Lite](https://itunes.apple.com/us/app/network-ping-lite/id289967115?mt=8) on iOS) in order to ensure connectivity between your device and your computer -* Acquire a paid Apple Developer Membership—see [Apple Membership](https://developer.apple.com/support/membership/) for more details - -## Android and macOS {#AndroidMac} - -This is perhaps the easiest combination of a mobile target platform and a development environment to configure. - -### macOS Configuration - -Since Mendix Studio Pro only runs on Windows, you need to make sure that your virtual (Windows) machine can be accessed by the outside world. To do that, the network setting must be shared between the virtual machine and your Mac, and the appropriate ports forwarded. Follow these steps to configure your development environment with Parallels: - -1. Open the Parallels **Configure** dialog: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/mac-1.png" alt="mac-1" class="no-border" >}} - -2. Go to the **Hardware** tab: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/mac-1b.png" alt="mac-1b" class="no-border" >}} - -3. Make sure that the **Source** for **Network 1** is set to **Shared Network**. Click the lock to make changes. - -4. Open the Parallels **Preferences** dialog window: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/mac-3-1163108.png" alt="mac-3" class="no-border" >}} - -5. Go to the **Network** tab. -6. Make sure that the **Connect Mac to this network** option is checked: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/mac-3b-1163119.png" alt="mac-3b" class="no-border" >}} - -7. Click **+** button at the bottom of the page to add a new Port Forwarding Rule with the following settings: - * Protocol: *TCP* - * Source Port: *8080* - * Forward to: *Win10* - * Destination Port: *8080* - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/mac-4-1163092.png" alt="mac-4" class="no-border" >}} - -8. Add another rule, this time forwarding port *8090*. -9. Start the Mendix app locally, and verify that your mobile device can ping your development machine. -10. Find the local IP of your development machine on your network by going to **settings > network**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/mac-6-1163082.png" alt="mac-6" class="no-border" >}} - -11. Verify that your device can ping this address: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/win-2.png" alt="win-2" class="no-border" >}} - -### PhoneGap Configuration - -You can use PhoneGap Build to build the native mobile application and tell it to initialize based on this new URL, rather than the default. Follow these steps to download a package, update it, and upload it to PhoneGap Build: - -1. Go to home.mendix.com and open your app. -1. Go to the **Mobile App** page. -1. Configure this page as you normally would and then click **Publish for Mobile App Stores**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-1.png" alt="phonegap-1" class="no-border" >}} - -1. Select **Do it Yourself** and then click **Download Customizable Package**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-3.png" alt="phonegap-3" class="no-border" >}} - -1. Extract the downloaded package and then navigate to the `/dist/` folder: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-4.png" alt="phonegap-4" class="no-border" >}} - -1. Extract the contents of the **phonegap.zip** file and open the *www/settings.json* file: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-5.png" alt="phonegap-5" class="no-border" >}} - -1. Change the `url` property to the IP address of your local machine, with the port 8080. - - ```json - { - "url": "http://10.140.149.92:8080", - "hybridTabletProfile": "", - "hybridPhoneProfile": "", - "enableOffline": false, - "requirePin": false - } - ``` - -1. Save your changes and zip the unzipped **phonegap.zip** files you just extracted: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-7.png" alt="phonegap-7" class="no-border" >}} - -1. Upload the new zip file to a new app on PhoneGap Build: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-8.png" alt="phonegap-8" class="no-border" >}} - -1. When your app has finished building in the cloud, download it and run it to connect to your Mendix app running on your local machine. - -### Android Configuration - -1. Enable the developer options on your Android device. See [Configure On-Device Developer Options](https://developer.android.com/studio/debug/dev-options) for more information. -2. Connect your device to your development machine and when the popup window appears on your mobile device to allow USB debugging, choose **Allow**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/android-2.png" alt="android-2" class="no-border" >}} - -3. Open the **Chrome** browser. -4. Open the **Chrome Developer Tools (F12)**. -5. Click **Customize and control DevTools** ({{% icon name="three-dots-menu-vertical" %}}) and select **More tools** > **Remote devices**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/android-3.png" alt="android-3" class="no-border" >}} - -6. Select your device from the list: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/android-4.png" alt="android-4" class="no-border" >}} - -7. Inspect the tab from your mobile device to preview the view from your device on-screen and to gain access to the Chrome web inspector and the rest of the Developer Tools. - -You can now take advantage of all the debugging tools you know and love with Mendix, including offline breakpoints, quick updates/refreshes, and the Chrome Developer Tools. - -## iOS and macOS {#iosAndMac} - -### Apple Developer Configuration - -In order to build (and debug) a Mendix iOS app, you need to ensure that you have the right setup in your Apple Developer Account. You will need a Developer Provisioning Profile that includes your device ID and a Signing Certificate. If you already have an iOS Development provisioning profile, you can continue with [5.2 PhoneGap Configuration](#PhonegapConfiguration). Follow these steps to set up an iOS provisioning profile: - -1. Go to [developer.apple.com](https://developer.apple.com/) and sign in to your account. -1. Click **Certificates, IDs & Profiles** in the left-side navigation. -1. Click the `+` button to create a new certificate. -1. Select **iOS Development** and click **Continue**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-5.png" alt="apple-5" class="no-border" >}} - -1. Follow the instructions to create a Certificate Signing Request (CSR) and click **Continue**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-6.png" alt="apple-6" class="no-border" >}} - -1. Upload your new CSR and click **Continue**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-7.png" alt="apple-7" class="no-border" >}} - -1. Download your new certificate and click **Done**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-8.png" alt="apple-8" class="no-border" >}} - -1. On your Mac, open **Keychain Access** and select **Import Items…** from the **File** menu: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-9.png" alt="apple-9" class="no-border" >}} - -1. Select your new certificate: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-10.png" alt="apple-10" class="no-border" >}} - -1. Right-click the certificate in the list of certificates and select **Export**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-11.png" alt="apple-11" class="no-border" >}} - -1. Save this as a **.p12** file, and remember this for later. You will need this to build your Phonegap application: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-12.png" alt="apple-12" class="no-border" >}} - -1. Return to the **Certificates, Identifiers & Profiles** page. -1. Navigate to the **App IDs** page, located under **Identifiers**. -1. Click the `+` button to create a new **App ID**. -1. Enter an **App ID Description** and **Explicit App ID** and select the necessary Apple services your app will need, then click **Continue**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-15.png" alt="apple-15" class="no-border" >}} - -1. Click **Register**, then **Done**. -1. Connect your iOS device and open **iTunes**. -1. Navigate to your device overview in iTunes, and click where it lists the serial number to reveal the UDID: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-18.png" alt="apple-18" class="no-border" >}} - -1. When you see the UDID, right-click it and select **Copy**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-19.png" alt="apple-19" class="no-border" >}} - -1. Return to the **Certificates, Identifiers & Profiles** page and navigate to the **All** page under **Devices**. -1. Click the `+` button to add a new device. -1. Enter a name for the device and paste the UDID: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-21.png" alt="apple-21" class="no-border" >}} - -1. Navigate to **All** under **Provisioning Profiles**. -1. Click the `+` button to create a new Provisioning Profile. -1. Select **iOS App Development** and click **Continue**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-23.png" alt="apple-23" class="no-border" >}} - -1. Select your new **App ID** from the drop-down and click **Continue**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-24.png" alt="apple-24" class="no-border" >}} - -1. Select your new Certificate and click **Continue**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-25.png" alt="apple-25" class="no-border" >}} - -1. Select the devices you want to test your app and click **Continue**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-26.png" alt="apple-26" class="no-border" >}} - -1. Give you new Provisioning Profile a name and click **Continue**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/apple-27.png" alt="apple-27" class="no-border" >}} - -1. Download your Provisioning Profile (you will need this for Phonegap). - -### Phonegap Configuration {#PhonegapConfiguration} - -You can use PhoneGap Build to build the native mobile application and tell it to initialize based on this new URL, rather than the default. Follow these steps to change the PhoneGap Build - -1. Go to **home.mendix.com** and open your app. -2. Navigate to the **Mobile App** page, listed under Deploy. -3. Configure this page as you normally would and click **Publish for Mobile App Stores**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-1.png" alt="phonegap-1" class="no-border" >}} - -4. Select **Do it Yourself** and click **Download Customizable Package**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-3.png" alt="phonegap-3" class="no-border" >}} - -5. Unzip the downloaded package and navigate to the */dist/phonegap.zip* file: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-4.png" alt="phonegap-4" class="no-border" >}} - -6. Extract the contents of this file and find *www/settings.json*: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-5.png" alt="phonegap-5" class="no-border" >}} - -7. Change the `url` property to the IP address of your local machine, with the port 8080. - - ```json - { - "url": "http://10.140.149.92:8080", - "hybridTabletProfile": "", - "hybridPhoneProfile": "", - "enableOffline": false, - "requirePin": false - } - ``` - -8. Save your changes and rezip the *phonegap* directory in */dist/*: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-7.png" alt="phonegap-7" class="no-border" >}} - -9. Upload the new zip file to a new app on Phonegap Build: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-8.png" alt="phonegap-8" class="no-border" >}} - -10. Navigate to **Edit Account** from the account menu: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-9.png" alt="phonegap-9" class="no-border" >}} - -11. On the **Signing Keys** tab, click **Add a Key** under **iOS**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-10.png" alt="phonegap-10" class="no-border" >}} - -12. Choose your .p12 certificate (from Step 12 in the Apple Developer Configuration) section and your new provisioning profile: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-11.png" alt="phonegap-11" class="no-border" >}} - -13. Click the lock to temporarily unlock your key: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-12.png" alt="phonegap-12" class="no-border" >}} - -14. Return to the app online and choose your new key from the drop-down. This will trigger a new build of your app: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-13.png" alt="phonegap-13" class="no-border" >}} - -15. When your app finishes building in the cloud, scan the QR code to download the app and run it on your iOS device. - -### iOS Configuration - -1. Go to **Settings > Safari** on your iOS device: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/ios-1.png" alt="ios-1" class="no-border" >}} - -2. Select **Advanced**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/ios-2.png" alt="ios-2" class="no-border" >}} - -3. Ensure that **Web Inspector** is turned on: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/ios-3.png" alt="ios-3" class="no-border" >}} - -4. Ensure that your iPhone can ping your development machine (if you have not already): - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/ios-4.png" alt="ios-4" class="no-border" >}} - -5. Return to the running Mendix app on your iOS device. -6. Open Safari on your Mac. -7. If you do not have the **Develop** option on your menu bar, open **Safari > Preferences**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/ios-6.png" alt="ios-6" class="no-border" >}} - -8. On the **Advanced** tab, ensure that **Show Develop Menu in menu bar** is checked: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/ios-7.png" alt="ios-7" class="no-border" >}} - -9. From the Develop menu, select your device and running application: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/ios-8.png" alt="ios-8" class="no-border" >}} - -10. This will bring up the **Safari Web Inspector** for your device. - -## Android + Windows {#AndroidAndWindows} - -### Windows Configuration - -Follow these steps to test your computer's connection to your device: - -1. Open the command prompt and type `ipconfig /all` and find the IPv4 address of your wireless adapter: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/win-1.png" alt="win-1" class="no-border" >}} - -2. Verify that your device can ping this address: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/win-2-1162756.png" alt="win-2" class="no-border" >}} - -### PhoneGap Configuration - -You can use PhoneGap Build to build the native mobile application and tell it to intialize based on this new URL, rather than the default. Follow these steps to create a new configuration: - -1. Go to **home.mendix.com** and open your app. -2. Navigate to the **Mobile App** page under Deploy. -3. Configure this page as you normally would and then choose **Publish for Mobile App Stores**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-1.png" alt="phonegap-1" class="no-border" >}} - -4. Select **Do it Yourself** and then click **Download Customizable Package**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-3.png" alt="phonegap-3" class="no-border" >}} - -5. Unzip the downloaded package and navigate to the */dist/phonegap.zip* file: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-4-1162839.png" alt="phonegap-4" class="no-border" >}} - -6. Extract the contents of this file and find *www/settings.json*: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-5-1162847.png" alt="phonegap-5" class="no-border" >}} - -7. Change the `url` property to the IP address of your local machine, with the port 8080. - - ```json - { - "url": "http://10.140.149.92:8080", - "hybridTabletProfile": "", - "hybridPhoneProfile": "", - "enableOffline": false, - "requirePin": false - } - ``` - -8. Save your changes and rezip the `phonegap/` directory in `/dist/`: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-7-1162855.png" alt="phonegap-7" class="no-border" >}} - -9. Upload the new zip file to a new app on Phonegap Build: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/phonegap-8.png" alt="phonegap-8" class="no-border" >}} - -10. When your app finished building in the cloud, download the app and run it to connect to your Mendix app running on your local machine! - -### Android Configuration - -1. Enable the developer options on your Android device. See [Configure On-Device Developer Options](https://developer.android.com/studio/debug/dev-options) for more information. -2. Connect your device to your development machine and when the popup appears on your mobile device to allow USB debugging, choose **Allow**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/android-2.png" alt="android-2" class="no-border" >}} - -3. Open the **Chrome** browser. -4. Open the **Chrome Developer Tools (F12)**. -5. Click **Customize and control DevTools** ({{% icon name="three-dots-menu-vertical" %}}) and select **More tools** > **Remote devices**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/android-3.png" alt="android-3" class="no-border" >}} - -6. Select your device from the list: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/debug-a-mobile-app/android-4.png" alt="android-4" class="no-border" >}} - -7. Inspect the tab from your mobile device to preview the view from your device on-screen and to gain access to the Chrome web inspector and the rest of the Developer Tools. - -You can now take advantage of all the debugging tools you know and love with Mendix, including offline breakpoints, quick updates/refreshes, and the Chrome Developer Tools. - -For more help with Android remote debugging, check out [Get Started with Remote Debugging Android Devices](https://developers.google.com/web/tools/chrome-devtools/remote-debugging/). - -## Read More - -* [Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [Publish a Mendix Hybrid Mobile App in Mobile App Stores](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/deploy-your-first-hybrid-mobile-app.md b/content/en/docs/howto8/mobile/hybrid-mobile/deploy-your-first-hybrid-mobile-app.md deleted file mode 100644 index edb88295ccc..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/deploy-your-first-hybrid-mobile-app.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Deploy Your First Hybrid Mobile App" -url: /howto8/mobile/deploy-your-first-hybrid-mobile-app/ -weight: 50 ---- - -## Introduction - -Besides boasting native functionality, another major advantage of a hybrid mobile apps is that you only need to go through the approval process once. Updates after the approval process only require a new deployment of your app in Mendix Cloud. - -This how-to teaches you how to do the following: - -* Open a hybrid example app -* Install the app on your device - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install the hybrid Mendix Developer App on you device, which makes it easy to see a hybrid application in action without the need to get it approved in the Mendix Marketplace (for details and download links, see [Getting the Mendix Developer App](/refguide8/getting-the-mendix-app/) in the *Studio Pro Guide*) - -## Opening a Hybrid Example App - -To open a hybrid example app, follow these steps: - -1. Open Mendix Studio Pro, clikc **New App**, and under the **Starter Apps** tab click **Blank App**. -2. Click the **Use this starting point** button. -3. Adjust your configurations (be sure to keep **Enable online services** > **Yes** selected) and then click **Create app**. -4. Click **Run** to deploy this application to Mendix Cloud: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/deploy-your-first-hybrid-mobile-app/18581186.png" class="no-border" >}} - - Studio Pro will notify you as soon as the application is deployed. While you wait, go to **Navigation**, click the **Hybrid phone app online** tab, and make sure your **Default home page** is set to **MyFirstModule.Dashboard**. -5. Click the small arrow to open the **View App** menu and select **View Hybrid Mobile App**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/deploy-your-first-hybrid-mobile-app/18581185.png" class="no-border" >}} - - This will open the **View Hybrid Mobile App** pop-up window: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/deploy-your-first-hybrid-mobile-app/18581184.png" class="no-border" >}} - -6. Open the Mendix Developer App on your device and tap **Scan QR Code**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/deploy-your-first-hybrid-mobile-app/18581190.png" class="no-border" >}} - -7. Scan the QR code on the screen with your Mendix Developer App: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/deploy-your-first-hybrid-mobile-app/18581189.png" class="no-border" >}} - -You should see the example application running on your device. - -## Installing the App on Your Device - -If you want to install this application as a native mobile app on your device, you can install it via iTunes or publish it to one of the mobile app stores. For details on how to achieve this, see [How to Publish a Mendix Hybrid Mobile App in App Stores](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/). - -## Read More - -* [Debug a Hybrid Mobile Application](/howto8/monitoring-troubleshooting/debug-a-hybrid-mobile-application/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/feedback-widget-ios.md b/content/en/docs/howto8/mobile/hybrid-mobile/feedback-widget-ios.md deleted file mode 100644 index 52e9e8b087f..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/feedback-widget-ios.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "Configure the Mendix Feedback Widget for iOS" -linktitle: "Configure iOS Mendix Feedback Widget" -url: /howto8/mobile/feedback-widget-ios/ -weight: 20 -description: "How to configure ios security settings to render the feedback widget's content" ---- - -## Introduction - -When you first start a Mendix hybrid mobile app for iOS, the feedback button from the [Mendix Feedback](/appstore/modules/mendix-feedback/) widget will not work. This is due to an iOS security policy whereby the application is only allowed to make requests and load content from `file:///` URLs. Because the content in the feedback widget is hosted at `https://sprintr.home.mendix.com`, the widget will not work - -This how-to teaches you how to do the following: - -* Configure your iOS hybrid mobile app to allow access to the [feedback management](/developerportal/app-insights/feedback/) functionality in **Apps**. - -## Prerequisites - -* Ensure that you have access to the Mendix Portal and the **Custom Cordova configuration** section on the **Mobile App** page (accessible via **DEPLOY**) -* Alternatively, you can make this change directly in the *config.xml* file, if you have that available - -## Extending the config.xml File - -To make the feedback button work as it should, you need only to add two lines to your *config.xml* file inside the `` element: - -```xml - - - - -``` - -Now build your app and you will see a correctly rendered feedback widget! - -## Read More - -* [Feedback Management](/developerportal/app-insights/feedback/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml.md b/content/en/docs/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml.md deleted file mode 100644 index cff7d5a89a1..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: "Implement SSO on a Hybrid App with Mendix and SAML" -linktitle: "SSO on Hybrid App with SAML" -url: /howto8/mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/ -weight: 30 -description: "Describes how to address the challenges of implementing SSO in hybrid mobile apps." ---- - -## Introduction - -This how-to will describe the challenges involved in implementing SSO (single sign-on) in hybrid mobile apps, and teach you how this can be solved in Mendix app. - -{{% alert color="warning" %}} -The implementation described in this how-to will not work when you have enabled anonymous users in your app. Disable anonymous users in your app to use this implementation. -{{% /alert %}} - -{{% alert color="warning" %}} -The implementation described in this how-to will not work when you have enabled the PIN feature for your hybrid app. Disable the PIN feature for your hybrid app to use this implementation. -{{% /alert %}} - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Have a [PhoneGap Build account](https://helpx.adobe.com/experience-manager/kb/adobe-phonegap-end-of-service.html) -* Be familiar with how the [SAML](/appstore/modules/saml/) module works -* Read [How to Publish a Mendix Hybrid Mobile App in App Stores](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/) -* Read [Building a Mobile App with Mendix](https://www.mendix.com/blog/building-mobile-app-mendix/) - -## Context - -### Hybrid Apps, Cordova, and PhoneGap Build - -Hybrid Mendix apps can be viewed in mobile web browsers. However, some features of mobile devices cannot be accessed through HTML and JavaScript. Also, if you want to publish your app in the Apple App Store or Google Play Store, you have to wrap your app in a native shell. Mendix uses [Cordova](https://cordova.apache.org/) to do this. Cordova creates a native wrapper around a web application and provides access to native functionality through a JavaScript API. These apps are called hybrid apps, because they are a hybrid of a web and a native app. To create binaries of your app, Mendix leverages PhoneGap Build so that you do not need to install software (Android SDK, Xcode) for this. - -### How Authentication Against an IdP Works {#how} - -When authenticating against an identity provider (IdP), the following steps are taken: - -1. The client (user agent) requests a page/resource from Mendix. -2. Mendix redirects the authentication request to the IdP by redirecting the client user agent there. -3. The IdP contacts the client and presents a login page. -4. The client authenticates against the IdP, then the IdP generates a SAML token and sends it back to the client, where it will be stored as a cookie. -5. The SAML token is sent to the Mendix Server by redirecting the client user agent back to the Mendix app. -6. After authentication, Mendix redirects the client to the page requested initially. -7. The client now requests the page requested initially. -8. Now that a security context exists, Mendix responds with the requested resource (page). - -For more information on the authentication process, see Wikipedia's [SAML 2.0 Web Browser SSO Profile](https://en.wikipedia.org/wiki/SAML_2.0#SP_POST_Request;_IdP_POST_Response). - -## The Problems {#problems} - -There are two main problems when trying to implement SSO on a hybrid app. - -### The First Problem {#firstproblem} - -The first problem is that the JavaScript needed to start up the app mobile functionality is stored inside the Mendix hybrid app. The application is loaded from the locally stored *index.html* file. - -This is a problem because of all the browser redirects happening when doing the authentication against the IdP (as described in the section [How Authentication Against an IdP Works](#how) above). - -When a Mendix hybrid app is started on the mobile device, the localhost *index.html* page is loaded in order to load all the necessary JavaScript to run the app. However, to be able to authenticate the user, the user is redirected to the IdP, and then the IdP needs to redirect the user back to the app. The problem is that there is no way for the IdP to redirect to a localhost page, so there is no way to start the app while still including the right Cordova JavaScript. - -### The Second Problem {#secondproblem} - -The second problem is that Cordova does not store cookies permanently. And since Cordova does not store (authentication) cookies, when an app is closed, the IdP cannot recognize a returning user, so it will always ask the user for authentication. - -## The Solution - -Mendix has created a standard approach to support SSO via the SAML module in a Mendix hybrid app. This approach contains reusable JavaScript code which can be added to the PhoneGap Build package that is used to build the app binaries. It also requires a simple configuration change on the SAML module. These components can be used by Mendix developers to make mobile apps compatible with SAML. However, care must always be taken to ensure the solution fits the requirements for specific apps. - -### The JavaScript {#javascript} - -The JavaScript code below will address the two problems described above. - -To address the [first problem](#firstproblem), when the mobile app is starting to load, the JavaScript below will be executed. It opens a new window using [Cordova’s InAppBrowser](https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-inappbrowser/), and all the redirects for the authentication are done there. When all the redirects are completed and the requested resource is sent from the Mendix Server back to the app, the authentication process is complete. The new window can then be closed, and the loading of the localhost *index.html* page can proceed. - -```javascript -MxApp.onConfigReady(function(config) { - var samlLogin = function() { - var samlWindow = cordova.InAppBrowser.open(config.unmodifiedRemoteUrl + "SSO/", "_blank", "location=no,toolbar=no"); - - var exitFn = function() { - navigator.app.exitApp(); - }; - - samlWindow.addEventListener("exit", exitFn); - - var loop = setInterval(function() { - samlWindow.executeScript({ - code: "window.location.href;" - }, function(href) { - if (href[0].toLowerCase().indexOf(config.unmodifiedRemoteUrl.toLowerCase()) == 0 && href[0].indexOf("SSO") == -1) { - samlWindow.executeScript({ - code: "document.cookie;" - }, function(values) { - samlWindow.removeEventListener("exit", exitFn); - - var authPromise = new Promise(function(resolve, reject) { - var token = new RegExp('AUTH_TOKEN=([^;]+)', 'g').exec(values[0]); - if (token && token.length > 1) { - mx.session.tokenStore.set(token[1]).then(resolve); - } else { - resolve(); - } - }); - - var closeWindow = function() { - samlWindow.close(); - - if (window.mx.afterLoginAction) { - window.mx.afterLoginAction(); - } - }; - - authPromise.then(closeWindow); - }); - }; - }); - }, 1000); - } - - config.ui.customLoginFn = samlLogin; -}); -``` - -To address the [second problem](#secondproblem), after a successful authentication against the IdP, Mendix stores a token in the device’s local storage. The system will use that token from that moment on to create a new session for the user. The session is created in Mendix only, so a new authentication against the IdP will not be performed again. This token is a TokenInformation (part of the System module) object, and it can be accessed/edited in microflows. By default, this local token will never expire, but this can be overridden by changing the `com.mendix.webui.HybridAppLoginTimeOut` [Runtime customization setting](/refguide8/custom-settings/). The downside of this approach is that access rights will not be updated upon login, since no interaction is done with the IdP. However, in most systems using SSO, user and role provisioning is handled separately from the authentication, so this might not be an issue. - -In some cases the window will not close properly. To solve this issue, add the following code (after line 9 as shown in the snippet above) as a workaround: - -```javascript - samlWindow.addEventListener('loadstart', (param)=>{ - if(param.url == config.unmodifiedRemoteUrl + 'index.html'){ - samlWindow.close(); - window.mx.afterLoginAction && window.mx.afterLoginAction(); - } - }); -``` - -### The Hybrid App Package - -To use the hybrid app package, follow these steps: - -1. Open your app in [Apps](https://sprintr.home.mendix.com/). In the navigation pane, click **Mobile App**. -2. Click **Publish for Mobile App Stores**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/download-hybrid-app-package-step1.png" class="no-border" >}} - -3. Select **Do it yourself** and then click **Download Customizable Package**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/download-hybrid-app-package-step2.png" class="no-border" >}} - - This package you just downloaded is a customizable hybrid app package for your specific Mendix app. You can make changes to it, build a new PhoneGap Build package, and then upload it to PhoneGap Build to create the binaries (for example, APK for Android and IPA for iOS). To better understand the structure of what you just downloaded, see the **Folder Structure** section in the [Mendix PhoneGap Build App Template documentation](https://github.com/mendix/hybrid-app-template#folder-structure). - -4. Unzip the hybrid app package. -5. Edit the *Entry.js* file (under `phonegap/package/src/www/scripts/`). The file should look like this: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/entry.js.png" class="no-border" >}} - -6. Add the JavaScript code provided in [5.1 The JavaScript](#javascript) under `MxApp.onConfigReady(function(config) {`. Your *Entry.js* file should now look like this: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/entry.js-with-fix.png" class="no-border" >}} - -7. Create the PhoneGap Build package by following the instructions in the **Through Uploading to PhoneGap Build** section of the [Mendix PhoneGap Build App Template documentation](https://github.com/mendix/hybrid-app-template#through-uploading-to-phonegap-build). Be sure to read the **Prerequisites** and **Build on PhoneGap** sections of this documentation as well. This is an overview of the steps:
- 1. Install the latest stable version of [Node.js](https://nodejs.org/en/download/).
- 1. In the hybrid app root folder, execute **npm install**.
- 1. In the hybrid app root folder execute **npm run package**.
-8. Create an APK or iOS package from the PhoneGap Build package. You can upload the new PhoneGap Build package (in the **dist** folder) to PhoneGap to build the APK or iOS binary. - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/build.phonegap.com.png" class="no-border" >}} - -### The SAML Module - -{{% alert color="warning" %}} -Not all versions of the SAML module will work correctly when implementing SSO for your hybrid app. Please make sure you use a version of the SAML module that is capable of creating mobile app tokens (that is, version 1.9.3 or above). Mendix recommends updating the SAML module to the latest version available, and if needed, updating the Mendix version of your application. - -See the [Dependencies](/appstore/modules/saml/#dependencies) section of the *SAML* documentation for more information. -{{% /alert %}} - -{{% alert color="info" %}} -The **SAML20.HybridAppLoginTimeOutInMinutes** constant is only available in the following module versions: - -* v3.2.2 and above for Mendix 9 (only for apps migrated from Mendix 8) -* v2.2.2 and above for Mendix 8 -{{% /alert %}} - -If you have the **com.mendix.webui.HybridAppLoginTimeOut** [custom runtime setting](/refguide8/custom-settings/#web-client-settings) configured to customize the expiration of mobile authentication tokens, you will have to set the value of the **SAML20.HybridAppLoginTimeOutInMinutes** constant to match the value of the custom runtime setting. When you use the SAML module for SSO in your Mendix app, the authentication token is not created by the Mendix runtime, which uses the custom runtime setting. Instead, the authentication token is created by the Java code in the SAML module. This Java code does not have access to the custom runtime setting value, and thus requires the constant value to be set. - -Be sure to take these actions based on your use case: - -* If you use the default login handler in your hybrid app, you must change the **com.mendix.webui.HybridAppLoginTimeOut** custom runtime setting to change the validity of the authentication token used by the hybrid mobile app -* If you use the SAML module in your hybrid app, you must change the **SAML20.HybridAppLoginTimeOutInMinutes** constant to change the validity of the authentication token used by the hybrid mobile app -* If you use both the default login handler and the SAML module in your hybrid app, you must change both - -The last thing to do is to check the **Enable mobile authentication token** box in the **Provisioning** tab when configuring an identity provider in the Mendix SAML module. This will make sure the SAML module provides the correct login token to the JavaScript part. - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/saml-module.png" class="no-border" >}} - -## Read More - -* [Deploy Your First Hybrid Mobile App](/howto8/mobile/deploy-your-first-hybrid-mobile-app/) -* [Publish a Mendix Hybrid Mobile App in App Stores](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/) -* [Debug a Hybrid Mobile App](/howto8/mobile/debug-a-mobile-app/) -* [Debug a Hybrid Mobile Application](/howto8/monitoring-troubleshooting/debug-a-hybrid-mobile-application/) -* [Building a Mobile App with Mendix](https://www.mendix.com/blog/building-mobile-app-mendix/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/_index.md b/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/_index.md deleted file mode 100644 index fd45421ef63..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/_index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Include Push Notifications" -url: /howto8/mobile/push-notifications/ -weight: 10 -no_list: false -description_list: true ---- - -## Introduction - -Push notifications enable your app to notify a user of events, even if the user is not actively using the app. This is a native capability available on both Android and iOS devices, and it is controlled through external services via, for example, Firebase Cloud Messaging (FCM) or Apple Push Notifications service (APNs). - -The Mendix push notifications solution consists of these two parts: - -* [Push Notifications Connector](/appstore/modules/push-notifications/) module – this is the "server-side" component responsible for sending push notifications to FCM/APNs, which will in turn send the notifications to the user devices -* **PushNotifications widget** – this resides in the hybrid mobile app and is responsible for the application's interaction with FCM/APNs (via the Push Plugin) in terms of registering the devices with these services and handling the push notifications received from them - -The Mendix push notifications functionality makes it easy for developers to include push notification capabilities in their Mendix hybrid mobile apps. - -## Prerequisites - -To use push notifications, make sure you have the following: - -* Mendix Studio Pro from the [Marketplace](https://marketplace.mendix.com/link/studiopro/) -* The Mendix [Push Notifications Connector](/appstore/modules/push-notifications/) -* A mobile device (to get started, Mendix recommends an Android device connected to your development machine via a data cable) - -## Supported Platforms - -* Android 5.0 and above -* iOS 9.0 and above - -## GCM vs. FCM - -Earlier versions of the Mendix Push Notifications Connector supported Google Cloud Messaging (GCM) and APNs. Google has replaced GCM with FCM. - -## Dependencies - -* Apache Commons IO: Apache 2.0 -* Jackson (core+databind+annotations): Apache 2.0 -* Google APIs Client Library for Java: Apache 2.0 -* Google HTTP Client Library for Java: Apache 2.0 -* Google OAuth Client Library for Java: Apache 2.0 -* Gson: Apache 2.0 -* Guice: Apache 2.0 -* Netty: Apache 2.0 -* Netty Tomcat Native Fork: Apache 2.0 -* Pushy: MIT - -## Contributing - -For more information on contributing to this repository, see [How to Contribute to a Mendix GitHub Repository](/howto8/collaboration-requirements-management/contribute-to-a-github-repository/). - -## Documents in This Section diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/implementation-guide.md b/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/implementation-guide.md deleted file mode 100644 index f7c8de62a9a..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/implementation-guide.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: "Implement Push Notifications" -url: /howto8/mobile/implementation-guide/ -weight: 10 ---- - -## Introduction - -This how-to will walk you through the steps needed to implement push notifications in your application. - -This how-to teaches you how to do the following: - -* Import the PushNotifications module -* Add the push notification widget and administrator pages -* Update several project files with the necessary dependencies -* Obtain FCM/APNs access/credentials and configure them with your application -* Build the hybrid mobile package - -## Importing the PushNotifications Module from the Marketplace - -The [Push Notifications Connector](/appstore/modules/push-notifications/) module is published in the Mendix Marketplace. To import it into your project, click the Marketplace icon in the top right of Mendix Studio Pro. Search for "Push Notifications Connector" and click the title of the result: - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/implementation-guide/20218020.png" class="no-border" >}} - -On the resulting page, click the green **Download** button. Make sure that **Add as a new module** is selected, and then click **Import**: - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/implementation-guide/20217885.jpg" class="no-border" >}} - -{{% alert color="warning" %}} -The Push Notifications Connector assumes that the mobile app and the back-end part will reside in the same app. -{{% /alert %}} - -## Installing Module Dependencies - -The PushNotifications module has the following dependencies: - -* [Encryption](/appstore/modules/encryption/) -* [Community Commons Function Library](/appstore/modules/community-commons-function-library/) -* [Nanoflow Commons](https://marketplace.mendix.com/link/component/109515/) -* [Native Mobile Resources](/appstore/modules/native-mobile-resources/) - -To include these dependencies, download them from the Marketplace in a way similar to how you installed the PushNotifications module. While importing, you may get a pop-up window with information about overwriting project files, which you can confirm by clicking **OK**. - -{{% alert color="info" %}} - -If your project is using an older version of the [Encryption](/appstore/modules/encryption/) module, it might trigger an error for referencing a non-existent layout. You can fix this by assigning the primary layout of the **Encryption.ResponsiveLayout_Certificate** layout to another layout (please note that in this specific use case, it is not important which layout is used). This does not apply to version 1.3.1 and above. - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/implementation-guide/20217886.jpg" class="no-border" >}} - -{{% /alert %}} - -After importing the module and the dependencies, your error dock will inform you that entity access is out of date. To fix this error, double-click the error and then click **Update security** at the top of the domain model pane. - -## Including the Push Notifications Snippet in the Application's Layouts - -To properly register your device with a third-party remote push service (FCM or APNs) and display in-app notifications, you should put the widget on the pages of your app. You can accomplish this by dragging the **Online_Snippet** or **Offline_Snippet** (located in the **_USE ME** folder in the **PushNotifications** module) into the layouts used by your app. Which of these two you should pick depends on whether your Mendix hybrid app uses an online profile or an offline profile. Note that push notifications do not currently work on the desktop. - -If your app is offline-compatible, ensure that a sync button is available to the user so that device registration requests will be synchronized with the server. For more information, see [Offline](/refguide8/offline-first/) and [Navigation](/refguide8/navigation/#hybrid-profiles). - -{{% alert color="warning" %}} - -Please do not remove the button with the caption **Device Registration reference** from the **PushNotification_Snippet**. This is required to make the widget offline-compatible. Please note that this button is invisible to the user. - -{{% /alert %}} - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/implementation-guide/20217888.jpg" class="no-border" >}} - -## Starting Connectors from Your After-Startup Microflow - -The PushNotifications module contains a microflow named **AfterStartup_PushNotifications** that will start the APNs connector for you. Call this microflow from your **AfterStartup** microflow. - -If your project already has an AfterStartup microflow configured, it is recommended that you either: - -* create a new microflow, from which you will call both the existing AfterStartup microflow and the AfterStartup_PushNotifications microflow, and then set this as the AfterStartup microflow for your app -* add a new action to the existing AfterStartup microflow to run the AfterStartup_PushNotifications microflow - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/implementation-guide/on-app-startup.png" alt="On start push microflow" class="no-border" >}} - -## Setting Up the Administration Pages {#setting} - -Add the **PushNotifications_Administration** page to the project navigation, so it can be reached after you deploy your app. This page contains three tabs: - -* **Pending Messages** – shows all the messages that are queued either because they were sent using the QueueMessage action or because previous attempts to send them failed -* **Devices** – contains a list of all the devices registered with the application and is useful for testing purposes -* **Configuration** – configures your application so that it can reach the respective services (APNs and FCM) later on - -{{% alert color="warning" %}} - -Do not add the administration pages to the navigation layout of offline devices. The administration pages are not offline-compatible. - -{{% /alert %}} - -## Setting Up the Project Security for Your Module - -On the **User roles** tab of the **Project Security** dialog box, include the following: - -* The **PushNotifications.Administrator** role as part of the main **Administrator** role -* The **PushNotifications.User** role as part of the main **User** role -* The **PushNotifications.Anonymous** role role as part of the main **Anonymous** role (if your application allows anonymous users) - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/implementation-guide/21168173.png" class="no-border" >}} - -## Deploying Your App - -At this point, all the implementation steps are done and you can deploy your application to Mendix Cloud. If you are using a Free App, simply click **Run**. - -{{% alert color="warning" %}} - -Make sure that the `Encryption.EncryptionKey` constant has a value before you start the application. If the value is not set, you will get a `NullPointerException` when you try to send a notification to APNs. If you are using a Free App, set a default value for the constant in the model. Otherwise, configure the constant value in the Mendix Portal. - -{{% /alert %}} - -## Setting Up Access to APNs or FCM - -Below are instructions for setting up access to APNs or FCM and configuring them in your application. Mendix recommends starting with FCM, because it is significantly less complicated than setting up APNs. You can return to this section later to set up APNs. - -Open your Mendix app, sign in as an **Admin**, and open the **PushNotifications_Administration** page. Scroll to the **FCM** section and create or edit a configuration. - -Configure FCM as follows: - -1. Select the **Enabled** checkbox. -2. Enter a name for the new configuration. -3. Enter your Firebase project ID (located on the [Firebase console](https://console.firebase.google.com/) website). -4. Upload your private key (which you downloaded when you created a service account). - -{{% alert color="warning" %}} -Make sure the **Encryption.EncryptionKey** constant has a valid value before you start the application. If the value is not set, the private key will not be stored correctly and you will get a `NullPointerException` error when you try to send a notification to FCM. If you get the `NullPointerException` error, please double-check the value of the **Encryption.EncryptionKey** constant, restart your app, and upload the private key again. -{{% /alert %}} - -For more details, see [How to Set Up the Apple Push Notification Server](/howto8/mobile/setting-up-apple-push-notification-server/) and [How to Set Up the Firebase Cloud Messaging Server](/howto8/mobile/setting-up-google-firebase-cloud-messaging-server/). - -## Building the Hybrid Mobile Application - -You now need to build the hybrid mobile application. For an explanation on how to do this, see [How to Publish a Mendix Hybrid Mobile App](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/). - -## Read More - -* [Microflows](/refguide8/microflows/) -* [Test the Push Notifications Implementation](/howto8/mobile/testing-the-implementation/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/sending-push-notifications.md b/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/sending-push-notifications.md deleted file mode 100644 index d39d9ef1bbf..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/sending-push-notifications.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "Send Push Notifications" -url: /howto8/mobile/sending-push-notifications/ -weight: 20 ---- - -## Overview - -This is a list of microflow actions that can be called by your application to send push notifications. They are located in the **Toolbox** under the **Push notifications** category. - -| Microflow Action Name | Description | -| --- | --- | -| SendMessageToDevice | Sends a message to a device immediately. | -| SendMessageToDevices | Sends a message to multiple devices immediately. | -| SendMessageToUser | Sends a message to all the devices of a user immediately. | -| SendMessageToUsers | Sends a message to all the devices of multiple users immediately. | - -All actions accept a MessageData object as the first parameter. The MessageData entity contains all input data for the notification, such as title, body, and timeToLive. - -You may use the **PrepareMessageData** microflow to generate this entity (but you can also create it manually). - -| Parameter | Description | -| --- | --- | -| Title | The title of the message. | -| Body | The extended text of the notification. | -| TimeToLive | The number of seconds before the notification expires. | -| Badge | The number to show on the app icon. | -| ActionName | The name of the action to perform when the recipient clicks on the notification (see below). | -| ContextObjectGuid | The Mendix object ID of the entity to pass to the specified action. | - -In addition, you can modify the NextTry attribute to influence when the notification is delivered. - -As an alternative to providing a contextObjectGuid, you can pass the entity that you would like to use as a context object to the **SendMessage...** microflow actions. - -## Actions - -You can specify actions to be performed once the recipient clicks a notification. To do so, you should specify the available actions in the widget by following these steps: - -1. Locate the **Online_Snippet** or **Offline_Snippet** document and open it. - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/sending-push-notifications/push_notifications_snippets.png" class="no-border" >}} - -2. Double-click the widget to open the properties. - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/sending-push-notifications/push_notifications_widget_settings.png" class="no-border" >}} - -Use the **New** button to add new actions. Each action requires a name, an action type (Open Page or Call Microflow), and optionally an entity (the type of the context object). Depending on the action type, you should configure the page to be opened or the microflow to be called. - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/sending-push-notifications/push_notifications_action.png" class="no-border" >}} - -The names of the actions can be used as the value of the ActionName attribute of the MessageData entity. - -### Shortcomings of This Approach - -* Nanoflows are not yet supported -* Microflows can only be used in online apps; in offline apps, microflows are not supported - -## Read More - -* [Set Up the Apple Push Notification Server](/howto8/mobile/setting-up-apple-push-notification-server/) -* [Set Up the Google Firebase Cloud Messaging Server](/howto8/mobile/setting-up-google-firebase-cloud-messaging-server/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/setting-up-apple-push-notification-server.md b/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/setting-up-apple-push-notification-server.md deleted file mode 100644 index 6891d3755d2..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/setting-up-apple-push-notification-server.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "Set Up the Apple Push Notification Server" -linktitle: "Apple Push Notification Server" -url: /howto8/mobile/setting-up-apple-push-notification-server/ -weight: 30 ---- - -## Introduction {#intro} - -In order to proceed you need an Apple developer license and a device running Mac OS X. - -This how-to assumes that you already have the app signing key with provisioning profile and can freely build and install your mobile app (if not, please refer to [this how-to](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/)). Take into account that your App ID should use `Explicit App ID` and have `Push Notifications` turned on so you can receive push notifications with your app. - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/setting-up-apple-push-notification-server/20217895.png" class="no-border" >}} - -If this is not the case, you need to create new App ID with `Explicit App ID` and `Push Notifications` turned on. After following the steps below, you'll need to generate and download a new provisioning profile for this App ID and use it to rebuild the mobile app. - -If everything is set up and you can build and deploy your application, you can proceed with setting up the push notifications server. To establish connectivity between your notification server and the Apple Push Notification service you will need either: - -* An Apple Push Notification service key, or -* An Apple Push Notification service SSL certificate in the *.p12* format - -## Option A: Using a key - -Follow the steps below to obtain and set up an Apple Push Notifications key from Apple. - -### Signing Into the Apple Developer Center - -Sign in to Apple Developer and navigate to [https://developer.apple.com/account/ios/authkey/](https://developer.apple.com/account/ios/authkey/). - -### Creating a Key - -Click the **+** icon in the upper right of the screen. This will present you with a new form. Enter a descriptive name for this key, select the **Push Notifications service** checkbox, and then press **Contine**. On the next page, press **Confirm**. - -### Downloading the Key - -Press the download button and store the key in a secure place. Also, copy the **Key ID** for use in the next step. - -### Configuring APNs in Your Application - -For the last step, you need to configure APNs within your application. This can be done by signing into your application as a user with the Administrator role and navigating to the **PushNotifications_Administration** page that was set up in the [Setting Up the Project Security for Your Module](/howto8/mobile/implementation-guide/#setting) section of *How to Implement Push Notifications*. - -For this purpose, do the following: - -* Create a new APNs configuration, and choose a name for the new configuration -* Choose a topic for the new configuration (you can freely choose one) - * Set the **Authentication Type** to **Token** - * If you receive a "topic disallowed" error message, leave the topic field empty -* Add your Apple Push Notification service key - * Enter your team ID as shown on the Apple developer website - * Enter the key ID as copied during the previous step - -## Option B: Using an SSL certificate - -Follow the steps below to obtain and set up an Apple Push Notifications service SSL certificate from Apple. - -### Signing in to the Apple Developer Center - -Sign in to Apple Developer and select your app on [https://developer.apple.com/account/ios/identifier/bundle](https://developer.apple.com/account/ios/identifier/bundle). - -### Choosing the Certificate Type - -Click **Edit**, scroll to the **Push Notifications** section, and choose to configure either a **Development** certificate or a **Production** certificate. A Development certificate can only be used with iOS apps built and run in development mode. Production certificates can only be used with apps built and run in production mode. - -### Creating the CSR File - -The wizard now explains how to create a Certificate Signing Request (CSR). Read this description and press **Continue**. During the next step, you should be asked for your CSR file. You may use the same CSR you used to create the app signing certificate. If you do not have one, please follow the instructions as shown below. - -{{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/setting-up-apple-push-notification-server/20217898.png" class="no-border" >}} - -### Downloading the Certificate - -Download your Apple Push Notification service SSL certificate and add it to your Keychain. - -This certificate needs to be converted into the *.p12* format. If you do not know how to do this, refer to Apple's [What is app signing?](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingCertificates/MaintainingCertificates.html). - -### Configuring APNs in Your Application - -For the last step, you need to configure APNs within your application. This can be done by signing into your application as a user with Administrator role and navigating to the **PushNotifications_Administration** page that was set up in the [Setting Up the Project Security for Your Module](/howto8/mobile/implementation-guide/#setting) section of *How to Implement Push Notifications*. - -To configure your APNs, complete the following steps: - -* Create a new APNs configuration, and choose a name for the new configuration -* Choose a topic for the new configuration (you can freely choose one) - * Set the **Authentication Type** to **Certificate** - * Choose the **Stage** that corresponds to the type of certificate you have created -* Add your Apple Push Notification service SSL certificate in the *.p12* format - * Enter the password that you used during creation of the certificate - -## Read More - -* [Implement Push Notifications](/howto8/mobile/implementation-guide/) -* [Publish a Mendix Hybrid Mobile App in Mobile App Stores](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/testing-the-implementation.md b/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/testing-the-implementation.md deleted file mode 100644 index be0870d07cd..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/push-notifications/testing-the-implementation.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Test the Push Notifications Implementation" -linktitle: "Test Push Notifications" -url: /howto8/mobile/testing-the-implementation/ -weight: 60 ---- - -## Introduction - -Once you finish implementing the steps described in [How to Implement Push Notifications](/howto8/mobile/implementation-guide/), you need to test whether your push notifications work correctly. - -## Prerequisites - -To begin testing your push notifications, you will need to build new versions of your mobile application: - -1. Navigate to [Apps](https://sprintr.home.mendix.com/), then click your app. -2. Click **Deploy** > **Mobile App**. -3. Make sure the checkbox **Permissions** > **Push Notifications** is selected. -4. Click **Publish for Mobile App Stores**. -5. Select the **Do it yourself** checkbox, make sure your preferred environment is selected, and then click **Download Customizable Package**. - -This will give you a *zip* app that you can use to customize your app according to the [hybrid app package documentation](https://github.com/mendix/hybrid-app-template/). The *zip* app contains a *config.xml* file that refers to *google-services.json* and *GoogleService-info.plist* files. - -To successfully use FCM push notifications, you must put the *google-services.json* and *GoogleService-Info.plist* files – obtained in the [Downloading the Google Services Config Files](/howto8/mobile/setting-up-google-firebase-cloud-messaging-server/#downloading-the-google-services-config-files) section of *Set Up the Google Firebase Cloud Messaging Server* – in your app's **config** folder. - -When you add these files, it causes the **PushNotifications** widget to register your device with FCM, and then share the FCM registration token with your Mendix back-end server. This means you must use FCM to send messages to your devices. - -### Using APNS Instead of FCM for iOS Devices - -If you would like to use APNS instead of FCM for your iOS devices, then you will have to delete the reference to *GoogleService-info.plist* from *config.xml*. By doing this, you will not need to include the *GoogleService-info.plist* file, and can then use APNS to send messages to iOS devices. - -## Building Your Mobile App - -Now that you have set up your hybrid app for push notifications, you may continue building it by following the [hybrid app package documentation](https://github.com/mendix/hybrid-app-template/). Once you have a running app, continue to the section below. - -## Sending a Push Notification to a Device - -Follow these steps to test and send a push notification to a device: - -1. Open your application in the browser and sign in as administrator (for example, MxAdmin`). -2. To be able to sign in into your hybrid mobile application, you will need to create a new user. Typically, this can be done from the administration pages of your application. If you have anonymous access enabled, this step is of course not necessary. -3. Open your hybrid mobile app and sign in. If you are testing offline-mode, click the sync button to send the pending device registration request to the server. -4. Open the **Push Notifications Administration** page. Back in the administrator view of your web application, navigate to the **Devices** tab in the Push Notifications administration page. Here you should see one device in the list of registered devices, which is the device that you used to sign in to your hybrid mobile application. Continue by selecting the device and click **New Message**. - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/push-notifications/testing-the-implementation/21168174.png" class="no-border" >}} - -5. Fill in the title and the message in the form and press **Send**. Your device should receive a new push notification. If your hybrid mobile app is currently running in the foreground, the notification will be displayed in the app. Otherwise, it will be shown as a standard push notification. - -If you saw the notification, congratulations! By following this document, you have successfully tested push notifications on your device. - -## Read More - -* [Publish a Mendix Hybrid Mobile App in Mobile App Stores](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/) -* [Debug a Hybrid Mobile App](/howto8/mobile/debug-a-mobile-app/) diff --git a/content/en/docs/howto8/mobile/hybrid-mobile/setting-up-hybrid-push-notifications.md b/content/en/docs/howto8/mobile/hybrid-mobile/setting-up-hybrid-push-notifications.md deleted file mode 100644 index 8d7a276b9e2..00000000000 --- a/content/en/docs/howto8/mobile/hybrid-mobile/setting-up-hybrid-push-notifications.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Set Up Hybrid Push Notifications" -url: /howto8/mobile/setting-up-hybrid-push-notifications/ -weight: 9 -description: "Learn how to set up hybrid push notifications with PhoneGap Build." ---- - -## Introduction - -In this how to we will set up hybrid push notifications. - -This how-to teaches you how to do the following: - -* Customize your hybrid template to enable push notifications - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Complete [How to Set Up the Google Firebase Cloud Messaging Server](/howto8/mobile/setting-up-google-firebase-cloud-messaging-server/) - -## Building Your Mobile Application - -If your app supports push notifications, you are required to set up a Firebase account for your app and include Google service description files (*google-services.json* and *GoogleService-Info.plist*) in your hybrid app. - -As a result of this, Mendix hybrid apps that employ push notifications can no longer be built directly using the PhoneGap Build flow in the Mendix Portal. Instead, you will need to prepare the hybrid app package locally. You can use the generated hybrid app package to build your Android and iOS apps locally, or upload them to PhoneGap Build manually. - -To build the hybrid app package, follow these steps: - -1. Open your app in [Apps](https://sprintr.home.mendix.com/). In the navigation pane on the left, click **Mobile App**. -2. Make sure the **Push Notifications** permission is selected under **Permissions**. -3. Click **Publish for Mobile App Stores**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/download-hybrid-app-package-step1.png" class="no-border" >}} - -4. Select **Do it yourself** and then click **Download Customizable Package**: - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/download-hybrid-app-package-step2.png" class="no-border" >}} - - This package you just downloaded is a customizable hybrid app package for your specific Mendix app. You can make changes to it, build a new PhoneGap Build package, and then upload it to PhoneGap Build to create the binaries (*.apk* for Android and *.ipa* for iOS). To better understand the structure of what you just downloaded, see the **Folder Structure** section in the [Mendix PhoneGap Build App Template documentation](https://github.com/mendix/hybrid-app-template#folder-structure). - -5. Unzip the hybrid app package. -6. Copy and paste the *google-services.json* and *GoogleService-Info.plist* config files you downloaded before into the `config` folder. - {{% alert color="warning" %}} Only paste the *GoogleService-Info.plist* config file when you plan on using FCM for sending push notifications to iOS devices. If you plan on keeping using APNS to send push notifications to iOS devices, do not paste the *GoogleService-Info.plist* config file.{{% /alert %}} -7. Create the PhoneGap Build package by following the instructions in the [Through Uploading to PhoneGap Build](https://github.com/mendix/hybrid-app-template#through-uploading-to-phonegap-build) section of the *Mendix PhoneGap Build App Template* documentation. Be sure to read the **Prerequisites** and **Build on PhoneGap** sections of this documentation as well. This is an overview of the steps:
- 1. Install the latest stable version of [Node.js](https://nodejs.org/en/download/).
- 1. In the unzipped hybrid app package folder, execute `npm install`.
- 1. In the same folder execute `npm run package`.
-8. Create an APK or iOS package from the PhoneGap Build package. You can upload the new PhoneGap Build package (in the **dist** folder) to PhoneGap to build the APK or iOS binary. - - {{< figure src="/attachments/howto8/mobile/hybrid-mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/build.phonegap.com.png" class="no-border" >}} - -## Read More - -* [Implement Push Notifications](/howto8/mobile/implementation-guide/) -* [Publish a Mendix Hybrid Mobile App in Mobile App Stores](/howto8/mobile/publishing-a-mendix-hybrid-mobile-app-in-mobile-app-stores/) diff --git a/content/en/docs/howto8/mobile/native-mobile/_index.md b/content/en/docs/howto8/mobile/native-mobile/_index.md deleted file mode 100644 index aa1e8cc52ac..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/_index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Native Mobile" -url: /howto8/mobile/native-mobile/ -weight: 1 -no_list: false -description_list: true ---- - -## Introduction - -As of Mendix 8, it is possible to build fully native mobile apps. Native mobile apps differ from hybrid apps in that they do not render inside a web view. Instead, they use native UI elements. This enables fast performance, smooth animations, like swipe gestures, and improved access to all native device capabilities. - -You build Mendix native mobile apps the same way you build web or hybrid apps. You can use familiar elements such as pages, widgets, nanoflows, JavaScript actions, and microflows to put together your app. However, there are some differences between building native apps and hybrid apps. For example, the set of available widgets (and their properties) is slightly different. In addition, native styling is based on JavaScript instead of SASS/CSS. - -## Documents in This Section diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/_index.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/_index.md deleted file mode 100644 index de17a932924..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/_index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Build Native Apps" -url: /howto8/mobile/build-native-apps/ -weight: 8 -description: Tutorials for building native mobile apps. ---- - -These step-by-step guides teach you how to build native mobile applications and more. Many of these guides use the Native Builder UI tool included in Mendix Studio Pro 8.15 and above: - -* [Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) – Go from a blank slate to an app running on a device. -* [Build a Mendix Native App Locally](/howto8/mobile/native-build-locally/) – Follow this guide to build your apps locally using Mendix Native Mobile Builder. -* [Build a Mendix Native App Locally Manually](/howto8/mobile/native-build-locally-manually/) – Follow this guide to build your apps locally and without an internet connection. -* [Debug Native Mobile Apps (Advanced)](/howto8/mobile/native-debug/) – Debug native mobile apps using the Make It Native app. -* [Create a Custom Developer App](/howto8/mobile/how-to-devapps/) – Create a custom developer app: a substitute for the Make It Native app which accommodates custom dependencies such as native widgets or fonts. -* [Add Fonts to Your Native App](/howto8/mobile/native-custom-fonts/) - Add custom fonts to your native mobile apps. - -Mendix recommends using the Native Builder UI client to build apps. If you need to use the Native Builder CLI tool, however, see this collection of documents: - -* [How to Build Apps Using the Native Builder CLI](/howto8/mobile/use-cli-docs/) diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/deploying-native-app.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/deploying-native-app.md deleted file mode 100644 index dd4492c7d9e..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/deploying-native-app.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: "Build a Mendix Native App in the Cloud" -linktitle: "Deploy Mendix Native Mobile App" -url: /howto8/mobile/deploying-native-app/ -weight: 10 -description: Describes how to build a Mendix native app in the cloud with the Mendix Native Mobile Builder. ---- - -## Introduction - -This how-to teaches you how to go from a blank slate to an app running on a device. - -The Mendix Native Mobile Builder is the UI tool to set up and build your Mendix Native Mobile Apps. It is directly accessible in Mendix Studio Pro 8.15 and above for all projects with a native mobile navigation profile. - -## Prerequisites {#prerequisites} - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Mendix Studio Pro 8.15 and above installed using the online installer. The offline installer does not include the Mendix Native Mobile Builder dependency. -* Read [How to Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) to see how to create, style and debug an application with Mendix Studio Pro -* Deploy your native mobile app to the cloud via Studio Pro and have the cloud address of your deployed application available -* A [GitHub](https://github.com/) account. -* An [App Center](https://appcenter.ms/) account. Mendix recommends a paid account if you will be building and deploying regularly. - -### Platform-Specific Prerequisites - -If you plan to deploy your app for testing on an iOS device, make sure you have completed the following prerequisites: - -* Register for an Apple Developer Account -* Have an iOS device for testing the iOS package that will be produced -* Have an iOS deployment certificate and a provisioning file for which your device is activated -* Have Xcode installed on your computer for deploying the iOS package to your test device - -If you plan to deploy your app for testing on an Android device, make sure you have an Android device available. - -## Getting Your Tokens {#getting-your-tokens} - -To use the Mendix Native Mobile Builder, you will first need to get tokens to authenticate with GitHub and App Center. If you already have tokens for your GitHub and App Center, you do not need to complete the **Getting Your Token** sections. - -### GitHub Token {#github-token} - -1. Go to [GitHub](https://github.com/) and sign in. -2. Go to [Settings](https://github.com/settings/profile) by clicking your profile picture in the upper-right corner of the page. -3. Click [Developer settings](https://github.com/settings/apps) at the bottom of the left menu. -4. Navigate to [Personal access tokens](https://github.com/settings/tokens) and then click **Generate new token** to create a new personal access token. -5. In the **Note** field, write *Native Mobile Builder*. -6. Under **Select scopes**, select **repo** and **workflows**. -7. Click **Generate token**. -8. Store your token in a secure place. You will not be able to see it again. If you lose it, you will have to create a new token and delete your old one. - -### App Center Token {#appcenter-token} - -1. Go to [App Center](https://appcenter.ms/apps) and sign in. -2. Click your profile icon in the upper-right corner, then click **Settings**, and then **Account Settings**. -3. In the **API Tokens** tab, click **New API token**. -4. Add a description of your token, select **Full Access**, then click **Add new API token**, and then **New API Token**. -5. Store this token in a secure place as well. You will not be able to see it again. If you lose it, you will have to create a new token and delete your old one. - -## Build Your Native App {#building} - -{{% alert color="info" %}} -The Mendix Native Mobile Builder needs to communicate with GitHub and App Center. Therefore, make sure your firewall permissions do not restrict the tool. -{{% /alert %}} - -From Studio Pro: - -1. Click **Project** > **Build Native Mobile App**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/start-nbui.png" alt="Start Mendix Native Mobiler Builder" width="350" class="no-border" >}} - -1. When Mendix Native Mobile Builder launches you will see the home screen: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/home-screen.png" alt="Mendix Natve Mobile Builder Home Screen" width="350" class="no-border" >}} - -1. Select **Build app for distribution**. -1. Fill in your app's name and the app identifier. The wizard provides defaults, but you might want to align the app identifier to use your company's reversed URL, or change the app name to something besides the project name: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/wizard-app-details.png" alt="Wizard App Details" width="350" class="no-border" >}} - -1. Click **Next Step** when ready. -1. In the **Tokens** screen fill in your GitHub and App Center API tokens. The tool will verify the tokens grant sufficient access to valid accounts and will notify you if they do not: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/wizard-tokens.png" alt="Wizard Tokens" width="350" class="no-border" >}} - -1. Click **Next Step** when ready. -1. Select **Choose your icon** if you already have an image you would like to use as an icon. If you continue without adding a custom image, your app will use the default images displayed below. You can change app icon later if you wish: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/wizard-icons.png" alt="Wizard Icons" width="350" class="no-border" >}} - -1. Click **Next Step** when ready. -1. Select **Choose your splash screen** if you already have an image you would like to use as a splash screen, or just continue if you are satisfied using the default image. You can change the splash screen later if you wish: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/wizard-splashscreens.png" alt="Wizard Splash screen" width="350" class="no-border" >}} - -1. Click **Next Step** when ready. -1. Drag your custom fonts into the field if you already have a selection of fonts you would like to use, or continue if you do not need to add custom fonts. You can add custom fonts later if you wish: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/wizard-fonts.png" alt="Wizard Fonts" width="350" class="no-border" >}} - -1. Click **Next Step** when ready. - -You have completed the mandatory basic app configuration required to build your project. Now you see the **Build app for distribution** screen: - -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app.png" alt="Build release app" width="350" class="no-border" >}} - -Next, do the following: - -1. Fill in an intentional version number. For defaults, we reccomend you use these numbering guidelines: - - * Versions lower than 0.5.0 for alpha releases - * Versions ranging from 0.5 to 0.9.x for beta releases - * Versions starting from 1.0.0 for release - -1. Fill in your **Runtime URL**. It can be the IP of your local machine if you plan on testing against a locally-running Studio Pro installation. If you already deployed your app to Mendix Cloud, you can point it to the URL of the deployed runtime as found in Cloud Portal. -1. Click the **Build** button to start the build. -1. The tool will set up your GitHub repository, commit your changes, configure App Center with two new projects (one for iOS and one for Android), and continue building your apps: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app-build-step1.png" alt="Setting up build prerequisites" width="350" class="no-border" >}}{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app-build-step1.png" alt="Setting up build prerequisites" width="350" class="no-border" >}} - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app-build-step2.png" alt="Building release app" width="350" class="no-border" >}} - -1. After the build completes you can scan the QR code provided to install the app on your device. Currently the QR code service is only supported for Android devices: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app-build-done-both.png" alt="Build completed" width="350" class="no-border" >}} - -## Signing Your Apps {#signing-a-build} - -By default, App Center builds are unsigned and cannot be released on the Google Play Store or the Apple App Store. To release your apps, you must provide your signature keys to Mendix Native Mobile Builder. Signature keys prove the authenticity of your app and prevent forgeries. For more information to how to acquire these keys, see the [Managing App Signing Keys Reference Guide](/refguide8/managing-app-signing-keys/). - -### Set Up Signing for iOS {#signing-for-ios} - -iOS supports two types of signing configurations: **Development** and **Release**. The type of the build depends on the type of provisioning file and certificate that was used for configuring the tool. To set up signing for iOS, follow these steps: - -1. From within Mendix Native Mobile Builder, select **iOS** under **Certificates**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app.png" alt="Build release app" width="350" class="no-border" >}} - -1. Upload your provisioning file and P12 certificate, and then type in your password. The tool will verify that: - - * The app identifier of the app is included in the Provisioning file - * The Certificate is included in the Provisioning file - * The password can unlock the certificate - - If the tool errors, please correct the issue and try again: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/signing-ios.png" alt="Signing iOS" width="350" class="no-border" >}} - -1. Click **Save**. - -With that you have completed setting up signing for iOS. Your next build will use the provided configuration to sign your iOS app. - -### Set Up Signing for Android {#signing-for-android} - -1. From within Mendix Native Mobile Builder, choose **Android** under **Certificates**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app.png" alt="Build release app" width="350" class="no-border" >}} - -1. Upload your keystore file and provide the keystore password, the key alias and the key password as defined when setting up the keystore. The tool will verify that: - - * The keystore password is valid - * The key alias exists in the provided keystore - - If it errors, please correct the issue and try again: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/signing-android.png" alt="Signing iOS" width="350" class="no-border" >}} - -1. Click **Save**. - -With that you have completed setting up signing for Android. The next build will use the provided configuration to sign your Android app. - -## Distributing {#distributing} - -This section will guide you in distributing your binaries, setup, signing for [iOS](#signing-for-ios) and [Android](#signing-for-android) using your release certificates and keystore, and building your binaries. - -For distributing to a specific platform, consult the appropriate section below: - -* [Distributing for Android](#android-distributing) -* [Distributing for iOS](#ios-distributing) - -### Distribute the iOS app to App Store Connect {#ios-distributing} - -Depending on whether you chose to sign your iOS app or not, the output of the build will be an *IPA* or *XCArchive* file, respectively. *IPA* files can be directly distributed to App Store Connect for further processing. *XCArchives* require Xcode to sign and generate an *IPA* before they can be further processed. - -#### Distribute a Signed IPA - -To be able to upload your app to App Store Connect, you will have to have set up a new app using the App Store Connect website. While there, use the **app name** and **app id** you used to build your app. For further instruction, see the [App Store Connect Guide to adding a new app](https://help.apple.com/app-store-connect/en.lproj/static.html#devbec4892b7). - -When signing your iOS app, an *IPA* file is generated. To upload an *IPA* to the Apple App Store, Xcode includes a command line tool. Assuming Xcode is installed and the extra command line tool is set up, the command to upload the *IPA* is the following: - -```text -xcrun altool --upload-app --type ios --file "path/to/application.ipa" ---username "YOUR_APPSTORE_USER_EMAIL" --password "YOUR_APPSTORE_PASSWORD" -``` - -Replace `file "path/to/application.ipa"` with the absolute path to your IPA file, `username` with your developer app store email address, and `password` with your Apple App Store password. - -The command will first verify your IPA is packaged correctly and ready to be shipped, and then will then upload it to TestFlight for further processing. - -#### Distributed an Unsigned XCArchive - -Local signing is useful if you only want to test your app on a device, or you do not have a distribution certificate and have run out of build minutes on App Center when signing with a developer certificate. - -In order to deploy the *nativeTemplate.xcarchive* on a device or on the Apple App Store, an Apple developer account and development team is required. If one is available, do the following: - -1. Using Xcode, double-click the *nativeTemplate.xcarchive* file. It should open with the built-in **Application Loader** software. -1. Click the *Distribute App* button to start the local signing flow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-1.png" alt="Xcode Application loader" width="350" class="no-border" >}} - -1. Select **Development**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-2.png" alt="Xcode Application loader" width="350" class="no-border" >}} - -1. Choose a **Development Team**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-3.png" alt="Xcode Application loader" width="350" class="no-border" >}} - -1. Configure your **Development distribution options**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-4.png" alt="Xcode Application loader" width="350" class="no-border" >}} - -1. Select a re-signing option: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-5.png" alt="Xcode Application loader" width="350" class="no-border" >}} - -1. Review your *.ipa* content and click **Export**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-6.png" alt="Xcode Application loader" width="350" class="no-border" >}} - -Congratulations. You now have a signed *.ipa* file: - -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-7.png" alt="Xcode Application loader" width="350" class="no-border" >}} - -### Distribute the Android app to Google Play {#android-distributing} - -A signed Android APK can be uploaded to Google Play store directly. For more info on setting up a new app and uploading your binaries follow Google's guide on [Uploading an app](https://support.google.com/googleplay/android-developer/answer/113469?hl=en). - -## Read More - -* [How To Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/how-to-devapps.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/how-to-devapps.md deleted file mode 100644 index 933abe5cd4b..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/how-to-devapps.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: "Create a Custom Developer App" -url: /howto8/mobile/how-to-devapps/ -weight: 50 -description: A tutorial for creating custom developer apps. ---- - -## Introduction - -As your Mendix app matures, you may want to expand its functionality (such as by introducing custom widgets or logic that will require new native dependencies). One such customization could be adding a near-field communication (NFC) module to your app. While the Make It Native app suffices for testing basic apps, as your app adds custom dependencies—like custom native widgets or fonts—you will need a more tailored developer app. - -A custom developer app helps you by serving as a replacement for the Make It Native app, and should be used when you have custom widgets and logic which are not supported by the Make It Native app. Custom developer apps are apps you can generate yourself using your current project structure, your custom modules, and any other requirements to test your evolving app. Custom developer apps feature the same functionality as the Make It Native app but are tailored to your needs. - -## Prerequisites - -* Complete [How to Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) -* Complete the Mendix Native Mobile Builder wizard as found in [Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) - -## Build Your Developer App {#build-your-developer-app} - -1. Run Mendix Native Mobile Builder from your project: -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/start-nbui.png" alt="Start Mendix Native Mobile Builder" class="no-border" >}} - -1. When Mendix Native Mobile launches you are greeted with the home screen: -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/home-screen.png" alt="Mendix Native Mobile Builder Home Screen" class="no-border" >}} - -1. Choose *Build app for local development* -1. Given you already went through the initial wizard at least once, you should be greeted with the configuration screen for *Building an app for local development*: -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/how-to-devapps/build-custom-dev-app.png" alt="Mendix Native Mobile Builder Home Screen" class="no-border" >}} -1. Click the *Build developer app* button -1. The tool will set up your GitHub repository commit your changes, configure App Center if needed with two new projects, one for iOS and one for Android and continue with building the apps. -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app-build-step1.png" alt="Building" class="no-border" >}} -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app-build-step2.png" alt="Build release app" class="no-border" >}} - -1. When the build completes, you can scan the QR code provided to install the app to your device. Currently the QR code service is only supported for Android devices. -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/build-release-app-build-done-both.png" alt="Build release app" class="no-border" >}} - -## Installing Your Custom Developer App Manually - -### Android - -For Android the output of the build is an *APK* file. *APK* files can be directly installed on devices or emulators. - -#### Installing on an Emulator - -With your emulator running, install your app in your emulator by doing the following: - -1. Drag the *APK* onto the emulator's window. -2. Wait for the installation to be done. -3. Open the app from the launcher. - -#### Installing on a Device - -There are various ways install an app on a device. Installing using a USB is detailed below, but you can use a different method if it suits you. Do the following to install your *APK* onto a device: - -1. Connect your device to your machine via USB. -2. Enable file transfer on your device (differs per device). -3. Open **This PC** in File Explorer; your device should be listed as an external device. -4. Drag your *APK* onto your device. -5. Wait for it to finish transferring. -6. Open your device's file manager. -7. Navigate to the root of the file system. -8. Tap the *APK* to install. -9. Go through the installation steps. -10. Open the app from the launcher. - -### iOS - -By default your custom developer app will be unsigned. To get a signed *IPA*, follow the steps in the [Signing Your Build](/howto8/mobile/deploying-native-app/#signing-a-build) section of *How to Build a Mendix Native App in the Cloud*. Your custom developer app branch is named **developer**. - -The unsigned output of an iOS build is an *XCArchive* file. *XCArchive* files require manual signing before they are ready to be installed on a device. - -The signed output of iOS build is an *IPA* file. If correctly signed, *IPA* files can be installed on physical devices. - -#### Installing on an Emulator - -Before installing, make sure you have completed the following prerequisites: - -* Have a Mac OSX machine -* Install LTS builds of Node.js and NPM (download [here](https://nodejs.org/en/)) -* Install Cocoapods ([installation instructions](https://cocoapods.org/#install)) -* Install the latest Xcode version - -Builds with the Mendix Native Mobile Builder are stripped of simulator artifacts. Therefore, to run on Xcode's Simulator you will have to build the developer branch locally from source by completing these steps: - -1. Navigate to your GitHub repo. -2. Switch to your **developer** branch: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli/github-branch-switching.png" alt="Switch branch on GitHub" class="no-border" >}} - -3. Click **Clone or Download** and then click **Download ZIP**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli/github-download-branch.png" alt="Download repository" class="no-border" >}} - -4. Unzip the downloaded archive. -5. Open a terminal and change directory into the folder. -6. Run this command: - - ```shell - npm i && cd ios && pod install - ``` - - This will install the node module dependencies and the iOS Dependencies -7. In the **ios** folder, open the **NativeTemplate.xcworkspace** file: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli/ios-folder.png" alt="iOS folder structure" class="no-border" >}} - -8. In Xcode select the **Dev** target and the emulator you want to build your developer app for: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli/xcode-target-selection.png" alt="Dev target selection" class="no-border" >}} - -9. Click **Play**. - -#### Distributing the Custom Developer App - -To run your custom developer app on a device which is not a test device, you will have to sign the developer app with your certificates. - -If you want Native Builder to sign your custom developer app, follow the steps in the [Signing Your Build](/howto8/mobile/deploying-native-app/#signing-a-build) section of *How to Build a Mendix Native App in the Cloud*. - -## Read More - -* [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* [How to Use Over the Air Updates](/howto8/mobile/how-to-ota/) diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually.md deleted file mode 100644 index 0cd4bf3824a..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -title: "Build a Mendix Native Mobile App Locally Manually" -linktitle: "Local Native Mobile App Manual Build" -url: /howto8/mobile/native-build-locally-manually/ -weight: 30 -description: Describes how to build your first Mendix native mobile app locally manually. ---- - -{{% alert color="info" %}} -When Mendix Native Mobile Builder identifies a Mobile Toolkit capable Native Template version (v5.1.9 and above), it will not apply changes directly to the project. To apply the changes when building locally check out your latest changes, run `npm install` (for NPM v7 and above run `npm install --legacy-peer-deps`), then make sure to run `npm run configure`. -{{% /alert %}} - -## Introduction - -By default when building your native mobile app binaries, Mendix uses [Visual Studio App Center](https://appcenter.ms/sign-in?original_url=%2Fapps) as a service so that users can build without having to install tools like Xcode or Android Studio. However, there are cases when using App Center is not allowed or possible. In those situations, you can build your apps locally without an internet connection. - -Follow the sections below through [Building Your Native App](#building-app-project) to complete your builds. To go beyond those instructions, see [Adding Dependencies](#adding-dependencies) and [Removing Dependencies](#removing-dependencies) sections below. These sections will allow you to further customize your local builds. - -To understand the local build process, it is important to grasp a few basic concepts. Mendix native mobile apps are first and foremost React Native (RN) apps which follow the same rules as other RN apps: - -* The JS code and static assets need to be bundled together for RN to use -* The bundled code and assets are put into a React Native Template that represents an iOS and Android app - -In a similar fashion, MxBuild and the Mendix Native Template follow these rules: - -* When using MxBuild, the JS code and static assets are bundled together -* The bundled code and assets are put into the Mendix Native Template that provides a foundation for both an iOS and Android version of your app - -## Prerequisites {#prerequisites} - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install [Node and NPM](https://nodejs.org/en/download/) - -For iOS builds: - -* Have a Mac OS X machine -* Install the latest version of [Xcode](https://developer.apple.com/xcode/resources/) and [CocoaPods](https://guides.cocoapods.org/using/getting-started.html) - -For Android Builds: - -* Install [Android SDK](https://developer.android.com/studio) and [platform tools](https://developer.android.com/studio/releases/platform-tools) - -## Getting the Native Template - -The Native Template is the base for building native mobile apps with Mendix. In essence, it is a React Native template with the extra dependencies and configurations required to run your Mendix app. - -The Native Template is versioned against Mendix Studio Pro. This means the Studio Pro version you use to create your Mendix app dictates which version of the Native Template you should use. When using the Native Mobile Builder this is handled automatically when the tool is started form Studio Pro. - -### Determining Which Native Template Version to Use - -To determine which version of the Native Template you should use, do the following: - -1. Note which version of Studio Pro you are using. -1. Navigate to the [Native Template GitHub repository](https://github.com/mendix/native-template). -1. At the root of your project, open the *mendix_version.json* JSON file. - -The keys of the dictionary represent the Mendix Studio Pro version. The `min` and `max` values are the minimum and maximum Native Template versions supported: - -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/mendix-version.png" alt="iOS output" width="200" class="no-border" >}} - -So like in the example picture shown above, in the case of Mendix Studio Pro 8.9.x, you could choose any Native Template version from 4.0.0 to the latest. Ideally you should choose the most recent supported version. - -There is no best way of getting a copy of the Native Template. In the following sections we provide two ways to get the version you need. - -#### Getting the Native Template Using the Git CLI - -This method is useful if you have Git installed. To get the Native Template, do the following: - -1. Use `git@github.com:mendix/native-template.git` or `https://github.com/mendix/native-template.git` to clone the app locally. -1. Run the following command: `git clone --single-branch --branch release/ `. - -The final step differs based on your machine: - -For a Windows machine building an Android app, do the following: - -1. Run `npm i` to install the required dependencies. - - {{% alert color="info" %}}When Mendix Native Mobile Builder identifies a Mobile Toolkit capable Native Template version (v5.1.9 and above), it will not apply changes directly to the project. To apply the changes when building locally check out your latest changes, run `npm install`, then make sure to run `npm run configure`.{{% /alert %}} - -2. Instances of the Native Template v5.1.9 and higher include the Native Mobile Toolkit. Therefore, if you are using one of these versions you also must run the npm run configure command. This ensures that the changes from the Mendix Native Mobile Builder are applied to your project. - -For a Mac OS X machine building an iOS app, do the following: - -1. Run `cd ios && pod install` to install the required dependencies. - -#### Getting the Native Template by Downloading the Source Code from GitHub - -This method is useful if you do not have Git installed. To get the Native Template, do the following: - -1. Navigate to the [Native Template releases](https://github.com/mendix/native-template/releases). -1. Scroll to the version you want to download. -1. Select the source code binary to download a copy of the code: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/github-assets.png" alt="iOS output" width="250" class="no-border" >}} - -1. Unzip the file. -1. Run `npm i && cd ios && pod install` to install the required dependencies. - -Now that you have a copy of the Native Template checked out and ready, you can bundle your Mendix app, move it into the Native Template folder, and compile everything together to produce your finished native app. - -## Bundling Your Mendix App - -Bundling is the process of packaging everything you created in Studio Pro and making that package ready to be compiled into your native mobile app. Bundling in the case of a React Native app, and hence a Mendix Native App, includes transpiling the business logic and layout of your app into a JavaScript bundle and gathering all your static resources into the correct folder structure. - -For bundling your resources, Mendix Studio Pro comes with a helpfull tool called [MxBuild](/refguide8/mxbuild/). MxBuild can be found relatively to the location of the Studio Pro executable (for example *C:\Program Files\Mendix\Studio Pro (version)\mxbuild.exe*). - -1. Run the following command: - - ```shell - mxbuild.exe --java-home="JDKDirectory" --java-exe-path="javaExecutable" --target=deploy --native-packager --loose-version-check [path-to-project-mpr-file] - ``` - -The bundles will be generated relatively to the `project-directory\deployment\native\bundles` - -1. Run MxBuild against your project to generate the required bundle and assets. - -When completed there should be a folder under the project's deployment folder `project-directory\deployment\native\bundles` with two folders. One named `ios`, and one named `android`: - -1. Move the ios folder's content to *{your Native Template root}/ios/Bundle*. -1. The `android` folder structure should be the following: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/android-output.png" alt="iOS output" width="250" class="no-border" >}} - -1. Move the folder's content to *{your Native Template root}/android/app/src/main*. Choose to overwrite if requested to do so. -1. Open *{your Native Template root}/android/app/src/main/res/raw/runtime_url* using a text editor. -1. Replace the URL with the correct URL for your runtime. -1. Open *{your Native Template root}/ios/Config/config.xcconfig*, then replace the value of `RUNTIME_URL=` with the correct URL for your runtime. - -Congratulations! You have successfully completed the basic setup of a Native Template with the latest bundle and assets of your Mendix app. - -## Building Your Native Mobile App {#building-app-project} - -Now that the Native Template is ready and includes the app's bundle, resources, and runtime URL configuration, it can be built into a native app. To build your project you can open the app with Android Studio or Xcode for the Android and iOS project respectively, and then build as normal. More advanced use cases, such as apps for continuous integration pipelines, can make use of Gradle or xcodebuild to build the apps using command line. - -In the sections below you can see the basic steps to get an app up and running on an emulator or device using Android or iOS IDEs. - -### Building an Android App with Android Studio - -{{% alert color="warning" %}} -During this process, do not accept any suggestions to update to latest Gradle or Kotlin version. -{{% /alert %}} - -To build an Android app with Android Studio, do the following: - -1. Run `npm install` (for NPM v7 and above run `npm install --legacy-peer-deps`) in the app root to install the required dependencies. -1. Open Android Studio. -1. Select the `/android` as the entry point for the app. -1. After synchronizing the app your Android Studio should look something like this (remember to not accept any suggestions to update to latest Gradle or Kotlin version): - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/as-home.png" alt="Android Studio" width="350" class="no-border" >}} - - Mendix native mobile apps make use of **Build Variants** to build a release app or a custom developer app. The idea of **Build Variants** is a Gradle build system concept for sharing the same codebase but delivering different experiences. - -1. Choose the **appstoreDebug** variant to be able to build and test your app on an emulator or connected device: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/as-build-variants.png" alt="Android Build Variants" width="350" class="no-border" >}} - -1. After a short time the app should be synchronized and **Run Locally** ({{% icon name="controls-play" %}}) should be selectable. Select a device or create a device from the drop-down menu and click **Run Locally** to build and install your app on the device: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/as-start-build.png" alt="Android Build Toolbar" width="250" class="no-border" >}} - -### Building an iOS App with Xcode - -1. If you have not done so yet, run `npm install` (for NPM v7 and above run `npm install --legacy-peer-deps`) in the app root to install the required dependencies. -1. Change directory by running `cd ios`. -1. Complete one of the two paths below depending on your Mac type. - -**Path 1: Mac Running Apple Silicon (M1)** - -The Native Template does not yet support the ARM 64 Simulator architecture. For this reason, it is required that you install x86 pods and start Xcode with Rosetta: - -1. Ensure you have Rosetta installed on your system (for more information, see this [Apple documentation](https://support.apple.com/en-us/HT211861)). -1. Run `arch -x86_64 pod install` to install the correct type of pods. -1. Right-click on the **Xcode.app** icon and select **Get info**. -1. Select the checkbox **Open using Rosetta**. -1. Start Xcode. - -Xcode will now use x86_64 simulators and building should work as expected. Now that you have set up the 86 pods, click [here](#resume-ios) to skip the second path and resume the build process. - -**Path 2: Mac Running Intel Silicon** - -To build an iOS app with a Mac running Intel Silicon, do the following: - -1. Run `pod install`. -1. Start Xcode. - -The iOS project is using CocoaPods for its dependency management. For more information on installing the CocoaPods dependency manager on your machine see this CocoaPods [documentation](https://cocoapods.org/#install). - -Now that you have completed one of the two paths listed above, you can resume building your iOS app: - -1. Open *.xcodeworkspace* using Xcode. -1. Navigate to **Signing and Capabilities** and choose your **Team** from the drop-down menu: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/xc-setup-team.png" alt="Xcode Build Toolbar" width="350" class="no-border" >}} - - As with the Android **Build Variants** the iOS app makes use of **Build Targets** to switch between building a custom developer app or a release app. - -1. From the drop-down menu, choose **nativeTemplate** and the device you would like to run the app on. Then click **Run Locally** ({{% icon name="controls-play" %}}) to start a build for your app: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/xc-start-build.png" alt="Xcode Build Toolbar" width="250" class="no-border" >}} - -After the build succeeds the app should be running on the selected device and connected to the runtime using the runtime URL you provided. - -## Adding Dependencies{#adding-dependencies} - -At some point you will want to enhance your project with native pluggable widgets and functionality that will require the inclusion of React Native modules and libraries. - -Mendix native mobile apps are build on top of React Native. Therefore, any React Native module can be added and used in a project. The same rules apply as with any React Native project. - -### Adding Dependencies For Native Templates v4.0.0 and Above - -From Native Template v4.0.0 and above Mendix supports RN 0.6.x and therefore auto-linking. Auto linking is a React Native mechanism that allows React Native to link the native dependencies defined in the *package.json* file automatically with the native projects. To add dependencies for Native Template v4.0.0 and above, do the following: - -1. Add the dependency to the root *package.json* of your Native Template using `npm i -s `. -1. If the dependency supports auto-linking when `npm install` (for NPM v7 and above run `npm install --legacy-peer-deps`) is run it will automatically add itself correctly to the Android and iOS project. If the dependency does not support auto-linking or requires more configuration, follow its documentation to add the required entries manually. - -### Adding Dependencies For Native Templates Below v4.0.0 - -Native Template versions below v4.0.0 do not support React Native's auto-linking. Therefore always follow the manual steps of the dependency to add it to the Android and iOS projects. - -## Removing Dependencies{#removing-dependencies} - -As the requirements of a project might change, so do the required native modules and libraries. To avoid bloating your app with unnecessary libraries, consider removing unused libraries. This process is not currently automated and requires a bit of consideration when identifying any unused libraries. - -### Removing Dependencies Which Support Auto-Linking for v4.0.0 and Above - -To remove dependencies which support auto-linking, do the following: - -1. Remove the dependency entry from the *package.json* file. -1. Run `npm i`. - -### Removing Dependencies Which Do Not Support Auto-Linking or for v.3.x and Bellow - -To remove dependencies which do not support auto-linking, do the following: - -1. Remove the dependency's entry from the *package.json* file. -1. Remove the dependency's entry from the *ios/Podfile* file. -1. Remove the dependency's `include` and `project` entries from the *android/setting.gradle*. For example, to remove the Firebase module remove the following: - - ```text - include ':react-native-firebase' - project(':react-native-firebase').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-firebase/android') - ``` - -1. Remove the dependency's `implementation` entry in the *android/app/build.gradle*. For example, to remove the Firebase module remove the following: - - ```text - implementation project(":react-native-firebase") - ``` - -1. Remove any custom code included in the iOS or Android project. - -## Read More - -* [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* [How to Create a Custom Developer App](/howto8/mobile/how-to-devapps/) diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/native-build-locally.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/native-build-locally.md deleted file mode 100644 index daf24bf6522..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/native-build-locally.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: "Build a Mendix Native Mobile App Locally using Mendix Native Builder" -linktitle: "Build Local Native Mobile App" -url: /howto8/mobile/native-build-locally/ -weight: 30 -description: Describes how to build your first Mendix native mobile app locally using the Mendix Native Mobile Builder. ---- - -## Introduction - -{{% alert color="info" %}} -For this how-to, Mendix Studio Pro 8.15.1 is required. If you are using an older Studio Pro version, please use [How to Build a Mendix Native Mobile App Locally Manually](/howto8/mobile/native-build-locally-manually/). -{{% /alert %}} - -By default when building your native mobile app binaries, Mendix uses [Visual Studio App Center](https://appcenter.ms/sign-in?original_url=%2Fapps) as a service so that users can build without having to install tools like Xcode or Android Studio. However, there are cases when using App Center is not allowed or possible. In those situations, you can build your apps locally. - -Follow the sections below through [Building Your Native App](#building-app-project) to complete your builds. For further customization options for your local builds, see the [Adding Dependencies](#adding-dependencies) and [Removing Dependencies](#removing-dependencies) sections below. - -## Prerequisites {#prerequisites} - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Studio Pro 8.15.1 or above -* Install [Node and NPM](https://nodejs.org/en/download/) - -For iOS builds: - -* Have a Mac OS X machine -* Install [Xcode 12.4](https://apps.apple.com/us/app/xcode/id497799835?mt=12) or higher and [CocoaPods](https://guides.cocoapods.org/using/getting-started.html) - -For Android Builds: - -* Install [Android SDK](https://developer.android.com/studio) and [platform tools](https://developer.android.com/studio/releases/platform-tools) - -## Use the Mendix Native Mobile Builder to Set Up Your Local Project - -1. Run the Mendix Native Mobile Builder from your project: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/start-nbui.png" alt="Start Mendix Native Mobile Builder" width="350" class="no-border" >}} - -1. When the Mendix Native Mobile Builder launches you will see the home screen: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/home-screen.png" alt="Mendix Native Mobile Builder Home Screen" width="350" class="no-border" >}} - -1. Select **Build app for distribution**. -1. Fill in your app's name and the app identifier. The wizard provides defaults, but you might want to align the app identifier to use your company's reversed URL, or change the app name in some other way: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/wizard-app-details.png" alt="Wizard App Details" width="350" class="no-border" >}} - -1. Click **Next Step** when ready. -1. In **Build type**, select the **Advanced** checkbox: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally/wizard-buildtype-local.png" alt="Build type" width="350" class="no-border" >}} - -1. Select the folder where you want your project's Native Template to be created. Valid choices are either an empty directory or a directory with a Native Template. -1. Disable any service you do not wish to use. App Center requires GitHub as a service to work. -1. Click **Next Step** until you reach the end of the wizard. Feel free to configure any step as needed. -1. Select **Build type** from the side bar. - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally/advanced-buildtype-local.png" alt="Build type" width="350" class="no-border" >}} - - As you already selected to use the **Advanced** flow with this project it is not possible to switch back to just using **Cloud** services. But you can enable or disable any service as needed. If for instance GitHub is enabled, Native Mobile Builder will synchronize any local changes with your repository the next time you configure your project and commit your changes. But keep in mind that Mendix Native Builder is not a replacement of a Git client, and pushing local changes to a repository can add to the configuration time. - -1. Select **Configure app locally** and fill in the information as needed for your app: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally/advanced-configure-app-locally.png" alt="Build type" width="350" class="no-border" >}} - -1. Click **Configure locally**: - -The process will start and do the following: - -* Run MxBuild to build your project's app bundles -* Checkout the correct version of Native Template for the Mendix Studio Pro version you are using -* Configure the project - -If GitHub is enabled, in addition to the previous steps, it will do the following: - -* Commit the whole local copy to the project's repository - -## Building Your Native Mobile App {#building-app-project} - -Now that the Native Template is ready and includes the app's bundle, resources, and runtime URL configuration, it can be built into a native app. To build your project you can open the app with Android Studio or Xcode for the Android and iOS project respectively, and then build as normal. More advanced use cases, such as apps for continuous integration pipelines, can make use of Gradle or xcodebuild to build the apps using command line. - -In the sections below you can see the basic steps to get an app up and running on an emulator or device using Android or iOS IDEs. - -### Building an Android App with Android Studio - -{{% alert color="warning" %}} -During this process, do not accept any suggestions to update to latest Gradle or Kotlin version. -{{% /alert %}} - -To build an Android app with Android Studio, do the following: - -1. Run `npm install` (for NPM v7 and above run `npm install --legacy-peer-deps`) in the app root to install the required dependencies. -1. Open Android Studio. -1. Select the `/android` as the entry point for the app. -1. After synchronizing the app your Android Studio should look something like this (remember to not accept any suggestions to update to latest Gradle or Kotlin version): - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/as-home.png" alt="Android Studio" width="350" class="no-border" >}} - - Mendix native mobile apps make use of **Build Variants** to build a release app or a custom developer app. The idea of **Build Variants** is a Gradle build system concept for sharing the same codebase but delivering different experiences. - -1. Choose the **appstoreDebug** variant to be able to build and test your app on an emulator or connected device: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/as-build-variants.png" alt="Android Build Variants" width="350" class="no-border" >}} - -1. After a short time the app should be synchronized and **Run Locally** ({{% icon name="controls-play" %}}) should be selectable. Select a device or create a device from the drop-down menu and click **Run Locally** to build and install your app on the device: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/as-start-build.png" alt="Android Build Toolbar" width="250" class="no-border" >}} - -### Building an iOS App with Xcode - -1. If you have not ran it yet, run `npm install` (for NPM v7 and above run `npm install --legacy-peer-deps`) in the app root to install the required dependencies. -1. Change directory by running `cd ios` and run `pod install` to install the iOS dependencies. - - The iOS project is using CocoaPods for its dependency management. For more information on installing the CocoaPods dependency manager on your machine see CocoaPods [documentation](https://cocoapods.org/#install). - -1. Open *.xcodeworkspace* using Xcode. -1. Navigate to **Signing and Capabilities** and choose your **Team** from the drop-down menu: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/xc-setup-team.png" alt="Xcode Build Toolbar" width="350" class="no-border" >}} - - As with the Android **Build Variants** the iOS app makes use of **Build Targets** to switch between building a custom developer app or a release app. - -1. From the drop-down menu choose **nativeTemplate** and the device you would like to run the app on, then click **Run Locally** ({{% icon name="controls-play" %}}) to start a build for your app: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-build-locally-manually/xc-start-build.png" alt="Xcode Build Toolbar" width="250" class="no-border" >}} - -After the build succeeds the app should be running on the selected device and connected to the runtime using the runtime URL you provided. - -## Adding Dependencies{#adding-dependencies} - -At some point you will want to enhance your project with native pluggable widgets and functionality that will require the inclusion of React Native modules and libraries. - -Mendix native mobile apps are build on top of React Native. Therefore, any React Native module can be added and used in a project. The same rules apply as with any React Native project. - -### Adding Dependencies For Native Templates v4.0.0 and Above - -From Native Template v4.0.0 and above Mendix supports RN 0.6.x and therefore auto-linking. Auto linking is a React Native mechanism that allows React Native to link the native dependencies defined in the *package.json* file automatically with the native projects. To add dependencies for Native Template v4.0.0 and above, do the following: - -1. Add the dependency to the root *package.json* of your Native Template using `npm i -s `. -1. If the dependency supports auto-linking when `npm install` (for NPM v7 and above run `npm install --legacy-peer-deps`) is run it will automatically add itself correctly to the Android and iOS project. If the dependency does not support auto-linking or requires more configuration, follow its documentation to add the required entries manually. - -### Adding Dependencies For Native Templates Below v4.0.0 - -Native Template versions below v4.0.0 do not support React Native's auto-linking. Therefore always follow the manual steps of the dependency to add it to the Android and iOS projects. - -## Removing Dependencies{#removing-dependencies} - -As the requirements of a project might change, so do the required native modules and libraries. To avoid bloating your app with unnecessary libraries, consider removing unused libraries. This process is not currently automated and requires a bit of consideration when identifying any unused libraries. - -### Removing Dependencies Which Support Auto-Linking for Native Templates v4.0.0 and Above - -To remove dependencies which support auto-linking, do the following: - -1. Remove the dependency entry from the *package.json* file. -1. Run `npm i`. - -### Removing Dependencies Which Do Not Support Auto-Linking or for Native Templates v.3.x and Below - -To remove dependencies which do not support auto-linking, do the following: - -1. Remove the dependency's entry from the *package.json* file. -1. Remove the dependency's entry from the *ios/Podfile* file. -1. Remove the dependency's `include` and `project` entries from the *android/setting.gradle*. For example, to remove the Firebase module remove the following: - - ```text - include ':react-native-firebase' - project(':react-native-firebase').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-firebase/android') - ``` - -1. Remove the dependency's `implementation` entry in the *android/app/build.gradle*. For example, to remove the Firebase module remove the following: - - ```text - implementation project(":react-native-firebase") - ``` - -1. Remove any custom code included in the iOS or Android project. - -## Read More - -* [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* [How to Create a Custom Developer App](/howto8/mobile/how-to-devapps/) diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/native-debug.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/native-debug.md deleted file mode 100644 index 614fdd889b0..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/native-debug.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "Debug Native Mobile Apps (Advanced)" -url: /howto8/mobile/native-debug/ -weight: 40 -description: A how-to for debugging native mobile apps using the Make It Native app. ---- - -## Introduction - -When changing your native mobile app or designing a custom widget, you may need to debug your implementation. The Make It Native app exposes a developer mode which supports debugging native mobile apps for expert developers. Using Google Chrome is recommended for this, as it starts automatically during debugging. - -## Debugging Your Native App - -To start a debugging session, do the following: - -1. Run your Mendix app locally on your desktop. -2. Start the Make It Native app. -3. Select **Enable dev mode** in the Make It Native app. -4. Start your app on your mobile device in Mendix Studio Pro by clicking **View** > **View in the Mendix App**. -5. With your mobile device, tap **Scan QR code**, then scan the QR code on your desktop. - -When the Make It Native app finishes loading your app, do the following: - -1. Open the developer menu by using a three-finger long press. -2. Tap **Enable Remote js Debugging**. - -Your mobile app should start reloading, and a Chrome window should launch on your desktop pointing to a debugging address. Change the address in your browser's navigation bar to *localhost:8083/debugger-ui* manually and go to that page. - -If Chrome launches but does not load your app, check that your app is running in Mendix Studio Pro. If it is, click the **Stop** button, then click **Run Locally** ({{% icon name="controls-play" %}}) again to restart your app. - -You should see this page: - -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-debug/debug-waiting.png" alt="debug waiting" class="no-border" >}} - -If the status remains at **Waiting**, use the reload command (pictured above) to refresh your app. The **Waiting** status should change and indicate an **active** session: - -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-debug/debug-active.png" alt="debug active" class="no-border" >}} - -Your browser's debugging tools should be pointing to your app. Now, you can debug your app like you would any other web app. - -Other tools can help you debug Mendix apps, such as the [Using React Developer Tools](#rn-dev) section below. Regardless of which tool you use, remember that Mendix uses a different port (8083) than a default React Native installation would (8080). - -### Using React Developer Tools{#rn-dev} - -React Developer Tools is [an app](https://github.com/facebook/react/tree/main/packages/react-devtools) which will allow you to see investigate the way your native page is rendering, adjust things like spacing in a live editor, and inspect the state and props of your pluggable and native widgets. To proceed, you must also have [Node and NPM](https://nodejs.org/en/download/) installed. - -You can consult Facebook's [official documentation](https://reactnative.dev/docs/debugging) for extra information, but this document teaches you the basics of using React Developer Tools. - -To install React Developer Tools, do the following: - -1. Open your CLI and run NPX (an executable runner for NPM) with this code: `npx react-devtools@^3`. The `@^3` ensures compatibility with Mendix's React Native version. - -#### Debugging with iOS Simulator and Android Emulators - -Open your native app in iOS Simulator or Android emulator and then do the following: - -1. Select **Enable dev mode** on your native app. -2. Run `npx react-devtools@^3`. -3. React Developer Tools will launch and connect to Simulator. You can now inspect and modify the React Native elements the same way you could modify HTML elements in Chrome: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-debug/simulator-rn-dev.png" alt="debug simulator" width="350" class="no-border" >}} - -4. In the Make It Native App, use a three-finger tap to **Toggle Element Inspector** and enable enhanced inspection capabilities. - -#### Debugging with the Make It Native App - -To use the Make It Native app with React Developer Tools, do the following: - -1. Connect your mobile device to your laptop with a USB cord. -2. Run `adb devices` to ensure your device is listed. -3. Start your native app on your device with **Enable dev mode** selected. -4. Run `npx react-devtools@^3`. -5. Run `adb reverse tcp:8097 tcp:8097` to allow the applet to interact with your device. -6. React Developer Tools will launch and connect to your device. You can now inspect and modify the React Native elements the same way you could modify HTML elements in Chrome: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/native-debug/min-app-rn-devtools.png" alt="debug min app" width="350" class="no-border" >}} - -## Debugging Your Styling - -With the Make It Native app, you can examine your styling and the structure of your pages. This makes it easier to debug, test, and inspect styling. Inspect and debug your styling by doing the following: - -1. Install the LTS of [Node.js](https://nodejs.org/en/). -2. Open your command-line interface (CLI). -3. Run `npm i -g react-devtools@3` to install the React developer tools. -4. Run `react-devtools`. - -After running `react-devtools` you will see the React developer tools GUI. To use the tools to debug your styling, do the following: - -1. Open your app in the Make It Native app with **Enable dev mode** selected. -2. When running your app, shake your device to open developer settings. -3. Tap **Toggle Element Inspector** to start inspecting. -4. Tap any styled element in your app (like a text element) to see its style information on your device and inspect and debug it in your React developer tools GUI. -5. Shake your device and tap **Toggle Element Inspector** to turn off the inspector off. - -## Debugging the OS Logs - -When your Mendix app is crashing or the logging in Mendix Studio Pro is incomplete, you might want to dive into your operating system's log files for information. There are 2 options: - -1. You could start the app in [Xcode or Android Studio](/howto8/mobile/native-build-locally/#building-app-project), either of which will give you more information and allow you to set breakpoint and inspect variable values. This approach is a bit more cumbersome. -1. Get the log files directly from your device. - -The first approach is self-explanatory. For information on getting log files directly from your device, however, see below. - -### Using Android Logcat - -The Android Debug Bridge (ADB) can get the log files via command line (specifically logcat) by following these steps: - -1. Set up your phone:
- 1. If not already, enable **Developer Mode** by opening **Settings** > **System** and tap 7 times om the **Build Number**.
- 1. In **Settings** open the **Developer Options**.
- 1. Enable **USB Debugging**. -1. Download the [Latest Android Tools](https://dl.google.com/android/repository/platform-tools-latest-windows.zip) for Windows. -1. Unzip the files in a working directory, for example **C:\adb**. -1. Open a command line tool the in the working directory. -1. Execute the command `adb start-server`. -1. Connect your phone via USB, then accept the **Allow USB debugging?** dialog box on your phone. -1. Execute the command `adb logcat > output.txt`. All output will be written in *output.txt*. -1. Open your Mendix app and implement the actions that you want to debug. -1. Stop the log capturing in your command line tool by pressing Ctrl + C. -1. Open *output.txt* in a text editor. -1. Search for your issue. - -For more detailed steps how to set up ADB, see [Install ADB](https://www.xda-developers.com/install-adb-windows-macos-linux/). To learn more about ADB in general, see [Command ADB](https://developer.android.com/studio/command-line/adb). - -## Read More - -* [Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) -* [Debug a Hybrid Mobile App](/howto8/mobile/debug-a-mobile-app/) -* [Configure Parallels](/howto8/general/using-mendix-studio-pro-on-a-mac/) diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/_index.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/_index.md deleted file mode 100644 index 54e0e91d6b8..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/_index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Build Apps Using the Native Builder CLI" -linktitle: "Build Apps Using Native Builder CLI" -url: /howto8/mobile/use-cli-docs/ -weight: 89 -description: Tutorials for building native mobile apps using the Native Builder CLI. ---- - -For most app building Mendix recommends using the Native Builder UI tool included in Mendix Studio Pro 8.15 and above. However, certain use cases require you use the Native Builder CLI tool. - -These step-by-step guides teaches you how to build native mobile applications using the Native Builder CLI: - -* [How to Deploy Your First Mendix Native Mobile App with the Native Builder CLI](/howto8/mobile/deploying-native-app-cli/) – Go from a blank slate to an app running on a device. -* [How to Create a Custom Developer App with the Native Builder CLI](/howto8/mobile/how-to-devapps-cli/) – Create a custom developer app: a substitute for the Make It Native app which accommodates custom dependencies such as native widgets or fonts. -* [Release Over the Air Updates with App Center's CodePush using the CLI](/howto8/mobile/how-to-ota-cli/) - Make your over the air updatable using App Center's CodePush service and Native Builder CLI. diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli.md deleted file mode 100644 index ad22c08f82a..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli.md +++ /dev/null @@ -1,445 +0,0 @@ ---- -title: "Deploy Your First Mendix Native Mobile App with the Native Builder CLI" -linktitle: "Deploy Mobile App with Native Builder CLI" -url: /howto8/mobile/deploying-native-app-cli/ -weight: 20 -description: Describes how to build a Mendix native app in the cloud with the Native Builder CLI. ---- - -{{% alert color="warning" %}} -The Native Builder CLI has been deprecated in favor of the Mendix Native Mobile Builder, a UI tool, that integrates with Studio Pro. Read more on how to deploy your app [here](/howto8/mobile/deploying-native-app/). -{{% /alert %}} - -{{% alert color="warning" %}} -Please update to Native Builder v3.2.2. Native Builder v3.2.2 includes the fixes required to addresses GitHub's transition from using **master** to using **main** as its default repository branch name. -{{% /alert %}} - -## Introduction - -This how-to teaches you how to go from a blank slate to an app running on a device. - -Every Native Builder project has configurations. These configurations are useful for preparing your app, and then creating builds on App Center and GitHub respectively. Configurations are also critical for making updates to apps already delivered to production devices. For more information on the Native Builder's capabilities, see the [Native Builder Reference Guide](/refguide8/native-builder/). The native build process will use your local application, create a repository on GitHub, have App Center use the GitHub repo, build an *.apk*, then download that *.apk* to your local storage. - -## Prerequisites {#prerequisites} - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Read [How to Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) to see how to create, style and debug an application with Mendix Studio Pro -* Deploy your native mobile app to the cloud via Studio Pro and have the cloud address of your deployed application available -* Learn how to use Windows' command line interface (CLI) program `cmd` -* Install [Java JDK 11](https://adoptopenjdk.net/) (if you have Studio Pro installed, you should already have JDK 11 in *C:\Program Files\AdoptOpenJDK*) -* Download the Native Builder [executable](https://www.dropbox.com/sh/hpw7sshut9bco68/AABackrr75rPSgW7u5LBMkMra?dl=0) to a folder of your preference and extract all contents -* Use v1.0.0 with Mendix 8.0 -* Use v2.0.0 with Mendix 8.1.0 and above -* Use v3.0.0 with Mendix 8.3.0 and above -* A [GitHub](https://github.com/) account. -* An [App Center](https://appcenter.ms/) account. Mendix recommends a paid account if you will be building and deploying regularly. - -### Platform-Specific Prerequisites - -If you plan to deploy your app for testing on an iOS device, make sure you have completed the following prerequisites: - -* Register for an Apple Developer Account -* Have an iOS device for testing the iOS package that will be produced -* Have an iOS deployment certificate and a provisioning file for which your device is activated -* Have Xcode installed on your computer for deploying the iOS package to your test device - -If you plan to deploy your app for testing on an Android device, make sure you have an Android device available. - -## Getting Your Tokens - -To use the Native Builder, you will first need to get tokens to authenticate with GitHub and App Center. If you already have tokens for your GitHub and App Center, you do not need to repeat these sections. - -{{% alert color="info" %}} -The Native Builder needs to communicate with GitHub and App Center. Therefore, make sure your firewall permissions do not restrict the Native Builder. -{{% /alert %}} - -### GitHub Token {#github-token} - -1. Go to [GitHub](https://github.com/) and sign in. -2. Go to [Settings](https://github.com/settings/profile) by clicking your profile picture in the upper-right corner of the page. -3. Click [Developer settings](https://github.com/settings/apps) at the bottom of the left menu. -4. Navigate to [Personal access tokens](https://github.com/settings/tokens) and then click **Generate new token** to create a new personal access token. -5. In the **Note** field, write *Native Builder.* -6. Under **Select scopes**, select **repo** and **workflows**. -7. Click **Generate token**. -8. Store your token in a secure place. You will not be able to see it again. If you lose it, you will have to create a new token and delete your old one. - -### App Center Token {#appcenter-token} - -1. Go to [App Center](https://appcenter.ms/apps) and sign in. -2. Click your profile icon in the top right corner, then click **Settings**, and then **Account Settings**. -3. In the **API Tokens** tab, click **New API token**. -4. Add a description of your token, select **Full Access**, then click **Add new API token**, and then **New API Token**. -5. Store this token in a secure place as well. You will not be able to see it again. If you lose it, you will have to create a new token and delete your old one. - -## Preparing Your Project {#preparing} - -The Native Builder uses the `prepare` command as well as a line of parameters in your CLI to specify the details of your build. Below is an example of a `prepare` command with a complete set of parameters: - -```bash -native-builder.exe prepare --project-name CoolApp --java-home "C:\Program Files\Java\jdk-11.0.3" --project-path "Y:\Documents\Mendix\CoolApp\CoolApp.mpr" --mxbuild-path "C:\Program Files\Mendix\8.6.0.715\modeler\mxbuild.exe" --github-access-token b609183aa226a8c2d962700be7a387bd7776e986 --appcenter-api-token 440725eb1311ddfced62894a4d23fc90843370c7 --appcenter-organization "cool-organization" --runtime-url "https://coolapp.mendixcloud.com" --app-name "My Cool App" --app-identifier "com.mendix.coolapp" --mendix-version "8.6.0" -``` - -{{% alert color="info" %}} -To be valid, the `app-identifier` needs to be lower-case with no special characters. -{{% /alert %}} - -The `prepare` command does the following: - -* Generates a private GitHub repository which will house the project's source code and configurations -* Generates two different projects on App Center for Android and iOS respectively -* Modifies the default app icons and splash screen if any are provided -* Modifies the application's name and identifier for both Android and iOS if any are provided -* Modifies the Runtime URL for both Android and iOS if any are provided - -Now you will run your first `prepare` command: - -1. Open your CLI. -2. Change directory to the folder you extracted the Native Builder contents to. -3. Run `prepare` for the first time, which will produce this warning: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/native-builder-authentication-failure.png" alt="App Center authentication failure" class="no-border" >}} - - This warning is part of App Center's security policy. - -4. Visit App Center's [dashboard](https://appcenter.ms/) to see your applications created by the Native Builder: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/appcenter-apps.png" alt="App Center Applications" class="no-border" >}} - -To address the warning, complete the following steps (you must do them for both your iOS and Android apps if you have one of each): - -1. Navigate to [App Center](https://appcenter.ms/). -2. Select your newly created app. -3. Select **Build** on the left panel. -4. You will be greeted with a screen that allows you to link your account with a repository service. -5. Choose **GitHub**. -6. If you are not logged in already you will be asked to sign into your GitHub account. If asked, do so. -7. Select approve in the permission request. -8. Select the repository you want to connect to. -9. You will be redirected back to your App Center account. Your repository’s branches are now listed in the build page. - -{{% alert color="info" %}} -If you run into errors while running the `prepare` command, try running your CLI as an administrator. -{{% /alert %}} - -{{% alert color="info" %}} A free App Center account might run out of build hours. A workaround is to add another organization with another GitHub access token. {{% /alert %}} - -You have successfully prepared your app, and in the next section will make a build from it. - -## Making Your First Build {#first-build} - -To initiate your first build in the Native Builder, you will execute a command in CLI with various parameters included. For more information on parameters, see the [Commands](/refguide8/native-builder/#commands) section in the *Native Builder* guide. While some parameters are optional, two are required: the `--project-name` parameter and the `--build-number` parameter. - -This is an example build command using the two required parameters mentioned above, as well as the optional `--app-version` command (it is best practice to include a [new app version](https://semver.org/) with each release): - -```bash -native-builder.exe build --project-name CoolApp --build-number 1 --app-version 0.1.0 -``` - -Now it is time for you to make your own first build: - -1. Open your CLI. -2. Make sure you are in still in your Native Builder directory. -3. Write this command, with your own information replacing the example text: - - ```text - native-builder.exe build --project-name {ExampleName} --build-number {1} --app-version {0.1.0} - ``` - -4. Run the command. - -This command does the following: - -* Generates a JavaScript deployment bundle and images of the native mobile app from Studio Pro -* Creates a new build branch on GitHub and starts a build process on App Center - -If your `build` command fails citing version conflicts on Java classes, try the following: - -1. Clear your deployment directory. -2. Complete a new build in Studio Pro. -3. Run the `build` command again in the Native Builder. -4. Ensure the version in your `--java-home` file path matches the version being used in Studio Pro. - -### Signing a Build {#signing-a-build} - -By default, App Center builds are unsigned and cannot be released on the Google Play Store or the Apple App Store. To release your apps, you must provide your signature keys to App Center. Signature keys prove the authenticity of your app and prevent forgeries. For more information to how to acquire these keys, see the [Managing App Signing Keys Reference Guide](/refguide8/managing-app-signing-keys/). - -For Android, if you do not intend to publish your app to the Google Play Store, you can skip this section. For iOS, this step prepares an already installable iOS App Store Package (*.ipa*). Without this section's instructions, an unsigned version of an iOS app (*.xcarchive*) would need to be signed manually using Xcode in order to deploy on a device or in the Apple App Store. - -{{% alert color="info" %}} -Currently, the Native Builder is not able to copy signing keys from one branch to another. Therefore you must set up signing for each branch you want to release. When you build with the Native Builder, the build number provided is used to create a new branch with the format **{build/#number}**. When ready to release, set up signing for the build number branch you decided according to this documentation and rebuild with the Native Builder using the branch's build number. -{{% /alert %}} - -To sign your app using App Center, do the following: - -1. Navigate to [App Center](https://appcenter.ms/apps). -2. Select the application you wish to configure. -3. Select **Build** on the left panel. -4. Select the **branch** you would like to configure from the list. - -The next steps differ depending on the type of app you want to configure. - -#### Signing a Build for iOS - -1. Click the **Wrench icon** in the upper-right corner to open the **Build configuration** panel: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/ios-build-wrench.png" alt="Build Wrench" width="400" class="no-border" >}} - -2. Switch the **Sign builds** toggle on: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/ios-sign-upload.png" alt="iOS sign upload" width="400" class="no-border" >}} - -3. Upload your mobile provisioning profile. A **Distribution** profile is best, as App Center has a 30 minute limit for free accounts signing with a **Developer** profile. -4. Upload your *.p12* certificate. -5. Provide the password you used when exporting the *.p12* certificate. -6. Click **Save**, or **Save and build** if you wish to build immediately. - -#### Signing a Build for Android - -1. Select the **Wrench icon** in the upper-right corner to open the **Build configuration** panel: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/android-build-wrench.png" alt="Build Wrench" width="400" class="no-border" >}} - -2. In the **Build Variant** drop-down menu, select **release**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/android-release-variant.png" alt="Android release variant" width="400" class="no-border" >}} - -3. Select **Sign builds**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/android-sign-upload.png" alt="Android sign upload" width="400" class="no-border" >}} - -4. Upload your keystore file. -5. Provide the password to your keystore. -6. Provide the name of your key’s alias. -7. Provide the password of the key’s alias. -8. Click **Save**, or **Save and build** if you wish to build immediately. - -Finally, either start a build for this branch manually or run the `build` command again with the same build number as before: - -```bash -native-builder.exe build --project-name CoolApp --build-number 1 --app-version 0.1.0 -``` - -This allows the Native Builder to build again using the same keys already configured on App Center. - -### Native Builder and App Center Build Phase - -After your start your Native Builder build, you will see some or all of the following: - -* The Native Builder starting a build: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/native-builder-starting-build.png" alt="Native Builder starting a build" width="400" class="no-border" >}} - -* App Center starting a build: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/appcenter-building.png" alt="App Center starting a build" width="400" class="no-border" >}} - -* A successful App Center build: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/appcenter-successful.png" alt="Successful App Center build" width="400" class="no-border" >}} - -* A successful, downloaded Android build: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/native-builder-successful-android.png" alt="Successful and Downloaded Android build" width="400" class="no-border" >}} - -* A successful, downloaded iOS build: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/native-builder-successful-ios.png" alt="Successful and Downloaded iOS build" width="400" class="no-border" >}} - -If your build times out, you can either sign your app locally as described in [Android Local Signing](#android-local-signing) and [iOS Local Signing](#ios-local-signing) below, or upgrade to a paid App Center account. This build issue is more likely to affect iOS builds because of how long signing takes with an iOS developer profile. - -In case of failure, the build logs will be downloaded for your convenience. Please provide them when filing a [Support ticket](/support/submit-support-request/) with Mendix. - -Afer your build succeeds, note the downloaded *.zip* archives at the path provided by Native Builder. - -## Distributing {#distributing} - -If your builds are not signed, the downloaded archives `CoolApp-Android-1.zip` and `CoolApp-iOS-1.zip` will contain *non-release* builds, `app-debug.apk` and `nativeTemplate.xcarchive`. - -If your builds are signed, they will contain `app-release.apk` and `nativeTemplate.ipa` files for Android and iOS platforms respectively. - -For distributing to a specific platform, see the subsequent sections below: - -* [Distributing for Android](#android-distributing) -* [Distributing for iOS](#ios-distributing) - -### Distributing for Android {#android-distributing} - -#### Local Signing {#android-local-signing} - -You can skip this section if you completed [Signing a Build](#signing-a-build). To sign your Android app locally, use apksigner by following Google's [apksigner documentation](https://developer.android.com/studio/command-line/apksigner). - -#### Installing on a Device - -The *app-debug.apk* or *app-release.apk* can readily be installed on any device by sending the file over via any available means (for example USB). - -To install your app via USB, connect your device to a machine via USB. To Install an APK from your device's file manager app this way: - -1. Follow the instructions on Google’s [Transfer files between your computer & Android device](https://support.google.com/android/answer/9064445?hl=en) to get the APK onto your device. Note which folder you transfer the APK into. -2. Open your phone’s file manager, navigate to the folder containing your APK, then tap the APK file to open it. -3. Tap the **Install** button. - - {{% alert color="info" %}}On Android, you might see a dialog box warning you against installing because this is not a Play Store app. Tap **INSTALL ANYWAY**.{{% /alert %}} - -4. Tap the **Done** button when prompted. You should now be able to access your installed app via your **App Drawer**, as well as by tapping the **Open** button after the installation completes. - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/android-app-launch.gif" alt="android app launch" width="300" class="no-border" >}} - -You can also consult Google's [Run apps on a hardware device](https://developer.android.com/studio/run/device) for detailed instructions on testing your app using a physical Android device instead of an emulator. - -#### Uploading to the Google Play Store - -This section details publishing a signed Android app to the Google Play store. This section can only be started if you done the following: - -* Completed the [Signing a Build](#signing-a-build) section above -* Produced an *app-release.apk* build -* Read Google's overview of [the Android app publishing process](https://developer.android.com/studio/publish). - -Before submitting your app to an app store, you will have to complete Google's [signup steps](https://play.google.com/apps/publish/signup/). Also, [review the launch checklist](https://developer.android.com/distribute/tools/launch-checklist.html) before publishing your app. Beyond the launch checklist information, check Google's [Preparing your app for release](https://developer.android.com/studio/publish/preparing) for information on edge cases to resolve before publishing. - -Once you have satisfied those requirements, you can follow Google's [Upload your app to the Play Console](https://developer.android.com/studio/publish/upload-bundle). Then, follow Google's [Prepare and roll out a release](https://support.google.com/googleplay/android-developer/answer/7159011) to create, prepare, review, and roll out your app release. - -### Distributing for iOS {#ios-distributing} - -#### Local Signing {#ios-local-signing} - -You can skip this section if you completed [Signing a Build](#signing-a-build). Local signing is useful if you only want to test your app on a device, or you do not have a distribution certificate and have run out of build minutes on App Center when signing with a developer certificate. - -In order to deploy the *nativeTemplate.xcarchive* on a device or on the Apple App Store, an Apple developer account and a development team is required. If one is available, do the following: - -1. Using an Xcode version below 11, double-click the *nativeTemplate.xcarchive* file and it should open with the built-in *Application Loader* software. -2. Click the *Distribute App* button to start the local signing flow.: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-1.png" alt="Xcode Application loader" width="400" class="no-border" >}} - -3. Select **Development**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-2.png" alt="Xcode Application loader" width="400" class="no-border" >}} - -4. Choose a **Development Team**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-3.png" alt="Xcode Application loader" width="400" class="no-border" >}} - -5. Configure your **Development distribution options**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-4.png" alt="Xcode Application loader" width="400" class="no-border" >}} - -6. Select a re-signing option: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-5.png" alt="Xcode Application loader" width="400" class="no-border" >}} - -7. Review your *.ipa* content and click **Export**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-6.png" alt="Xcode Application loader" width="400" class="no-border" >}} - -8. Congratulations. You now have a signed *.ipa* file: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/xcode-app-loader-7.png" alt="Xcode Application loader" width="400" class="no-border" >}} - -#### Installing on a Device - -You can now deploy your app to your device. An easy way to do this is with Apple's iTunes program. - -To install the *ipa* on your device, follow these steps: - -1. Connect your Apple device to your computer. Both will show dialog boxes which ask you to confirm that you trust the devices. Tap **Continue** on your device, and **Trust This Computer?** on your mobile device to proceed: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/appletrust.png" alt="trust dialog" width="400" class="no-border" >}} - -2. Open iTunes and connect your iOS device to your computer. -3. Select the *.ipa* package file that you downloaded earlier, and drag it into your device's **Devices** section on iTunes' left menu. Drop the *.ipa* file there to install it on your device. -4. If there is an existing version, iTunes will ask if you want to replace that existing version of the app. If there is one, do so. -5. Your app will show up in the list of apps. Click the **Install** button next to your app. -6. Click **Apply** at the bottom of the screen to execute the actual installation. - -#### Distributing for iOS Tablets - -When you try to build an app for tablets, your app will run as a phone app in a scaled mode optimized for tablet form factors. Please note, however, that Apple has far stricter rules for releasing tablet apps. For example, they require the app to behave well in any possible rotation or resolution. This means that when making a Mendix app for iOS tablets you should take extra care to style your app correctly so it is not rejected. - -There are two ways to enable tablet mode: - -* If you are working with a Mac and are familiar with Git you can use Xcode -* You can directly do the changes in the appropriate files using GitHub's page - -##### Use Xcode on a Mac - -By default, building for tablets is disabled in Xcode. Do the following to enable tablet settings: - -1. Select the following options in your Xcode workspace:
- 1. **iPad**: this enables tablet mode. By default, if tablet mode in enabled you also have to support any possible orientation.
- 1. **Portrait**.
- 1. **Landscape Left**.
- 1. **Landscape Right.**
- 1. **Requires full screen**: Mendix requires this because full-screen orientations are easier on Mendix developers than smaller side-by-side forms. - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/tablet-workspace.png" alt="select tablet options" width="300" class="no-border" >}} - -1. Commit these changes to your project's primary branch so consecutive builds have the tablet settings enabled. - -##### Directly Change the Files on GitHub - -First, navigate to your project's repository. This should be `www.github.com//`. Then do the following to enable tablet mode: - -1. Using the **Find file** functionality, find and open *project.pbxproj*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/github-find-file.png" alt="find file toolbar" width="400" class="no-border" >}} - -1. Click **Edit this file** ({{% icon name="pencil" %}}): - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/github-edit-file.png" alt="find file toolbar" width="400" class="no-border" >}} - -1. Change both instances of `TARGET_DEVICE_FAMILY = “1”;` to `TARGET_DEVICE_FAMILY = “1,2";`. -1. Commit these changes. -1. Using the **Find file** functionality again, find and open *info.plist*. -1. Click **Edit this file** again, then change the code like so: - - 1. Before the final `` line, add this key:
- - ```text - UIRequiresFullScreen - - ``` - - 1. Change this code:
- - ```text - UISupportedInterfaceOrientations - - UIInterfaceOrientationPortrait - - ``` - - to the following:
- - ```text - UISupportedInterfaceOrientations - - UIInterfaceOrientationPortrait - UIInterfaceOrientationLandscapeLeft - UIInterfaceOrientationLandscapeRight - - ``` - -1. Commit these changes. - -#### Uploading to the Apple App Store - -To upload your app to the iOS App Store, follow these instructions (to continue, you must have completed the [Signing a Build](#signing-a-build) section above and received a build signed for the Apple Store): - -1. Follow Apple's [Add an app to your account](https://help.apple.com/app-store-connect/#/dev2cd126805) tutorial to add an app entry to your account. -2. After adding a new app to your account, follow Apple's [View and edit app information](https://help.apple.com/app-store-connect/#/dev97865727c) tutorial to describe your new app entry. Consult the other pages under the left menu's **Enter app information** category should they apply to your app: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/ios-enter-app-info.png" alt="enter app information" width="400" class="no-border" >}} - -3. Follow Apple's [Uploading builds overview](https://help.apple.com/app-store-connect/#/dev82a6a9d79) to upload a build of your app to App Store Connect. -4. Use Apple's [Upload tools guide](https://help.apple.com/app-store-connect/#/devb1c185036) to upload your *ipa*. -5. Use Apple's [Choose the build before you submit to review](https://help.apple.com/app-store-connect/#/dev7cbda8c55) to select the build which you will submit to App Review. -6. Publish your app by following Apple's [Overview of publishing an app](https://help.apple.com/app-store-connect/#/dev34e9bbb5a) and the subsequent documents in the left menu's **Publish on the App Store** category: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/deploying-native-app-cli/ios-publishing-an-app.png" alt="publish on the app store" width="400" class="no-border" >}} - -## Read More - -* [Native Builder Reference Guide](/refguide8/native-builder/) -* [How To Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli.md deleted file mode 100644 index 4b879760a32..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: "Create a Custom Developer App with the Native Builder CLI" -linktitle: "Custom Developer App with Native Builder CLI" -url: /howto8/mobile/how-to-devapps-cli/ -weight: 30 -description: A tutorial for creating custom developer apps. ---- - -## Introduction - -As your Mendix app matures, you may want to expand its functionality (such as by introducing custom widgets or logic that will require new native dependencies). One such customization could be adding a near-field communication (NFC) module to your app. While the Make It Native app suffices for testing basic apps, as your app adds custom dependencies—like custom native widgets or fonts—you will need a more tailored developer app. - -A custom developer app helps you by serving as a replacement for the Make It Native app, and should be used when you have custom widgets and logic which are not supported by the Make It Native app. Custom developer apps are apps you can generate yourself using your current project structure, your custom modules, and any other requirements to test your evolving app. Custom developer apps feature the same functionality as the Make It Native app but are tailored to your needs. - -## Prerequisites - -* Complete [How to Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) - -## Build Your Developer App - -1. Open a command line interface (CLI) such as Command Prompt. -2. Navigate to the directory of your Native Builder: - - ```powershell - cd {path to Native Builder executable file} - ``` - -3. Run the following command to build your project's custom developer app: - - ```powershell - native-builder.exe build dev-app --project-name {your project's name} - ``` - - This command does the following:
- 1. Creates a branch named `developer` based on the committed changes to your `main`.
- 1. Starts a build using the developer app flavors for your project. -4. Wait until the Native Builder completes your builds. - -As with a release build, when the Native Builder is done building you should have two archives for each build: an iOS and an Android build. These archives can be found under the build output path `{build output path}` with **Dev** prepended to their name. The default `{build output path}` is the `./builds` folder relative to your `native-builder.exe` location. - -## Installing Your Custom Developer App - -### Android - -By default your custom developer app will be unsigned. To get a signed *IPA*, follow the steps in the [Signing Your Build](/howto8/mobile/deploying-native-app/#signing-a-build) section of *How to Build a Mendix Native App in the Cloud*. Your Custom developer app branch is named **developer**. - -For Android the output of the build is an *APK* file. *APK* files can be directly installed on devices or emulators. - -#### Installing on an Emulator - -With your emulator running, install your app in your emulator by doing the following: - -1. Drag the *APK* onto the emulator's window. -2. Wait for the installation to be done. -3. Open the app from the launcher. - -#### Installing on a Device - -There are various ways install an app on a device. Installing using a USB is detailed below, but you can use a different method if it suits you. Do the following to install your *APK* onto a device: - -1. Connect your device to your machine via USB. -2. Enable file transfer on your device (differs per device). -3. Open **This PC** in File Explorer; your device should be listed as an external device. -4. Drag your *APK* onto your device. -5. Wait for it to finish transferring. -6. Open your device's file manager. -7. Navigate to the root of the file system. -8. Tap the *APK* to install. -9. Go through the installation steps. -10. Open the app from the launcher. - -### iOS - -By default your custom developer app will be unsigned. To get a signed *IPA*, follow the steps in the [Signing Your Build](/howto8/mobile/deploying-native-app/#signing-a-build) section of *How to Build a Mendix Native App in the Cloud*. Your custom developer app branch is named **developer**. - -The unsigned output of an iOS build is an *XCArchive* file. *XCArchive* files require manual signing before they are ready to be installed on a device. - -The signed output of iOS build is an *IPA* file. If correctly signed, *IPA* files can be installed on physical devices. - -Before installing, make sure you have completed the following prerequisites: - -* Have a Mac OSX machine -* Install LTS builds of Node.js and NPM (download [here](https://nodejs.org/en/)) -* Install Cocoapods ([installation instructions](https://cocoapods.org/#install)) -* Install the latest Xcode version - -#### Installing on an Emulator - -Builds with the Native Builder are stripped of simulator artifacts. Therefore, to run on Xcode's Simulator you will have to build the developer branch locally from source by completing these steps: - -1. Navigate to your GitHub repo. -2. Switch to your **developer** branch: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli/github-branch-switching.png" alt="Switch branch on GitHub" class="no-border" >}} - -3. Click **Clone or Download** and then click **Download ZIP**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli/github-download-branch.png" alt="Download repository" class="no-border" >}} - -4. Unzip the downloaded archive. -5. Open a terminal and change directory into the folder. -6. Run this command: - - ```shell - npm i && cd ios && pod install - ``` - - This will install the node module dependencies and the iOS Dependencies -7. In the **ios** folder, open the **NativeTemplate.xcworkspace** file: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli/ios-folder.png" alt="iOS folder structure" class="no-border" >}} - -8. In Xcode select the **Dev** target and the emulator you want to build your developer app for: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-devapps-cli/xcode-target-selection.png" alt="Dev target selection" class="no-border" >}} - -9. Click **Run** ({{% icon name="controls-play" %}}). - -#### Distributing the Custom Developer App - -To run your custom developer app on a device which is not a test device, you will have to sign the developer app with your certificates. - -For local builds, follow the [Signing a Build](/howto8/mobile/deploying-native-app-cli/#signing-a-build) section of *How to Deploy Your First Mendix Native Mobile App with the Native Builder CLI* to sign the *.xarchive* file. - -If you want Native Builder to sign your custom developer app, follow the steps in the [Signing a Build](/howto8/mobile/deploying-native-app-cli/#signing-a-build) section of *How to Deploy Your First Mendix Native Mobile App with the Native Builder CLI*. - -## Read More - -* [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* [How to Use Over the Air Updates](/howto8/mobile/how-to-ota/) diff --git a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli.md b/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli.md deleted file mode 100644 index dfb918d9e30..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: "Release Over the Air Updates with App Center's CodePush using the CLI" -linktitle: "Over the Air Updates with CodePush and CLI" -url: /howto8/mobile/how-to-ota-cli/ -weight: 71 -description: A tutorial for pushing over the air updates (OTA). ---- - -## Introduction - -{{% alert color="info" %}} -This document is for legacy cases when older projects cannot use the Mendix Native Mobile Builder. However, we *strongly suggest* you migrate your project to the Mendix Native Mobile Builder. If you have not migrated your project to the Native Mobile Builder, or are on an Native Template version older than 5.1.9 (Mendix Studio Pro 8.15.0 or older), follow the [Transfer a CLI OTA-Compatible App to the Mendix Native Mobile Builder](/howto8/mobile/how-to-ota/#from-cli-to-ui) section of *How to Release Over the Air Updates with App Center's CodePush* to update your Native Template. If for whatever reason it's not possible to migrate your project to a newer version of Native Template, continue with this guide. -{{% /alert %}} - -Using Native Builder and Mendix Studio Pro, you can update your Mendix Native Apps over the air (OTA). OTA updates are a fast and painless way of updating things like layouts, pages, assets, or even you app's business logic (such as nanoflows and JavaScript actions). - -Native apps are separated into two parts: a wrapper that is basically a native iOS or Android app and a bundle that is being loaded dynamically by said wrapper. Things like your business logic and static assets are part of this dynamically-loaded bundle. When you have changes you want to deploy, the Native Builder can bundle them in a new, updated bundle and painlessly deploy them. On the next app restart, your app's users will be updated to the latest version and continue their business as usual. - -OTA updates are bound to a specific app version and build number. Therefore, you can target specific updates to specific versions of your app. For example, you can push an update for version 1.0.0 as a legacy version that supports older devices, and also push an update for the 2.0.0 version of your app which includes more features. - -{{% alert color="info" %}} -Currently OTA does not update your app while the app is open or minimized. -{{% /alert %}} - -This how-to teaches you how to do the following: - -* Push an OTA update for a released app -* Rollback an update -* Configure an already pushed update - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install Native Builder 3.0.0 or higher -* Install Mendix Studio Pro 8.4 or higher -* Complete [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* Complete at least one successful build using Native Builder v3.0.0 and Native Template v2.0.0 -* Install your app on a test device or emulator -* Read the [Offline First Reference Guide](/refguide8/offline-first/) - -## When to Use OTA Updates - -### Safely Pushing OTA Updates Without Redeploying Your Mendix App {#safeToUpdate} - -It is good practice to *always* redeploy your Mendix App before pushing a new over the air update. However, releasing an OTA update without redeploying your Mendix App to Mendix Cloud in these cases is usually safe: - -* Style changes -* Changes to static images, text, or other static assets -* Layout changes -* Nanoflow changes -* JavaScript action changes -* Widgets shipped with Mendix added or removed -* You added a new custom JavaScript-only widget or module -* You added a page with no additional logic -* Non-destructive model changes (for more information, see the [Offline First Reference Guide](/refguide8/offline-first/)) - -### When a Full Release is Required - -If you have made any changes directly to your iOS or Android project, you will have to fully redeploy you app to the app stores for the changes to take effect. OTA updates do not suffice, and a full release is required, in the following cases: - -* The initial release of your app -* A Mendix Studio Pro version upgrade that requires a new Native Template version -* You fundamentally changed your app's functionality (this is an Apple App Store limitation, and will require a re-release and re-review of your app by Apple — your app might be removed if you do not comply) -* A new native module has been added -* The app has been renamed -* You added a new microflow or nanoflow -* The app's launcher icons have been changed -* The splash screen has been changed - -## Deploying An Over the Air Update - -Over the air updates let you correct mistakes in your published apps without issuing a new release. For example, imagine you issued a new release and later found a spelling mistake on your welcome screen: - -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/phone-error-text.png" alt="Typo in welcome screen" width="300" class="no-border" >}} - -Before OTA updates, you would have to make a new release and configure it in the app stores. But OTA updates make fixing such a mistake easy. - -To release a new version OTA, follow these steps: - -1. Correct the title and message as follows: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/modeller-correct.png" alt="Make some changes" width="300" class="no-border" >}} - -2. Save your changes. -3. Note the version and build number of the app build you want to update. This how-to assumes an app version of 1.0.0 and a build number of 1. -4. Open a command line interface (CLI) such as Command Prompt. -5. Navigate to the directory of your Native Builder: - - ```powershell - cd {path to Native Builder executable file}` - ``` - -6. Run the following command to build and push a new update: - - ```text - native-builder.exe release push-update --project-name "CoolApp" --target-version "1.0.0" --build-number 1 --rollout-percentage 100 --mandatory - ``` - - {{% alert color="info" %}} -This command does the following:
- -* Runs MxBuild to build your project
-* Packages your project to be pushed as a new update
-* Pushes the new update package for the app's version 1.0.0
-* Sets the rollout percentage to 100% (all app users)
-* Marks the update as mandatory for the app's users to install - {{% /alert %}} - -1. Wait for the Native Builder to complete. -2. Restart the app on your testing device. You should be greeted with the following message: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/phone-update-prompt.png" alt="Update available prompt" width="300" class="no-border" >}} - -3. Tap **Confirm** to update your app. -4. The app should reload and greet you with the following dialog box: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/phone-success-prompt.png" alt="Update success prompt" width="300" class="no-border" >}} - -## Rolling Back Updates - -Sometimes an update might not perform as expected. Out of the box, when an update fails, the automatic update mechanism will try to recover by switching back to the bundle packaged with your app's binary. In cases such as these, you should update your bundle by either fixing the issue and pushing a new update or by rolling back to the previous version. - -Imagine you want to rollback an update. Maybe you released it too early or something is wrong with it. Rollback an update by following these steps: - -1. Get your list of available releases by running the following command: - - ```text - `native-builder.exe release list --project-name "CoolApp"` - ``` - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/release-list.png" alt="List of available release" class="no-border" >}} - -2. To roll back from {v2} to {v1} type the following command: - - ```text - native-builder.exe release rollback-update --project-name "CoolApp" --label "v1" - ``` - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/rollback-result.png" alt="Output of rollback command" width="300" class="no-border" >}} - -3. Next time you open your app, you should be greeted with the **Update available** dialog box. Tap **Confirm** to roll your app back on your device. - -## Initiating a Partial Initial Rollout - -### When it is Safe to Rollback an Update - -For information on rollbacks, see [Safely Pushing OTA Updates Without Redeploying Your Mendix App](#safeToUpdate) above. The cases listed there also apply to rolling back safely. - -### Doing a Partial Rollout - -In case you want to test the stability of a new update, it is good practice to test releases on a small number of users before fully rolling them out. - -To roll out your app to only *some* of your users, run this command: - -```text -`native-builder.exe release push-update --project-name "CoolApp" --target-version "1.0.0" --build-number 1 --rollout-percentage 50 --mandatory` -``` - -Instead of passing a rollout percentage of 100%, you are passing 50%. This means the update will be distributed to 50% of the app's user base. This number can be an any integer from 1 to 100, representing the percentage of your user base which will receive the update. - -To fully roll out the update, run this command: - -```text -native-builder.exe release patch-update --project-name "CoolApp" --target-version "1.0.0" --build-number 1 --rollout-percentage 100 -``` - -## Configuring a Pushed Update - -You might want to reconfigure an update which has already been pushed for the following reasons: - -* You did a partial rollout and want to raise the number -* You want to make a update mandatory - -The key here is `patch-update`. The `patch-update` command allows you to modify a pushed updated. You can modify things like a rollout percentage, or you can choose to make a release mandatory. - -### Releasing an Optional Update - -Using a modification of `rollout-percentage` you can make builds optional. To do so, run this command: - -```text -native-builder.exe release push-update --project-name "CoolApp" --target-version "1.0.0" --build-number 1 --rollout-percentage 100 --mandatory false -``` - -Instead of the mandatory update pop-up window, you app's users should now be greeted with an optional pop-up window. This window will allow them to choose to install the update or not. - -## Preserving your Model's Integrity - -Before issuing OTA updates or releasing new versions, please read and understand the [Offline First](/refguide8/offline-first/) reference guide. It is important to understand the implications of offline first. - -Mendix Native Apps are offline first. This means you should be cautious when changing the following elements, and should avoid changing them if possible: - -* The navigation profile -* An offline first entity, for example entity name changes, new entity relationships, and more - -Generally, you should avoid doing destructive changes to offline-synced entities. In the rare cases this is unavoidable, releasing a new app version or doing over the air updates might put your app's users in an unrecoverable state. - -### Offline Apps and Data Loss - -Data loss can occur when OTA updates or new releases coincide with apps being offline. For example, imagine your Mendix developers were hard at work optimizing the data store entity structure by consolidating entities to speed up sync operations. They release that morning. They push a new runtime by pressing the **Run** button in Studio Pro, and then run the Native Builder to push a new update to the apps. All seems to work fine. - -That same morning however, your engineers were hard at work gathering field data in a remote area. Later that afternoon the engineers return back to the city and attempt to synchronize their data using the app's built-in synchronize button. Their synchronization fails. They do the only thing they can think of: restart the app. When the app starts they are greeted with the **Update Available** screen. They hit the continue button, get updated, and their data is lost or partially synchronized. - -This issue is independent from OTA updates and specific to offline apps. Your offline app runs a snapshot of your runtime's model locally. So as a Mendix Developer, you have to think twice before doing major changes that might make the app's state unrecoverable. In the example above the entity model was changed, and when the app attempted to synchronize it failed. This can create unrecoverable situations that will require a re-installation of the app, and can lead to data loss for unsynced data. - -## Read More - -* [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* [Native Builder Reference Guide](/refguide8/native-builder/) -* [Offline First Reference Guide](/refguide8/offline-first/) -* [Codepush Introduction](https://docs.microsoft.com/en-us/appcenter/distribution/codepush/) -* [Using the CodePush UI](https://docs.microsoft.com/en-us/appcenter/distribution/codepush/using-ui) diff --git a/content/en/docs/howto8/mobile/native-mobile/common-issues.md b/content/en/docs/howto8/mobile/native-mobile/common-issues.md deleted file mode 100644 index 878435e6b6f..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/common-issues.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Troubleshoot Common Native Mobile Issues" -url: /howto8/mobile/common-issues/ -weight: 80 -description: Troubleshoot common issues associated with building and running native mobile apps. ---- - -## Introduction - -Mendix strives to make building and running native mobile apps as simple as possible. But because some complexity is inherent in making apps, problems can come up. If you are having issues while building or running native mobile apps, please consult the sections below to see if your issue has already been solved. - -## Make It Native App - -To troubleshoot issues related to the [Make it Native](/refguide8/getting-the-make-it-native-app/) app, see the sections below. - -### Port Issues - -Mendix recommends keeping the **Runtime port** in your [configuration](/refguide8/configuration/#server) on **8080**. If you change it, do not change it to **8083**, because that is designated for app packaging. - -### Wifi Network Settings - -If you are using Windows, make sure your WiFi network is set to **Private**. Windows often sets WiFi to **Public** by default, which blocks incoming connections. - -### Error: Unable to Load Script - -Depending on your device settings and network characteristics, the Make it Native app can fail to connect to the runtime. If so, the Make it Native app can show the following error messages: - -* **Unable to load script**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/common-issues/unabletoloadscript.png" alt="unable to load script" width="250" class="no-border" >}} - -* **Cannot detect your runtime**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/common-issues/min-error-firewall.png" alt="cannot detect runtime" width="250" class="no-border" >}} - -These failures are often caused by the Windows Defender firewall. In such cases, attempts to open the runtime URL from the mobile browser will also fail. To mitigate these issues, please do the following: - -1. Make sure that your computer and the mobile device are connected to the same network. -1. Make sure that incoming connections are allowed by doing the following:
- 1. Open **Firewall & Network Protection** settings in Windows.
- 1. Go to **Advanced Settings**.
- 1. Select the **Inbound Rules** and scroll to the **Mendix Native Mobile** entries.
- 1. For each Node.js entry, note their values in the **Program** column. They should all have a green check mark in front of them.
- 1. If the **Program** column shows a Mendix installation directory, then there should be a green icon in front of the entry. If this is not the case, double-click the entry and select **Allow the connection**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/common-issues/inboundrules.png" alt="inbound rules" width="350" class="no-border" >}} - -1. Windows distinguishes between two types of networks: private and public. Windows Defender Firewall applies stricter regulations for public networks. If, and only if, you are connected to a trusted network, configure the network as **Private** on your computer. - -## Read More - -* [How to Debug Native Mobile Apps (Advanced)](/howto8/mobile/native-debug/) -* [Native Builder Reference Guide](/refguide8/native-builder/) diff --git a/content/en/docs/howto8/mobile/native-mobile/getting-started-with-native-mobile.md b/content/en/docs/howto8/mobile/native-mobile/getting-started-with-native-mobile.md deleted file mode 100644 index eab3fd13f72..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/getting-started-with-native-mobile.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "Get Started with Native Mobile" -url: /howto8/mobile/getting-started-with-native-mobile/ -weight: 5 -description: A how-to for creating a native mobile Mendix app and viewing it on a mobile device. ---- - -## Introduction - -To use Mendix Studio Pro's native mobile app capabilities, you can use the [Blank Native Mobile App](https://marketplace.mendix.com/link/component/109511/) from the Mendix Marketplace. This app is optimized to quickly build a native mobile app. Out of the box, this app gives you a native page, a native phone profile to enable native device navigation, a native layout with menus, and native widgets and actions which leverage device capabilities. - -The Blank Native Mobile App also includes four modules: - -* **Administration** – helps you manage users -* **Atlas UI Resources package** – allows for app styling -* **Nanoflow Commons** – contains generic useful nanoflow actions -* **Native Mobile Actions** – contains various native widgets and nanoflow actions that leverage device capabilities - -## Prerequisites {#prerequisites} - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Have a mobile device to test your native mobile app -* For information on device requirements, see [System Requirements](/refguide8/system-requirements/) -* If you wish to use an emulator for Android mobile testing, install a product such as [Bluestacks](https://www.bluestacks.com/nl/index.html) or [Genymotion](https://www.genymotion.com/) (your emulator must have Google Play services supported) - -## Creating a New App Based on the Quickstarter App {#quickstartapp} - -For details on making a Mendix app using the Blank Native Mobile App template, download the Make It Native 8 app on either the [Google Play store](https://play.google.com/store/apps/details?id=com.mendix.developerapp) or the [Apple App Store](https://apps.apple.com/us/app/make-it-native/id1334081181). This app template includes the latest version of Atlas UI, as well as the [Native Mobile Resources](/appstore/modules/native-mobile-resources/) module containing widgets and nanoflow actions for native mobile apps. For more information on building native mobile apps, see the [Build a Native Mobile Inspection App](https://academy.mendix.com/link/path/66) learning path (you must be signed in to the Mendix Platform to see this learning path). Using the Make It Native app to view the changes to your Mendix app, see the sections below. - -### Starting a Quickstarter App - -To start a new app based on a template, follow these steps: - -1. Open Mendix Studio Pro. Select **File** > **New Project**, and then select the **Blank Native Mobile App**. -2. Click **Use this starting point**. -3. Click **Create app** to close the dialog box. -4. Click **Run Locally** to see the app in action. Please note that starting a native mobile app for the first time can take a bit longer (about one minute total) than subsequent instances. -5. After running your app, you may see a Windows Security Alert dialog box. Accept the permissions selected by default and click **Allow access** to close the dialog box. -6. If asked to create database **'default'**, click **Yes**. - -At this point you have a running native mobile app. To view your app on a mobile device, however, you need to download the Make It Native app. - -### Downloading and Installing the Make It Native App - -#### Downloading for Android - -To view your app on an Android device (or emulator), you must download and install the Make It Native 8 app from the [Google Play store](https://play.google.com/store/apps/details?id=com.mendix.developerapp): - -{{< figure src="/attachments/howto8/mobile/native-mobile/getting-started-with-native-mobile/make-it-native-googleplay.png" alt="native app on googleplay" width="500" class="no-border" >}} - -#### Downloading for iOS {#downloading-for-ios} - -To view your app on an iOS device, you must download and install the Make It Native 8 app from the [Apple App Store](https://apps.apple.com/us/app/make-it-native/id1334081181): - -{{< figure src="/attachments/howto8/mobile/native-mobile/getting-started-with-native-mobile/make-it-native-ios.png" alt="native app on app store" width="500" class="no-border" >}} - -### Viewing Your App on Your Testing Device - -Viewing your app on a mobile device will allow you to test native features and other aspects of your app. This section is written for mobile devices, but you may use an Android emulator mentioned in the [Prerequisites](#prerequisites) section above. To view your app, follow these steps: - -1. Locate your app's QR code in Mendix Studio Pro by clicking the drop-down menu next to the **View** button, then selecting **View on your device** and navigating to the **Native mobile** tab. Here you will see your test app's QR code. -2. Start the Make It Native app by tapping its icon on your device. -3. Tap the **Scan a QR Code** button: - - {{< figure src="/attachments/howto8/mobile/native-mobile/getting-started-with-native-mobile/scan-qr.png" alt="Scan QR Code" width="500" class="no-border" >}} - -4. If prompted, grant the app permission to access your device's camera. -5. Point your mobile device's camera at the QR code. It will automatically launch your test app on your mobile device. - -{{% alert color="warning" %}} - -Your mobile device has to be on the same network as your development machine for the Make It Native app to work. If this is the case and the connection still fails, make sure that communication between devices is allowed in the Wi-Fi access point. Also, Mendix recommends keeping the **Runtime port** in **Project Settings** > **Edit** on **8080**. If you change it, do not change it to **8083**, because that is designated for app packaging. - -{{% /alert %}} - -Now you can see your app on your device. While this is just a template app, whenever you make changes you will be able to view them live on your Make It Native app. - -You may notice an **Enable dev mode** toggle on the Make It Native app home page. Turning this toggle on will give you more detailed warning messages during error screens, as well as additional functionality on the developer app menu: - -{{< figure src="/attachments/howto8/mobile/native-mobile/getting-started-with-native-mobile/enable-dev-mode.png" alt="enable dev mode" width="500" class="no-border" >}} - -### Viewing Changes to Your App on Your Testing Device {#viewingchanges} - -To see how changes made in Mendix Studio Pro are displayed live on your testing device, make a small change to your app. - -1. Put a text widget on your app's home page. Then, write some text into it. In this example, "Native rules!" has been added: - - {{< figure src="/attachments/howto8/mobile/native-mobile/getting-started-with-native-mobile/new-text-studiopro.png" alt="new studio pro text" class="no-border" >}} - -2. Click **Run Locally** to automatically update the running app on your device, and see your new text. When you click **Run Locally**, your app will automatically reload while keeping state. - -If you get an error screen while testing your app, there are easy ways to restart it: - -* Tap your test app with three fingers to restart your app -* With the **Enable dev mode** toggle turned on, hold a three-fingered tap to bring up the developer app menu—here you can access **ADVANCED SETTINGS** and **ENABLE REMOTE JS DEBUGGING** - -For more detailed instructions on debugging a native mobile app, see [Debug Native Mobile Apps (Advanced)](/howto8/mobile/native-debug/). - -## Read More - -* [How to Build Pluggable Widgets](/howto8/extensibility/pluggable-widgets/) -* [Native Mobile Styling Reference Guide](/refguide8/native-styling-refguide/) -* [How to Debug Native Mobile Apps (Advanced)](/howto8/mobile/native-debug/) diff --git a/content/en/docs/howto8/mobile/native-mobile/how-to-maps.md b/content/en/docs/howto8/mobile/native-mobile/how-to-maps.md deleted file mode 100644 index 1962b285385..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/how-to-maps.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Set Up Maps in Native Mobile Apps" -url: /howto8/mobile/how-to-maps/ -weight: 78 -description: This guide teaches you how to set up native mobile maps capabilities for Android and Apple devices. ---- - -## Introduction - -The Maps module allows you to work with maps. Consult the instructions below to include map capabilities in your native mobile apps. - -## Prerequisites - -* Complete the [Prerequisites](/refguide/mobile/getting-started-with-mobile/prerequisites/) of your app per its type -* Create an app on the [Google Cloud Console](https://console.cloud.google.com/google/maps-apis/overview) and have Google Maps enabled for Android (and iOS, if you wish to use Google Maps on iOS as well) and also posses an [API key](https://developers.google.com/maps/documentation/android-sdk/get-api-key). -* Before you can start using the Google Maps Platform APIs and SDKs, you must sign up and create a [billing account](https://developers.google.com/maps/gmp-get-started/#create-billing-account). -* Install Mendix Studio Pro 8.15.0 and above to use the Native Mobile App Builder - -## Setting Up App Deep Linking {#set-up} - -Make sure you have app containing the Maps module. This is a core module, so it is available in the **Widgets** panel. You can either add it to an existing project or make a new project from scratch. - -### Configuring Map Provider - -Next you will configure the **Maps** widget provider. You will have two choices: **Default** and **Google Maps**. Selecting **Default** will have your app use the default-enabled map on your device. This means using Google Maps on Android devices and Apple Maps on iOS devices. Selecting **Google Maps** as your **Maps** configuration will have only Google Maps used on both platforms: - -1. Double-click your Maps widget and Selecting the **Map** tab. -1. Select either the **Default** or **Google Maps** provider: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-maps/maps-provider-configuration.png" alt="maps provider configuration" width="400" class="no-border" >}} - -### Configuring Maps Capability - -1. Set up a native template with the **Native Mobile App Builder**. This can be launched from the Project menu as shown in [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/). Complete the wizard and configure the project's details and tokens: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-maps/launch-native-mobile-app-builder.png" alt="launch native mobile builder" width="400" class="no-border" >}} - -1. Once done with the wizard, select the **Capabilities** menu item: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-maps/capability-menu-option.png" alt="capability menu option" width="400" class="no-border" >}} - -1. Enable the maps capability. This exposes a set of configurations: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-maps/maps-input-fields.png" alt="maps input fields" width="400" class="no-border" >}} - - * As described in the Prerequisites section, the API key gives the maps widget access to Google Cloud services - * The **Purpose for maps** string is a specialized text that tells Apple why you need to use maps in your app (Apple requests explanation as maps use device location data) - * **I want to use Apple Maps for iOS** mirrors the decision explained in the Configuring Map Provider section above - -1. Click the **Save** button. -1. Navigate to the build page then click **Build**. - -{{% alert color="info" %}} -When running locally from source, on iOS you have to run `pod install` once more -{{% /alert %}} - -## Read More - -* [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* [How to Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) diff --git a/content/en/docs/howto8/mobile/native-mobile/how-to-ota.md b/content/en/docs/howto8/mobile/native-mobile/how-to-ota.md deleted file mode 100644 index 856d83605d8..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/how-to-ota.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: "Release Over the Air Updates with App Center's CodePush" -linktitle: "Over the Air Updates with CodePush" -url: /howto8/mobile/how-to-ota/ -weight: 71 -description: A tutorial for pushing over the air updates (OTA) using App Center's CodePush. ---- - -## Introduction - -{{% alert color="warning" %}} -In Studio Pro 10.6 and above, Mendix has discontinued support for CodePush. If your app relies on CodePush for over-the-air updates, please note that it will no longer be available. - -We recommend migrating your app to a higher version that supports [Mendix OTA](/refguide/mobile/distributing-mobile-apps/overtheair-updates/) for managing over-the-air updates. -{{% /alert %}} - -Using Native Mobile Builder and Mendix Studio Pro, you can update your Mendix Native Apps over the air (OTA). OTA updates are a fast and painless way of updating things like layouts, pages, assets, or even you app's business logic (such as nanoflows and JavaScript actions). - -Native apps are separated into two parts: a wrapper that is basically a native iOS or Android app and a bundle that is being loaded dynamically by said wrapper. Things like your business logic and static assets are part of this dynamically-loaded bundle. When you have changes you want to deploy, the Native Mobile Builder can bundle them in a new, updated bundle and painlessly deploy them. On the next app restart, your app's users will be updated to the latest version and continue their business as usual. - -OTA updates are bound to a specific app version and build number. Therefore, you can target specific updates to specific versions of your app. For example, you can push an update for version 1.0.0 as a legacy version that supports older devices, and also push an update for the 2.0.0 version of your app which includes more features. - -{{% alert color="info" %}} -Currently OTA does not update your app while the app is open or minimized. -{{% /alert %}} - -This how-to teaches you how to do the following: - -* Push an OTA update for a released app - -## Prerequisites {#prerequisites} - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install Mendix Studio Pro 8.15 or above using the online installer (the offline installer does not include the Mendix Native Mobile Builder dependency) -* Deploy your app by completing [How to Deploy Your First Mendix Native Mobile App](/howto8/mobile/deploying-native-app/). -* Ensure you have set up and configured App Center for your app. For information on setting up App Center, see the [App Center Token](/howto8/mobile/deploying-native-app/#appcenter-token) section of *How to Deploy Your First Mendix Native Mobile App*. If you previously opted out of configuring App Center while building your app, you must navigate to the **Tokens** screen and toggle on the **I want to use App Center** option. -* Install your app on a test device or emulator. -* Read the [Offline First Reference Guide](/refguide8/offline-first/). - -{{% alert color="info" %}} -Before using this document, please ensure compatibility. If you have not migrated your project to the Native Mobile Builder or are on an Native Template version older than 5.1.9 (Mendix Studio Pro 8.15.1 and below), either follow [Transfer a CLI OTA-Compatible App to the Mendix Native Mobile Builder](#from-cli-to-ui) section below **before** implementing OTA updates, or update your Native Template. - -If you cannot migrate your project to a newer version of Native Template, for example if you have to use an older version of Studio Pro, use [Release Over the Air Updates with App Center's CodePush using the CLI](/howto8/mobile/how-to-ota-cli/) instead of this document. -{{% /alert %}} - -## When to Use OTA Updates - -### Safely Pushing OTA Updates Without Redeploying Your Mendix App {#safeToUpdate} - -It is good practice to *always* redeploy your Mendix App before pushing a new over the air update. However, releasing an OTA update without redeploying your Mendix App to Mendix Cloud in these cases is usually safe: - -* Style changes -* Changes to static images, text, or other static assets -* Layout changes -* Nanoflow changes -* JavaScript action changes -* Widgets shipped with Mendix added or removed -* You added a new custom JavaScript-only widget or module -* You added a page with no additional logic -* Non-destructive model changes (for more information, see the [Offline First Reference Guide](/refguide8/offline-first/)) - -### When a Full Release Is Required - -If you have made any changes directly to your iOS or Android project, you will have to fully redeploy you app to the app stores for the changes to take effect. OTA updates do not suffice, and a full release is required, in the following cases: - -* The initial release of your app -* A Mendix Studio Pro version upgrade that requires a new Native Template version -* You fundamentally changed your app's functionality (this is an Apple App Store limitation, and will require a re-release and re-review of your app by Apple — your app might be removed if you do not comply) -* A new native module has been added -* The app has been renamed -* You added a new microflow or nanoflow -* The app's launcher icons have been changed -* The splash screen has been changed - -## Build an App That Can Use CodePush OTA Updates {#build-with-ota-support} - -Apps built using the Mendix Native Mobile Builder have OTA updates with App Center's CodePush disabled by default. To make OTA updates via App Center's CodePush available to your app's users, you must toggle the **App Center OTA Support** capability on. - -Next you must build new binaries with this capability toggled on, and then release the apps to their respective app stores (only users with the new apps will be able to receive OTA updates). To do these things, follow these general steps: - -1. Click **Project** > **Build Native Mobile App**. -1. Navigate to **App Capabilities**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-ota/advanced-capabilities.png" alt="Start Mendix Native Mobile Builder" width="350" class="no-border" >}} - -1. Toggle **App Center CodePush OTA Support** on: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-ota/advanced-capabilities-ota.png" alt="OTA capability enabled" width="350" class="no-border" >}} - -1. Click **Save**. -1. Now build an application for distribution and make a note of the version number used: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-ota/build-release-app-for-ota.png" alt="Build release app page" width="350" class="no-border" >}} - -1. To make the OTA update functionality available to your users, please release the new binaries via the appropriate app stores. If you are testing the functionality you can now install the apps on your test devices. - -## Deploying An Over the Air Update - -Over the air updates let you correct mistakes in your published apps without issuing a new release. For example, imagine you issued a new release and later found a spelling mistake on your welcome screen: - -{{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/phone-error-text.png" alt="Typo in welcome screen" width="300" class="no-border" >}} - -Before OTA updates, you would have to make a new release and configure it in the app stores. But OTA updates make fixing such a mistake easy. - -To release a new version OTA, follow these steps: - -1. Correct the title and message as follows: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/modeller-correct.png" alt="Make some changes" width="300" class="no-border" >}} - -1. Save your changes. -1. Note the version and build number of the app build you want to update. This how to assumes an app version of 1.0.0 and a build number of 1. -1. Click **Project** > **Build Native Mobile App**. -1. Under **Build app for distribution**, select **Deploy OTA update via CodePush**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-ota/advanced-ota-menu.png" alt="Menu entry Deploy OTA update via CodePush" width="350" class="no-border" >}} - -1. Type in the target app version you wish to release the OTA update for. This version needs to match exactly with the app version used for building the app binaries in the previous step, or the one released on the app stores: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-ota/advanced-ota-configuration.png" alt="OTA configuration screen" width="350" class="no-border" >}} - -1. Click **Release an OTA update via CodePush**. -1. The Mendix Native Mobile Builder will compile your app and resources and release the OTA updates: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-ota/advanced-ota-building.png" alt="OTA build step" width="350" class="no-border" >}} - -1. On compilation you will receive links to the CodePush OTA update administration pages for your Android and iOS apps: - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-ota/advanced-ota-success.png" alt="OTA build step success" width="350" class="no-border" >}} - - {{< figure src="/attachments/howto8/mobile/native-mobile/how-to-ota/advanced-ota-appcenter-page.png" alt="OTA App Center page" width="350" class="no-border" >}} -1. Wait for the Native Mobile Builder to complete. -1. Restart the app on your testing device. You should be greeted with the following message: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/phone-update-prompt.png" alt="Update available prompt" width="300" class="no-border" >}} - -1. Tap **Confirm** to update your app. -1. The app should reload and greet you with the following dialog box: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/use-cli-docs/how-to-ota-cli/phone-success-prompt.png" alt="Update success prompt" width="300" class="no-border" >}} - -## Preserving your Model's Integrity - -Before issuing OTA updates or releasing new versions, please read and understand the [Offline First](/refguide8/offline-first/) reference guide. It is important to understand the implications of offline first. - -Mendix Native Apps are offline first. This means you should be cautious when changing the following elements, and should avoid changing them if possible: - -* The navigation profile -* An offline first entity, for example entity name changes, new entity relationships, and more - -Generally, you should avoid doing destructive changes to offline-synced entities. In the rare cases this is unavoidable, releasing a new app version or doing over the air updates might put your app's users in an unrecoverable state. - -### Offline Apps and Data Loss - -Data loss can occur when OTA updates or new releases coincide with apps being offline. For example, imagine your Mendix developers were hard at work optimizing the data store entity structure by consolidating entities to speed up sync operations. They release that morning. They push a new runtime by clicking the **Publish** button in Studio Pro, and then run the Native Mobile Builder to push a new update to the apps. All seems to work fine. - -That same morning however, your engineers were hard at work gathering field data in a remote area. Later that afternoon the engineers return back to the city and attempt to synchronize their data using the app's built-in synchronize button. Their synchronization fails. They do the only thing they can think of: restart the app. When the app starts they are greeted with the **Update Available** screen. They hit the continue button, get updated, and their data is lost or partially synchronized. - -This issue is independent from OTA updates and specific to offline apps. Your offline app runs a snapshot of your runtime's model locally. So as a Mendix Developer, you have to think twice before doing major changes that might make the app's state unrecoverable. In the example above the entity model was changed, and when the app attempted to synchronize it failed. This can create unrecoverable situations that will require a re-installation of the app, and can lead to data loss for unsynced data. - -## Transfer a CLI OTA-Compatible App to the Mendix Native Mobile Builder {#from-cli-to-ui} - -The transition from the CLI to Mendix Native Mobile Builder for OTA supporting apps requires a few manual steps. These steps ensure you do not have to release your apps to the app stores again. - -### Gather the Required Information - -1. Navigate to [App Center](https://appcenter.ms). -1. While logged in, find the Android and iOS apps used for building your app. -1. Check the URLs and note down the application ID as seen in the URLs. For example, in **https://appcenter.ms/users/user.name/apps/App-Android/distribute/code-push**, **App-Android** is the Android app's ID. -1. If your app is built under an organization the URL might look like this: **https://appcenter.ms/orgs/org-name/apps/App-Android/distribute/code-push**. In this case, note the **org-name** as seen in the URL. - -### Move Your App to the Mendix Native Mobile Builder - -1. Launch the Mendix Native Mobile Builder for your project. -1. If you have not yet completed the setup wizard, please complete it now. -1. Quit the tool completely. -1. Navigate to your app's directory and find the **nativemobile** folder (for example **C:\Users\user\Documents\Mendix\App\nativemobile**). -1. Enable **Hidden items** in Explorer to be able to see the *.config* file if it is not visible. -1. Open the *.config* file using Notepad and look for a key named **App Center**. If it is there it might contain some app names already like this example: - - ```text - "appcenter": { - "iosAppName": "App-iOS", - "androidAppName": "App-Android" - }, - ``` - - Optionally, if your apps are built in an App Center organization add the organization name like this example: - - ```text - "appcenter": { - "iosAppName": "App-iOS", - "androidAppName": "App-Android" - "organization": "your-organization-here" - }, - ``` - -1. Also, check the **appCenterOTA** key in the **Capabilities** section and confirm it is set to `"enabled": true`: - - ```text - "appCenterOTA": { - "enabled": true - } - ``` - - If the file does not exist add it manually. Either way, **make sure to change the names to reflect the IDs of your App Center apps**. Then make sure the newly changed file is still a valid JSON. - -1. Restart the Mendix Native Mobile Builder for your project. If the tool does not start, verify once more that the *.config* file is a valid JSON. - -Try to push an OTA update for an unreleased version of your app, for example v0.1.0. If the OTA update shows up on your App Center app's CodePush administration page, congratulations! You successfully transferred your project over to the Mendix Native Mobile Builder. - -If the OTA release button remains disabled. Verify that the app names added in the configuration are correct and make sure to add the organization property if your apps are under an organization. After you corrected the mistakes, restart the Mendix Native Mobile Builder and try again. - -## Read More - -* [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* [Offline First Reference Guide](/refguide8/offline-first/) -* [Codepush Introduction](https://docs.microsoft.com/en-us/appcenter/distribution/codepush/) -* [Using the CodePush UI](https://docs.microsoft.com/en-us/appcenter/distribution/codepush/using-ui) diff --git a/content/en/docs/howto8/mobile/native-mobile/native-custom-fonts.md b/content/en/docs/howto8/mobile/native-mobile/native-custom-fonts.md deleted file mode 100644 index db5a5b9bab8..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/native-custom-fonts.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: "Add Fonts to Your Native Mobile App" -url: /howto8/mobile/native-custom-fonts/ -weight: 42 -description: "This how-to teaches you how to enrich the design of your native mobile app with custom fonts." ---- - -## Introduction - -Good typography plays a major role in conveying your app's message while reinforcing your company's brand identity. Setting up the fonts you need is as simple as dragging and dropping the required fonts and setting your app's style. As you can see in the [Prerequisites](#prerecs) section below, Mendix offers two ways for you to add custom fonts: using the Mendix Native Mobile Builder or manually. - -### Introduction to Fonts in Mendix Native Mobile Apps - -When it comes to fonts files, several standards and types are common. True Type (*.ttf*), Open Type (*.otf* or *.ttf*), and Web Open Font Format (*.woff*) are the most common. - -The *.woff* file type does not work with native mobile apps. As this document focuses on native mobile platforms only, you should not use this file type in your apps. - -Open Type fonts support a variety of metadata as also the possibility to package multiple font varieties in a single file. This feature is not supported for mobile platforms. You should have each variety of the Font Family you would like to add as a separate file. - -Android and iOS each take a different approach to fonts. Where Android requires an explicit declaration for each font added, iOS can derive the font type and font style dynamically. Adding fonts to each platform requires a different approach. Android expects font files to exist in a specific folder, while iOS requires the font files to be explicitly linked in its build process. - -Furthermore, both platforms resolve available fonts differently. While iOS fully supports Open Type fonts and can select fonts based on their metadata, Android requires explicit linking of the font file to the weight and style. - -React Native, the underlying framework of Mendix native mobile apps, unifies the process of adding fonts. For example, fonts added under **assets/fonts** on Android are explicitly linked in the app. These fonts are then exposed directly in the framework for styling your widgets using the common CSS properties you use routinely. - -There are limitations to mobile font capabilities. For example, Android supports a very limited set of font types: regular, bold, italic, and bold italic. - -What does that mean for your app's CSS styles? - -For example, what would happen if you were to use the following snippet in your CSS styles: - -```css -{ - fontWeight: 550 -} -``` - -Your font, when running app on Android, would end up looking regular instead of the semi-bold font you would expect. This is because Android would first look up the available font styles registered. Unable to resolve the weight, it would fall back to the next best option. The same applies to styles. - -In addition, Android expects the font filename to be a combination of the actual font family name, weight, and style. For example, for Times New Roman bold italic, it expects something like *TimesNewRoman_bold_italic.ttf*. Failing to comply with these naming conventions makes the `fontFamily`, `fontWeight`, and `fontStyle` attributes fail to style text correctly. - -So how can these issues be mitigated? First of all, explicitly styling text using the common CSS text attributes `fontWeight` and `fontStyle` should be avoided. The results will vary per platform. Instead, use postscript names. Specifically, instead of a single `fontFamily` attribute with multiple weights and styles, a font family needs to be defined per weight and style combination. - -For example, instead of writing this: - -```text -export const bold = { - fontFamily: "Times New Roman", - fontWeight: "bold" | "500" -} -``` - -Define a constant like this: - -```text -export const timesNewRomanFontFamily = { - regular: "TimesNewRomanPSMT", - boldItalic: "TimesNewRomanPS-BoldItalicMT", - bold: "TimesNewRomanPS-BoldMT", - italic: "TimesNewRomanPS-ItalicMT", -}; -``` - -Then define the styles as follows: - -```text -export const boldText = { - fontFamily: timesNewRomanFontFamily.bold, -} -``` - -Now wherever you use `boldText`, you will get the expected result on both platforms consistently. - -## Prerequisites {#prerecs} - -Before starting this how-to, make sure you have completed the following prerequisites: - -Before adding fonts [using the Mendix Native Mobile Builder](#fonts-nbui): - -* Run through the Native Mobile Builder's wizard at least once - -Before [adding fonts manually](#manual): - -* Understand the native mobile [local build process](/howto8/mobile/native-build-locally/) -* Locally check out your repository -* Understand Git and have a Git tool installed -* Have Xcode installed for the iOS sections below - -## Add Custom Fonts With the Mendix Native Mobile Builder {#fonts-nbui} - -The Mendix Native Mobile Builder simplifies adding custom fonts to your app. It configures both Android and iOS apps and also provides the snippets needed to simply copy and paste in your Mendix app's native styles. To add custom fonts to your app, follow these steps: - -1. Start the Native Builder: - - {{< figure src="/attachments/howto8/mobile/native-mobile/build-native-apps/deploying-native-app/start-nbui.png" alt="Start Native Builer" width="350" class="no-border" >}} - -1. Navigate to **Custom Fonts**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/advanced-fonts.png" alt="Custom fonts screen" width="350" class="no-border" >}} - -1. Drag and drop the font files you would like to apply. For example, Times New Roman is being used here. When the process is complete you should see the font family uploaded in the list: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/advanced-fonts2.png" alt="Custom fonts screen filled" width="350" class="no-border" >}} - -1. Extend the list using the arrow to the right. Verify the expected fonts are available. You can continue by adding as many fonts as you prefer: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/advanced-fonts2.png" alt="Custom fonts screen filled and extended" width="350" class="no-border" >}} - -1. Click the snippet button to get the code snippet which you can copy to your styles: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/advanced-fonts4.png" alt="Custom fonts screen code snippet" width="350" class="no-border" >}} - -1. Build your app to get a new binary with fonts included. - -## Use Custom Fonts in Your App - -To use the new fonts to style your content, follow these instructions: - -1. Copy the snippet from the Native Mobile Builder: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/advanced-fonts4.png" alt="Custom fonts screen code snippet" width="350" class="no-border" >}} - -1. Open your styles *js* file and paste the snippet there. For this example, the *custom-variables.js* file is being used. For more information on styling your app, see [How to Style Your Mendix Native Mobile App](/howto8/mobile/how-to-use-native-styling/): - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/custom-variables.png" alt="Custom variables file" width="350" class="no-border" >}} - -1. The constant can now be imported and used to define the font family of any test style. Elements styled using these classes will now be styled using the font: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/custom-style.png" alt="Custom style" width="350" class="no-border" >}} - -## Add Custom Fonts Manually {#manual} - -While the Mendix Native Mobile Builder simplifies adding fonts, you might find yourself in a situation where you must add fonts manually instead. - -### Add Custom Fonts to an Android App - -To manually add custom fonts to your Android app, follow these instructions: - -1. Collect all the fonts you would like to use. -1. Use a tool like [Open Type Inspector](https://opentype.js.org/font-inspector.html) and derive the PostScript names for each font: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/postscript-name.png" alt="Open Type Inspector name metadata" width="350" class="no-border" >}} - -1. Rename the fonts to match the Postscript name. The Times New Roman font used in our example has these options: - * TimesNewRomanPSMT, for regular - * TimesNewRomanPS-BoldMT, for bold - -1. Copy the renamed fonts to the `android\app\src\main\assets\fonts` folder. -1. If you plan on using the tool to build your app, commit your changes: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/custom-fonts-android-repo.png" alt="GitHub repo after uploading custom fonts" width="350" class="no-border" >}} - -1. Build your Android app using your preferred method. - -Congratulations, you have learned how to add fonts to an Android app. - -### Add Custom Fonts to an iOS App - -Use Xcode to manually add fonts to an iOS app: - -1. Collect all the fonts you would like to use. -1. Use a tool like [Open Type Inspector](https://opentype.js.org/font-inspector.html) and derive the PostScript names for each font: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/postscript-name.png" alt="Open Type Inspector name metadata" width="350" class="no-border" >}} - -1. Rename the fonts to match the Postscript name. The Times New Roman font used in our example has these options: - * TimesNewRomanPSMT, for regular - * TimesNewRomanPS-BoldMT, for bold - -1. Open Xcode and select the workspace at **ios\NativeTemplate.xcworkspace**. -1. Drag the renamed fonts into the **Resources/Fonts** folder in Project Explorer. -1. Select both targets from the dialog box that shows up: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/custom-fonts-xcode-dialog.png" alt="Xcode option dialog for adding files" width="350" class="no-border" >}} - -1. Your folder structure should look like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/custom-fonts-project-explorer-filled.png" alt="Project explorer with fonts" width="350" class="no-border" >}} - -1. Open the *Info.plist* file by pressing Command + Shift + 0 and searching for the file. Press Enter to open it: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/xcode-open-infoplist.png" alt="Xcode Open file dialog" width="350" class="no-border" >}} - -1. Find the key `Fonts provided by the application`. Expand it if needed: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/xcode-plist-fonts.png" alt="Plist fonts key" width="350" class="no-border" >}} - -1. Press the **+** button next to the key to create a new, empty item in the list. -1. Type the font file name you wish to add as the value. In this case, we are adding the regular Times New Roman font, therefore the filename value is `TimesNewRomanPSMT.ttf`: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/xcode-plist-fonts-filled.png" alt="Plist fonts key filled" width="350" class="no-border" >}} - -1. If you plan on using the tool to build your app, commit your changes: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-custom-fonts/custom-fonts-ios-repo.png" alt="GitHub repo after uploading custom fonts" width="350" class="no-border" >}} - -1. Build your iOS app with your preferred method. - -Congratulations, you have learned how to add fonts to an iOS app. - -## Read More - -* [Implement Native Mobile Styling](/howto8/mobile/native-styling/) -* [Troubleshoot Common Native Mobile Issues](/howto8/mobile/common-issues/) diff --git a/content/en/docs/howto8/mobile/native-mobile/native-deep-link.md b/content/en/docs/howto8/mobile/native-mobile/native-deep-link.md deleted file mode 100644 index b74a49d5def..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/native-deep-link.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: "Set Up Deep Links in Native Mobile Apps" -linktitle: "Deep Links in Native Mobile Apps" -url: /howto8/mobile/native-deep-link/ -weight: 75 -description: "Connect URLs to your native mobile app by adding a deep link." ---- - -## Introduction - -While URLs typically open websites, they can also open an installed app on your mobile device. With this tutorial you will learn how to connect the URL `app://myapp` to your Mendix native app installed on your Android or iOS device. It is also possible to pass additional data using paths, query parameters, and hashes. Passing additional data could look like this: `app://myapp/task/123?action=close#info`. - -Deeplinks are always called or triggered within the schema that they define. For example, using `makeitnative://` instead of `http://` in the mobile browser would force the Make It Native app to open. - -A URL is constructed of these parts (everything after **path** is defined as a detail): - -{{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/url-parts.png" alt="url details" class="no-border" >}} - -You can also register the handling of a normal weblink beginning with `http://` or `https://`. However this requires some more work for iOS, and is not covered in this tutorial. For iOS see [Universal Links: Make the Connection](https://www.raywenderlich.com/6080-universal-links-make-the-connection) by Owen L. Brown. Android does allow for both types of weblink handling out of the box, as shown in the [For Android Apps](#for-android) section below. - -When an app is installed it registers the `schema` and optionally the `host` so its operating system knows which application should be opened when the URL is clicked. If you tap the link, the application will be opened whether it is running, running in the background, or closed. - -Deep links registration persist after the app is closed. Specifically, deep links are registered in the app manifest, which for Android production apps is read when the app is installed and for iOS apps is registered in the OS *info.plist* (which also makes the OS aware). - -### Testing With the Make It Native App - -For this tutorial Mendix recommends running your app from source against a local instance of Mendix Studio Pro. This will save you time when rebuilding and redeploying your app. To do this, follow the steps in [How to Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) to make an app and link it to the Make It Native mobile testing app. - -Please note that the Make It Native app has already the registered schema `makeitnative://` and can be used out of the box. To use the Make It Native app with that schema, see the [Using Deep Linking in Your App](#using-deep-linking) section below. If you want to change this schema, see [How to Create a Custom Developer App](/howto8/mobile/how-to-devapps/) to build your own custom developer app and then use the [Setting up App Deep Linking](#set-up) section below to change its schema. - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Complete the [Prerequisites](/refguide/mobile/getting-started-with-mobile/prerequisites/) of your app per its type -* Make sure your [Native Mobile Resources](/appstore/modules/native-mobile-resources/) module is up to date -* Install Git [command line](https://git-scm.com/downloads) tool for working with the Native Mobile App Builder CLI -* Install Mendix Studio Pro v 8.15.0 or above in order to use the Native Mobile App Builder - -## Setting up App Deep Linking {#set-up} - -If you do not already have a native template for your app, you can create one by following the sections below. - -### Using the Native Mobile App Builder - -Set up a native template with the **Native Mobile App Builder** by following these instructions: - -1. Launch the Native Mobile App Builder from the **Project** menu. Walk through the wizard and configure the project's details and tokens (for more information, see [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/)): - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/launch-native-mobile-app-builder.png" alt="launch native mobile builder" width="400" class="no-border" >}} - -2. Once done with the wizard you will enable deep linking capabilities. First, select the **Capabilities** menu item: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/capability-menu-option.png" alt="capability menu option" width="400" class="no-border" >}} - -3. Enter the `schema` name without the appending `://`: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/deep-link-input-field.png" alt="deep link input field" width="400" class="no-border" >}} - -4. Click the **Save** button. -5. Navigate to the build page and click **Build**. - -{{% alert color="info" %}} -When running locally from source, on iOS you have to run `pod install` once more -{{% /alert %}} - -### Using the Native Mobile App Builder CLI - -1. Create a shell app with Native Builder using the `prepare` command as shown in [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/). When you do this, replace the parameters in this example command with your own project's parameters, local paths, and tokens: - - ``` shell - native-builder.exe prepare --project-name "Native Deep Link" --app-name "Native Deep Link" --java-home "C:\Program Files\AdoptOpenJDK\jdk-11.0.3.7-hotspot" --mxbuild-path "C:\Program Files\Mendix\8.6.0.715\modeler\mxbuild.exe" --project-path "C:\mendix-projects\NativeDeepLink\NativeDeepLink.mpr" --github-access-token "c3f322c471623" --appcenter-api-token "2d5b570693d34" --app-identifier "com.mendix.native.deeplink" --runtime-url "https://nativedeeplink-sandbox.mxapps.io/" --mendix-version "8.6.0" - ``` - -1. Open your command line interface (CLI) of choice and change directory to the folder where you want to edit the build template: - - ```shell - cd c:/github - ``` - -1. Use Git to clone your Native Builder template from GitHub: - - ```shell - git clone https://github.com/your-account/native-deeplink-app - ``` - -#### For Android Apps {#for-android} - -The manifest file registers the schema and host on your Android device that will be associated with your Mendix app. Put simply, the manifest file controls the permissions, `activity` code, and more. So to enable deep linking, you will need to configure your *AndroidManifest.xml* file: - -1. Open the folder that you cloned your template into: `c:/github/native-deeplink-app`. -1. Open *android/app/src/main/AndroidManifest.xml*. -1. In `activity`, add the attribute `android:launchMode="singleTask"`. For more information on Launch Mode, see this [Android documentation](https://developer.android.com/guide/topics/manifest/activity-element#lmode). -1. Add an `intent-filter` in the `activity`: - - ```xml - - - - - - - ``` - - For more information on linking in Android, see this [Android documentation](https://developer.android.com/training/app-links/deep-linking#adding-filters). - -#### For iOS Apps - -The *info.plist* file registers the schema and host so that they will be associated with your app in iOS. This *plist* file controls permissions, app information, and more. So to enable deep linking, you will need to configure your *info.plist* file: - -1. Open the folder that you cloned your template into: `c:/github/native-deeplink-app`. -1. In Xcode (available on Apple Mac only) open *ios/NativeTemplate.xcworkspace*. -1. Open *ios/NativeTemplate/Info.plist* -1. Add `URL types`, then add `URL Schemes` and `URL identifier`: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/ios-info-plist.png" alt="ios info plist" class="no-border" >}} - - When viewing *Info.plist* as a text file, you would see that a section is added: - - ```xml - CFBundleURLTypes - - - CFBundleURLSchemes - - app - - CFBundleURLName - myapp - - - ``` - -1. Open *ios/AppDelegate.m* -1. Add this import to the existing imports: `#import "React/RCTLinkingManager.h"`. -1. Change the `openURL` method from this: - - ```objc - - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation { - [MendixAppDelegate application:application openURL:url sourceApplication:sourceApplication annotation:annotation]; - return YES; - } - ``` - - to this: - - ```objc - - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation { - [RCTLinkingManager application:application openURL:url sourceApplication:sourceApplication annotation:annotation]; - [MendixAppDelegate application:application openURL:url sourceApplication:sourceApplication annotation:annotation]; - return YES; - } - ``` - - This method will register the opened URL so it can be used in the **Native Deep Link** nanoflow actions. - -#### Rebuilding Your Native Mobile App - -When running locally from source you have to launch your app again: - -1. With your CLI, open the folder that you cloned your template into: `cd c:/github/native-deeplink-app`. -1. Add, commit, and push all changes from steps above: - - ```shell - git add . - git commit -m "Add deeplink handling" - git push - ``` - -1. Now rebuild and install your native mobile app to add your new capabilities: - - ```shell - native-builder.exe build --project-name "Native Deep Link" --app-version "1.0.0" --build-number 1 - ``` - -## Using Deep Linking in Your App {#using-deep-linking} - -Now your app is ready to use links, so you will set up the additional path and query data handling. If you skip this section, the links to your app will just open the app. Nothing will be done with the additional data available in your URL. - -### Native Deep Link Nanoflow Actions - -Now you have to handle the incoming URL in your Mendix application. To do this, you will use the Nanoflow Actions **Register Deep Link** and **Parse Url To Object** found in the [Native Mobile Resources](/appstore/modules/native-mobile-resources/) module. This module is automatically included in your app if it began as an up-to-date Starter App. If you do not see these actions available in your app, please update the module through the Marketplace. - -#### Registering Deep Link - -The Register Deep Link nanoflow action registers a callback nanoflow, which is called each time the app is opened using a URL. This **URL Handler** nanoflow will receive the URL, of type string, as an input parameter. - -{{% alert color="info" %}} -The name of the input parameter is case sensitive and can not be changed. -{{% /alert %}} - -#### Parsing a URL To a Mendix Object - -The Register Deep Link nanoflow action will create a new Mendix object, split a URL, and set all the object attributes with their values. For example, the URL https://john.doe:secret@www.example.com:123/forum/questions/?tag=networking&order=newest#top has the following attributes and values: - -| Attribute | Value | -| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -| href | https://john.doe:secret@www.example.com:123/forum/questions/?tag=networking&order=newest#top | -| protocol | https: | -| hash | top | -| query | ?tag=networking&order=newest | -| pathname | /forum/questions/ | -| auth | john.doe | -| host | www.example.com:123 | -| port | 123 | -| hostname | www.example.com | -| password | secret | -| username | john.doe | -| origin | https://www.example.com:123 | -| **Dynamically based on the number of slashes in the paths** | | -| path0 | forum | -| path1 | questions | -| **Dynamically based on the number of query keys** | | -| tag | networking | -| order | newest | - -### Using Utilities in Your App - -Now that the **Native Deep Link** nanoflow actions are available in Studio Pro, you have the utilities to register and process an URL. You will now use them in your application: - -1. In your app add the **App events** widget, which is also part of the Native Mobile Resource module, on your home page. -1. Double-click the **App events** widget. In **App events** tab, select **Page load** > **On load** > **Call a nanoflow**, and create a new nanoflow named *OL_RegisterDeepLink*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/app-events-register-deep-link.png" alt="app event register deeplink" class="no-border" >}} - - This nanoflow will be called only once when the app is started. - -1. In the **OL_RegisterDeepLink** nanoflow, add the action **Register DeepLink**, and in that action's **Url handler** create an nanoflow named *DL_ShowUrlDetails*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/nanoflow-register-deep-link.png" alt="nanoflow register deeplink" class="no-border" >}} - - This nanoflow will be called every time the app is opened using a URL. - -1. To parse the URL into an object, you will use a non-persistable entity named **DeepLinkParameter** from the **NativeMobileResources** module in the next step. For now, go to **NativeMobileResources** > **Domain Model** and examine this entity. If you use query strings or more, you can copy this entity to your own module. The attributes are all optional and you should only add the attributes your implementation requires. Besides the standard list of possible URL parts, you can also add the query string's keys (for example `?name=Jhon&title=sir`). The attributes are not case sensitive. You can add attributes for path segments of the URL which will be split into `Path0` , `Path1`, and more: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/entity-parameter.png" alt="parameter entity" class="no-border" >}} - -Next you will implement the deep link handler nanoflow **DL_ShowUrlDetails** so that it can pass URL data: - -1. In **DL_ShowUrlDetails** drag a parameter into your nanoflow's white space. -1. Double-click the parameter, give it the name *URL* (which is case sensitive) and the type **String**. -1. Add a **Parse URL to Object** activity to your nanoflow. Double-click it and configure it like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/parse-url.png" alt="parse url" class="no-border" >}} - -1. Add a **Show message** activity to the right of your **Parse URL to Object** activity. -1. Double-click the **Show message** activity. -1. In **Template** write *Your deep link callback URL {1} host = {2}*. -1. Click **Parameters** > **New**, write *$Parameter/Href*, and click **OK**. -1. Click **Parameters** > **New**, write *$Parameter/Host*, and click **OK**. -1. Right-click your **Parse URL to Object** activity, click **Set error handling**, and click **Custom without rollback**. -1. Drop an **End event** below your **Parse URL to Object** activity. Drag a line from **Parse URL to Object** down to the end event, right click it, and click **Set as error handler**. -1. Add a **Show message** activity to this line. Set it as type **Error**, and into template type *Failed to parse deep link data.*. Your finished nanoflow will look like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-deep-link/deep-link-nano-full.png" alt="full nanoflow" class="no-border" >}} - -### Testing Deep Linking - -Add a few test link buttons, for example {app://myapp/task/123} or {makeitnative://task/123}, to your web page, then re-run your project. Open the your app in your device's browser by typing *{your local IP address}:8080* into the browser. With the app loaded, tap the links to test. You should be brought out of your browser and into your app's page! - -{{% alert color="info" %}} -Please note that if you are not running the app from a local source, you must build your app again with the Native Builder before testing. Do this by using the `build` command: `build --project-name “Native Deep Link” --app-version “1.0.0" --build-number 2`. -{{% /alert %}} - -## Read more - -* [Native Builder Reference Guide](/refguide8/native-builder/) -* [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) -* [React Native Linking](https://facebook.github.io/react-native/docs/linking) -* [Deep Linking Android](https://developer.android.com/training/app-links/deep-linking) -* [Deep Linking iOS](https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content/defining_a_custom_url_scheme_for_your_app) -* [Universal Linking iOS](https://developer.apple.com/ios/universal-links/) -* [URL Schema vs Universal Link](https://medium.com/wolox-driving-innovation/ios-deep-linking-url-scheme-vs-universal-links-50abd3802f97) diff --git a/content/en/docs/howto8/mobile/native-mobile/native-styling/_index.md b/content/en/docs/howto8/mobile/native-mobile/native-styling/_index.md deleted file mode 100644 index 32c45ecc777..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/native-styling/_index.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Implement Native Mobile Styling" -url: /howto8/mobile/native-styling/ -weight: 30 -description: General information for native styling in Mendix. ---- - -{{% alert color="info" %}} -The Atlas UI Resources module is deprecated, as is Atlas 2. If you are still using Atlas 2, Mendix recommends that you [migrate from Atlas 2 To Atlas 3](/refguide9/moving-from-atlas-2-to-3/). -{{% /alert %}} - -## Introduction - -With Mendix 8, you can build native mobile apps with custom styling in Mendix Studio Pro. Styling native mobile apps uses JavaScript style sheets, which are new to Mendix Studio Pro. Consult the guidelines below for information on theme folder structure, classes, and design properties. - -## Theme Folder Structure - -For each app, styling is stored in the **theme/styles** folder. From there styling is split into **native** and **web** folders. Both have the same structure. - -These folders have strict protocols: - -* Users should only add or change styling in the **app** folder -* The **app** folder has two files: *custom.js* and *custom-variables.js*—when changing the styling, always copy the variable you want to change from *native/core/variables.js* to *native/app/custom-variables.js* -* The *custom-variables.js* file will overwrite the *variables.js* file—do not change anything in the **core** folder directly, as this makes updating Atlas more difficult -* Any variables you want to change or add should be put in *custom-variables.js* -* Any classes you want to change or add should be put in *custom.js* - -The **native/core/base** folder contains global helper classes. These classes are generic and can be put on all widgets. Some of them are also available as design properties in Mendix Studio Pro. - -The **native/core/helpers** folder contains helper classes for widgets. Every widget has its own file which contains its design properties and some extra classes. - -The **native/core/helpers/_helperfunctions** folder contains multiple helper functions. These functions can help you style more easily. For example, the `adjustFont` function receives a font and adjusts it to the screen size. This will make your font sizes responsive. For more information about these helper classes, see their descriptions in the code. - -The **native/core/widgets** folder contains the default widget styling. Every widget has its own file which contains its default class name. - -In **native/ui_resources** you will find resource package styling. Here you can find all styling related to building blocks, page templates and layouts. - -## Classes - -Default class names—which are the class names set by Mendix Studio Pro—will always be named in Pascal case. All other classes will be in lowerCamelCase. This keeps changes to default widget styles clear. - -## Design Properties - -Available in Mendix Studio Pro, design properties are an easier way to apply classes. Atlas already offers several useful design properties out of the box. You can see them by clicking on a widget and looking at the **Properties** panel. A design property can be either a drop-down menu or a toggle. A toggle will toggle one class, while a drop-down menu will apply a different class for each drop-down item. - -## Read More - -* [Mendix Atlas UI](/howto8/front-end/atlas-ui/) -* [Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) diff --git a/content/en/docs/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling.md b/content/en/docs/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling.md deleted file mode 100644 index 8301a1e750c..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: "Style Your Mendix Native Mobile App" -url: /howto8/mobile/how-to-use-native-styling/ -weight: 30 -description: A how-to for styling your first Mendix Native App. -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -With Mendix 8, you have the capacity to alter design properties with Mendix Studio Pro. Furthermore, because all native mobile styling is written in JavaScript, you have new ways of applying your styling customizations. For more details on native styling, class names, and widget styling, see the [Native Mobile Styling Reference Guide](/refguide8/native-styling-refguide/). - -## Prerequisites - -* Install an integrated development environment (IDE) of your choice (Mendix recommends [Microsoft Visual Studio Code](https://code.visualstudio.com/)) -* Create a Mendix app based on the Blank Native Mobile App template by following the [Creating a New App Based on the Quickstarter App](/howto8/mobile/getting-started-with-native-mobile/#quickstartapp) section of *Get Started with Native Mobile* -* Download the Make It Native 8 app on your mobile device via either the [Google Play](https://play.google.com/store/apps/details?id=com.mendix.developerapp) store or the [Apple App Store](https://apps.apple.com/us/app/make-it-native/id1334081181) so you can text your app and see your styling changes - -### Customizing the Quickstarter App - -The [Blank Native Mobile App](https://marketplace.mendix.com/link/component/109511/) is styled using an Atlas UI resources package. This package consists of: - -* Widgets -* Building blocks -* Page templates -* Page layouts - -These resources let you style your app with a wide variety of interface parts. However, you can customize them further by following these steps: - -1. On your **Home_Native** home page, delete the **Intro screen** content. -1. Place a button widget on your app's home page: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling/button-one.png" alt="button" class="no-border" >}} - -1. Click **Run Locally** and then click **View** to see your app. The button will be blue with white text, which is its default styling. -1. Open *theme/styles/native/app/custom-variables.js* using your IDE of choice. -1. Change the `brand.primary` from **#0595DB** to *rosybrown*: - - ```javascript - //Brand Style - export const brand = { - primary: "rosybrown", - success: "#76CA02", - warning: "#f99b1d", - danger: "#ed1c24", - }; - ``` - -1. Save your file. -1. Click **Run Locally** to apply your changes: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling/brand-primary-rosybrown.png" alt="rosybrown button" class="no-border" >}} - - You have successfully altered a default button to look rosy brown These screenshots employ the Make It Native app's [Dark Mode](/releasenotes/mobile/make-it-native-app/#new-features-5). - -## Classes - -Classes are groups of styling properties which define how certain elements of your app will be rendered. Once you make a class, one which applies to a button for example, you can reuse that class to easily style subsequent buttons in the same way. To learn how to apply a class to a widget, follow the steps below. - -1. Place a second button widget on your app's home page. -2. Run your app to view your button. -3. Select the button widget, and then click the **Properties** panel. Under **Common** you will see the button's **Class** field. -4. Type *btnSuccess* into the **Class** field: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling/btn-success.png" alt="class field" class="no-border" >}} - -5. Click **Run Locally** to save and refresh your app. Notice the button turned green: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling/green-button.png" alt="green button" class="no-border" >}} - - You have successfully applied an Atlas-provided class to a button widget. - -## Design Properties - -Design properties are easy-to-use classes in Mendix Studio Pro which you do not need to look up before using. Design properties are present inside Mendix Studio Pro with every widget they apply to. They can be accessed in the **Properties** panel, or by double-clicking the widget and clicking the **Appearance** tab for more advanced options. Design properties are particularly useful for creating generic styling for use on multiple widgets. Below you will use design properties to alter a button widget. - -1. Place a third button widget on your app's home page. -2. Select the button, and find its **Design Properties** in the **Properties** panel. -3. Click the **Button style** drop-down arrow and select **Warning**. - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling/btn-warning.png" alt="warning button" class="no-border" >}} - -4. Run your app again to see the *design* button's new color: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling/orange-button.png" alt="orange button" class="no-border" >}} - - Using design properties, you have changed the blue default button widget to orange. For any other warning buttons, you could easily apply the same design property. - -## Creating Your Own Classes {#creating-your-own-classes} - -When you have specific design requirements, you will need to build custom classes to fit. To harness the power of custom classes, follow the instructions below. - -1. Place a fourth button widget on your app's home page. -2. Navigate to your Mendix app's folder using your IDE. -3. Open the **theme** folder of your app. -4. Open *styles/native/app/custom.js*. -5. Copy this code snippet into *styles/native/app/custom.js*: - - ```javascript - export const className = { - container: { - - }, - icon: { - }, - caption: { - - } - } - ``` - - To alter a class on your own, consult the [Native Mobile Styling Reference Guide](/refguide8/native-styling-refguide/) to understand widget structures. - -6. Now you will edit the code you pasted. Apply a transparent background color to customize the default button widget: - - ```javascript - export const className = { - container: { - backgroundColor: "transparent" - }, - icon: { - }, - caption: { - } - } - ``` - -7. Because your app already has default styling, you can remove the icon and caption properties. Also, change the constant to a unique, self-explanatory value such as `btnBordered`: - - ```javascript - export const btnBordered = { - container: { - backgroundColor: "transparent" - }, - } - ``` - -8. Save your work. -9. In Mendix Studio Pro, select your fourth button. In the **Properties** panel, type *btnBordered* into the **Class** field. -10. Click **Run Locally** to see that your button's background color is transparent: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling/bordered-button.png" alt="bordered button" class="no-border" >}} - - You have successfully customized a simple button widget. Using these basic principles, you can go on to customize widgets with distinct looks. - -## Implementing Custom Design Properties - -In this section you will learn to turn the class you made into a design property, so that it can be easily used by other people. - -1. Place a fifth button widget on your app's home page. -2. Open *theme/settings-native.json* in your IDE. -3. Find the `ActionButton` class. There are already design properties in `ActionButton`. Next, you will add some of your own. -4. Place this object under the first one in `ActionButton`: - - ```json - { - "name": "Bordered", - "type": "Toggle", - "description": "Create a bordered button.", - "class": "btnBordered" - }, - ``` - -5. In Mendix Studio Pro, press F4 to synchronize your project directory. -6. Select the fifth button. In **Properties** > **Design Properties**, your **Bordered** design property should now be visible: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling/bordered-design-property.png" alt="bordered design property" class="no-border" >}} - -7. Enable the **Bordered** design property by clicking its drop-down menu and selecting **Yes**. - -8. Click **Run Locally** again and view your app: - - {{< figure src="/attachments/howto8/mobile/native-mobile/native-styling/how-to-use-native-styling/design-property-border-button.png" alt="design properties border" class="no-border" >}} - - You have implemented your own custom design property. Other users can quickly harness your design property without having to consult a class name list. - -Congratulations! By completing this how-to, you have learned how to alter a styling property, apply classes and design properties, and create your own classes and design properties. - -## Read More - -* [How to Implement Native Mobile Styling](/howto8/mobile/native-styling/) -* [Native Mobile Styling Reference Guide](/refguide8/native-styling-refguide/) -* [Mendix Atlas UI](/howto8/front-end/atlas-ui/) -* [How to Get Started with Native Mobile](/howto8/mobile/getting-started-with-native-mobile/) diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/_index.md b/content/en/docs/howto8/mobile/native-mobile/notifications/_index.md deleted file mode 100644 index 897ccaae6b6..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/_index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Use Notifications" -url: /howto8/mobile/notifications/ -weight: 54 -description: Tutorials for configuring push and local notifications. ---- - -## Introduction {#intro} - -These guides teach you how to configure push notifications (also known as remote notifications) for your Mendix apps. The guides are meant to be completed in order, and they teach you how to send a test push notification to a single device. Depending on your app's starting template your app may already satisfy certain prerequisites and conditions. Complete only the steps which apply to your use case, and skip what does not apply. - -* [Add Module Dependencies](/howto8/mobile/notif-add-module-depends/) — Install the required dependency modules so your app can use push notifications. -* [Implement the Push Notifications Module](/howto8/mobile/notif-implement-module/) — Learn to implement the Push Notifications Connector module. -* [Set Up the Google Firebase Cloud Messaging Server](/howto8/mobile/setting-up-google-firebase-cloud-messaging-server/) — Set up a Firebase account and configure the service in your app so that you can send push notifications. -* [Configure Push Notifications](/howto8/mobile/notif-config-push/) — Learn to configure push notifications in the runtime. -* [Implement Push Notifications in Your Native App](/howto8/mobile/notif-implement-native/) — Implement push notifications for a native app. -* [Build a Native App with Push Notifications Enabled](/howto8/mobile/notif-build-native/) — Build a native app with push notifications enabled. -* [Send Your First Test Push Notification](/howto8/mobile/notif-send-test/) — Send a test notification to confirm your app is working properly. - -After you complete the how-tos above, you may wish to do more advanced tasks with notifications. For information on **sending push notifications to multiple devices**, use this how-to: - -* [Send Notifications to Multiple Devices](/howto8/mobile/notif-mult-devices/) - -The documentation described above is specifically for native mobile apps. For information on push notifications in hybrid apps, see [Set Up Hybrid Push Notifications](/howto8/mobile/setting-up-hybrid-push-notifications/). For information on local notifications, see [Use Local Notifications](/howto8/mobile/local-notif-parent/). - -To get started, begin with the series' first entry: [Add Module Dependencies](/howto8/mobile/notif-add-module-depends/). diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/_index.md b/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/_index.md deleted file mode 100644 index 427faeb1c76..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Use Local Notifications" -url: /howto8/mobile/local-notif-parent/ -weight: 88 -description: Tutorials for setting up local push notifications which do not use an internet connection. ---- - -These step-by-step guides teach you how to build local notifications for native mobile applications. Local notifications will only allow you to schedule and send notifications confined to one mobile device. These notifications do not use an internet connection. One use of a local notification might be an alarm app which sends a notification after an amount of time has elapsed. - -These how-tos teach you how to do the following: - -* [Part 1: Local Notifications](/howto8/mobile/native-local-notifications/) – Trigger native notifications from Mendix app's microflow, configure your notification permissions, and test the notifications on a device -* [Part 2: Badges](/howto8/mobile/local-notif-badges/) – Make your notifications leave badge indicators on your application's icon -* [Part 3: Actions](/howto8/mobile/local-notif-action/) – Configure notifications to do an action after being tapped (in this case, show a page) -* [Part 4: Data](/howto8/mobile/local-notif-data/) – Enable notifications to pass data and bring a user to a page with specific parameters set -* [Part 5: Scheduling](/howto8/mobile/local-notif-schedule-cancel/) – Make notifications trigger at a certain time and cancel them diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-action.md b/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-action.md deleted file mode 100644 index ccb60fcd277..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-action.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Part 3: Actions" -url: /howto8/mobile/local-notif-action/ -weight: 30 -description: A tutorial for making your push notifications trigger actions when tapped. -canonical_url: "https://docs.mendix.com/refguide/mobile/using-mobile-capabilities/local-notifications/local-notif-action/" ---- - -## Introduction - -Several apps which use push notifications will also need actions to trigger after a user taps a notification. This step-by-step guide teaches you how to make a tapped notification show a specific page. - -{{% alert color="warning" %}} -The Make It Native app is currently experiencing limitations which interfere with notifications. We are currently fixing those limitations. To test your local notification actions, please use a native release app installed on a mobile testing device instead of the Make It Native app. To build a native release app, please complete [How to Deploy a Native App](/howto8/mobile/deploying-native-app/) and use that app to test local notification actions. -{{% /alert %}} - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Review the [basic differences](https://developer.apple.com/documentation/usernotifications) between local notifications and push notifications -* Install the [Make It Native](/refguide8/getting-the-make-it-native-app/) app on your mobile device -* Complete the preceding tutorials in this [Use Local Notifications](/howto8/mobile/local-notif-parent/) series - -## Setting an Action for When a Notification is Tapped - -In this section you will learn to show a page when a user taps a notification. - -1. Drag a **Notifications** widget onto your native home page. - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-action/notif-widget.png" alt="notifications widget" width="400" class="no-border" >}} - -2. Double-click the widget. -3. Click **Actions** > **New**. -4. Name your action *show_page*. -5. Select **On open to** > **Show a Page**. -6. Click **New** to make a new page. -7. Type *NotifPage* into **Page Name**. -8. Click **Blank** pane on the left and select the **Blank** page template. -9. Click **OK** to create your page. -10. Drag an **Open page button** widget onto **NotifPage**. -11. When prompted, click your **Home_Native** page: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-action/home-native-select.png" alt="click home page" width="400" class="no-border" >}} - -12. Click **Select**. Now you have a button which will bring you back to your home screen when you are testing: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-action/nav-button.png" alt="click home page" class="no-border" >}} - -13. Navigate back to your **ACT_CreateAndSendNotification** nanoflow. - -In **ACT_CreateAndSendNotification** you will set up the logic for tapping a notification which brings you to a page. This process requires you set up a string variable. However, because this string variable will never be used with other variables—it will only be used for internal notification functionality—you will not set it up by dragging and dropping a create variable activity like you did before. You will set it up with an expression. - -1. Double-click your **Display Notification** activity: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-action/set-action-name-display.png" alt="click display notification" class="no-border" >}} - -2. Click **Action Name** > **Edit** - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-action/add-action-name.png" alt="edit action name" width="500" class="no-border" >}} - -3. Type `'show_page'` into the expression field: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-action/show-page-exp.png" alt="show page expression" width="400" class="no-border" >}} - -4. Click the **OK** buttons until you are back at your nanoflow. - -Great job setting up your notification. Now you can test it: - -1. Click **Run Locally** to update your app. -2. Start the app on your mobile device. -3. Tap your **Send notification** button. -4. Tap the notification to navigate to the page you selected. -5. Tap the **Return to home page** button to navigate back to your home page. - -Now you can show pages after notifications are tapped. Next, in [How to Use Local Notifications Part 4: Data](/howto8/mobile/local-notif-data/), you will learn to pass data to such pages. - -## Read More - -* [Implement Push Notifications](/howto8/mobile/implementation-guide/) -* [Build JavaScript Actions](/howto8/extensibility/build-javascript-actions/) diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges.md b/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges.md deleted file mode 100644 index b57789356a1..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Part 2: Badges" -url: /howto8/mobile/local-notif-badges/ -weight: 20 -description: A tutorial for setting up badges for local push notifications. ---- - -## Introduction - -Badges are crucial for many apps on iOS and Android. Badges differ in appearance based on platform, and often indicate important information in applications. For example with messaging applications, it is good practice to employ badges which alert users to new messages. - -You will need to build badge functionality into your app so that when a user gets a notification, the app shows a badge on its app's icon. Also, badges are *not automatically decreased or removed* when a user checks an app. These two functions must be built manually by a developer. - -In this document you will learn to add badge functionality to your app, as well as how to remove a badge. - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Review the [basic differences](https://developer.apple.com/documentation/usernotifications) between local notifications and push notifications -* Install the [Make It Native](/refguide8/getting-the-make-it-native-app/) app on your mobile device -* Complete the preceding tutorial in this [Use Local Notifications](/howto8/mobile/local-notif-parent/) series - -## Setting a Badge Number - -Since you know how to send a simple local notification, you can now set the badge number by following these steps: - -1. Open **ACT_CreateAndSendNotification**. -2. Drag a **Create variable** activity to the right of the three string variables you made: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/new-variable-badge.png" alt="new create variable" width="500" class="no-border" >}} - -3. Double-click the variable activity and select **Data type** > **Integer/Long**. -4. Type *1* into the expression value field. -5. Type *badge_number* into the **variable name** field: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/badge-1.png" alt="badge number" width="400" class="no-border" >}} - -6. Click **OK**. -7. Drag a **Set badge number** JavaScript action to the right of your merge activity: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/set-badge-act.png" alt="drag set badge number" class="no-border" >}} - -8. Double-click the badge number activity. -9. Set the value of **Badge number** to **$badge_number** - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/badge-input.png" alt="value badge number" class="no-border" >}} - -10. Click **OK**. - -Start and load the app on your mobile device and tap the button which calls your nanoflow. You will see a notification. Go to your device's start screen to see the notification badge on your app: - -{{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/badge-mobile.png" alt="badge number on mobile" width="300" class="no-border" >}} - -## Reducing a Badge Number - -To make your badge disappear after your user opens your app, follow the instructions below. - -1. Drop an **App events** widget onto **Home_Native** (you have this widget because it is included in the [Blank Native Mobile App](https://marketplace.mendix.com/link/component/109511/)): - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/app-events.png" alt="app event widget" class="no-border" >}} - -2. Double-click your **App events** widget. -3. Select **On load** > **Call a nanoflow**. -4. Click **New** and make a new nanoflow: *ACT_ClearBadge*. -5. Go to **ACT_ClearBadge**. -6. Drag a **Set badge number** activity into your nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/clear-set-badge.png" alt="set badge activity" class="no-border" >}} - -7. Double-click your **Set badge number** activity. -8. Click **Badge number** > **Edit**. -9. Type *0* and click **OK**. -10. Set **Use Return Value** to **No**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/clear-badge-settings.png" alt="return value" width="400" class="no-border" >}} - -11. Drag a **Log message** activity into your microflow. -12. Double-click your **Log message** activity, write *Your notification has been cleared* into **Template**, and click **OK**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/clear-text-log.png" alt="clear text" width="500" class="no-border" >}} - -13. Go back to your **Home_Native** page and double-click your **App events** activity. -14. Make sure **Page load** > **On load** is set to **Call a nanoflow**, and specify that nanoflow as **ACT_ClearBadge**. This will make sure your badge clears on page load. -15. Set **App resume** > **On resume** is set to **Call a nanoflow**, and specify that nanoflow as **ACT_ClearBadge**. This will make sure your badge clears when your app is resumed: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/app-event-final-settings.png" alt="app event final settings" width="300" class="no-border" >}} - -16. Click **OK** and save your changes. - -You can now test your badge clearing. - -1. Start and load the app on your mobile device and tap the button which calls your nanoflow. You will see a notification. -2. Go to your device's start screen to see the notification badge on your app: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/badge-mobile.png" alt="badge number on mobile" width="300" class="no-border" >}} - -3. Tap your app again to open it. -4. Navigate to your device's home screen and see that your Make It Native app has no more badge: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-badges/cleared-badge-icon.png" alt="cleared-badge-icon.png" width="300" class="no-border" >}} - -5. Check your Studio Pro **Console** to read the **Your notification has been cleared** text you set up. - -Congratulations! You successfully implemented basic badge clearing. Next, in [How to Use Local Notifications Part 3: Actions](/howto8/mobile/local-notif-action/), you will learn how to configure a notification so that when a user taps a notification, they are brought to a page. - -## Read More - -* [Implement Push Notifications](/howto8/mobile/implementation-guide/) -* [Build JavaScript Actions](/howto8/extensibility/build-javascript-actions/) diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data.md b/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data.md deleted file mode 100644 index 764bf592cf9..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -title: "Part 4: Data" -url: /howto8/mobile/local-notif-data/ -weight: 40 -description: A tutorial for integrating data into your push notifications. ---- - -## Introduction - -Several apps make it so that when user taps a notification, the user is taken to specific page with specific parameters set. You can achieve this by sending data along with a notification. - -For example, a user could tap a notification about an entity object. They should be brought to a details page which shows an entity object's details. But in order to make that happen, you must set your notification up to pass that particular entity to its details page. - -Every entry in the Mendix database has an unique ID. If you want to pass an object, your GetGUID JavaScript action must retrieve that object's GUID and pass it to your local notification. When the notification is tapped, the widget can use the object's GUID to retrieve that object using the GetObjectByGUID JavaScript action. Finally, your object will be passed to the action you specify in your notification. - -You will create the following things to send data to pages: - -* **Two entities** – *TestEntity* to test how to show particular object, and *Notification* to help pass data to your page -* **One page** – *DetailTestEntity* which will be shown on tapping a notification -* **One microflow** – *DS_TestEntity* to create dummy data for testing -* **Three nanoflows** – *DS_Notification* to create a dummy notification object, *ACT_PassGUIDToNotification* to pass a GUID, and *On_tapNotification* to process data from your notification - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Review the [basic differences](https://developer.apple.com/documentation/usernotifications) between local notifications and push notifications -* Install the [Make It Native](/refguide8/getting-the-make-it-native-app/) app on your mobile device -* Complete the preceding tutorials in this [Use Local Notifications](/howto8/mobile/local-notif-parent/) series - -## Sending Data to Pages - -To make your two entities, do the following: - -1. Navigate to your domain model. -2. Drag a new entity into your domain model: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/new-entity.png" alt="new entity" width="500" class="no-border" >}} - -3. Double-click it and name it *TestEntity*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/test-entity.png" alt="test entity" width="500" class="no-border" >}} - -4. Click **Attributes** > **New**, name it *StringAttribute_1*, and click **OK**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/first-string-attribute.png" alt="string attribute" width="400" class="no-border" >}} - -5. Click **OK** again until you are back at the domain model. -6. Create an entity named *Notification* on your domain model with a string attribute *GUIDString*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/guid-notification.png" alt="GUID string" width="500" class="no-border" >}} - -To set up a notification nanoflow, do the following: - -1. Create a nanoflow named *DS_Notification*.
-2. Drag a create object activity into your nanoflow. -3. Double-click your create object activity. -4. Click **Entity** > **Select**. -5. Click **Notification**, then click **Select**. -6. Click **OK**. -7. Right-click your create object activity and select **Set $NewNotification as return value**:
- - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/create-notif-nano.png" alt="create notification nanoflow" width="500" class="no-border" >}} - -To set up your microflow, do the following: - -1. Create a microflow named *DS_TestEntity*. -2. Drag a create object activity into your microflow. -3. Double-click your create object activity. -4. Click **Entity** > **Select**. -5. Click **NativeMobile.TestEntity**. -6. Click **Select**. -7. Check **Commit** -8. Click **OK**. -9. Double-click your end event, make sure its **Type** is **Boolean**, type *true* into the value field, and click **OK**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/end-event-true.png" alt="end event true" width="500" class="no-border" >}} - -To make this microflow run after startup, do the following: - -1. Double-click **Settings** in your Project Explorer: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/pe-settings.png" alt="project explorer" width="400" class="no-border" >}} - -2. Click the **Runtime** tab: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/runtime-tab.png" alt="click runtime" width="400" class="no-border" >}} - -3. Click **After startup** > **Select**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/after-startup.png" alt="select after start up" width="500" class="no-border" >}} - -4. Click **DS_TestEntity** then click the **Select** button to achieve this result: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/select-ds-entity.png" alt="select test entity" width="500" class="no-border" >}} - -5. Click **OK** - -To make your page, do the following: - -1. Crete a new blank native page named *DetailTestEntity*. -2. Drag a data view widget onto your new page. -3. Double-click your data view widget. -4. In **Data Source**, click **Entity (path)** > **Select**. -5. Click **TestEntity**. -6. Click **Select** to see the following: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/data-view-source.png" alt="entity test entity" class="no-border" >}} - -7. Click **OK**. -8. When asked **"Do you want to automatically fill the contents of the data view?"** click **Yes**. -9. This will be the page your user sees when they tap the notification: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/page-with-data-view.png" alt="page with data view" width="300" class="no-border" >}} - -Next you will learn how to pass data to pages after you have tapped a notification. First, make a nanoflow: - -1. Create a nanoflow named *ACT_PassGUIDToNotification*. - -2. Add a retrieve action to your nanoflow, set **Source** to **From Database**, and set **Range** to **First**. Click **Entity** > **Select** and select the **TestEntity**. In **Object name** type *FirstTestEntityObject*. Then click **OK**. This will be the object that gets the GUID: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/retrieve-object.png" alt="retrieve object" class="no-border" >}} - -3. Add a JavaScript Action Call activity to your nanoflow. -4. Double-click the action call activity. -5. Click **JavaScript Action** > **Select**. -6. Type *GetGuid* into the search field, click **GetGuid**, and click **Select**. (You are able to find the GetGuid JavaScript action because it is included in the NanoflowCommons module inside the Native Quickstarter template.) -7. Click **Entity Object** drop-down and click **$FirstTestEntityObject**. -8. In **Variable name** field type **GUIDForFirstObject**. -9. Click **OK**. -10. Drag four create variable activities into your nanoflow: *Title*, *Subtitle*, *Body*, and *ActionName*. Give them the values *'title1'*, *'subtitle1'*, *'body1'*, and *'OpenPageWithParams'* respectively: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/title1-activity.png" alt="title1" width="400" class="no-border" >}} - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/subtitle1-activity.png" alt="subtitle1" width="400" class="no-border" >}} - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/body1-activity.png" alt="body1" width="400" class="no-border" >}} - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/actionname-activity.png" alt="actionname" width="400" class="no-border" >}} - - This is how all of your activities will look: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/guid-nano-with-four-strings.png" alt="actionname" width="500" class="no-border" >}} - -11. Drag a JavaScript action call activity into your nanoflow. -12. Double-click the action call. -13. Click **JavaScript action** > **Select**. -14. Type *DisplayNotification* into the search field, click the corresponding JavaScript action, and click **Select**. -15. Set the **Body**, **Title**, **Subtitle**, **Action name**, and **Action guid** to the corresponding variables you created previously, and set **Play Sound** to **True**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/first-guid-action.png" alt="first guid action" width="500" class="no-border" >}} - -16. Click **OK**. -17. Drag this nanoflow onto your app's **Home_Native** page to create a button which calls it, and name the button *Pass GUID to Notification*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/pass-guid-button.png" alt="guid button" width="500" class="no-border" >}} - -Good job! When a user taps a notification from the **Pass GUID to Notification** button, they will now be brought to the **DetailTestEntity** page. Next you will create a nanoflow which receives **notificationEntity** as a parameter, retrieves an object via this parameter, and passes the object to a page. - -1. Make a new nanoflow named *ON_tapNotification*. -2. Drag a parameter into your nanoflow. -3. Click **Data Type** > **Select**. Click **Notification**, then click **Select**. -4. Fill **Name** in as *notificationEntity*. -5. Click **OK**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/notif-entity.png" alt="guid button" class="no-border" >}} - -6. Drag a JavaScript action call into your nanoflow. -7. Double-click the JavaScript action call, then click **Select**. -8. Type *GetObjectByGuid* into the search field, click that action, then click **Select**. -9. Click **TestEntity** and then click **Select**. -10. Next to the **Object guid** drop-down menu click **Edit**. -11. Type *$NotificationEntity/GUIDString* into your argument field and click **OK**. -12. Select **Use Return Value** > **Yes**. -13. In **Object name** write *ReturnedObjectByGUID*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/get-object-by-guid-settings.png" alt="guid settings" width="500" class="no-border" >}} - -14. Click **OK** to save and close your JavaScript Action settings: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/guid-activity.png" alt="guid activity" width="500" class="no-border" >}} - -15. Drop a **Change object** activity into your nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/new-change-object.png" alt="change object" width="500" class="no-border" >}} - -16. Double-click the change object activity. -17. Select **Object** > **ReturnedObjectByGUID (NativeMobile.TestEntity)** from the drop-down menu. -18. Click **Action** > **New**, make sure **Member** is set to the string attribute, and into **Value** type *'Your notification has forwarded you here!'*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/change-object-action.png" alt="change object action" width="400" class="no-border" >}} - -19. Click **OK**. Check that your dialog box looks like this, then click **OK** again to close it: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/change-object-final.png" alt="change object final" width="400" class="no-border" >}} - -Next you are going to create a show page action for **ON_tapNotification**. - -1. Drag a **Show Page** activity into your nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/add-show-page.png" alt="new show page" width="500" class="no-border" >}} - -2. Double-click the **Show Page** activity. -3. From the **Object to pass** drop-down menu select **ReturnedObjectByGuid**. -4. Click **Page** > **Select**, click **DetailTestEntity**, then click **OK**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/show-page-settings.png" alt="guid button" width="400" class="no-border" >}} - -5. Click **OK** to close the **Show Page** activity settings, then navigate to your **Home_Native** page. - -Now you will set up a data view on your home page. - -1. Drag a **Data View** widget onto your **Home_Native** page. -2. Double-click your data view. -3. Select **Data source** > **Type** > **Nanoflow**. -4. Click **Nanoflow** > **Select** and choose **DS_Notification**. -5. Click **OK** to go back to your home page, and click **OK** on the subsequent data view dialog box. -6. Move the **Notifications** widget inside this data view. -7. Confirm that the text box in your data flow is using **GUIDString** as its data source: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/GUID-data-source.png" alt="first guid action" width="500" class="no-border" >}} - -8. Double-click your notifications widget. -9. Click **GUID** > **Select**. -10. Click **GUIDString (String (200))**, then click **Select**. Your results will look like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/set-guid-string.png" alt="guid string" width="500" class="no-border" >}} - -11. Click **Actions** > **New**. -12. Create a **New Action** named *OpenPageWithParams*, set **On open** to **Call a nanoflow**, and select **ON_tapNotification**. - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-data/notif-action-2.png" alt="notification action" width="500" class="no-border" >}} - -Great job! Now you will test your data notification functionality. - -1. Start and load the app on your mobile device. -2. Tap the button which sends a notification. -3. Tap the notification to navigate to the **DetailTestEntity** page with the proper object. - -Congratulations! You have harnessed the power of data to enhance your push notifications. Next, in [How to Use Local Notifications Part 5: Scheduling](/howto8/mobile/local-notif-schedule-cancel/), you will learn how to schedule notifications for specific times and cancel them. - -## Read More - -* [Implement Push Notifications](/howto8/mobile/implementation-guide/) -* [Build JavaScript Actions](/howto8/extensibility/build-javascript-actions/) diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel.md b/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel.md deleted file mode 100644 index c6a6f555c5d..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: "Part 5: Scheduling" -url: /howto8/mobile/local-notif-schedule-cancel/ -weight: 50 -description: A tutorial for scheduling and cancelling push notifications. ---- - -## Introduction - -Local notifications should rarely notify a user right after they perform an action. Here you will learn to configure local notifications to trigger after a period of time. To do this, you will use a JavaScript action named **ScheduleNotification**. After that, you will learn how to cancel scheduled notifications. - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Review the [basic differences](https://developer.apple.com/documentation/usernotifications) between local notifications and push notifications -* Install the [Make It Native](/refguide8/getting-the-make-it-native-app/) app on your mobile device -* Complete the preceding tutorials in this [Use Local Notifications](/howto8/mobile/local-notif-parent/) series - -## Scheduling a Notification - -To schedule a notification for a specific time, do the following: - -1. Navigate to your **ACT_CreateAndSendNotification** nanoflow. -2. Replace your **Display notification** JavaScript action with a new **Schedule notification** action: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel/new-schedule-action.png" alt="schedule action replace" width="500" class="no-border" >}} - -3. Double-click your new **Schedule notification activity**. -4. Set the **Date** to **EndOfCurrentMinute**. -5. Change the **body**, **title**, and **subtitle** to the variables that you created. -6. Set **Play sound** to **true**. -7. For now, set **Notification id** to **empty**. -8. Set **Action name** and **Action guid** to **empty**. -9. Click **OK**. -10. Start and load the app on your mobile device. -11. Tap the **Send notification** button, then quickly minimize your app. - -The notification should be displayed at the end of the minute. - -If your app is open, it will not show the notification due to iOS and Android user guidelines. However, notifications for open apps can still trigger onReceive events. This allows you to design custom actions for notifications, such as showing a page with pop-up layout. Follow these steps to model an onReceive event: - -1. Make a new nanoflow named *ON_ReceiveNotification*. -2. Drag a **Log message** activity into your nanoflow. -3. Double-click this activity. -4. In **Template** write *I triggered on receive notification* then click **OK**. -5. Double-click your home page's notifications widget. -6. Click **Actions** > **New**. -7. Create a **New Action** named *TriggerOnReceive*, set **On receive** to **Call a nanoflow**, and select **ON_ReceiveNotification**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel/on-receive-action.png" alt="on receive settings" width="500" class="no-border" >}} - -8. Click **OK** then **OK** again. -9. In **ACT_CreateAndSendNotification**, double-click your schedule notification activity. -10. Click **Action name** > **Edit**. -11. Type *'TriggerOnReceive'* into the argument field and click **OK**. -12. Click **OK**. -13. Start and load the app on your mobile device. -14. Tap the **Send notification** button, and *do not* minimize your app. -15. You will see the log **I triggered on receive notification** in the Studio Pro console. - -But what if you want to cancel a scheduled notification? Read on to learn more. - -## Cancelling Scheduled Notifications - -To cancel a scheduled notification, you can use either the **Cancel Scheduled Notification** or **Cancel All Scheduled Notification** JavaScript actions. To cancel a specific notification, provide an identifier of that particular notification to **Cancel Scheduled Notification**. To cancel all notifications, call the **Cancel All Scheduled Notification** JavaScript action. For further information, see the subsections below. - -### Cancelling all Scheduled Notifications - -To cancel all scheduled notifications, do the following: - -1. Create a nanoflow named *ACT_CancelAllScheduledNotifications*. -2. Drag a JavaScript action named **Cancel all scheduled notifications** into your nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel/cancel-all-action.png" alt="cancel scheduled action" width="500" class="no-border" >}} - -3. Double-click your new cancel notification action. -4. Select **Use return value** > **No**. -5. Click **OK**. -6. Drag this nanoflow onto your home screen and name its button *Cancel all*. - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel/cancel-button.png" alt="cancel button" width="300" class="no-border" >}} - -To test your new cancel button, do the following: - -1. Start and load the app on your mobile device. -2. Tap your **Send notification** button. -3. Tap your **Cancel all** button. -4. Minimize your app. - -You will not see a notification at the end of the minute, proving your cancel action a success! - -### Cancelling a Specific Scheduled Notification - -To cancel a specific scheduled notification, you will need to supply a notification ID for the notification you wish to cancel. - -1. Navigate to **ACT_CreateAndSendNotification**. -2. Double-click your **Schedule notification** activity. -3. Click **Notification id** > **Edit**. -4. Type *'testID'* into the argument field and click **OK**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel/test-id-arg.png" alt="test id argument" class="no-border" >}} - -5. Click **OK** once more to close the dialog box. -6. Create a nanoflow named *ACT_CancelScheduledNotifications*. -7. Drag a JavaScript Action named **Cancel scheduled notification** into your nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel/cancel-scheduled-notif.png" alt="cancel one notification" class="no-border" >}} - -8. Double-click your new cancel notification action. -9. Click **Notification id** > **Edit**. -10. Type *'testID'* into the parameter argument field and click **OK**. -11. Click **OK** again to close the dialog box. -12. Drag this nanoflow onto your home screen and name its button *Cancel a specific notification*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/local-notif-schedule-cancel/cancel-specific-button.png" alt="cancel one button" width="300" class="no-border" >}} - -To test your new cancel button, do the following: - -1. Start and load the app on your mobile device. -2. Tap your **Send notification** button. -3. Tap your **Cancel a specific notification** button. -4. Minimize your app. - -You will not see a notification at the end of the minute, proving your cancel action a success! Congratulations on completing this series and mastering the power of local notifications. - -## Read More - -* [Implement Push Notifications](/howto8/mobile/implementation-guide/) -* [Build JavaScript Actions](/howto8/extensibility/build-javascript-actions/) diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications.md b/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications.md deleted file mode 100644 index d4e731cccc2..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: "Part 1: Local Notifications" -url: /howto8/mobile/native-local-notifications/ -weight: 10 -description: A tutorial for setting up local push notifications which do not use an internet connection. ---- - -## Introduction - -This how-to teaches you how to build local notifications for native mobile applications. Local notifications will only allow you to schedule and send notifications confined to one mobile device. These notifications do not use an internet connection. One use of a local notification might be an alarm app which sends a notification after an amount of time has elapsed. - -This how-to teaches you how to do the following: - -* Build a button connected to a nanoflow which calls a local notification -* Make your notification nanoflow request device permission for local notifications - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Review the [basic differences](https://developer.apple.com/documentation/usernotifications) between local notifications and push notifications -* Install the [Make It Native](/refguide8/getting-the-make-it-native-app/) app on your mobile device - -{{% alert color="info" %}} -To use push notifications with apps created with the Native Builder, make sure you have completed [How To Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) and the how-tos described in [Use Notifications](/howto8/mobile/notifications/) -{{% /alert %}} - -## Creating a Project and Configuring Notifications - -Follow the instructions below to set up your first local notification: - -1. Open Mendix Studio Pro. -2. Select **File** > **New Project**. -3. Select the **Blank Native Mobile App** (also available online [here](https://marketplace.mendix.com/link/component/109511/)): - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/quickstart.png" alt="Blank Native Mobile App" class="no-border" >}} - -4. Click **Use this starting point**. -5. Click **Create App** to close the dialog box: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/app-settings.png" alt="app settings" width="500" class="no-border" >}} - -6. Make sure you have a **Native phone** profile enabled: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/native-profile.png" alt="app settings" width="500" class="no-border" >}} - -7. Drag a **Call nanoflow button** onto your app's home page, then click **New** to make a new nanoflow (note: you may wish to rename this button *Send Notification*): - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/call-button.png" alt="app settings" width="400" class="no-border" >}} - -8. Name the nanoflow *ACT_CreateAndSendNotification* and click **OK**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/name-nano.png" alt="app settings" width="400" class="no-border" >}} - -9. In **ACT_CreateAndSendNotification**, drag three **Create variable** activities into your nanoflow and set them as string variables titled *Title*, *Subtitle*, and *Body*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/create-string-variables.png" alt="app settings" width="500" class="no-border" >}} - -10. Double-click your **Title** activity and then configure it:
- 1. Make sure **Data type** is set to **String**.
- 1. Click **Generate**.
- 1. Type *Title* into the **Constant** field.
- 1. Type *Title* into **Output** > **Variable**.
- 1. Click **OK**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/title-activity.png" alt="app settings" width="400" class="no-border" >}} - -11. Double-click your **Subtitle** activity and configure similarly to your **Title** activity. - -12. Double-click your **Body** activity and configure similarly to your **Title** activity. - -Now you will set up the final logic necessary for your app to display a notification. A user must give permission for an app to send notifications. You will include a **Request notification permission** activity in your nanoflow to account for this, and include a few other activities. - -1. Drag a **Has notification permission** activity into your nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/has-notif.png" alt="app settings" width="500" class="no-border" >}} - -2. Double-click your **Has notification permission** activity, type *NotificationPermission* into **Variable**, then click **OK**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/set-haspermission-variable.png" alt="app settings" width="500" class="no-border" >}} - -3. Drag a decision after your **Has notification permission** activity into your nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/new-decision.png" alt="app settings" width="500" class="no-border" >}} - -4. Double-click that decision and give it the **Caption** *Permission*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/decision-caption.png" alt="app settings" width="500" class="no-border" >}} - -5. Click **Expression wizard**, select **Variable** > **NotificationPermission (Boolean)**, and then click **OK** until you are back at your nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/expression-variable.png" alt="app settings" width="500" class="no-border" >}} - -6. Drag a **Request notification permission** activity into your nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/request-notif.png" alt="app settings" width="500" class="no-border" >}} - -7. Double-click your **Request notification permission** activity and set **Output** > **Variable** to *PermissionGranted*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/permission-granted.png" alt="app settings" width="500" class="no-border" >}} - -8. Drag a decision next to your **Request notification permission** activity. - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/decision-1.png" alt="app settings" width="400" class="no-border" >}} - -9. Connect your activities and decisions, and set those connections' values like so: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/connections-1.png" alt="app settings" width="400" class="no-border" >}} - -10. Double-click the decision, then set the **Caption** as *Permission?*. -11. Click **Expression wizard** -12. Select **Value** > **Variable** > **Permission (Boolean)** from the drop-down menu. When finished, your **Decision** should look like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/decision-1-config-new.png" alt="app settings" width="400" class="no-border" >}} - -13. Navigate back to your nanoflow. - -14. Drag a **Show message** activity into your nanoflow and connect it like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/show-message.png" alt="app settings" width="400" class="no-border" >}} - -15. Double-click your **Show message** activity, then do the following:
- 1. Select **Type** > **Error** from the drop-down menu.
- 1. Into **Template** type *No notification permissions, go to your app permission settings to grant permission*.
- 1. Click **OK**. - -16. Drag an **End event** under your **Show message** and connect them like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/error-end-event.png" alt="app settings" width="400" class="no-border" >}} - -Now you will set up the final piece of your nanoflow's logic. - -1. Delete the end event in the upper-right corner of your nanoflow, drag and drop a **Merge** in its place, and rebuild your connections: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/merge.png" alt="app settings" width="400" class="no-border" >}} - -2. Drag and drop a **Display Notification** activity and connect it to your merge like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/display-notif-merge.png" alt="app settings" width="400" class="no-border" >}} - -3. Set its **Body**, **Title**, and **Subtitle** to the variables that you created in the same nanoflow: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/tsb-variables.png" alt="app settings" width="500" class="no-border" >}} - -4. Set **Play sound** to **true**. - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/sound.png" alt="app settings" width="500" class="no-border" >}} - -5. Set **Action name** and **Action guid** to **empty**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/notif-action-actionguid.png" alt="app settings" width="500" class="no-border" >}} - -6. Select **Use return value** > **no**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/return-no.png" alt="app settings" class="no-border" >}} - -7. Click **OK**, then navigate back to your nanoflow. -8. Add a final **End event** next to your **Display notification** activity and connect it like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/final-end-event.png" alt="app settings" class="no-border" >}} - -9. When you are all finished, your nanoflow will look like this: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/finished-flow.png" alt="app settings" width="500" class="no-border" >}} - -Now you can run your app and see if your notification works. - -1. Start and load your app in your mobile device, then tap **Send Notification**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/app-1.png" alt="app settings" width="400" class="no-border" >}} - -2. When prompted to **Allow notifications**, tap **OK**. -3. After you allow notifications, you will receive a notification: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/local-notif-parent/native-local-notifications/basic-notif.png" alt="app settings" width="400" class="no-border" >}} - - If you did not see a notification, try clicking **Run Locally** to reload your app. Then, tap the **Send Notification** button again. - -Congratulations! You can now see local notifications on your device. Next, in [How to Use Local Notifications Part 2: Badges](/howto8/mobile/local-notif-badges/), you will learn how to configure notification badges. - -## Read More - -* [Implement Push Notifications](/howto8/mobile/implementation-guide/) -* [Build JavaScript Actions](/howto8/extensibility/build-javascript-actions/) diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-add-module-depends.md b/content/en/docs/howto8/mobile/native-mobile/notifications/notif-add-module-depends.md deleted file mode 100644 index 54a051ad14f..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-add-module-depends.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Add Module Dependencies" -url: /howto8/mobile/notif-add-module-depends/ -weight: 52 -description: Tutorial for adding push notification module dependencies. ---- - -## Introduction - -This how-to will help you add module dependencies for the [Push Notifications Connector](/appstore/modules/push-notifications/) module. You only need to install the modules your use case requires. Once your app has the modules it needs, you may move on to [Implement the Push Notifications Module](/howto8/mobile/notif-implement-module/). - -## Implement the Encryption Module - -Skip this section if the [Encryption](https://marketplace.mendix.com/link/component/1011) module is already implemented in your app. Implement this module by doing the following: - -1. Open up the Marketplace from Studio Pro. -1. Search for *Encryption*. -1. Open the [Encryption](https://marketplace.mendix.com/link/component/1011) module. -1. Click **Download**. -1. Follow the instructions on the [Encryption marketplace guide](/appstore/modules/encryption/) to set up this module. - -## Implement the Community Commons Module - -Skip this section if the [Community Commons](https://marketplace.mendix.com/link/component/170) module is already implemented in your app. Implement this module by doing the following: - -1. Open up the Marketplace from Studio Pro. -1. Search for *Community Commons*. -1. Open the [Community Commons](https://marketplace.mendix.com/link/component/170) module. -1. Click **Download**. -1. No further installation is required. If you want to know more about the module visit the [Community Commons marketplace guide](/appstore/modules/community-commons-function-library/). - -## Implement the Nanoflow Commons Module - -Skip this section if the [Nanoflow Commons](https://marketplace.mendix.com/link/component/109515/Mendix/Nanoflow-Commons) module is already implemented in your app. Implement this module by doing the following: - -1. Open up the Marketplace from Studio Pro. -1. Search for *Nanoflow commons*. -1. Open the [Nanoflow commons](https://marketplace.mendix.com/link/component/109515/Mendix/Nanoflow-Commons) module. -1. Click **Download**. -1. No further installation is required. If you want to know more about the module visit the [Nanoflow Commons marketplace guide](/appstore/modules/nanoflow-commons/). - -## Implement the Native Mobile Resources Module - -Skip this section if the [Native Mobile Resources](https://marketplace.mendix.com/link/component/109513/Mendix/Native-Mobile-Resources) module is already implemented in your app. Implement this module by doing the following: - -1. Open up the Marketplace from Studio Pro. -1. Search for *Native mobile resources*. -1. Open the [Native mobile resources](https://marketplace.mendix.com/link/component/109513/Mendix/Native-Mobile-Resources) module. -1. Click **Download**. -1. Add the `NativeMobileResources.User` module role to any user role that needs to interact with notifications. -1. No further installation is required. If you want to know more about the module visit the [Native mobile resources marketplace guide](/appstore/modules/native-mobile-resources/). - -## Implement the Atlas Core Module - -{{% alert color="warning" %}} -The Atlas UI Resources module is deprecated, as is Atlas 2. If you are still using Atlas 2, Mendix recommends that you [migrate from Atlas 2 To Atlas 3](/refguide9/moving-from-atlas-2-to-3/). -{{% /alert %}} - -Implement the Atlas Core module for apps in Mendix Studio Pro 9.0 and above. Skip this section if the [Atlas Core](https://marketplace.mendix.com/link/component/117187/Mendix/Atlas-Core) module is already implemented in your app. Implement this module by doing the following: - -1. Open up the Marketplace from Studio Pro. -1. Search for *Atlas Core*. -1. Open the [Atlas Core](https://marketplace.mendix.com/link/component/117187/Mendix/Atlas-Core) module. -1. Click **Download**. -1. No further installation is required. If you want to know more about the module visit the [Atlas UI marketplace guide](https://marketplace.mendix.com/link/component/104730). - -Now that you have installed the dependencies you need, you can move on to [Implement the Push Notifications Module](/howto8/mobile/notif-implement-module/). diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-build-native.md b/content/en/docs/howto8/mobile/native-mobile/notifications/notif-build-native.md deleted file mode 100644 index 4de2d81d433..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-build-native.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Build a Native App with Push Notifications Enabled" -linktitle: "Native App with Push Notifications" -url: /howto8/mobile/notif-build-native/ -weight: 60 -description: Tutorial for building a native app with push notifications enabled. ---- - -## Introduction - -Now that you have implemented push notifications, it is time to build and deploy the native mobile app. Deploying your iOS or Android app allows the server to send push notifications to mobile devices which have your app installed. - -## Build Your Native App {#build-native-app} - -1. In Studio Pro top bar navigation, click **App** > **Build Native Mobile App**:
- * If you are building your native app for the first time, click [here](/howto8/mobile/native-build-locally/) for instructions.
-1. After choosing the type of build (local development or distribution) go to **App capabilities**.
-1. Under **Firebase configuration** switch **Push notifications** to **On**.
-1. Scroll down and upload the Firebase configurations:
- 1. *google-services.json* for the Android build.
- 1. *GoogleServices-Info.plist* for the iOS build.
-1. Save the configuration. Now you are ready to build. - -When building for local development, keep in mind that Mendix's Make it Native does not support push notifications. In order to use and test push notifications, you will have to build your own native app as described above and distribute it to an emulator (Android only) or test device. - -Now you are able to build, the next step is to run your app in an emulator or test device so you can try to [Send Your First Test Push Notification](/howto8/mobile/notif-send-test/). diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-config-push.md b/content/en/docs/howto8/mobile/native-mobile/notifications/notif-config-push.md deleted file mode 100644 index 26065f2a488..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-config-push.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Configure Push Notifications" -url: /howto8/mobile/notif-config-push/ -weight: 56 -description: Tutorial for configuring push notifications. ---- - -## Introduction - -This how-to teaches you how to configure the runtime for using push notifications in native apps. - -## Configure Your Notifications - -If you have completed [Add Module Dependencies](/howto8/mobile/notif-add-module-depends/) and [Implement the Push Notifications Module](/howto8/mobile/notif-implement-module/) per your use case, do the following to configure your push notifications: - -1. Open your app in Mendix Studio Pro. -1. Log in as the Administrator user you [previously designated](/howto8/mobile/notif-implement-module/#config). -1. Navigate to the **Administration** page. - -The first time you open this page it will present you with a wizard to set up the Firebase configuration. If you have not set up Firebase yet, see [Set Up the Google Firebase Cloud Messaging Server](/howto8/mobile/setting-up-google-firebase-cloud-messaging-server/). The wizard will mention the following files: - -| **File** | **Source** | **Usage** | -| -------- | -------- | ------- | -| **{project_id}-firebase-adminsdk-{identifier}.json** | Google Firebase | Private key for the Firebase service account, used in runtime configuration. | -| **GoogleServices-Info.plist** | Google Firebase | Firebase configuration and private key, bundled as part of your iOS application. | -| **google-services.json** | Google Firebase | Firebase configuration and private key, bundled as part of your Android application. | - -These files contain the information and private keys necessary to enable push notifications in your iOS and Android apps. The private key for the Firebase service account must be uploaded in the configuration wizard (or manual configuration) in your Mendix app. The Android and iOS specific configuration files must be configured when you build your native apps for Android and iOS, see [Build a Native App with Push Notifications Enabled](/howto8/mobile/notif-build-native/). - -Before you build your app, make sure to implement push notifications in the native app first. See [Native Push Notification Implementation](/howto8/mobile/notif-implement-native/). diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-implement-module.md b/content/en/docs/howto8/mobile/native-mobile/notifications/notif-implement-module.md deleted file mode 100644 index b8d0a9255f7..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-implement-module.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Implement the Push Notifications Module" -linktitle: "Push Notifications Module" -url: /howto8/mobile/notif-implement-module/ -weight: 54 -description: Tutorial for implementing the push notification module. ---- - -## Introduction - -Now that you have implemented the prerequisites in your app, you must implement the [Push Notifications Connector](/appstore/modules/push-notifications/) module. Complete the steps below to enable the basic configuration. - -## Download From Marketplace - -If you have not done so, make sure to download the **Push Notification Connector** module from the Marketplace: - -1. Open up the Marketplace from Studio Pro. -1. Search for *Push Notification Connector*. -1. Open the **Push Notification Connector** module. -1. Click **Download**. - -## Configure Your App {#config} - -In order for your app to use to use the Push Connections Module, configure the following things: - -1. Open **Project** > **Security** in the App Explorer. -1. Go to **User roles**.
-1. Adjust the user roles that should have access to the push notifications:
- 1. The `Administrator` module role should be assigned to at least one user executing configuration and administrative tasks.
- 1. The `Anonymous` module role may be assigned to your anonymous project user role.
- 1. The `User` role is for any user role that needs to interact with notifications without being an `Administrator` or `Anonymous` user. - 1. Verify that the `NativeMobileResources.User` module role has been added to any user role that needs to interact with notifications. -1. Save the Security settings. -1. Open up **Project** > **Navigation** in the App Explorer. -1. Add a new open page navigation item to the **Responsive** navigation profile. -1. Select the **Administration** page from the **PushNotifications** module. This page is located in the **_USE ME/Web** folder of the **PushNotifications** module. -1. Add a microflow sub-call to your **AfterStartup** microflow for the microflow **AfterStartup_PushNotifications**:
- * If you do not have an **AfterStartup** microflow configured yet, read the [After Startup](/refguide8/project-settings/#after-startup) section of *App Settings* for more information. - -Now you are able to start your app and move on to the next step: [Set Up the Google Firebase Cloud Messaging Server](/howto8/mobile/setting-up-google-firebase-cloud-messaging-server/). diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-implement-native.md b/content/en/docs/howto8/mobile/native-mobile/notifications/notif-implement-native.md deleted file mode 100644 index 6cc25a5ab2b..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-implement-native.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Implement Push Notifications in Your Native App" -linktitle: "Push Notifications in Native App" -url: /howto8/mobile/notif-implement-native/ -weight: 58 -description: Tutorial for implementing push notifications in a native app. ---- - -## Introduction - -This how-to will help you set up the elements which allow your native app to handle push notifications sent from your server Mendix application. After completing this step you will be able to build a native app with support for push notifications. - -To make setup easy, the Push Notifications Connector module includes snippets that will help you with the initial setup. Do the following: - -1. Expand the **Marketplace modules** > **PushNotifications** > **USE ME** folder. -1. Find and copy the **Native** folder. -1. Paste the **Native** folder contents into your own app's navigation. -1. In your app's navigation, expand the new **Native** folder. -1. Copy the **Native_Snippet** snippet. -1. Paste the snippet into your Native navigation’s home page. - -## App Events Widget - -Completing the previous section brings the **App events** widget into your app. This widget is already configured and part of a snippet, so you should not need to change it. - -If you already had an **App events** widget on your home page, follow these steps: - -1. Open the **App events** widget. -1. In **Page load**, select **Call a nanoflow** from the **On load** drop-down list. -1. For **Nanoflow**, click **Select** and specify the nanoflow **OnPageLoad_RegisterPushNotifications** from the **PushNotifications** module:
- * If you already have a nanoflow selected, make a **Call nanoflow** activity to the nanoflow in that existing nanoflow.
-1. In **App resume**, select **Call a nanoflow** from the **On Resume** drop-down list. -1. For **Nanoflow**, click and specify the nanoflow **OnPageLoad_RegisterPushNotifications** from the **PushNotifications** module:
- * If you already have a nanoflow selected, make a **Call nanoflow** activity to the nanoflow in that existing nanoflow.
- -## Notifications Widget - -The snippet also adds the **Notifications** widget which lets users interact with the notifications the app receives. - -By default this widget is configured with an **Example** action. It uses a non-persistable entity ([NPE](/refguide8/persistability/#non-persistable)) that stores data received from the notifications. It then uses that data in the nanoflow upon receiving or opening the notification. Use this example to make your own actions. - -## Customize Offline Synchronization - -To ensure push notification integration executes properly on your native app you must adjust the objects that are synchronized to your mobile device: - -1. Open your app's **Navigation**. -1. Click the **Native mobile (tablet & phone)** navigation tab. -1. Click the **Synchronization configuration** button. -1. If it is not already added, add the **DeviceRegistration** entity from the **PushNotifications** module. -1. From the **Download** dropdown menu, select **All Objects** for that entity and click **OK**. - -This will ensure that the correct objects are synchronized to your native apps. - -Now that you have everything set up, it is time to deploy your native app. See [Build a Native Mobile App with Push Notifications](/howto8/mobile/notif-build-native/) for instructions on enabling push notifications when building a native app. diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-mult-devices.md b/content/en/docs/howto8/mobile/native-mobile/notifications/notif-mult-devices.md deleted file mode 100644 index 5a1cdb4a9e9..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-mult-devices.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "Send Notifications to Multiple Devices" -url: /howto8/mobile/notif-mult-devices/ -weight: 71 -description: Learn to send notifications to multiple devices with the Native Mobile Builder. ---- - -## Introduction - -This tutorial teaches you how to send test push notifications to multiple devices. - -{{% alert color="info" %}} -Push notifications only work with apps created through the Mendix Native Mobile Builder. You cannot send notifications to an app inside the Make it Native app. -{{% /alert %}} - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisite: - -* Send one test push notification as described in [Use Notifications](/howto8/mobile/notifications/) - -If you want to use push notifications with custom apps created with Mendix Native Mobile Builder, make sure you have completed the following prerequisite: - -* Complete [How to Build a Mendix Native App in the Cloud](/howto8/mobile/deploying-native-app/) through the end of the *Making Your First Build* section - -## Sending Notifications to Multiple Devices - -What if you want to send messages to all your users' devices with a single button push, but you do not want to handle the GUID retrieval? The section below will address this scenario. Specifically, you will send a push notification containing a data object to your users' devices via the Push Notifications API. - -### Creating a Microflow to Send a Data Object Push Notification - -Create a microflow *ACT_SendProductToAllDevices* with the following elements: - -{{< figure src="/attachments/howto8/mobile/native-mobile/notifications/notif-mult-devices/SendProductToAll.png" alt="SendProductToAll" width="300" class="no-border" >}} - -1. Add a *Product* data parameter to your microflow. -2. Retrieve the *PushNotifications.Device* entity list from a database: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/notif-mult-devices/retrieveDevices.png" alt="retrieveDevices" width="300" class="no-border" >}} - -3. Drag the **PrepareMessageData** microflow from *PushNotifications/_USE ME/API* onto **ACT_SendProductToAllDevices** and configure the following:
- 1. Title: *myTitle*.
- 1. Body: *myBody*.
- 1. TimeToLive: *0*.
- 1. Badge: *0*.
- 1. ActionName: *sendProduct*.
- 1. ContextObjectGuid: *empty*: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/notif-mult-devices/prepareMessageData.png" alt="prepareMessageData" width="300" class="no-border" >}} - - **ContextObjectGuid** is set to empty since you will pass the object itself to the **SendMessageToDevices** Java action where it will be retrieved automatically. - -4. Drag the **SendMessageToDevices** Java action from *PushNotifications/_USE ME/API* onto **ACT_SendProductToAllDevices** and configure the following:
- 1. **Message data param**: **$MessageToBeSent**.
- 1. **Device param**: **$Devices**.
- 1. **Context object**: **$Product**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/notif-mult-devices/sendMessagesJava.png" alt="sendMessagesJava" width="300" class="no-border" >}} - -5. Go to **Product_NewEdit** and drag **ACT_SendProductToAllDevices** into that page's data view: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/notif-mult-devices/sendProductToAllButton.png" alt="sendProductToAllButton" width="300" class="no-border" >}} - -### Testing the Implementation - -Test your new push notification capabilities by doing the following: - -1. Run your native app in your device's background. -2. In your web browser, go to **Product_NewEdit** and click your **ACT_SendProductToAllDevices** microflow button. - -This will send a notification to all available devices. When you tap the notification, you will be redirected to the particular product page you modeled. - -## More Java Action Explanations - -For more detail on Java actions available in the Push notifications module, see the sections below. - -### PrepareMessageData Microflow - -This allows users to create their own user interfaces in order to alter and create a push notification message. - -### SendMessageToDevice and SendMessageToDevices Java Actions - -These Java actions have the following parameters: - -* **MessageDataParam** (PushNotifications.MessageData): this parameter can be generated by the **PrepareMessageData** microflow -* **DeviceParam** (List of PushNotifications.Device or PushNotification.Device): this parameter can be used to send the same message to a list of devices -* **ContextObject**: this parameter will allow any Mendix object to be passed to the notification - -### SendMessageToUsers and SendMessageToUser Java Actions - -Every user is allowed to have more than one device. When sending push notifications to every device of a particular user, use the **SendMessageToUser** Java action. - -To send a push notification to all users, use the **SendMessageToUsers** Java action. - -## Troubleshoot Notification Issues - -If you run into issues, see the [Troubleshoot Notification Issues](/howto8/mobile/notif-send-test/#troubleshoot) section of *Send Your First Test Push Notification*. - -## Read More - -* [Use Notifications](/howto8/mobile/notifications/) diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-send-test.md b/content/en/docs/howto8/mobile/native-mobile/notifications/notif-send-test.md deleted file mode 100644 index 68bd4bb20a0..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/notif-send-test.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Send Your First Test Push Notification" -url: /howto8/mobile/notif-send-test/ -weight: 64 -description: Tutorial for testing your push notifications. ---- - -## Introduction - -After [configuring the Push Notifications module](/howto8/mobile/notif-config-push/) and [building your native app](/howto8/mobile/notif-build-native/) it is now time to send your first test push notification. - -## Send the Test Notification - -To send your first test notification, do the following: - -1. Login to your web application. -1. Go to the push notification administration page you added earlier to your navigation. -1. Go to the **Devices** tab. -1. Select the your test device. -1. Click **New Message** (or double-click your test device). -1. Fill in any **Title**/**Body** that you want for your notification. -1. Set the **Action name** to *Example*. -1. Leave the remaining fields to the defaults. -1. Click **Send**. - -You should now receive the notification on your device. If the application is already opened, the action will log a message (on log node **ExampleNotification**) and show a dialog box in the app. - -If the app is not open (or running in the background) it will deliver and show the notification in the usual location for Android or iOS devices. Click on the notification to trigger the in-app action. - -Congratulations, you have just sent your first push notification! - -If you did not receive the message, check the application's logs to see if the message was sent successfully. See the troubleshooting section below for solutions to the most common issues. - -## Troubleshoot Notification Issues {#troubleshoot} - -| Issue | Cause | Solution | -|-----|----|-----| -| Sending a message causes a **SenderId mismatch** error or **403: Forbidden**. | Your native mobile app registered the device within your Mendix applications, but not with Firebase. | Follow the [Build Your Native App](/howto8/mobile/notif-build-native/#build-native-app) section in *Build a Native App with Push Notifications Enabled* and make sure you add the *google-services.json* file. | -| Sending a message causes a **Request contains an invalid argument** error or **400: Bad Request**. | Your **Project ID** does not match the **project_id** in your private key *json* file. | Upload the correct file or [generate a new private key](/howto8/mobile/setting-up-google-firebase-cloud-messaging-server/#setting-up-a-service-account) in Firebase and upload it. | -| Mendix Runtime exception on JavaAction 'DecryptString': **Key should not be empty**. | This module depends on the **Encryption** module, which requires a key. | Set the constant **EncryptionKey** in the **Encryption** module with a key of exactly 32 characters. | -| Error sending message: **Error reading credentials from stream, 'type' field not specified. at PushNotifications.SendFCMMessages (JavaAction : 'GetFCMAccessToken')**. | The wrong private key file was uploaded. | Upload the correct file or [generate a new private key](/howto8/mobile/setting-up-google-firebase-cloud-messaging-server/#setting-up-a-service-account) in Firebase and upload it. | diff --git a/content/en/docs/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server.md b/content/en/docs/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server.md deleted file mode 100644 index 30f0168cf7a..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: "Set Up the Google Firebase Cloud Messaging Server" -linktitle: "Set Up Firebase Cloud Messaging" -url: /howto8/mobile/setting-up-google-firebase-cloud-messaging-server/ -weight: 55 ---- - -## Introduction - -You can use Google's Firebase Cloud Messaging (FCM) service to send push notifications to both Android and iOS devices. To send push notifications using FCM from the Push Notifications Connector module, you must set up a Firebase account with FCM enabled. This how-to teaches you how to register for FCM and configure the service in your app. - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Have a Firebase account (https://firebase.google.com) - -## Setting up a Firebase Project - -There are two possible scenarios: you can create a new FCM project, or you can update your existing GCM project to FCM. Both scenarios are described below. - -### Migrating a GCM project to FCM - -To prevent the degraded reliability of push notifications delivery, you should migrate existing GCM projects to FCM and upgrade credentials if needed. - -#### Sign into the Developer's Console - -Open the [Firebase developer's console](https://console.firebase.google.com/) and sign in with your Google ID. - -#### Importing the Project - -To import your project, do the following: - -1. In the Firebase console, select **Import Google Project**. -1. Select your GCM project from the list of existing projects, select a region, and click **Add Firebase**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server/Add_Firebase_to_a_Google_Project.png" width="350" class="no-border" >}} - -With that done, continue with [Configuring APNs Credentials](#configuring) below. - -### Creating a New FCM Project - -#### Signing into the Developers Console - -Open up the [Firebase developers console](https://console.firebase.google.com/) and sign in with your Google ID. - -#### Creating the Project - -To create a project, do the following: - -1. Click **Create new project**. -1. Fill in your application's project name and region. -1. Click **Create**" - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server/Create_Firebase_Project.png" width="350" class="no-border" >}} - -## Adding an Android or iOS App {#native-apps} - -Before you add an app to FCM, you must retrieve your app's bundle ID. Its location depends on your type of your mobile app. - -For a native mobile app, your bundle ID will be what you specify for the **App identifier** in the NBUI. You can find this ID later in your generated GitHub repo: - -* For Android, open *android/app/build.gradle* and consult **applicationId** to find your ID -* For iOS, open *ios/Config/config.xcconfig* and consult **BUNDLE_IDENTIFIER** to find your ID - -Click **Deploy**, then **Mobile App**. Your ID is listed as **App Identifier**: - -{{< figure src="/attachments/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server/hybrid_app_identifier.png" width="350" class="no-border" >}} - -Do the following to add your app to FCM: - -1. Click the **Project Overview** cogwheel and select **Project settings**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server/project_settings.png" width="350" class="no-border" >}} - -1. Go to the **General** tab and click **Add app**: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server/add_app.png" width="350" class="no-border" >}} - -1. Select Android and, fill in the bundle_id, and skip the rest of the steps: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server/android_setup.png" width="350" class="no-border" >}} - -Bundle ID must be matching with your package ID. Make sure to repeat this step for iOS as well. - -## Configuring APNs Credentials (Optional) {#configuring} - -If you wish to send push notifications to iOS devices through FCM (for native mobile apps), you will need to configure your APNs credentials: - -1. Click in the upper-left corner of the screen and select **Project settings**. -1. Navigate to the **Cloud messaging** tab: - - {{< figure src="/attachments/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server/push_notifications_cloud_messaging.png" width="350" class="no-border" >}} - -1. On this tab, upload either your APNs key or your APNs certificate(s) as configured in your [Apple Developer account](https://developer.apple.com). - -## Setting Up a Service Account {#setting-up-a-service-account} - -In the upper-left corner of the screen, click the cogwheel and select **Project settings**. Then navigate to the **Service accounts** tab. - -{{< figure src="/attachments/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server/push_notifications_service_accounts.png" width="350" class="no-border" >}} - -On this page, press **Generate new private key**. Store the resulting file in a secure location. You will use this file when configuring FCM in the back-end of your Mendix application. - -The file you just created gives API access to all available Firebase services for your app. If you want a more restrictive service account, click **Manage all service accounts** in the top-right of the screen, then create a service account that is restricted to using the Cloud Messaging functionality. - -## Downloading the Google Services Config Files {#downloading-the-google-services-config-files} - -In addition to the back-end configuration set up in the previous steps, you will need additional files that will be bundled as part of your mobile application. To obtain these, again click the cogwheel in the upper-left of the screen and select **Project settings**. Then navigate to the **General** tab: - -{{< figure src="/attachments/howto8/mobile/native-mobile/notifications/setting-up-google-firebase-cloud-messaging-server/push_notifications_platforms.png" width="350" class="no-border" >}} - -The list at the bottom shows the Android and iOS applications that you have configured for your Firebase project. Select the Android application and click *google-services.json*. Then click the iOS application and click *GoogleService-Info.plist*. Store both files in a secure location. You will need these when building your mobile application. - -{{% alert color="warning" %}} -Only create an iOS application in your Firebase project when you plan on using FCM for sending push notifications to iOS devices. If you plan on keeping using APNS to send push notifications to iOS devices, you do not have to create an iOS application in your Firebase project, and you do not have to download a *GoogleService-Info.plist* config file. -{{% /alert %}} - -## Read More - -* [Set Up Push Notifications](/howto8/mobile/notifications/) -* [Set Up Hybrid Push Notifications](/howto8/mobile/setting-up-hybrid-push-notifications/) diff --git a/content/en/docs/howto8/mobile/native-mobile/ui-best-practices.md b/content/en/docs/howto8/mobile/native-mobile/ui-best-practices.md deleted file mode 100644 index 578f8da5126..00000000000 --- a/content/en/docs/howto8/mobile/native-mobile/ui-best-practices.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: "Implement Best Practices for Native Mobile App UI" -linktitle: "Native Mobile App UI Best Practices" -url: /howto8/mobile/ui-best-practices/ -weight: 35 -description: "This document teaches you how to build a native mobile app's UI." ---- - -## Introduction - -This document discusses how Mendix Platform users can build a native mobile app's user interface (UI). Other topics like testing and distributing are not discussed here. The guidelines in this document are a general advice and can be adjusted to better suit use cases and specific situations. - -## Roles - -When building a native application, different roles are needed for app development. This does not necessarily mean there must be a different person for every role, as developers can serve multiple roles. Also, depending on your app there should be a difference in the level of expertise among certain roles. - -### Different Types of Roles - -For most apps, development teams should include the following roles in their overall configuration: - -* **Mendix development** – Building the domain model, pages, logic, integrations, and overall flow of the app. This is the most common and available role. -* **Front-end development** – Implementing the styling or the theme of the app as created in the designs. -* **UI design** – Designing the user interface, for example how the screens and components look, and determining the theme colors, typography, spacing, and borders. -* **UX design** – Designing the user experience (such as the flow of the app), determining which use cases to support, and deciding how certain functions should work. -* **Widget development (optional)** – Building new widgets to provide new interaction patterns or UI components that are not offered out of the box by Mendix or available though the Mendix Marketplace. - -As mentioned above, not all apps require five different persons each handling one of these roles. Different team configurations are common. - -### Roles, Staff, and Types of Apps - -Which roles and staff make up your development team depends on the type of apps you produce. In cases when less UI or UX expertise is required, most often with B2E apps, a Mendix developer can fill all roles. If the default theme is sufficient, or there are restrictions on time and budget this can be an effective configuration. By using Mendix's default Atlas theme and by discussing with users or the product owner, one Mendix developer can build the UI and UX on their own. - -In apps where custom UX or UI is more important (for example B2C and B2B apps) the following combinations are often employed: - -* **UI design + UX design** – This configuration is often used if an in-house UX team is used or a design agency is hired. -* **UI design + UX design + front-end development** – UX or UI experts that also have the skills to implement their designs and UX are key for this configuration. For example, several people in Mendix Expert Services are of these type. -* **Mendix development + front-end development** – A Mendix developer who knows how to implement styling, but does have to the skills to create the design. - -## Process - -At Mendix we strongly believe in enabling other developers as they grow to scale and speed up development. In general there are more Mendix developers than UI or UX designers. Therefore, when building a mobile app it is important that a UI or UX designer can enable Mendix developers as much as possible to speed up development. - -One could compare building with Mendix to building with toy blocks. Give a user a set of generic blocks that can be combined, and they can build anything. However if they constantly need to buy new types of specific blocks, their building would be slow and hampered. - -To learn about building a Mendix native mobile app's UI, consult the sections below. Be sure to see the [Configure Design Properties](#configure-design-props) section below for key information on implementing design easily. - -### Create App Designs Using a UI Kit - -By designing a set of reusable components including variations, a UI designer can create a UI kit that can be used to design pages. This includes settings like the brand colors, typography, spacing settings, and the UI components (for example buttons and inputs) including variations. Designers frequently use the [Sketch](https://www.sketch.com/) tool to complete these tasks with satisfying results. - -This UI kit will be the input for creating the Mendix theme and related components. Therefore it helps to have Mendix and front-end knowledge to align what is available already in Mendix and what is needed for the designs.. - -### Translate the UI Kit to Mendix Theme and Components - -The front-end developer can translate the UI kit to a Mendix theme and standard layouts, as well as building blocks and page templates. - -#### Set Up Main Theme Settings - -The goal of configuring the theme setting is to quickly implement the look and feel of your app or company branding. Mendix comes ready with a highly-configurable theme which gives you a head start in creating your app's overall look and feel. Configuring the theme settings inside your app's *theme/styles/native/app/custom-variables.js* file. - -#### Configure Design Properties {#configure-design-props} - -The goal of design properties is to enable developers to implement design without having to know custom class names or write custom styling. This is a very important step in enabling developers. - -By default Mendix has a default set of design properties which enable developers to build pages with several options. We advise you to change, add, or remove design properties according to your variations in the UI kit. - -For example, Mendix offers a set of button variants (default, secondary, warning, success, and danger). However, during your design process you can choose to just have a default and a secondary variant. Choices like this are a part of UI design. It is up to people in UI and front-end design roles to determine how much freedom a Mendix developer should have. - -The design properties are located in *theme/settings-native.json*, and more information be found in the [Design Properties API Documentation](/apidocs-mxsdk/apidocs/design-properties/). - -#### Create the App Layouts - -The default Atlas theme comes pre-bundled with a set of layouts. If these do not fit your app’s design, you can create or customize the layouts and name them accordingly. Do not change the supplied layouts. Either create a separate module with the custom layouts, page templates, and building blocks or create your own [UI resources module](/howto8/front-end/create-company-atlas-ui-resources/#moving-from-local-to-atlas-ui-resources). - -#### Create Building Blocks for Common UI Structures - -Apps often have multiple instances of patterns on pages or more complex UI patterns. For these cases it is useful to create building blocks so that other Mendix developers can easily apply common patterns. In building blocks, you can use custom class names in order to be more specific. For that properties that developers should be able to change in building blocks, use design properties as much as possible. - -#### Create Page Templates for Common Page Structures - -Similar to buildings blocks, developers can create standard page templates so that other developers can easily implement a common type of page. - -### Implement Your UI Using Theme and Content - -A Mendix developer can build an app's interface based on that app's theme, design properties, layouts, building block, and page templates. When missing capabilities make it difficult to build the pages as designed, it is good to iterate on the UI kit, theme, or available content. In certain cases it can be good to apply specific styling as explained in the next section. - -### Implement App or Use-Case Specific Styling - -There are several cases in which an app's standard theme and content is not rich enough to build every page. In these cases front-end development can be used to implement specific styling. - -### Iterate and Discuss - -Mendix is a platform for [Agile development](https://www.mendix.com/blog/design-thinking-vs-agile-combine-problem-finding-problem-solving-better-outcomes/) environments, which also applies when creating a UI kit and the related Mendix themes and components. Keep iterating, discussing, and improving. - -## Best Practices - -### Use Design Properties as Often as Possible - -Try to avoid custom styling. Instead, use the available design properties as much as possible. This makes it easier for other developers to understand what is styled. We do not recommend creating a single design property that combines different styles, for example a property with padding and font size styles combined. - -### Plan to Reuse as Much as Possible - -A common pitfall is to start directly implementing directly from designs without thinking about reuse. While implementing directly can make sense for small apps, this practice risks creating several custom classes, spawning more variations of components which can slow down development, and creating significant technical debt. - -Try to avoid very specific class names. Very specific class names are often only used once, although the styles are probably used at least a few times. Combine and rewrite classes where possible. This will keep the theme clean and simple, and makes it easier to create design properties and enable Mendix developers. - -### Never Change Something in the Core Folder - -By changing styling in the **core** folder you risk incurring errors the next time you update Atlas. Updating Atlas might also be more difficult. - -A large part of your app's overall styling can be changed in `theme/styles/native/app/custom-variables.js`. However, if more changes are needed you could extend a widget’s default styling or define the default styling yourself. - -### Favor Design Properties Over Including Properties - -Avoid including properties which can be set with design properties. By being careful with your properties, your apps will be easier for other developers to understand and change. For example, if you make a certain element always have a margin there is a chance that this will not fit in certain designs. However, a developer could easily set a margin using design properties. One particularly useful approach is providing a default spacing this will cover 90% of cases, and give the developer the option to overwrite it using design properties. - -### Study the Core Styling - -The default Mendix theme is a complete theme which serves as a good source of examples for how to approach styling. - -### Keep Styling Maintainable - -It is a common pitfall to keep adding classes to a single file. However, this will make the file more difficult to maintain. Here some best practices for keeping styling maintainable: - -* Apply clear, descriptive, and consistent names in styling—add comments when needed -* Use variables as much as possible for consistency and easy updating -* Combine and reuse parts of classes by using the spread operator `…` -* Split the styling in logical parts, group related styles together, and split them into separate files if those groups become too large—if you have multiple custom styling files, use *theme/styles/native/app/custom.js* to import all those files (this will make updating easier, as customizations are only in the *app* folder) -* *Custom.js* should not contain classes—only `export * from …*` statements to include classes from other files -* Put the styling for building blocks and page templates in *theme/styles/native/ui_resources/{YOUR_APP_OR_MODULE_NAME}* and include it in *theme/styles/native/main.js* -* Create separate folders in the app folder for the generic company styling and app specific styling (this enables re-use and consistency between apps) -* Always think about reuse; that common class you just created may be useful in other apps as well. Consider adding them to your company theme - -## Read More - -* [Native Mobile Styling Reference Guide](/refguide8/native-styling-refguide/) -* [How to Style Your Mendix Native Mobile App](/howto8/mobile/how-to-use-native-styling/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/_MAPPING.txt b/content/en/docs/howto8/monitoring-troubleshooting/_MAPPING.txt deleted file mode 100644 index 1eaedad50e8..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/_MAPPING.txt +++ /dev/null @@ -1 +0,0 @@ -There are document files in this folder that are mapped to the product. Refer to Mapping to Products for the names of these files and how to proceed. \ No newline at end of file diff --git a/content/en/docs/howto8/monitoring-troubleshooting/_index.md b/content/en/docs/howto8/monitoring-troubleshooting/_index.md deleted file mode 100644 index c3f54738c88..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/_index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Monitoring and Troubleshooting" -url: /howto8/monitoring-troubleshooting/ -weight: 110 -no_list: false -description_list: true -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -Stay updated on the health of your app and reference these documents troubleshooting when needed. - -## Documents in This Category diff --git a/content/en/docs/howto8/monitoring-troubleshooting/clear-warning-messages.md b/content/en/docs/howto8/monitoring-troubleshooting/clear-warning-messages.md deleted file mode 100644 index f742750352b..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/clear-warning-messages.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: "Clear Warning Messages" -url: /howto8/monitoring-troubleshooting/clear-warning-messages/ -weight: 1 ---- - -## Introduction - -This how-to explains how to eliminate design time warnings. While these warnings will not cause the application to break, it is important to fix them to keep a clean app. - -This how-to teaches you how to do the following: - -* View warning messages -* Clear warning messages - -## Viewing Warning Messages - -Warning messages can be seen in the **Error List** tab of Studio Pro (by default shown at the bottom of Studio Pro). Note that the **Warnings** box must be selected for them to display. - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/clear-warning-messages/18579992.png" class="no-border" >}} - -If this tab is not visible, it can be displayed via the **View** menu by selecting the **Error List** option: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/clear-warning-messages/18579991.png" class="no-border" >}} - -To get more information, double-click or right-click the warning. - -## Common Warnings - -{{% alert color="warning" %}} - -[Deprecated] Using the main placeholder contents for pop-ups is deprecated. This potion will be removed in a future version. Please use a separate pop-up layout instead. - -{{% /alert %}} - -* This will not affect the app in this version of Studio Pro, but it may cause problems when upgrading -* In this example, the pop-up layout must be adjusted in order to no longer use the main placeholder - -{{% alert color="warning" %}} - -A flow origination from an error handler should not return to the main flow. - -{{% /alert %}} - -* Once the microflow has split due to an error, the flow that executes due to the error should not merge with the flow that executes when no error occurs - -{{% alert color="warning" %}} - -Access rules for entity ‘System.FileDocument’ exist that define access rights for users with module role ‘System.User’. Note that these access rights apply to all users of your application, including anonymous users (if enabled). It is recommended it create a specialized entity for each use case and configure access rules for those entities instead. - -{{% /alert %}} - -* The security for the System.FileDocument entity has a default setting that which can cause security loopholes -* This warning suggests creating specialized entities to eliminate such scenarios - -{{% alert color="warning" %}} - -Action activity that has a side effect on the client is not recommended here because the microflow is used as a data source for data view ‘dataView1’. - -{{% /alert %}} - -* Data source microflows should not have an effect on the client -* This microflow likely has a show message or show page activity that should be removed - -{{% alert color="warning" %}} - -Empty caption. [English, United States] / Empty title. [English, United States] - -{{% /alert %}} - -* The specified caption or title is empty -* This should be populated so that the page will be understood - -{{% alert color="warning" %}} - -Empty page title of target page. Either set the page title of the target page or override it here. [English, United States] - -{{% /alert %}} - -* This should be populated to ensure the page will be understood (similar to the "empty caption" above) - -{{% alert color="warning" %}} - -Empty progress message. [English, United States] - -{{% /alert %}} - -* The selected progress message is empty, but it should be populated - -{{% alert color="warning" %}} - -Events have no effect inside a non-editable context. - -{{% /alert %}} - -* This context is read-only, but there are events set on the field (either on-change, on-leave, or on-enter) - -{{% alert color="warning" %}} - -Microflow ‘microflowname’ is accessible through the server API because it specifies allowed roles. This is unnecessary because the microflow is not used from navigation or a page. - -{{% /alert %}} - -* There is no need for a microflow that is not accessed through navigation or a page to have security roles allowed -* This can lead to a security problem, and the assigned roles should be removed - -{{% alert color="warning" %}} - -Microflow does not do anything. - -{{% /alert %}} - -* This microflow performs no functionality; it should be removed or functionality should be added - -{{% alert color="warning" %}} - -Module role is not part of any user role. - -{{% /alert %}} - -* The module role cannot be used by any users -* This module role should either be removed or assigned to a user role so that the proper security is enforced - -{{% alert color="warning" %}} - -Property ‘XPath constraint’ on the data grid of the select page has no effect when the page is used for selecting. Instead, the selection constraints properties of the reference selector can be used to constrain the selectable objects. - -{{% /alert %}} - -* When using a form for a reference selector, the constraint should be set on the reference selector (*not* on the form) - -{{% alert color="warning" %}} - -Empty required message while required is true. [English, United States] - -{{% /alert %}} - -* On a page, a field can be set to required -* When the field is set to required, the **Required Message** should be set -* In this case, either the **Required Message** must be set or the field must not be required - -{{% alert color="warning" %}} - -Required message is set even though required is set to false. [English, United States] - -{{% /alert %}} - -* This is similar to the previous warning -* If the field is not required, the **Required Message** should be empty -* If the **Required Message** was set with the intention of making the field required, the field should be made required - -{{% alert color="warning" %}} - -Target namespace is ‘[http://www.example.com/](http://www.example.com/)’. Please provide a target namespace specific to your published web service. - -{{% /alert %}} - -* Edit the published web service to include a proper namespace - -{{% alert color="warning" %}} - -Variable ‘Variable’ is never used. - -{{% /alert %}} - -* There are multiple potential causes here -* The solution involves removing the variable from the microflow, which could mean deleting the retrieve activity or electing to not use the return value of a microflow call - -## Read More - -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Java Actions Remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Configure Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [Debug Microflows Remotely](/howto8/monitoring-troubleshooting/debug-microflows-remotely/) - -Several warnings relate to improper security. For more information on this, see [Project Security](/refguide8/project-security/) in the *Studio Pro Guide*. diff --git a/content/en/docs/howto8/monitoring-troubleshooting/debug-a-hybrid-mobile-application.md b/content/en/docs/howto8/monitoring-troubleshooting/debug-a-hybrid-mobile-application.md deleted file mode 100644 index f9d3a987e46..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/debug-a-hybrid-mobile-application.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Debug a Hybrid Mobile Application" -url: /howto8/monitoring-troubleshooting/debug-a-hybrid-mobile-application/ -weight: 5 ---- - -## Introduction - -This how-to explains the steps involved in debugging a Mendix application that is running in the Mendix Developer App on your mobile phone. - -This how-to teaches you how to do the following: - -* Debug a mobile application - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install [weinre](https://people.apache.org/~pmuellr/weinre/docs/latest/) -* Install the Mendix Developer App on your mobile device - -## Start weinre - -From your console, start weinre with the following parameters: `weinre --boundHost 1.2.3.4 --httpPort 9090`: - -* `1.2.3.4` is your local IP, which will most probably match the address that you see in the history of your Mendix Developer App -* You can change `9090` to a different port as long as it doesn't clash with your application's port, which is usually 8080 - -## Connect Your Mendix Developer App - -Click **Settings** ({{% icon name="cog" %}}) on the upper-right corner of the screen to configure your debugger: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-a-hybrid-mobile-application/18580021.png" class="no-border" >}} - -On the configure screen, fill in the same settings that you used to start weinre, which should be `http://1.2.3.4:9090` (wherein `1.2.3.4` is your local IP). - -You can now navigate to the same address on your local browser to start the debugging session. - -## Read More - -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clear Warning Messages in Mendix](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Java Actions Remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [Debug Microflows Remotely](/howto8/monitoring-troubleshooting/debug-microflows-remotely/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/debug-java-actions/_index.md b/content/en/docs/howto8/monitoring-troubleshooting/debug-java-actions/_index.md deleted file mode 100644 index 7157a0f341c..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/debug-java-actions/_index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Debug Java Actions" -url: /howto8/monitoring-troubleshooting/debug-java-actions/ -weight: 4 ---- - -## Introduction - -Mendix Studio Pro has a built-in debugger to solve errors on the microflow level. A microflow can be extended with custom Java actions, but because these actions are text-based, they can only be checked on compile errors. If you run into an error in any of the Java actions, you can easily debug them by utilizing the debugger of Eclipse. - -This how-to teaches you how to do the following: - -* Set breakpoints -* Debug in Eclipse - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Install [Eclipse](https://eclipse.org/) -* Add a Java action and open the project in Eclipse -* Read [How to Extend Your Application with Custom Java](/howto8/logic-business-rules/extending-your-application-with-custom-java/) -* Deploy the application for Eclipse by selecting **Deploy for Eclipse** from the project menu in Studio Pro (you should redo this every time you make changes in Studio Pro): - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-java-actions/18581045.png" class="no-border" >}} - -## Setting Breakpoints - -1. Open Eclipse and locate the project in the **Package Explorer**. -2. Double-click **ReverseCustomerName.java**: - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-java-actions/18581041.png" class="no-border" >}} -3. Place the cursor on the line that needs debugging, hold down Ctrl + Shift, and press B to enable a breakpoint. A blue dot in front of the line will appear: - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-java-actions/18580059.png" class="no-border" >}} - - {{% alert color="info" %}}You can also use Ctrl + Shift + B to disable a breakpoint.{{% /alert %}} - -## Debugging in Eclipse - -1. Select the project root node in the package explorer and click the debug icon in the Eclipse toolbar: - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-java-actions/18580062.png" class="no-border" >}} - - The application will now be started with Eclipse attached as debugger. - -2. As soon as the deployment process is ready, open the application in your browser and trigger the Java action: - * As an end-user of the application, you will see a progress bar on your application - * As a developer, you will see the Eclipse icon flashing on the Windows task bar -3. Open Eclipse. You should now see the "debug" perspective of Eclipse. -4. Click **Step into** (or press F5) or **Step over** (or press F6) to move on the next step in the microflow: - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-java-actions/18580056.png" class="no-border" >}} - - {{% alert color="warning" %}}With debugger options, the difference between "Step into" and "Step over" is only noticeable if you run into a function call. "Step into" means that the debugger steps into the function, and "Step over" just moves the debugger to the next line in the same Java action. With "Step Return" (pressing F7), you can instruct the debugger to leave the function; this is basically the opposite of "Step Into." Clicking "Resume" (pressing F8) instructs the debugger to continue until it reaches another breakpoint.{{% /alert %}} - -5. Place your cursor on any of the variables in the Java action to see its value in a pop-up window: - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-java-actions/18580057.png" class="no-border" >}} - -## Read More - -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clear Warning Messages in Mendix](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Java Actions Remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debug Microflows Remotely](/howto8/monitoring-troubleshooting/debug-microflows-remotely/) -* [Java Actions](/refguide8/java-actions/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/debug-java-actions/debug-java-actions-remotely.md b/content/en/docs/howto8/monitoring-troubleshooting/debug-java-actions/debug-java-actions-remotely.md deleted file mode 100644 index f3d0dbd7e51..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/debug-java-actions/debug-java-actions-remotely.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Debug Java Actions Remotely" -url: /howto8/monitoring-troubleshooting/debug-java-actions-remotely/ ---- - -## Introduction - -To debug the Java actions used in a Mendix microflow, you need to make some configuration changes to the way you start the Mendix Runtime. This how-to will explain how to manage this. - -This how-to teaches you how to do the following: - -* Edit the server configuration -* Configure remote debugging - -## Editing the Server Configuration with Extra JVM Parameters - -In this section, you will learn how to configure the security at the [Prototype / demo](/howto8/security/create-a-secure-app/#prototype) level. Be aware that this level of security is only applicable for development/demo purposes. This level is available for the quick development of demo applications. It simulates security without the more complex configuration of data access. When deploying to the [Mendix Cloud](/developerportal/deploy/mendix-cloud-deploy/), setting [Production](/howto8/security/create-a-secure-app/#production) security is mandatory. - -To edit the server configuration with extra JVM parameters, follow these steps: - -1. Open the [Project Settings](/refguide8/project-settings/). -2. Edit the configuration on the **Configurations** tab. -3. Go to the **Server** tab of the configuration, add the following line to the **Extra JVM parameters** field: `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005` - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-java-actions/debug-java-actions-remotely/18580063.png" class="no-border" >}} - -4. Run your application. - -## Configuring Remote Debugging - -In your Java IDE, you need to configure remote debugging. - -To configure IntelliJ, follow these steps: - -1. Start the **Debugger**. -2. Place some breakpoints in your Java code. -3. Start debugging. - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-java-actions/debug-java-actions-remotely/intellij_rundebug_configurations.png" class="no-border" >}} - -To configure Eclipse, follow these steps: - -1. Open the project in Eclipse. -2. Open the menu with the bug icon or the **Run** menu. -3. Select **Debug Configurations**. -4. In the left menu bar, select **Remote Java Application**. -5. Right-click **New**. -6. Be sure your current project is under **Project**, and change the port to 5005 (view the JVM parameters). -7. Click **Debug**. - -## Read More - -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clear Warning Messages in Mendix](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/debug-microflows/_index.md b/content/en/docs/howto8/monitoring-troubleshooting/debug-microflows/_index.md deleted file mode 100644 index 22930e8c6ef..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/debug-microflows/_index.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: "Debug Microflows" -url: /howto8/monitoring-troubleshooting/debug-microflows/ -weight: 2 ---- - -## Introduction - -Mendix Studio Pro has a built-in consistency checker that validates if the application you are building contains any obvious errors. This dramatically reduces the amount of technical errors during run-time, but Studio Pro isn't able to check if your app contains functional errors. This is mainly a manual practice, but Mendix does support enough tools to make this easier. If you run into a functional error in any of the microflows, you can easily debug them with the debugger. - -This how-to teaches you how to do the following: - -* Use breakpoints -* Debug microflows - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Read [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/) -* Read [How to Create Your First Two Overview and Detail Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/) - -## Debugging Overview - -There are three debugging panes to be aware of: **Breakpoints**, **Debugger**, and **Variables**: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580004.png" class="no-border" >}} - -The **Breakpoints** pane shows all the microflows that contain breakpoints, which makes it easier to find your breakpoints. The best practice is to remove any breakpoints after you are done troubleshooting your microflows. You can always delete them from the **Breakpoints** pane. - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580017.png" class="no-border" >}} - -The **Debugger** pane is useful when you are debugging your microflow, as it will walk you through the microflow: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580008.png" class="no-border" >}} - -The **Variables** pane shows the variables, objects, and lists involved in your microflow and how they change as you step through the microflow via the **Debugger** pane: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580005.png" class="no-border" >}} - -The best practice is to have the **Debugger** and **Variables** panes in different docks. The **Debugger** pane should usually be at the bottom of your development dock, and the **Variables** pane can be either in the left dock or the side dock. You want to be aware of how the values are being changed in the microflow, and it is difficult to see those changes if both panes are tabs within the same dock. - -## Using Breakpoints - -Breakpoints are points in a microflow where the application will halt execution. This is useful to analyze the application execution and data up to that point. You can add breakpoints at any point in your microflow by following these steps: - -1. Run your application locally. -2. Open the microflow that needs debugging in Studio Pro. -3. Right-click any of the activities or decisions in the microflow and select **Add breakpoint**. This sets a breakpoint on the selected step in the microflow, which is visually represented by a red dot: - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580020.png" class="no-border" >}} - - You can open an overview of all the breakpoints by going to **View** > **Breakpoints**: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580019.png" class="no-border" >}} - - In the **Breakpoints** pane, you can enable, disable, and delete breakpoints. You can also configure a breakpoint condition and open the microflow that contains that breakpoint: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580017.png" class="no-border" >}} - -## Debugging - -1. Run the application and open it in your browser. -2. Do whatever is needed to trigger the microflow that you want to debug: - * As an end-user of the application, you will see a progress bar on the application - * As a developer of the application, you will see the Mendix icon flashing on the panes task bar -3. Click the icon on the panes task bar to open Studio Pro. The element with the breakpoint that interrupts this microflow should be highlighted with a red border: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580010.png" class="no-border" >}} - -4. Open the **Debugger** pane from the **View** menu: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580009.png" class="no-border" >}} - - The debugger can be used to go through the microflow step by step: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580008.png" class="no-border" >}} - -5. You have the following options on this pane: - * Click **Step into** or **Step over** to move to the next step in the microflow (note that the difference between **Step into** and **Step over** is only noticeable if you run into a microflow call activity or a loop) - * **Step into** means that the debugger steps into the sub microflow or loop - * **Step over** moves the debugger to the next step in the same microflow - * Click **Step out** to instruct the debugger to leave the sub microflow or loop (this is basically the opposite of **Step Into**) - * Click **Continue** to instruct the debugger to continue until it reaches another breakpoint - -For details on available shortcut keys, see the [Debugger Shortcut Keys](/refguide8/studio-pro-overview/#debugger-shortcuts) section of *Studio Pro Overview*. - -## Variables Viewer - -As you are stepping through a microflow, the variables pane will start to change. This overview will show you all the variables, objects, and lists involved in the application, that is all the variables, entities, references, current-user information, and device-type information. It can be used as you are stepping through the microflow to review the values and see if they match your expectations. - -You can open the **Variables** pane from the **View** menu: -{{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580006.png" class="no-border" >}} - -The **Variables** viewer can be used to inspect values accessible to the microflow. The values are updated with every step you make in the **Debugger**: -{{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580005.png" class="no-border" >}} - -## Breakpoint Conditions - -Sometimes it is necessary to configure a breakpoint so that the microflow only breaks on a certain condition. This is achieved with breakpoint conditions and is configured by use of microflow expressions. Setting a breakpoint condition can be very useful if you are debugging a batch process and you only want to break at a certain value. Using breakpoint conditions is strongly advised if you are debugging an application that is running in production, as this will prevent the application from stopping for users other than yourself. - -To use breakpoint conditions, follow these steps: - -1. Right-click the activity or decision in the microflow with a breakpoint and select **Edit breakpoint condition**: - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580018.png" class="no-border" >}} -2. Use the expression below to make sure this breakpoint only interrupts the microflow if you are executing it yourself (replace `YourUserName` with your own user name): - - ```java - $currentUser/name = 'YourUserName' - ``` - - The expression should look like this: - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/18580012.png" class="no-border" >}} - -3. Click **OK** to save the breakpoint condition. - -## Read More - -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clear Warning Messages in Mendix](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Java Actions Remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [Debug Microflows Remotely](/howto8/monitoring-troubleshooting/debug-microflows-remotely/) -* [Common Properties](/refguide8/microflow-element-common-properties/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely.md b/content/en/docs/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely.md deleted file mode 100644 index 3c83264c113..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: "Debug Microflows Remotely" -url: /howto8/monitoring-troubleshooting/debug-microflows-remotely/ ---- - -## Introduction - -In addition to debugging a local deployment of your app, it is also possible to debug applications that are already in a cloud environment. - -{{% alert color="warning" %}} -**Debugging in a production environment is not recommended.** - -If you are debugging in the cloud, be aware of other app end-users. Breakpoints in the debugger will pause processes for all users of the app in this environment. -{{% /alert %}} - -This how-to teaches you how to do the following: - -* Connect the debugger in Studio Pro to your Mendix Cloud environment - -## Prerequisites - -Before starting this how-to, make sure you have completed the following prerequisites: - -* Have access as a team member to a Mendix app deployed to a [licensed](/developerportal/deploy/licensing-apps/) Mendix Cloud environment -* Have **TRANSPORT RIGHTS** to the app environment you want to debug in the app's [node permissions](/developerportal/deploy/node-permissions/) - -## The Basics - -In Mendix Cloud, the debugger is always listening for connections so you cannot turn it on or off. To debug your app in the cloud, you need to get a URL and a password from the app environment and provide that information to Studio Pro. The steps below explain how to do this. - -{{% alert color="info" %}} -The debugger supports only debugging of single-instance environments. Multi-instance environments need to be scaled down to one instance before the debugger can be used. See [Scaling Your Environment in Mendix Cloud](/developerportal/deploy/scale-environment/) for more information. -{{% /alert %}} - -### Obtain Debugging Credentials - -#### Obtain Debugging Credentials from Mendix Cloud - -When your application is in Mendix Cloud, follow these steps: - -1. Open your app in [Apps](https://sprintr.home.mendix.com/). - -2. Click **Environments** in the navigation pane. - -3. In the **Deploy** tab, click **Details** ({{% icon name="notes-paper-edit" %}}) for the environment that you want to debug: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely/environment-details.png" class="no-border" >}} - -4. In the **General** tab, click **Show Debugger Information**: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely/show-debugger-information.png" class="no-border" >}} - - This invokes the **Debugger settings** pop-up window, which provides a URL (such as `http://yourapp.mendixcloud.com/debugger/`) and a password: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely/debugger-settings.png" class="no-border" >}} - -You will need to provide these credentials to Studio Pro to connect the debugger to the app running in the cloud. - -#### Obtain Debugging Credentials from Mendix on Kubernetes Connected{#private-cloud} - -If your application is on a connected Mendix on Kubernetes, you can get the credentials from the Mendix Portal: - -{{% alert color="warning" %}} -You can only remotely debug apps deployed to Mendix on Kubernetes for Mendix if you are using Mendix Operator version 1.6.0 or above. -{{% /alert %}} - -1. Open your app in [Apps](https://sprintr.home.mendix.com/). - -2. Click **Environments** in the navigation pane. - -3. Click **Details** for the environment that you want to debug. - -4. Open the **Debugger** tab: - -5. If the debugger is currently disabled, click **Enable Debugger**. You will be asked to confirm the generated strong password. Mendix recommends not changing this password. - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely/pc-debugger-password.png" alt="Enter password for the Mendix on Kubernetes debugger" class="no-border" >}} - - You will receive a warning that you have made some changes. Click **Apply Changes** to restart the app and apply the changes. - -Once the debugger is enabled, you will see the **URL** and **Password** which are the credentials you need to supply to Studio Pro. Use the **Copy to clipboard** links to simplify providing the credentials. - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely/pc-debug-tab.png" class="no-border" >}} - -When the debugger is enabled, you can click **Disable Debugger** to disable it. You will be asked to confirm your choice and will receive a warning that you have made some changes. Click **Apply Changes** to restart the app and apply the changes. - -#### Obtain Debugging Credentials from SAP S/4 HANA Cloud - -If your application is on the SAP S/4 HANA cloud, you will need to set the password in the SAP Cockpit: - -1. Log in to the SAP Cockpit and go to your application's settings page. - -2. Go to your application > **User-Provided Variables**. - -3. Click on the button 'Add variable' and add 'DEBUGGER_PASSWORD' and the password. Both are case-sensitive. - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely/debugger-settings-saps4hana.png" alt="SAP Cockpit showing user-provided variables" class="no-border" >}} - -4. Restart your application. - -### How to Enable Cloud Debugging in Studio Pro - -Once you have the unique URL and password, there are two methods for connecting Studio Pro to the cloud environment. - -{{% alert color="warning" %}} -If you do cannot connect the debugger, then you do not have sufficient permissions to your app. Ask the Technical Contact or the project Scrum Master to provide the correct permissions. -{{% /alert %}} - -1. Open the **Connect Debugger** dialog box – you can do this in two ways within Studio Pro: - - * Go to the **Run** menu and select **Connect Debugger…**: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely/18580048.png" class="no-border" >}} - - * Click **Connect…** in the **Debugger** pane: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely/debugger-pane.png" class="no-border" >}} - -2. In the **Connect Debugger** dialog box set the following: - - * **Connect to** – select the option *An app running in Mendix Cloud or on another remote server.* - * **URL** – the *URL* from the **Debugger Settings** for your app environment - * **Password** – the *Password* from the **Debugger Settings** for your app environment - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/debug-microflows/debug-microflows-remotely/18580047.png" class="no-border" >}} - -3. Click **OK**. - -The debugger is now connected to your app running in the cloud. - -## Read More - -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clear Warning Messages](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Java Actions Remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [The Ultimate Debugger](https://www.mendix.com/tech-blog/the-ultimate-debugger/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues.md b/content/en/docs/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues.md deleted file mode 100644 index 86349801ea2..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: "Detect and Resolve Performance Issues" -url: /howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues/ ---- - -## Introduction - -Any application can run into performance issues. This document describes a number of performance issues you may run into, some root causes, and how you can resolve these issues. - -The flow chart below, which is designed like a microflow, presents infrastructure for deciding how to troubleshoot and resolve performance-related issues. This document is based on this flow. - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues/18580226.png" class="no-border" >}} - -## Issues - -Performance issues typically manifest themselves for end-users in one of two ways: either an action takes too long to complete (a page feels slow or unresponsive), or an entire page loads slowly. In both cases, some process is running too long or too many times to complete a specific task. Your goal should be to identify which tasks in particular are causing your issue, and then focus your effort on optimizing those tasks. - -First, you will need to identify if your issue is UI-centric or microflow-centric: - -* If a page is taking a long time to initially load or if a page gets slow or unresponsive after clicking a microflow button, a microflow is most likely slowing your application down -* If the UI feels glitchy or slow after the page has loaded, you may have a UI-centric issue - -{{% alert color="info" %}} -All performance issues are extremely context-sensitive, which means there is no single cure-all for a performance problem. This document will attempt to address common issues and how you can resolve them. -{{% /alert %}} - -## Slow UI - -If your user interface is slow, you will need to figure out whether this is due to slow microflows called by the page or to a large number of calls made by the UI. To determine this, you need to use a web browser with developer tools (a console, debugger, performance tools, etc.) like [Firefox Developer Edition](https://www.mozilla.org/nl/firefox/developer/). - -In an example scenario, you run tests on your app and find that you have 26 XPath retrieves for a single page load. You may be able to see the run times for each step and how long each step waited before starting. Some retrieves may take longer than others, but the fact that you have such a large amount of retrieves occurring is also a potential issue. - -Once you have identified the cause for your slow UI—either [too many loads](#loads) or [slow loads](#slow)—you can move on to the sections below. - -### Too Many Loads {#loads} - -If you have too many loads occurring on a single page, review the page structure in Studio Pro to determine if that number can be reduced. Here are a few common causes of large number of loads: - -* Many data grids -* Many nested dataviews -* Many reference selectors -* Many tabs -* Widgets - -Every situation is unique, but you are well on your way to finding your slow component. From here, sometimes trial and error can work best. Remove objects from your page until it speeds up to narrow down the slow component. - -### Slow Loads {#slow} - -If you have determined that slow loads are your issue, take a look at the slow load with your developer tools and determine where it comes from. The sections below address specific examples. - -#### Slow Network - -If your data transfers are taking a long time for a small amount of data, you may wish to contact a system administrator for further assistance. This document focuses on issues you can resolve within your application model. - -#### Retrieve Action - -If you find that a particular retrieve action is slow, you can work to simplify it. Review the following: - -* Complex XPath -* Missing indexes -* Combined security rules (as in, there is a user with multiple user roles, each with complex security) - -#### Microflow - -If your slow action occurs via microflow, see the [Slow Microflows](#slow-micro) section below for information on troubleshooting. - -## Slow Microflows {#slow-micro} - -If your performance issue is caused by a microflow, you need to find which microflow and which activities are the slowest in that microflow. - -Sometimes, identifying the slow activity and activities in your slow microflow will be obvious. You may have a single microflow with just a few steps, and one of them is egregiously slow. If this is the case, move on to the next section and focus on optimization. If not, continue on below. - -Tools you can use to identify your slow microflow and the specific slow activities in that microflow are described in the sections below. - -### Server Monitoring - -The Mendix Server and [Apps](/developerportal/) offer a number of performance graphs and logs. - -### Microflow Debugger - -Once you have identified a slow page, it is easy to identify which microflows are executed on that page. Make sure you look at directly referenced microflows (such as data sources), and also at sub-microflows, on-change event handlers, and domain model event handlers that could be called by your page. - -Setting a break point and stepping through these relevant microflows can often give you a quick (although subjective) way to find a slow action (for details, see [How to Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/)). If you cannot subjectively identify your slow process, move on to the next step. - -### Microflow Time Stamps - -Times stamps can allow you to objectively identify slow microflows and activities by timing their execution. To do so, consider a simple microflow like this: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues/18580222.png" class="no-border" >}} - -To set up a timer, first add a **Create variable** activity as the first step, where you are going to store the current time: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues/18580221.png" class="no-border" >}} - -Then, add a **Log message** activity at the end of your microflow: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues/18580219.png" class="no-border" >}} - -Set up the activity similar to this: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues/18580220.png" class="no-border" >}} - -Here, you are calculating the number of milliseconds between when your microflow began and when it completed, and then writing that out to the console as info. When you run your app, you will see a line in the console every time this microflow executes. The message will contain the execution time. - -Add microflow timers until you find your culprit microflow, then add extra timers in that microflow to determine which activity is the slow one. When you find a slow activity, see the [Optimizing Microflow Activities](#optimizing) section below. These sections present details on how to optimize your microflow as a whole. - -## Optimizing Microflow Activities {#optimizing} - -### Slow Database Retrieves - -Slow retrieves can occur for a number of different reasons, such as: - -* Sub-optimal XPath -* Complex security XPath -* Missing indexes -* Complex calculated attributes -* Large number of objects retrieved (see the [Batches](#batches) section below) - -Additionally, for details on how denormalization can improve your app performance in some cases, review [How to Denormalize Data to Improve Performance](/howto8/data-models/denormalize-data-to-improve-performance/). - -### Slow Database Commits - -Slow commits are often caused by a before-commit or after-commit event. Review those microflows for slow activities. - -If you are committing large amounts of data (for example, thousands of rows), you might consider using batching to improve performance. Additionally, check for use of the [Refresh in client](#refresh) property. - -#### Batches {#batches} - -Below is an example of how to retrieve in batches. You can do something quite similar for commits as well. - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues/18580216.png" class="no-border" >}} - -#### Refresh in Client {#refresh} - -The **Refresh in client** property of a change or commit activity is quite useful to provide updated information to your user. However, when committing large numbers of rows, this can slow you application down, as it attempts to update thousands of rows in your client's browser. Consider turning it off if possible. - -### Slow Sub-Microflow - -If you find that you have a slow sub-microflow, begin the process of identifying the slow activity within the microflow, based on the [Slow Microflows](#slow-micro) section above. - -### General Slow Microflow (No Specific Activity Identified) - -If your microflow is slow as a whole but there is no particular activity that stands out as the culprit, consider the structure of your microflow. The sections below describe a number of possible issues. - -#### Many Commits - -If you find yourself committing data inside a loop, you can typically optimize this by making changes to your entities and storing them into a list. For example, consider this microflow: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues/18580218.png" class="no-border" >}} - -Every time the loop executes, an **Order** object is committed. You can optimize this by committing the entire list outside the loop after processing is completed. Simply set the **Commit** property to **No** on the **Change order** activity, then add a commit of the entire OrderList outside the loop: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/detect-and-resolve-performance-issues/18580217.png" class="no-border" >}} - -This ultimately reduces the number of database operations that need to be performed during execution of your microflow, thus enhancing performance. - -#### Many Retrieves - -If your microflow performs multiple retrieves, especially in a loop, this may be the cause of your performance issues. To optimize this, think about how you could retrieve data in lists outside of a loop. - -Additionally, check for any calculated attributes on your retrieved entities, as they are calculated every time you retrieve that entity, regardless of whether they are actually used. - -#### Unnecessary or Nested Loops - -If you find that your microflow has a large number of objects to loop over, or especially if your microflow has nested loops, execution time can escalate quickly. In this situation, think about your domain model architecture and how an additional entity, attribute, or association might make it more simple to access the information you need. You might also be able to more effectively use XPath rather than search in a loop for a particular object. - -As always, make sure you look at the retrieves and commits performed in your loops, and try to minimize them wherever possible. - -## Read More - -* [Expert Webinar Series: Performance](https://youtu.be/xNR3BjJYt3U) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors.md b/content/en/docs/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors.md deleted file mode 100644 index 3b606728e06..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Find the Root Cause of Runtime Errors" -url: /howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/ -weight: 8 ---- - -## Introduction - -This how to will show you how to find the information necessary to locate the root cause of a runtime error. The message displayed in the application is often vague and non-descript. Depending on the environment in which the error occurred, there are two methods for finding this information. - -This how-to teaches you how to do the following: - -* Find the root cause of runtime errors via two methods - -## Method #1 – Using Studio Pro - -If the application is deployed from Studio Pro, the information is located in the console: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/18580024.png" class="no-border" >}} - -When an error occurs, a line with a red font will appear in the console. Double-clicking on this line brings up the **View Log Line Details** pop-up window: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/18580023.png" class="no-border" >}} - -There are three key pieces of information in this window: - -1. The microflow and action where the error occurred. -2. The type of error that occurred. -3. The expression in which the error occurred. - -With these three pieces of information, you should be able to find the cause of the error. If you cannot determine the cause from this information, you can put a break point in the specified microflow and debug the situation. - -## Method #2 – Using the Application Logs - -If the application is deployed from the service console or in the cloud, the information is available in the application logs. - -{{% alert color="info" %}} - -You need to have the timestamp of when the error occurred. The logs can contain a lot of information, and this timestamp will make searching through them much easier. Once you navigate to the log file, you can search for the error. - -{{% /alert %}} - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/18580022.png" class="no-border" >}} - -Go to the section of the log that corresponds to the time of the error. There will be a number of lines in that timeframe that have `ERROR –` after the timestamp. These are the lines of the log file that contain the necessary information. There are three key pieces of information here: - -1. The microflow and action where the error occurred. -2. The type of error that occurred. -3. The expression in which the error occurred. - -With these three pieces of information, you should be able to find the cause of the error. If you cannot determine the cause from this information, you can put in a break point in the specified microflow and debug the situation. - -## Read More - -* [Clear Warning Messages](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Java Actions Remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debug Microflows Remotely](/howto8/monitoring-troubleshooting/debug-microflows-remotely/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [The Root Cause of Runtime Errors and Resolving the 2 Most Common Issues](https://www.mendix.com/blog/the-root-cause-of-runtime-errors-and-resolving-the-2-most-common-issues/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/log-levels.md b/content/en/docs/howto8/monitoring-troubleshooting/log-levels.md deleted file mode 100644 index fe8627bf131..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/log-levels.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: "Set Log Levels" -url: /howto8/monitoring-troubleshooting/log-levels/ -weight: 9 ---- - -## Introduction - -Each application has a log to which it writes log messages to monitor the health of the running application. Log levels are used to label the log messages and to highlight the highest priority ones so that they can be easily identified and responded to. - -This how-to teaches you how to do the following: - -* Configure the log levels for the various types of logging within your app - -## Logging Basics - -### Log Messages - -Log messages appear in the log of your Mendix application and present contextualized and detailed information, including the following: - -* Date and time the log message was created -* Level -* Log node -* Message -* Stack trace - -#### Log Node - -The log node describes the source of the log message. For example, in a log message from the email module, the log node could be set to **Email Module**. - -#### Message - -Most messages in the log are auto-generated by the system (for example, **Mendix Runtime successfully started, the application is now available**). However, log messages that are created via a microflow, can be customized by the developer. - -Customized log messages are created by defining a **Template**. The template is the structure of the message, and can be composed of parameters and free text. - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/log-levels/18580031.png" class="no-border" >}} - -In the image above, the template for the message is **Email not sent to customer {1}**. With this example template, when the error occurs the customer’s email address is inserted into the parameter placeholder **{1}** (for example, the log message would be **Email not sent to customer john.smith@hiscompany.com**). Thus, the log message is customized with data that is specific to the error. - -#### Stack Trace - -The stack trace is a list of current method calls from the point when the application was started to the point where the exception occurred. - -In Studio Pro, log messages that include a stack trace are marked with a paperclip icon. Double-clicking this icon shows the stack trace. - -### Level {#level} - -The log level defines the severity of the log message. In Studio Pro, this is represented by different colors and an icon. - -These are the log levels used by Mendix: - -| Level | Icon | Color | Description -| --- | --- | --- | --- | -| Trace | | | More detailed information. These are only written to logs. | -| Debug | | | Detailed information, typically of interest only when diagnosing problems. | -| Info | | | Confirmation that things are working as expected. | -| Warning | {{< figure src="/attachments/howto8/monitoring-troubleshooting/log-levels/18580038.png" class="no-border" >}} | Orange | Indicates that something unexpected happened or that there is some problem in the near future (for example, "disk space low"). The application is still working as expected. | -| Error | {{< figure src="/attachments/howto8/monitoring-troubleshooting/log-levels/18580037.png" class="no-border" >}} | Red | Due to a more serious problem, the application has not been able to perform some function. | -| Critical | {{< figure src="/attachments/howto8/monitoring-troubleshooting/log-levels/18580036.png" class="no-border" >}} | White (text), red (background) | A serious error has occurred, indicating that the application itself may be unable to continue running. | - -## Setting the Log Levels - -In this section, you will learn how to configure the log levels of the messages produced by the system. The different highlighted [levels](#level) can be applied to the predefined logging produced by Mendix Studio Pro and to custom logging. - -This section describes how to configure both the log levels for predefined logging created by Studio Pro and custom logging. - -### Configuring Log Levels via Script - -Log levels can be configured through the runtime admin port before the actual log levels exist. This enables creating a script that sets all the required log levels at once. - -This is a Python script that sets `ConnectionBus` and `ActionManager` to the Trace and Debug levels: - -```py -import requests, base64, json, sys - -payload = { - 'action':'set_log_level', - 'params': {'nodes' : [ - { 'name':'ConnectionBus', 'level':'TRACE'}, - { 'name':'ActionManager', 'level':'DEBUG'} - ], 'force':True} -} -``` - -You can run this script as follows: - -```powershell -C:\temp\LogDemoApp\python -λ python setlogs.py 87a32a3e-c6db-4bc8-9fa3-7cd5b108eaec 8090 -{"feedback":{},"result":0} -``` - -### Configuring the Log Levels for Standard Log Messages - -To set the log levels for standard log messages, follow these steps: - -1. In the **Console** pane, click **Advanced** to open the menu of advanced options. -2. Click **Set log levels**. -3. For the relevant **Log node**, select the desired level from the drop-down in the **Log level** column. - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/log-levels/18580029.png" class="no-border" >}} - -{{% alert color="info" %}} -You can override the log level for standard log messages in each environment when your app is deployed to Mendix Cloud. See the [Log Levels Tab](/developerportal/deploy/environments-details/#log-levels) section in *Environment Details* for more information. -{{% /alert %}} - -### Configuring the Log Levels for Custom Log Messages - -To set the level of custom log messages that you have created via a microflow, follow these steps: - -1. Open the microflow in which you intend to change the log message level. -2. Double-click the log message activity. -3. In the **Log level** drop-down, select the desired level. - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/log-levels/18580028.png" class="no-border" >}} - -## Read More - -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clear Warning Messages in Mendix](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/manage-app-performance/_index.md b/content/en/docs/howto8/monitoring-troubleshooting/manage-app-performance/_index.md deleted file mode 100644 index 2f27064733b..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/manage-app-performance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Manage App Performance" -url: /howto8/monitoring-troubleshooting/manage-app-performance/ -weight: 12 ---- - -You can [Manage App Performance with New Relic](/howto8/monitoring-troubleshooting/manage-app-performance-with-new-relic/). diff --git a/content/en/docs/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic.md b/content/en/docs/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic.md deleted file mode 100644 index 58629ef73a9..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "Manage App Performance with New Relic" -url: /howto8/monitoring-troubleshooting/manage-app-performance-with-new-relic/ -weight: 2 ---- - -## Introduction - -To ensure your applications run smoothly, they need to be actively monitored so that the information is available in order to do the following: - -* Avoid performance problems -* Diagnose performance problems when they occur - -New Relic is a flexible application performance management tool that provides information to help you achieve the above goals. - -This how-to teaches you how to do the following: - -* Set up application performance management for your Mendix application on New Relic - -## Prerequisite - -Before starting with this how-to, make sure you have completed the following prerequisite: - -* Create a New Relic account by signing up here: [https://newrelic.com/signup](https://newrelic.com/signup) - -## Setting Up - -In this section, we will walk through all the steps to configure New Relic so that it can be used for the [application performance diagnostics](/appstore/partner-solutions/apd/) of your Mendix application. - -## Setting up New Relic (On-Premises Only) - -The following steps are only relevant for on-premises deployments (skip to [2.2.1 Cloud Foundry](#CloudFoundry) if you are deploying your Mendix application to Cloud Foundry). - -1. Sign in to New Relic and create a new application: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic/19398929.png" class="no-border" >}} -2. Select Java: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic/19398930.png" class="no-border" >}} - -3. Download the Java agent archive and save your license key: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic/19398932.png" class="no-border" >}} - -4. Add your license key to the *newrelic.yml* file from the downloaded archive as described here: [https://docs.newrelic.com/docs/agents/java-agent/installation/java-agent-manual-installation#h2-download-files](https://docs.newrelic.com/docs/agents/java-agent/installation/java-agent-manual-installation#h2-download-files). - -## Setting Up Your Mendix Deployment - -### Cloud Foundry{#CloudFoundry} - -Follow these buildpack instructions to set up New Relic for Cloud Foundry deployments: [https://github.com/mendix/cf-mendix-buildpack#new-relic](https://github.com/mendix/cf-mendix-buildpack#new-relic). - -### On Premise Linux and Windows Service Console - -To the `javaopts` list in your *m2ee.yaml* file, add "-javaagent:javaagent.jar". For example: - -```java - javaopts: [ - "-Dfile.encoding=UTF-8", "-Xmx512M", "-Xms512M", - "-Djava.io.tmpdir=/srv/mendix/data/tmp", - "-javaagent:/opt/newrelic/javaagent.jar" - ] -``` - -### Mendix Studio Pro (Development Mode Only) - -1. Open your Mendix application, and click **Settings** in the **Project Explorer**. -2. Open a configuration: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic/19398903.png" class="no-border" >}} - -3. In the **Extra JVM parameters** field on the **Server** tab, add: `-javaagent:javaagent.jar`: - - {{< figure src="/attachments/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic/19398904.png" class="no-border" >}} - -## Transactions - -After completing the steps described above, all the requests handled by your Mendix application should become visible together with various graphs and statistics: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic/19398943.png" class="no-border" >}} - -## Databases - -Your database calls and queries will now be visible on the database page: -{{< figure src="/attachments/howto8/monitoring-troubleshooting/manage-app-performance/manage-app-performance-with-new-relic/19398944.png" class="no-border" >}} - -## Further Documentation - -For more information on New Relic, see the New Relic documentation here: [https://docs.newrelic.com/](https://docs.newrelic.com/). - -## Read More - -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clear Warning Messages in Mendix](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Java Actions Remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Set Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [Solve Load and Import Errors](/howto8/monitoring-troubleshooting/solving-load-and-import-errors/) -* [Debug Microflows Remotely](/howto8/monitoring-troubleshooting/debug-microflows-remotely/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx.md b/content/en/docs/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx.md deleted file mode 100644 index e948b54ac3e..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: "Monitor Mendix Using JMX" -url: /howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/ -weight: 10 ---- - -## Introduction - -This how-to is relevant if you run Mendix on-premises. If you do this, you probably have standard monitoring tooling that you use to monitor all your applications. - -For Java applications, most monitoring tools provide a way to hook into [JMX](https://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html) in order to get information about the application. This how-to describes using JMX to get information on your Mendix application. - -Mendix doesn’t provide any runtime or application specific MBeans, which means that without writing your own MBeans, you will only be able to monitor generic JVM statistics. This how-to will also describe enabling JMX on your Mendix Runtime as well as writing custom MBeans to expose Mendix Runtime information and app-specific information. - -This how-to teaches you how to do the following: - -* Start Mendix Runtime with JMX -* Expose management information with an MBean -* Expose app-specific statistics with an MBean - -## Prerequisites - -None. - -## Starting the Mendix Runtime with JMX enabled - -To enable JMX on your Mendix Runtime, you can use the following Java options in the *m2ee.yaml* for your Mendix Runtime: - -```yaml -javaopts: [ - -"-Dfile.encoding=UTF-8", "-Xmx128M", "-Xms128M", - -"-Djava.io.tmpdir=/tmp", - -"-Dcom.sun.management.jmxremote", - -"-Dcom.sun.management.jmxremote.port=7845", - -"-Dcom.sun.management.jmxremote.local.only=false", - -"-Dcom.sun.management.jmxremote.authenticate=false", - -"-Dcom.sun.management.jmxremote.ssl=false", - -"-Djava.rmi.server.hostname=192.168.1.70", - -] -``` - -## MBean Exposing Generic Mendix Statistics - -The simplest way to expose management information is by writing an MBean interface and a Java class that implements the interface. You can define the getters and setters, but you can also define methods that can be called from the generic management tooling. This can be used, for example, to tell a running application to reload its configuration file. - -This is an example of an interface that contains getters for some generic Mendix information, *MxStatsMBean.java*: - -```java - -package jmx.actions; - -public interface MxStatsMBean { - -public int getMaximumNumberConcurrentUsers() throws Exception; - -public int getActionQueueSize(); - -public int getActiveActionCount(); - -public int getScheduledActionCount(); - -public long getNumberConcurrentSessions(); - -public long getCurrentUserCount(); - -public long getCompletedActionCount(); - -public long getNamedUserCount(); - -} -``` - -This is the implementation, `MxStats.java`. The methods call the [Mendix Core](https://apidocs.rnd.mendix.com/4/runtime/classcom_1_1mendix_1_1core_1_1_core.html) class and return the value: - -```java -package jmx.actions; - -import com.mendix.core.Core; - - public class MxStats implements MxStatsMBean { - - public int getMaximumNumberConcurrentUsers() throws Exception { - - return Core.getMaximumNumberConcurrentUsers(); - - } - - public int getActionQueueSize(){ - - return Core.getActionQueueSize(); - - } - - public int getActiveActionCount(){ - - return Core.getActiveActionCount(); - - } - - public int getScheduledActionCount(){ - - return Core.getScheduledActionCount(); - - } - - public long getNumberConcurrentSessions(){ - - return Core.getNumberConcurrentSessions(); - - } - - public long getCurrentUserCount(){ - - return Core.getConcurrentUserCount(true); - - } - - public long getCompletedActionCount(){ - - return Core.getCompletedActionCount(); - - } - - public long getNamedUserCount(){ - - return Core.getNamedUserCount(); - - } -} -``` - -Now you're able to see the result of the values exposed by this MBean in the JConsole: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/18580003.png" class="no-border" >}} - -## MBean Exposing App-Specific Statistics - -You can use the same approach with an interface and an implementation class to expose app-specific information. Here’s a different approach: one that exposes a dynamic set of values. You can do the same with methods, but the example only shows the attributes to retrieve values. - -The idea is that you will have a Java Action that you can call in a microflow where you expose arbitrary key value pairs. - -## Read More - -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clear Warning Messages](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) -* [Debug Java Actions Remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Debug Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [Debug Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debug Microflows Remotely](/howto8/monitoring-troubleshooting/debug-microflows-remotely/) -* [Debug Java Actions Remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) diff --git a/content/en/docs/howto8/monitoring-troubleshooting/solving-load-and-import-errors.md b/content/en/docs/howto8/monitoring-troubleshooting/solving-load-and-import-errors.md deleted file mode 100644 index 61796988edb..00000000000 --- a/content/en/docs/howto8/monitoring-troubleshooting/solving-load-and-import-errors.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Solve Load and Import Errors" -url: /howto8/monitoring-troubleshooting/solving-load-and-import-errors/ -weight: 11 -aliases: - - /howto8/solving-load-and-import-errors.html - - /howto8/solving-load-and-import-errors -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -This how-to will help you to solve problems that may occur when opening a project in Mendix Studio Pro. - -One possible cause of errors that prevent loading is the usage of the [Mendix Model SDK](/apidocs-mxsdk/mxsdk/) for creating or editing the project. With the Mendix Model SDK it's possible to edit your project in such a way that its format becomes invalid, and in the process preventing Studio Pro from opening it. When this happens the following message is shown: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/solving-load-and-import-errors/18580055.png" class="no-border" >}} - -Read on to find out how to determine the origin of these errors, and possible ways to solve them. - -## Determining the Actual Problems - -Click the **Details >>** button to show the actual errors that occurred while loading your project: - -{{< figure src="/attachments/howto8/monitoring-troubleshooting/solving-load-and-import-errors/18580052.png" class="no-border" >}} - -These detailed messages tell you the following: - -* The module and document in which the error occurred (for example, the domain model of the module 'Transportation'). -* The model element that caused the error (for example, the entity 'Vehicle'). -* What the actual problem is (for example, there's an index that doesn't contain any attributes, which is not permitted). - -## Determining the Origin of Your Project - -Before trying to solve the problems, it's useful to discover the origin of the project, because the errors may be introduced by someone else. Go through the following possibilities: - -### Is This a Team Server Project? - -If your project is a [Team Server](/developerportal/repository/team-server/) project, and you just did a [download or update](/refguide8/using-version-control-in-studio-pro/) from the server, the problem may have been added in a revision that was recently committed to the Team Server. You can check who made the most recent commit via the [Team Server](/developerportal/repository/team-server/) menu item in [Apps](https://sprintr.home.mendix.com/).home.mendix.com). - -If the latest change on your branch line was committed by someone other than yourself, please inform the person about the problem. - -### Did You Obtain the Model from Someone Else? - -If you received the model from someone else, for example as a [project package](/howto8/integration/importing-and-exporting-objects/) (*.mpk*) file, then it's possible they created the model with the Mendix Model SDK. Please inform the person about the problem and ask them for a solution. - -### Did You Create the Project Yourself? - -If you created or edited the project yourself, you will want to read the next section of this how-to to find out what you can do to solve the problem. - -## Solving the Problems - -The problems described in this how-to can't be solved by editing the project in Mendix Studio Pro, because the project's file format is invalid in a way that prevents Studio Pro from reading it. This also means the problems are probably not caused by working on the project with Studio Pro. - -The most likely cause for these kinds of errors is a faulty script that was run on the Mendix Model SDK and, if this is the case, means you will also need to use the SDK to fix the problems. If you created or edited the model yourself using the Mendix Model SDK, you will probably know what to do to solve the problems by carefully reading the messages in the error dialog, and locating the relevant part of you SDK code, after which you can change your SDK script to make the project valid again. Be sure to check the [Mendix Model SDK documentation](/apidocs-mxsdk/mxsdk/) if you need information about constructing or altering models with SDK scripts. - -## Read More - -* [Clearing Warning Messages in Mendix](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Debug a Hybrid Mobile Application](/howto8/monitoring-troubleshooting/debug-a-hybrid-mobile-application/) -* [Debugging Java Actions](/howto8/monitoring-troubleshooting/debug-java-actions/) -* [Debugging Java actions remotely](/howto8/monitoring-troubleshooting/debug-java-actions-remotely/) -* [Debugging Microflows](/howto8/monitoring-troubleshooting/debug-microflows/) -* [Debugging Microflows Remotely](/howto8/monitoring-troubleshooting/debug-microflows-remotely/) -* [Finding the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Log Levels](/howto8/monitoring-troubleshooting/log-levels/) -* [Monitoring Mendix using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) diff --git a/content/en/docs/howto8/security/_index.md b/content/en/docs/howto8/security/_index.md deleted file mode 100644 index ecb04e4e4b3..00000000000 --- a/content/en/docs/howto8/security/_index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Security" -url: /howto8/security/ -weight: 90 -no_list: false -description_list: true -#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. ---- - -## Introduction - -This category of how-tos presents details on how to secure your data and make sure that the right user is seeing the data that they are allowed to see. - -## Documents in This Category diff --git a/content/en/docs/howto8/security/best-practices-security.md b/content/en/docs/howto8/security/best-practices-security.md deleted file mode 100644 index e1a349e09d5..00000000000 --- a/content/en/docs/howto8/security/best-practices-security.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: "Implement Best Practices for App Security" -linktitle: "Best Practices for App Security" -url: /howto8/security/best-practices-security/ -weight: 20 -description: "A set of security aspects and checks to use when developing your Mendix application." -#The anchor request-handlers below is mapped, so it should not be removed or changed. ---- - -## Introduction - -Security is one of the most important aspects of an application, because misconfiguration or failing security can have large stakeholder consequences. The Mendix Runtime protects your application and data according to your model, and Mendix Cloud handles security at the infrastructure level. - -This document describes the common aspects you should consider when delivering an application within Mendix Cloud. - -## Implementing Access Rules - -The Mendix architecture includes the Mendix Client, which can compose its own queries (generated by widgets) and send them to the Mendix Runtime. If the Mendix Runtime were to execute these queries without touching them, the Mendix Client would be able to request data that the user should not be allowed to see. - -{{< figure src="/attachments/howto8/security/best-practices-security/mendix-runtime-architecture.png" alt="Mendix Runtime Architecture" width="500" class="no-border" >}} - -When designing an application, a developer can specify access rules on an entity (for more information, see [How to Create A Secure App](/howto8/security/create-a-secure-app/)). These access rules are applied whenever a query (received from a client) should be executed, thus they constrain the data returned to the client. For example, users with the "Customer" role can only view orders that are associated to the customer of which this user is part. - -While the data that should be viewable and editable in which role is application-specific, the following best practices are key: - -* Attributes determined by the system (like the status of an order) should never be writable -* If an anonymous user is allowed to create objects, constrain these objects to the owner (an anonymous user is actually a **System.User** object created on the fly) -* Do not set a default rule for read-and-write access – this forces you to think about each attribute that is added to an entity -* Security constraints should be formed as entity access rules and visibility constraints in page components (grids, list views, data views) -* Keep your attributes editable within data views, because if an access rule prohibits write access, your client will display it as non-editable – this way you are aware of the (correct) working of an access rule - -## Avoiding Injection - -Injection occurs when (user) input can be misused to influence the behavior of a system. Common cases are parameters for queries (to influence the results of database queries) or HTML with JavaScript contents (to influence browser behavior). - -When using Mendix-native components, there are no concerns about the possibility of injection. Queries (like XPath) are parametrized and therefore always escaped, making SQL-injection impossible. For the other way around, retrieved data shown in the user interface is escaped to the HTML format. - -When you are building an application, you may use [Mendix Marketplace](https://marketplace.mendix.com/) components and external interfaces. Remember that values which originate from user input or other systems should be escaped to avoid injection (and to ensure they are properly display). - -These are the common cases and best practices: - -* HTML content, usually derived from an HTML editor and displayed using an HTML viewer, format string, or an email client – these are the ways to avoid this abuse: - * Use the XSSSanitize action from the [CommunityCommons Function Library](/appstore/modules/community-commons-function-library/) module to strip malicious code from the entered HTML - * Display the value of an attribute as HTML or using the HTMLEncode function from the [Community Commons Function Library](/appstore/modules/community-commons-function-library/) module -* Database connections (for example, using the [Database Connector](/appstore/modules/database-connector/)), where user input is being used within constraints – these are the ways to avoid this abuse: - * Use prepared statements, which will cause the database-specific connector to take care of escaping the value - * Sanity-check your user input (for example, use a regular expression to check if your user input only contains alphanumeric characters, spaces, and dashes) - -## Applying Access Restrictions to Unnecessary Request Handlers{#request-handlers} - -A Mendix app offers various endpoints that can be used to obtain information about offered services. The paths used by these endpoints end in `-doc`. By default, access to these endpoints is disabled when deploying to a cloud node. - -Access restrictions can be configured within the Mendix Portal. They can be found in the **Environment details** of your cloud node. This is an example of this overview showing the default settings after deploying to a new environment: - -{{< figure src="/attachments/howto8/security/best-practices-security/default-access-restrictions.png" alt="Mendix Cloud Access Restrictions Overview" class="no-border" >}} - -Examples are the `ws-doc` or `rest-doc` endpoints that enumerate all the published web and REST services of the application. An attacker could use this information to discover possible areas to exploit. - -You can take the following preventative measures: - -* Disable unused endpoints within the Mendix Portal completely by applying a **deny all access** preset on them -* Apply IP filtering or client certificate authentication to restrict access - -Keep the following in mind: - -* If there are other app-specific request handlers that should have an access restriction applied, then click **New** to add them as additional paths -* The URLs of test and acceptance environments can easily be guessed; in order to take effective measures, the restrictions should be applied to these environments also - -## Applying Authentication on Services - -When publishing a web or REST service, you should consider whether this service should be consumable by everybody (anonymous) or by a limited set of users or systems. Whenever a limited set of users should be allowed, a Mendix (web service) user should be created for each consumer of this service. The option of creating (fine-grained instead of generic) users enables an application to do the following: - -* Identify which user caused a change in your application (traceability) -* Constrain access on the user (role) level -* Log the usage of your service - -Mendix offers the following options for providing authentication for your services: - -* User name and password validation, specified within Mendix Studio Pro (for details, see [Published Web Services](/refguide8/published-web-services/)) -* Client certificates and IP ranges, which are specified in Mendix Cloud – these can be found at the network tab of your node’s environment details as **Access Restriction Profiles** - -## Using the Encryption Module When Storing Sensitive Information - -Your application might require sensitive information that should be extra encrypted. These are some examples: - -* Connection information for consumed services (like credentials, service locations, or keys) -* Personal information (like bank account numbers or social security numbers) - -This data is defined within the domain model and stored within the database of your application. To minimize the impact of this information when it is leaked, Mendix recommends storing this data in a (symmetric) encrypted manner. The [Encryption](/appstore/modules/encryption/) module available from the Mendix Marketplace provides a way to encrypt this sensitive information in a database record based on an encryption key that is stored at the Mendix application server. - -## Using a Third-Party Identity Provider - -When developing an application, authentication is one of the basic considerations. Even though Mendix comes with a basic authentication mechanism, your application’s security is improved when authentication is delegated to an enterprise grade identity provider like ADFS. - -Mendix offers the [SAML](/appstore/modules/saml/) module that enables your application to be connected with these services. - -Your application can gain the following benefits from using an identity provider: - -* User management is centralized (for example within Active Directory), which simplifies the on- and off- boarding of new employees or changed roles -* The Mendix app does not contain (hashed) passwords -* Identity providers can add extra layers of security, like two-factor authentication -* Stronger password policies are applied -* The user experience is improved by facilitating single sign-on (SSO) - -## Applying a Strong Password Policy - -By default, Mendix forces a strong password policy. The same password policy that is configured in Mendix Studio Pro is also used for apps running in a hosted environment (for example, on test, acceptance, and production). - -It is very tempting to simplify the password constraints for development purposes (for example, making it possible to use a single character to login). However, Mendix recommends avoiding this approach so that deployments will continue to force a strong password policy. - -The password policy can be set by via the guidelines described in [Password Policy](/refguide8/password-policy/). - -## Renaming the Administrator User - -Each application requires power users who should be able to administer technical functions (like configuring SSO). By default, the user who has these capabilities is called **MxAdmin** and has the **Administrator** role. - -This information can be exploited by an attacker (for example, by trying to guess the password). Even though Mendix will block the user for about 5 minutes after three unsuccessful login attempts, renaming the default MxAdmin user is recommended. - -The user name of the administrator can be changed in 's **Project Security** settings on the **Administrator** tab. - -When deployed to Mendix Cloud, the information about the administrator user name and role is taken into account when using the **Change admin password** button on the environment. After changing the settings in and redeploying the application, a successful admin password change will trigger the creation of a user in the app with the new name and role. - -{{% alert color="info" %}} -At this point, the application does not automatically remove the user with the previous user name. Removing the old **MxAdmin** account has to be done manually. -{{% /alert %}} - -## Using SSL on Consumed Web Services Whenever Possible - -Most apps consume (web) services that could be located within an organization itself or at an external third party. When such a service is consumed by an application, your request crosses multiple networks and devices before it reaches its endpoint (the service). A potential attacker in between would be able to read and manipulate the conversation between the application and the service. - -By using an SSL connection and adding the public key of the endpoint within your application, you will ensure the following: - -* The conversation between you and the service has not been tampered with -* The conversation is not readable if it was ever intercepted -* The identity of your endpoint is confirmed - -There are several scenarios possible for protecting your outgoing connections using encryption. These depend on the infrastructure possibilities and protocols used. For more information, see [How to Secure Outgoing Connections from Your App](/developerportal/deploy/securing-outgoing-connections-from-your-application/). - -You can add individual certificates in your project’s settings in . Test, acceptance, and production environments require their certificates to be uploaded to Mendix Cloud (for more information, see [Certificates](/developerportal/deploy/certificates/)). - -## Adding HTTP Headers {#adding-http-header} - -HTTP headers can add an additional layer of security and help you detect certain attacks. For information on how to add HTTP headers, see the [HTTP Headers](/developerportal/deploy/environments-details/#http-headers) section in *Environment Details*. - -An example of an attack is when an application is embedded in an iframe. Applications that can be embedded within an iframe can be misused by attackers. By using an overlay, it could trick users into clicking buttons and make them perform actions within the application on their behalf without knowing it. This approach is called [clickjacking](https://www.owasp.org/index.php/Clickjacking). - -By sending a header to the user’s browser, it can block the use of the Mendix application within an iframe and avoid this type of attack. The header is set by default to block embedding within an iframe, but can be configured using [HTTP Headers](/developerportal/deploy/environments-details/#http-headers) in your node’s environment details within **Apps**. If you change this value, you will also need to ensure that *SameSite* cookies are set to the correct value. See [Iframes and Running Apps](/developerportal/deploy/running-in-iframe/) for more information. - -## Maintaining a High Level of Project Hygiene - -As an application grows in functionality, it also increases the chance of containing logic that could be exploitable for an attacker. Also, over time, vulnerabilities within logic can be discovered. Keeping your project hygiene at a high level will reduce the chances of a vulnerable application. - -To keep your project hygiene at a good level, perform the following steps: - -* Remove unused modules, widgets, and Java libraries -* Remove microflows that are not being used (these appear as warnings in Studio Pro) -* Avoid using components with known vulnerabilities (like Java or JavaScript libraries) - -A good source of known vulnerabilities is the [Common Vulnerabilities and Exposures website](https://cve.mitre.org/). - -## Configuring User Roles and Access - -Which users and roles are defined within an application is different per app and project. However, there are some key guidelines to keep in mind when validating the user security: - -* Anonymous access should be disabled if it has no function within the application - * Some applications have anonymous access enabled, solely to serve a custom login form – this can be replaced by modifying the default *login.html* within your theme (which will also help the user experience with an improved loading time) -* Roles managing other user roles should be as strict as possible (configured via **User management** within the user role options) -* The role of the app's administrator user (default **MxAdmin**) should only be able to create the actual administrative accounts (or configure SSO) - -## Scanning Uploaded Files for Malicious Content {#scanning-for-malicious-content} - -Security in Mendix does not include scanning files that end-users upload or download from your application for viruses and malware. - -To scan uploaded files for malicious content, do one of the following: - -* Create a custom module and configure the functionality yourself. -* Check available modules in the [Mendix Marketplace](https://marketplace.mendix.com/). For more information on how to use the Mendix Marketplace content, see [How to Use Marketplace Content](/appstore/use-content/). diff --git a/content/en/docs/howto8/security/create-a-secure-app.md b/content/en/docs/howto8/security/create-a-secure-app.md deleted file mode 100644 index 96a5ff2b1f3..00000000000 --- a/content/en/docs/howto8/security/create-a-secure-app.md +++ /dev/null @@ -1,289 +0,0 @@ ---- -title: "Create a Secure App" -url: /howto8/security/create-a-secure-app/ -weight: 10 ---- - -## Introduction - -Each application must have a proper security configuration in order to have its data secured. This how-to teaches you how to turn the security on and configure it. - -You will start with the configuration of user and module roles for access to pages and microflows, so we’ll turn on the prototype/demo security. Next you will deal with production security. - -This how-to teaches you how to do the following: - -* Configure prototype/demo security -* Configure production security - -## Prerequisites - -Before starting with this how-to, make sure you have completed the following prerequisites: - -* Know how to create a domain model (for details, see [How to Create a Basic Data Layer](/howto8/data-models/create-a-basic-data-layer/)) -* Know how to create overview and detail pages (for details, see [How to Create Your First Two Overview and Details Pages](/howto8/front-end/create-your-first-two-overview-and-detail-pages/)) -* Know how to create menu items (for details, see [How to Set Up the Navigation Structure](/howto8/general/setting-up-the-navigation-structure/)) -* Know how to add action buttons (for details, see [Button Widgets](/refguide8/button-widgets/)) - -## Preparing the Data Structure, GUI, and Example Data - -To see the results of this how-to, you must set up a test project with test data by following these steps: - -1. Create the following domain model: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581378.png" class="no-border" >}} - -2. Create overview and detail pages to manage objects of **Customer** and **Order** type. -3. Create menu items to access the **Customer** and **Order** overview pages. -4. Add a new microflow by right-clicking your module and selecting **Add** > **Microflow**: -5. Name the microflow *IVK_SetOrderToComplete*: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/8946808.png" class="no-border" >}} - -6. Save the new menu item by clicking **OK**. You should see an empty microflow like this: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/8946316.png" class="no-border" >}} - -7. Add an **Action** button to the toolbar of the orders overview: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/8946696.png" class="no-border" >}} - -8. Double-click the new button and in the button's properties editor, enter *Set Processing to Complete* for the **Caption**. -9. Set **On click** to **Call a microflow**, and then select the **IVK_SetOrderToComplete** microflow you just created: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/8946804.png" class="no-border" >}} - -10. Add the following customer data to your app: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581374.png" class="no-border" >}} - -11. Add the following order data to your app: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581373.png" class="no-border" >}} - -## Setting the Security Level to Prototype/Demo {#prototype} - -In this part of the how-to, you will learn how to configure the security at the prototype/demo level. Be aware that this level of security is only applicable for development/demo purposes. This level is available for the quick development of demo applications. It simulates security without the more complex configuration of data access. When deploying to Mendix Cloud, production security is mandatory. - -To set the security level to prototype/demo, follow these steps: - -1. Open the project **Security**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581561.png" class="no-border" >}} - - This will open the **Project Security** properties editor. -2. Switch the **Security level** to **Prototype / demo**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581559.png" class="no-border" >}} - -3. Go to the **Administrator** tab and set the primary administrator **Password**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581565.png" class="no-border" >}} - -### Creating Module Roles Within a Module - -You have added one or more modules while the security was turned off, so there is currently no security configured for those modules. Now that security is turned on, you have to configure it from scratch. Access to a module is managed using module roles. You will now add these. - -To create module roles within a module, follow these steps: - -1. Open the module **Security** of the **MyFirstModule** module: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581558.png" class="no-border" >}} - -2. On the **Module Security Type 'Security'** properties editor, click **New**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581556.png" class="no-border" >}} - -3. In the **New Module Role** dialog box, enter *Administrator* for the module role **Name**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581555.png" class="no-border" >}} - -4. Create the **User** module role: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581554.png" class="no-border" >}} - -### Connecting the User Roles to Module Roles - -The two module roles that have been created should be assigned to a user role. When an end-user has a specific user role, the end-user has access to the data, forms, and microflows according to the assigned module roles of that user role: - -1. Open the project **Security.** -2. On the **Project Security** dialog box, go to the **User roles** tab and double-click the **Administrator** user role: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581553.png" class="no-border" >}} - -3. In the **Module roles** section of the **User Role 'Administrator'** properties editor, click **Edit**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581552.png" class="no-border" >}} - -4. In the **Select Module Roles** pop-up window, select the **Administrator** module role for all the modules: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581550.png" class="no-border" >}} - -5. Repeat steps 2–4 for the **User** user role: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581548.png" class="no-border" >}} - -### Configuring the Page and Microflow Access of a Module - -To configure the page and microflow access of a module, follow these steps: - -1. Open the module **Security** of the **MyFirstModule** module: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581558.png" class="no-border" >}} - -2. Open the **Page access** tab: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581547.png" class="no-border" >}} - -3. Check the pages according to the example shown here: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581546.png" class="no-border" >}} - -4. On the **Microflow access** tab, check the microflows according to the example shown here: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581544.png" class="no-border" >}} - -5. Deploy the application. -6. Create new users with different roles. -7. Sign out and back in with these users (add a **Sign out** button to your app if necessary). -8. Test the differences in your application. - -## Setting the Security Level to Production {#production} - -In this section of the how-to, you will configure the security at the production level. At this level, all security settings must be configured. In addition to prototype/demo security, you have to configure the entity (data) access. Production security is mandatory when deploying to Mendix Cloud. - -To set the security level to production, follow these steps: - -1. Open the project **Security**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581561.png" class="no-border" >}} - -2. On the **Project Security** dialog box, switch the security level to **Production**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581543.png" class="no-border" >}} - -### Configuring Form Entity Access - -To configure the form entity access, follow these steps: - -1. Open the **Security** module of the **MyFirstModule** module: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581558.png" class="no-border" >}} - -2. On the **Module Security Type 'Security'** dialog box, open the **Entity Access** tab: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581541.png" class="no-border" >}} - -3. Click **New** to create access rules for the **Role Administrator** module. Make sure you allow an administrator to read/write all and restrict some of the user's read/write rights so that you can clearly see the difference in these roles. - -### Creating Access Rules for the Administrator Module Role - -You will now create access rules for the Administrator module role. Since this role represents an administrator, let’s assume that they are allowed to create, delete, read, and write everything, so you can create the rules in a quick batch. - -To create access roles for the Administrator module role, follow these steps: - -1. Select all the entities and click **OK**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581539.png" class="no-border" >}} - -2. Set up the rule configuration: - * **Rule applies to the following module roles**: **Administrator** - * **Allow creating new objects**: true - * **Allow deleting existing objects**: true - * **Member read and write rights**: **Read, Write** - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581572.png" class="no-border" >}} - -3. Click **OK**. - -{{% alert color="warning" %}} -A separate access rule will be created for all entities when the module role is set to Administrator. It is possible to adjust each rule individually later. -{{% /alert %}} - -### Creating Access Rules for the User Module Role - -Next you have to create access rules for the User module role. Since this role represents a user with limited access, let’s assume they are only allowed to read most data and is allowed to write some of the Order data. This means you have to configure all the access rules individually. - -To create access roles for the User module role, follow these steps: - -1. On the **Module Security Type 'Security"'** dialog box, click **New** to create a new access rule for the User module role: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581538.png" class="no-border" >}} - -2. Select the **Customer** entity and click **OK**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581536.png" class="no-border" >}} - -3. Set up the rule configuration: - * **Rule applies to the following module roles**: **User** - * **Allow creating new objects**: false - * **Allow deleting existing objects**: false - * **Default rights for new members**: **Read** - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581535.png" class="no-border" >}} - -4. Adjust the rule for the **Order** and set up the rule configuration: - * **Rule applies to the following module roles**: **User** - * **Allow creating new objects**: true - * **Allow deleting existing objects**: false - * **Default rights for new members**: Read, Write - * **Access rights** for each member: **Read, Write** - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581534.png" class="no-border" >}} - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581533.png" class="no-border" >}} - -5. Deploy the application. -6. Sign in with the different users and test the differences in your application. - -## Defining the Access Rules on the Order Entity Using XPath - -In the previous section you set some access rules on your domain model. In this section you will define the access rules on the Order entity so that orders can only be viewed by a user if the payment status of the order is set to open. You will do this by adding an XPath constraint to the Order entity for the User module role. - -An XPath constraint can be used to constrain the set of objects to which the access rule applies. If the XPath constraint is empty, the rule applies to all the objects of the entity. For more information, see [XPath Constraints](/refguide8/xpath-constraints/) in the *Studio Pro Guide*. - -### Adding an Account with the User User Role - -1. Click the **Accounts** in the **Administration** menu: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581532.png" class="no-border" >}} - -2. On the **Accounts** screen, click **New user**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581530.png" class="no-border" >}} - -3. Add an account with a user role named **User**: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581528.png" class="no-border" >}} - -4. Click **Save**. - -### Set the Entity Access to Open Order Status - -1. Double-click the **Order** entity: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581527.png" class="no-border" >}} - -2. On the **Properties of Entity 'MyFirstModule.Order'** editor, open the **Access rules** tab: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581525.png" class="no-border" >}} - -3. Double-click the **User** module role to open the **Edit Access Rule of Entity 'MyFirstModule.Order'** editor and select the **XPath constraint** tab: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581523.png" class="no-border" >}} - -4. To constrain the access of the financial administrator to only the open orders, add the following XPath statement: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581522.png" class="no-border" >}} - -5. Click **OK**. The properties editor of your Order entity should look like this: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581521.png" class="no-border" >}} - -6. Re-deploy your application. -7. If you sign in with the Test User account, you will see that only orders with the **Order status** of **Open** are shown in the overview: - - {{< figure src="/attachments/howto8/security/create-a-secure-app/18581520.png" class="no-border" >}} - -## Read More - -* [Set Up Anonymous User Security](/howto8/security/set-up-anonymous-user-security/) diff --git a/content/en/docs/howto8/security/set-up-anonymous-user-security.md b/content/en/docs/howto8/security/set-up-anonymous-user-security.md deleted file mode 100644 index b4acca6f916..00000000000 --- a/content/en/docs/howto8/security/set-up-anonymous-user-security.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Set Up Anonymous User Security" -url: /howto8/security/set-up-anonymous-user-security/ -weight: 30 ---- - -## Introduction - -When setting up anonymous access for your application, you should be careful about where you give access to users. There are some guidelines for this so that you don't make your entire application accessible to the public. - -When creating an anonymous user role, always make sure you give it as little access as possible. Accordingly, you never want to re-use module rules from your named user accounts. It may be faster to reuse module rules, but this makes it much easier to give an anonymous user too much access to information in your application. When you are using anonymous users, any changes made to your object can never be traced back to the actual user, since the user was anonymous and no longer exists. - -**After using this how-to, you will know how to do the following:** - -* Set access to a non-persistable object -* Give anonymous users read and write access - -## Non-Persistable Objects - -When you set access to a non-persistable object, the security rules you specify should be whatever you functionally need. Non-persistable objects only live in the session cache from the user that created the object; therefore, an anonymous user is never able to access any information that wasn't created specifically for or by them. However, it is a completely different situation for a persistable object. - -## Write Access - -If you give an anonymous user write access on any field in the application, you must specify instance access as well. An anonymous user is hardly ever allowed to change every single record of a certain object type. The anonymous user is usually only allowed to change the record they just created; therefore, you will want to specify this access rule: `[System.Owner='[%CurrentUser%]']` That way, the anonymous user can only change the records they just created during their session. - -## Read Access - -If an anonymous user needs to have access to certain primary data tables or needs the name of a user in an overview, the anonymous user needs read access on that entity. However, you should always limit this access. If the user doesn't need to have access to all fields, do not give it to them. If you see an anonymous user with full read access, always confirm that they cannot work with less access. - -## Security Review - -When going over an application and reviewing an anonymous user, there are three things that most often trigger a red flag (indicating the application is not secure): - -* An anonymous user role that reuses the module roles from the regular application user -* An anonymous module role that has write access but no instance access XPath constraint -* An anonymous module role that has full read access on an entity - -Whenever you see any of these situations, you should carefully consider if these parameters are necessary for what you want to achieve. - -**Always be aware that limiting data in pages does NOT make your application secure.** The only way to make an application secure is by specifying access rules on all of your entities and limiting the instances of objects that you are allowed to see. - -Any user can talk directly to the API by downloading a tool that can post messages to a URL and trying to send JSON queries to the platform. This simulates communication between the browser and the server, because the server doesn't care who sends the messages as long as they match what is allowed within the session. - -## Best Practice - -If you have anonymous access, you need to limit the access to as few entities as possible and never give full read access to all attributes if it is just for selecting items. For example, if an anonymous user is allowed to see a project name, then only give read access to the project name and not the full entity. - -If you need to give an anonymous user access to change an object ALWAYS apply instance access as well. An anonymous user should NEVER have write access on all records in an entity. - -Limiting the navigation or page display is not the same thing as security. All data can be accessed by talking directly to the Platform APIs, and anything that is visible according to the security model is accessible by sending the correct messages to the server. Limiting data in the UI does not mean that it cannot be accessed. Only instance access rules guarantee what you can and cannot do. - -## Read More - -* [Creating a Secure App](/howto8/security/create-a-secure-app/) diff --git a/content/en/docs/howto8/testing/_index.md b/content/en/docs/howto8/testing/_index.md deleted file mode 100644 index f85d25fcc0e..00000000000 --- a/content/en/docs/howto8/testing/_index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "Testing" -url: /howto8/testing/ -weight: 100 -no_list: false -description_list: true ---- - -## Introduction - -Testing is a vital component when creating a Mendix application. In this category, you can find all the test-related how-tos and blogs written by experienced Mendix professionals. - -## Other References - -* [Three Tools to Test Your Mendix Application](https://www.mendix.com/blog/three-tools-to-test-your-mendix-application/) -* [8 Lightweight Quality Assurance Practices](https://www.mendix.com/blog/8-lightweight-quality-assurance-practices/) -* [The Quality Assurance Mindset in Mendix](https://www.youtube.com/watch?v=hpJp-tAUn-g) - -## Documents in This Category diff --git a/content/en/docs/howto8/testing/create-automated-tests-with-testng.md b/content/en/docs/howto8/testing/create-automated-tests-with-testng.md deleted file mode 100644 index 3ae85f57db6..00000000000 --- a/content/en/docs/howto8/testing/create-automated-tests-with-testng.md +++ /dev/null @@ -1,494 +0,0 @@ ---- -title: "Create Automated Tests with TestNG" -url: /howto8/testing/create-automated-tests-with-testng/ -weight: 50 ---- - -## Introduction - -Automated tests can be created with different tools, depending on the type of tests. Integration tests can be created with [SoapUI](/howto8/integration/testing-web-services-using-soapui/), unit tests with the [Unit Testing](/howto8/testing/testing-microflows-using-the-unittesting-module/) module, and UI tests with [Selenium IDE](/howto8/testing/testing-mendix-applications-using-selenium-ide/). With Selenium IDE you can create scripts to aid in automation-aided exploratory testing. If you’re looking to create robust, browser-based tests, you should look into using a testing framework with Selenium. - -TestNG is a Java testing framework that can be used to drive Selenium. In this how-to you will learn how to create an automated test with TestNG. - -This how-to teaches you how to do the following: - -* Create TestNG test files -* Run automated tests with TestNG -* Generate reports with TestNG - -## Prerequisites - -Before starting with this how-to, make sure you have completed the following prerequisites: - -* Download and install [Eclipse](https://www.eclipse.org/downloads/) -* Download the [Selenium Client and WebDriver](https://www.selenium.dev/downloads/) for Java - -{{% alert color="warning" %}} -This how-to uses the Company Expenses app template starting in the [Add the Third Test Method](#third) section for an example scenario. However, this app template is no longer platform-supported by Mendix. Therefore, sections using this app template can only be used as reference and not as sections that can be completed step-by-step. -{{% /alert %}} - -## Creating a Java Project - -In this chapter you will install the TestNG plug-in and create a Java project in Eclipse including the TestNG and Selenium libraries: - -1. Open Eclipse. -2. Follow the instructions in the **Eclipse plug-in** > **Install from update site** section in [Downloading TestNG](https://testng.org/doc/download.html). -3. Restart Eclipse for changes to take effect. -4. Select **File** > **New** > **Java Project**. -5. Enter *MyFirstTestNGProject* for the **Project name** and click **Next**. -6. Select the **Libraries** tab and click **Add Library**. -7. Select **TestNG** and click **Next**. -8. Click **Finish** to set the default TestNG library to this project. -9. Click **Add External JARs...** and navigate to where you saved the Selenium JAR files. -10. Add all the JAR files inside the **selenium-[version]** and **libs** folders: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580403.png" class="no-border" >}} - -11. Click **Finish** to create the Java project. **MyFirstTestNGProject** will be shown in the **Package Explorer**: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580401.png" class="no-border" >}} - -You are now done setting up your project! - -## Create a TestNG File - -To create a new TestNG file, follow these steps: - -1. Right-click the **src** folder and select **New** > **Other...**: -2. Select **TestNG class** and then click **Next**: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580398.png" class="no-border" >}} - -3. Click **Browse...** to select a source folder, select **MyFirstTestNGProject** > **src**, and click **OK**. -4. Enter the following information: - * **Package name**: *myfirsttestngpackage* - * **Class name**: *MyFirstTestNGFile* - * **@BeforeTest**: true - * **@AfterTest**: true - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580393.png" class="no-border" >}} - -5. Click **Finish**. The template for your first TestNG file will be created automatically: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580392.png" class="no-border" >}} - - The `@Test` annotation is used to state that the method under it is a test case. In this case, the method `f` is a test case. The `@BeforeTest` annotation is used to state that the method under it will be executed before the first test case. The `@AfterTest` annotation is used to state that the method under it will be executed after the last test case. - -## Creating a Test Case - -Let's now code your test case. - -### Add a WebDriver - -To create a variable to be used for the WebDriver, follow these steps: - -1. Search for the following: - - ```java - public class MyFirstTestNGFile { - ``` - -2. Add the code below on the next line. This will create a `driver` variable of the WebDriver type: - - ```java - public WebDriver driver; - ``` - -3. Press Ctrl + Shift + O to organize the imports. This will import the missing statements and remove the unused import statements. The following statement will be imported: - - ```java - import org.openqa.selenium.WebDriver; - ``` - -### Add a BeforeTest Method - -The `@BeforeTest` annotation is used to state that the method under it will be executed before the first test case. Before the first test case, open the Firefox browser by following these steps: - -1. Change the following code: - - ```java - @BeforeTest - public void beforeTest() { - } - ``` - - into: - - ```java - @BeforeTest - public void beforeTest() { - driver = new FirefoxDriver(); - } - ``` - - This creates a new instance of the Firefox driver and opens the Firefox browser. - -2. Press Ctrl + Shift + O. The following statement will be imported: - - ```java - import org.openqa.selenium.firefox.FirefoxDriver; - ``` - -### Add an AfterTest Method - -The `@AfterTest` annotation is used to state that the method under it will be executed after the last test case. After the last test case, close the browser by changing the following code: - -```java -@AfterTest -public void afterTest() { -} -``` - -into: - -```java -@AfterTest -public void afterTest() { -driver.close(); -} -``` - -This will close the Firefox browser. - -### Add the First Test Method - -To add the first test method, open a URL in the browser, and then change the following code: - -```java -@Test -public void f() { -} -``` - -into: - -```java -@Test(priority=1) -public void openApp() { -driver.get("http://localhost:8080/index.html"); -} -``` - -This test method will open the URL `http://localhost:8080/index.html` in the Firefox browser. By default, the methods annotated by `@Test` are executed alphabetically. You can use parameters to modify the annotation's function. The `priority` parameter can be used to execute the methods in a different order. TestNG will execute the `@Test` annotation with the lowest priority value up to the largest. - -### Add the Second Test Method - -Now that you are on the login window, you will want to sign in. To add the second test method, follow these steps: - -1. Open Firefox and go to `http://localhost:8080/index.html`. -2. Use the developer tools to inspect the element. -3. Click the **User name** input field. The ID of the this field is *usernameInput*. The CSS selector of an ID is a hashtag (`#`) + the name of the ID. For the **User name** field, this will be *#usernameInput*. The same principle is used for the other steps. The CSS selector *#usernameInput* is unique. There is one matching node: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580373.png" class="no-border" >}} - -4. Repeat steps 5–6 for the **Password** input field and the **Sign in** button: - - Element | CSS Selector - --- | --- - **Password** input field | `#passwordInput` - **Sign in** button | `#loginButton` - -5. Add a new test method called `login`. Use the following code: - - ```java - @Test(priority=2) - public void login() { - driver.findElement(By.cssSelector("#usernameInput")).sendKeys("MxAdmin"); - driver.findElement(By.cssSelector("#passwordInput")).sendKeys("1"); - driver.findElement(By.cssSelector("#loginButton")).click(); - } - ``` - -This test method contains the following test steps: - -1. Enter *MxAdmin* as the user name. -2. Enter *1* as the password. -3. Click the login button. - -### Add the Third Test Method {#third} - -To add the third test method, follow these steps: - -1. Open your app and in the **Project Explorer**, open the **ProgramDetail** page. -2. Select the **Expenses** tab: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580389.png" class="no-border" >}} - - The name of the **Expenses** tab is **tabPage4**. Every element will automatically get the CSS class `mx-name-[Name]`, so the expenses tab will get the CSS class `mx-name-tabPage4` when the app is running. - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580388.png" class="no-border" >}} - -3. Go back to **Eclipse**. -4. Add a new test method called `openExpensesTab`. Use the following code: - - ```java - @Test(priority=3) - public void openExpensesTab() { - WebDriverWait wait = new WebDriverWait(driver, 10); - wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector(".mx-name-tabPage4"))).click(); - } - ``` - - This test method calls `ExpectedCondition` every 500 milliseconds until it either returns successfully or 10 seconds have passed. When 10 seconds have passed and the element is not located, a TimeoutException will be thrown. If the element is located within 10 seconds, the method will click the element with class name `mx-name-tabPage4`. The class of the expenses tab is `mx-name-tabPage4`. The CSS selector of a class is a dot (`.`) + the class name, so for the expenses tab, it will be `.mx-name-tabPage4`. - -### Add the Fourth Test Method - -Now that you are on the **Expenses** tab, you will want to create a new expense. To add the fourth test method, follow these steps: - -1. Open Studio Pro and then open the **Desktop_AdminMenu** page. -2. Select the **New Expense** button: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580387.png" class="no-border" >}} - - The name of the **New Expense** button is `newButton3`, so the button will have the `mx-name-newButton3` CSS class: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580386.png" class="no-border" >}} - -3. Open the **Desktop_Expense_NewEdit_Admin** page. -4. Find the names of the following elements (as you did in step 3): - - | Element | Name | - | --- | --- | - | Amount field | `textBox6` | - | Description dropdown | `referenceSelector1` | - | Save button | `saveButton1` | - - {{% alert color="info" %}}The name of an element in your app may be different than the name shown in the Name column. In step 7, use the name of the element of your app.{{% /alert %}} - -5. Go back to **Eclipse**. -6. Add a new test method called `createExpense`. Use the following code: - - ```java - @Test(priority=4) - public void createExpense() { - driver.findElement(By.cssSelector(".mx-name-newButton3")).click(); - driver.findElement(By.cssSelector(".mx-window-active .mx-name-textBox6 input")).clear(); - driver.findElement(By.cssSelector(".mx-window-active .mx-name-textBox6 input")).sendKeys("15.00"); - driver.findElement(By.cssSelector(".mx-window-active .mx-name-referenceSelector1 option:nth-child(2)")).click(); - driver.findElement(By.cssSelector(".mx-window-active .mx-name-saveButton1")).click(); - } - ``` - - This test method contains the following test steps: - - 1. Click **New Expense**. - 2. Clear the **Amount** field. - 3. Enter *15.00* in the **Amount** field. - 4. Select the second option from the **Description** drop-down menu. - 5. Click **Save**. - - A pop-up window will be shown after clicking **New Expense** (`.mx-name-newButton3`). To be sure the element of the active page is retrieved (which in this case is the pop-up), you need to add `.mx-window-active` to the CSS selector of the elements in the pop-up. - - For every input field, you need to add `input` at the end of the CSS selector. - - The default value of the amount field is 0.00. To enter a new value, you first need to clear the field. - - The reference selector has six options; empty, Accomodation, Meal, Other, Supplies, Transport. To select Accomodation (the second option), you need to add `option:nth-child(2)` at the end of the CSS selector. - -### Add the Fifth Test Method - -After you have created an expense, you will want to sign out. To add the fifth test method, follow these steps: - -1. Open Studio Pro and then open the **Desktop_MyInfo** snippet. -2. Find the name of the following element: - - | Element | Name | - | --- | --- | - | Sign out button | `signOutButton1` | - -3. Add a new test method called `signOut`. Use the following code: - - ```java - @Test(priority=5) - public void signOut() { - driver.findElement(By.cssSelector(".mx-name-signOutButton1")).click(); - } - ``` - - This test method will click the element with the `mx-name-signOutButton1` class name. - -## Run the Test {#RuntheTest} - -You are now ready to run the test. To run the test, follow these steps: - -1. Right-click the **MyFirstTestNGProject** folder. -2. Select **Run as** > **TestNG Test**: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580385.png" class="no-border" >}} - - The results of the test will be shown in the console window and in the TestNG results window: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580384.png" class="no-border" >}} - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580383.png" class="no-border" >}} - -## Test Report - -TestNG generates reports in the HTML format. To test the report, follow these steps: - -1. Right-click the **MyFirstTestNGProject** folder and select **Refresh**. A test-output folder will be created: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580382.png" class="no-border" >}} - -2. Open the **test-output** folder. -3. Right-click the **index.html** file. -4. Select **Open with** > **Web Browser**. The report will look like this: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580381.png" class="no-border" >}} - -5. Click **(show)**. The test methods are shown alphabetically: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580378.png" class="no-border" >}} - -6. Click the **Chronological** view. An overview with the methods in chronological order will be shown: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580380.png" class="no-border" >}} - -## Creating a Test Suite - -When you run your test as you did in [Run the Test](#RuntheTest), a test suite is created automatically. This test suite contains all testNG files that can be found in the project. But what if you only want to run specific tests? Than you need to create a test suite yourself. - -1. Right-click the **src** folder and select **New** > **Other**. -2. Open the **XML** folder and select **XML File**: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580377.png" class="no-border" >}} - -3. Click **Next**. -4. Change the file name to *MyFirstTestSuite.xml*. -5. Click **Finish** to create the XML file: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580376.png" class="no-border" >}} - -6. Click the **Source** tab: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580375.png" class="no-border" >}} - -7. Change the following code: - - ```xml - - ``` - - into - - ```xml - - - - - - - - - ``` - - This will create the new test suite `MyFirstTestSuite`. The test suite contain one test: `Test1`. The test contain one testNG file, `myfirsttestngpackage.MyFirstTestNGFile`. - -8. Right-click the **MyFirstTestSuite.xml** file and select **Run as** > **1 TestNG Suite**. - -Well done! You created your first TestNG Suite! - -## Run Your Test Suite on Multiple Browsers Using @Parameters - -The test you created is now run on Firefox only. If you want to make sure the functionality works as expected in other browsers, you need to perform multi-browser testing. With TestNG it is very easy to perform the same test on different browsers. - -1. Download the ChromeDriver here: [https://sites.google.com/a/chromium.org/chromedriver/downloads](https://sites.google.com/a/chromium.org/chromedriver/downloads). -2. Configure the IE Driver here: [https://www.selenium.dev/documentation/ie_driver_server/#installing](https://www.selenium.dev/documentation/ie_driver_server/#installing) -3. In Eclipse, open **MyFirstTestNGFile** and change the following code: - - ```java - @BeforeTest - public void beforeTest() { - driver = new FirefoxDriver(); - } - ``` - - into: - - ```java - @Parameters("browser") - @BeforeTest - public void beforeTest(String browser) { - if(browser.equalsIgnoreCase("chrome")){ - System.setProperty("webdriver.chrome.driver", "C://Selenium/chromedriver.exe"); - driver = new ChromeDriver(); - } - else if(browser.equalsIgnoreCase("ie")){ - System.setProperty("webdriver.ie.driver", "C://Selenium/IEDriverServer.exe"); - driver = new InternetExplorerDriver(); - } - else{ - driver = new FirefoxDriver(); - } - } - ``` - - `@Parameters` is used to insert a parameter (in this case `browser`) from the test suite XML. If the browser parameter is `chrome`, a Chrome driver will start. - - In this section, *chromedriver.exe* is stored in the *C://Selenium* folder. Be sure to use the right path in this code. - -4. Press Ctrl + Shift + O , and the following statements will be imported: - - ```java - import org.openqa.selenium.chrome.ChromeDriver; - import org.openqa.selenium.ie.InternetExplorerDriver; - import org.testng.annotations.Parameters; - ``` - -5. Open **MyFirstTestSuite** and change the following code - - ```xml - - - - - - - - - ``` - - into: - - ```xml - - - - - - - - - - - - - - - - - - - - - - ``` - - The first test (called `ChromeTest`) has the browser parameter `chrome`. This parameter will be used in the `@BeforeTest` method in MyFirstTestNGFile. - -6. Right-click the **MyFirstTestSuite.xml** file and select **Run as** > **TestNG Suite**: - - {{< figure src="/attachments/howto8/testing/create-automated-tests-with-testng/18580372.png" class="no-border" >}} - -Well done! You created your first automated cross-browser test with TestNG! - -Now you know how to create a TestNG test file, how to create a test suite and how to run the automated test(s) on multiple browsers. - -Happy testing! - -## Read More - -* [Test Mendix Applications Using Selenium IDE](/howto8/testing/testing-mendix-applications-using-selenium-ide/) -* [Test Microflows Using the Unit Testing Module](/howto8/testing/testing-microflows-using-the-unittesting-module/) diff --git a/content/en/docs/howto8/testing/testing-mendix-applications-using-selenium-ide.md b/content/en/docs/howto8/testing/testing-mendix-applications-using-selenium-ide.md deleted file mode 100644 index 6e1096341c2..00000000000 --- a/content/en/docs/howto8/testing/testing-mendix-applications-using-selenium-ide.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: "Test Mendix Apps Using Selenium IDE" -url: /howto8/testing/testing-mendix-applications-using-selenium-ide/ -weight: 40 ---- - -## Introduction - -Selenium IDE is a Firefox plugin that records and plays back user interactions with the browser. - -**After using this how-to, you will know how to do the following:** - -* Record a simple test scripts with Selenium IDE -* Find unique CSS selectors - -## Prerequisites - -This how-to teaches you how to do the following: - -* Download and install [Firefox](https://www.mozilla.org/nl/firefox/new/) -* Download and install [Selenium IDE](https://addons.mozilla.org/en-US/firefox/addon/selenium-ide/) (when Selenium IDE is installed, it is then available as a Firefox plugin) - -These are the software versions used in this how-to: - -| Software | Version Used in This How-To | -| --- | --- | -| Firefox | 67.0.1 | -| Selenium IDE | 3.8.1 | - -{{% alert color="warning" %}} -All images, names, and steps in this how-to are based on these versions. When using other versions, the images and/or names on your screen may be different than what is used in this how-to. -{{% /alert %}} - -{{% alert color="warning" %}} -This how-to uses the Company Expenses app template for an example scenario. However, this app template is no longer platform-supported by Mendix. Therefore, sections using this app template can only be used as reference and not as sections that can be completed step-by-step. -{{% /alert %}} - -## Installing and Running the Company Expenses App - -Follow these steps to install and run the Company Expenses app: - -1. Open Mendix Studio Pro. -2. Click the Marketplace icon in the top toolbar: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/app-store.png" class="no-border" >}} - -3. Search for *Company Expenses*, then select **Company Expenses**: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/company-ex.png" class="no-border" >}} - -4. Click **Download** and then **OK**. This will open the Company Expenses app in Studio Pro. - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/download.png" class="no-border" >}} - -5. Click **Run Locally**, then **View**. - -## Create Your First Automated Test - -To create an automated test by using the record button in Selenium IDE, follow these steps: - -1. Open **Firefox** and click the **Selenium IDE** icon in the browser toolbar: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/icon.png" class="no-border" >}} - -2. Select **Record a new test in a new project**: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/sel-menu.png" class="no-border" >}} - -3. Enter a name for your new Selenium project (for example, *CompanyExpenses*). -4. Enter the URL for your Company Expenses app's login screen (`http://localhost:8080/login.html`), then click **START RECORDING**. This will open up your app in a new browser window. The Selenium IDE is now recording. -5. Sign in with default [administrator credentials](/refguide8/administrator/#administrator-properties): - * **User name**: MxAdmin - * **Password**: 1 - -6. After you logged in, click **Sign out** on the right side of the app: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/sign-out.png" class="no-border" >}} - -7. In the Selenium IDE, click the record icon to stop recording: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/record.png" class="no-border" >}} - -8. Enter a name for your new test, (for example, *Test1*). The Selenium IDE should now look like this: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/after-test.png" class="no-border" >}} - -9. Now that you have a test, click the **Run current test** icon: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/run-current-test.png" class="no-border" >}} - - Every passed test step will be marked green: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/green-test.png" class="no-border" >}} - -## Locating and Changing a Test Target - -It is possible that you will need to edit your Selenium IDE test script before you can run it regularly. This may happen because, for example, HTML tag IDs are generated dynamically and will be different with each run of the same page. - -When necessary, you will need to find the right locators in order to tell Selenium IDE the GUI targets (for example, buttons, text boxes, and data grids) on which it needs to operate. To make it easier to create a locator for Mendix elements, `mx-name` is added to the class of an element. If you change the position of an element in a document, there is thus no need to rewrite the script. - -In this example scenario, a running test has failed on the target `id=mxui_widget_Wrapper_23`: - -{{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/fail.png" class="no-border" >}} - -The element with this target does not exist on the page for Selenium IDE, because the number in the ID is not always the same. You need to find another target selector for the same element that Selenium IDE will pick up. Mendix uses CSS classes to identify page content like widgets and pop-up windows, so you can use these classes in Selenium IDE to manipulate pages and verify data. - -A widget can be given a name in Mendix Studio Pro, and this name will appear in the HTML document as a class name prefixed by `mx-name-`. For instance, a grid named `EmployeeGrid` will get the CSS class `mx-name-EmployeeGrid`. This is true for all Mendix widgets. - -In this example scenario, you need to do the following: - -1. Open the page in Studio Pro that corresponds to where the Selenium IDE test failed. -2. Highlight the element where the Selenium IDE test failed. -3. The **Name** property for the **User name** field is **textBox10**. Every Mendix element automatically gets the CSS class `mx-name-[Name]`, so note that this field will have the CSS class `mx-name-textBox10`. - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/name.png" class="no-border" >}} - -4. Open the developer tools for your browser (with the app still open to where the Selenium IDE test failed) and search for `mx-name-textBox10`. There is a matching node, so you have now verified a unique selector for the **User name** field. - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/inspector.png" class="no-border" >}} - -5. In Selenium IDE, change the **Target** `id=mxui_widget_Wrapper_23` into `css=.mx-name-textBox6`: - - {{< figure src="/attachments/howto8/testing/testing-mendix-applications-using-selenium-ide/change.png" class="no-border" >}} - -6. Click the **Run current test** icon to see if your test passes. - -## Read More - -* [Automated Tests with TestNG](/howto8/testing/create-automated-tests-with-testng/) -* [Test Microflows Using the Unit Testing Module](/howto8/testing/testing-microflows-using-the-unittesting-module/) -* [Find the Root Cause of Runtime Errors](/howto8/monitoring-troubleshooting/finding-the-root-cause-of-runtime-errors/) -* [Clear Warning Messages in Mendix](/howto8/monitoring-troubleshooting/clear-warning-messages/) -* [Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/) -* [Monitor Mendix Using JMX](/howto8/monitoring-troubleshooting/monitoring-mendix-using-jmx/) - -Learn more about this topic using the following helpful link: - -* [Selenium IDE Documentation](https://www.selenium.dev/selenium-ide/docs/en/introduction/getting-started) diff --git a/content/en/docs/howto8/testing/testing-microflows-using-the-unittesting-module.md b/content/en/docs/howto8/testing/testing-microflows-using-the-unittesting-module.md deleted file mode 100644 index dab35dc180c..00000000000 --- a/content/en/docs/howto8/testing/testing-microflows-using-the-unittesting-module.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: "Test Microflows Using the Unit Testing Module" -linktitle: "Test Microflows Using Unit Test Module" -url: /howto8/testing/testing-microflows-using-the-unittesting-module/ -weight: 10 ---- - -## Introduction - -To smarten up your app with business logic you can use microflows. To verify that your microflow works as expected you can create unit tests using the Unit Testing module. The Unit Testing module provides an easy to use interface to manage and run unit tests. The module supports unit tests that are created using microflows and unit tests that are created using JUnit. - -This how-to teaches you how to do the following: - -* Set up the Unit Testing module -* Create a microflow unit test - -## Preparation - -Before you can start with this how-to, make sure you have completed the following prerequisites: - -* Download [Mendix Studio Pro](https://marketplace.mendix.com/link/studiopro/) -* Review the Marketplace components used in this how-to: - - | Component | Version Used in This How-to | - | --- | --- | - | [Unit Testing](/appstore/modules/unit-testing/) | 8.0.0 | - | [Community Commons Function Library](/appstore/modules/community-commons-function-library/) | 8.1.0 | - | [Object Handling](/appstore/modules/object-handling/) | 3.0.0 | - - {{% alert color="warning" %}}All the images, names, and steps in this how-to are based on the Marketplace component versions listed above. When using later versions of this content, images and/or names on your screen may be different than what is used in this how-to.{{% /alert %}} - -## The Unit Testing Module - -In this chapter you will set up the unit testing module and run the example tests. - -1. Create a new project. -2. Download the [Unit Testing](/appstore/modules/unit-testing/) module. -3. Download the [Community Commons Function Library](/appstore/modules/community-commons-function-library/) module. -4. Download the [Object Handling](/appstore/modules/object-handling/) module. -5. Open the **Settings** of the project: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580371.png" class="no-border" >}} - -6. Click the **Runtime** tab. -7. Click the **Select** button to select an **After startup** microflow: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580370.png" class="no-border" >}} - -8. Select the **Startup** microflow from **Unit Testing** > **USE ME** > **Microflows**: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580369.png" class="no-border" >}} - -9. Click **OK**. -10. Open the **Navigation** of the project. -11. Click **New item** to add a new item to the menu. -12. Enter *UnitTestOverview* in the **Caption** field. -13. Select **Call a microflow** for the **On click** action, and then select the **UnitTestOverview** microflow: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580363.png" class="no-border" >}} - -14. Click **OK**: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580362.png" class="no-border" >}} - -15. Run the project locally. -16. Go to `http://localhost:8080/index.html`. -17. Click **UnitTestOverview** in the navigation. - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580341.png" class="no-border" >}} - - On the left side of the page, two buttons are shown. When you click **Run all module tests**, all the unit tests are executed (with check mark icons). When you click **Reset all tests**, the status of the tests change to not executed (with question mark icons). - - Beneath these buttons, the modules that contain unit tests are shown. To begin with and in this scenario, **Unit Testing** is the only module that contains unit tests. When you click a module, all the unit tests of the module are shown. - - If you want to save all the changes made in the microflow to the database, you need to clear the **Rollback microflow tests after execution** box. Keep the box checked if you want to roll back all the changes. - - On the right side of the page, the unit tests of the selected module are shown. In this scenario, five main unit tests are shown. When you click **Run module tests**, all the unit tests are executed. When you click **Run test** next to a unit test, only that unit test is executed. - -18. Click **Run Test** for **UnitTesting.Test_ValidUnitTest**. The color of the test case changes to red if failed and to green if passed: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580358.png" class="no-border" >}} - -19. Click **Details** for Unit Testing.TestValidUnitTest to see the relevant details of the test case: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580340.png" class="no-border" >}} - -## Creating a Microflow Test - -In this section, you will learn how to create a microflow test. To create a new microflow test in a module, you need to add a microflow with a name that starts with *Test*. A test microflow should have no input arguments and a Boolean or string as the result type. For a Boolean result type, true means success, false means the test failed. For a string result type, any non-empty string indicates a failed test. - -### Creating a Microflow - -To create the microflow, follow these steps: - -1. Create a new enumeration and name it *Level* with three enumeration values: *Junior*, *Medior*, and *Senior*. - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580356.png" class="no-border" >}} - -2. Open the domain model of **MyFirstModule**. -3. Create a new entity, name it *Employee*, and add two attributes: *Name* (of the **String** type) and *Level* ( of the **Enumeration** > **Level** type). - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580355.png" class="no-border" >}} - -4. Create a microflow called **Promote** that looks like this: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/promote.jpg" class="no-border" >}} - -### Creating a Unit Test - -1. Add a new folder to MyFirstModule and name it *UnitTests*. -2. Add a new microflow to the **UnitTests** folder and name it *Test_PromoteEmployeeToJunior*. -3. Add one input parameter to the microflow for **Employee**. -4. Add a new **Create object** activity for the **Employee** entity and set **Commit** to **Yes**. -5. Add a new **Member** with *John* set for **Name**: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580353.png" class="no-border" >}} - -6. Now, you need to call the **Promote** microflow with the **Employee** object you just created. So, add a new activity of the **Microflow call** type, select the **Promote** microflow, and enter `$NewEmployee` for the argument: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580352.png" class="no-border" >}} - -7. Now, the employee needs to be promoted to the right level. Add a new activity of the **Microflow call** type and select the**UnitTesting.AssertTrue1** microflow. -8. Set the argument of **ValueToAssert** parameter to `$NewEmployee/Level = MyFirstModule.Level.Junior`: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580344.png" class="no-border" >}} - -9. Right-click the **AssertTrue1** activity you just configured, select **Edit caption**, then enter *Promoted to Junior?* for the new caption. -10. For failed tests, the last step information can be very useful. You can provide this information in your microflow by calling the **ReportStep** sub-microflow. So, add a new activity of the **Microflow call** type between **Create Employee** and **Promote** and select the **UnitTesting.ReportStep** microflow. -11. Set the argument of parameter **Message** to `'Employee created'`. -12. Add a new activity of the **Microflow call** type between **Promote** and **Promoted to Junior?** and select the **UnitTesting.ReportStep** microflow . -13. Set the argument of parameter **Message** to `'Employee promoted'`. -14. Double-click the **End event**, select **Boolean** as the return **Type**, and enter `true` as the **Return value**. -15. The microflow should look like the model below: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/promotetojunior.jpg" class="no-border" >}} - -16. Create three more test microflows as shown below: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/promotetomedior.jpg" class="no-border" >}} - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/promotetosenior.jpg" class="no-border" >}} - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/stillsenior.jpg" class="no-border" >}} - -17. Run the app locally and view it. -18. Click **UnitTestOverview** in the navigation, and click **MyFirstModule** in the list of modules that contain one or more test cases: - - {{< figure src="/attachments/howto8/testing/testing-microflows-using-the-unittesting-module/18580348.png" class="no-border" >}} - - This will display all the test cases for **MyFirstModule**. - -19. Verify the **Rollback microflow tests after execution** box is checked. -20. Click **Run all module tests**. All the test cases should pass. - -Congratulations! You created your first unit tests using the Unit Testing module. - -{{% alert color="info" %}} -It is possible to create a "Setup" and "TearDown" microflow per module. The "Setup" microflow is invoked once before each test run, and the "TearDown" microflow is invoked once after each test run (regardless of whether the test run consists of one or multiple unit tests). -{{% /alert %}} - -{{% alert color="warning" %}} -Do not test everything, focus on the most used and complex microflows! -{{% /alert %}} - -## Read More - -* [How to Create Automated Tests with TestNG](/howto8/testing/create-automated-tests-with-testng/) diff --git a/content/en/docs/howto8/testing/testing-with-application-test-suite.md b/content/en/docs/howto8/testing/testing-with-application-test-suite.md deleted file mode 100644 index e424f7bf90b..00000000000 --- a/content/en/docs/howto8/testing/testing-with-application-test-suite.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Test with ATS" -url: /howto8/testing/testing-with-application-test-suite/ -weight: 20 ---- - -The Mendix Application Test Suite (ATS) is a suite of tools for embedding testing in your application lifecycle. These tools are built in Mendix on top of Selenium. - -For more details, see the [ATS](/appstore/partner-solutions/ats/) documentation. diff --git a/content/en/docs/howto9/extensibility/build-native-widget.md b/content/en/docs/howto9/extensibility/build-native-widget.md index 83650d7a6a5..d5423c60a60 100644 --- a/content/en/docs/howto9/extensibility/build-native-widget.md +++ b/content/en/docs/howto9/extensibility/build-native-widget.md @@ -1090,7 +1090,7 @@ First change the widget property configuration: 2. Rename the file to *GroupBox.icon.png* 3. Add the file to the *src* folder which contains the *xml* file - {{% alert color="info" %}}This functionality was introduced in Studio Pro 9.6. To show a widget icon in Studio Pro 9.5 or below, the icon needs to be added to the *xml* file. To do this, follow the steps from the [Mendix 8](/howto8/extensibility/build-native-widget/#adding-a-collapsible-property) version of this document.{{% /alert %}} + {{% alert color="info" %}}This functionality was introduced in Studio Pro 9.6. To show a widget icon in Studio Pro 9.5 or below, the icon needs to be added to the *xml* file. {{% /alert %}} Now support this section's two features with your display component: diff --git a/content/en/docs/marketplace/platform-supported-content/modules/SAML/idp-attributes.md b/content/en/docs/marketplace/platform-supported-content/modules/SAML/idp-attributes.md index 4b251e023c1..be3d8b5995c 100644 --- a/content/en/docs/marketplace/platform-supported-content/modules/SAML/idp-attributes.md +++ b/content/en/docs/marketplace/platform-supported-content/modules/SAML/idp-attributes.md @@ -138,7 +138,7 @@ Checking this box will force the SAML IdP to (re)authenticate end-users, even if ### Enable Mobile Authentication Token -If you are using a [hybrid mobile](/refguide9/mobile/introduction-to-mobile-technologies/hybrid-mobile/) app and you enable this, you can sign in to your Mendix hybrid mobile app after the app is closed, using an authentication token cookie. Only check this if you are using SAML on a hybrid mobile app. Note that this functionality also requires changes to the hybrid app package as described in [How To Implement SSO on a Hybrid App with Mendix and SAML](/howto8/mobile/implement-sso-on-a-hybrid-app-with-mendix-and-saml/). +If you are using a [hybrid mobile](/refguide9/mobile/introduction-to-mobile-technologies/hybrid-mobile/) app and you enable this, you can sign in to your Mendix hybrid mobile app after the app is closed, using an authentication token cookie. Only check this if you are using SAML on a hybrid mobile app. ### ⚠ Enable Delegated Authentication {#delegated-auth} diff --git a/content/en/docs/marketplace/platform-supported-content/modules/mendix-sso.md b/content/en/docs/marketplace/platform-supported-content/modules/mendix-sso.md index f82460af9ae..44c02f056b0 100644 --- a/content/en/docs/marketplace/platform-supported-content/modules/mendix-sso.md +++ b/content/en/docs/marketplace/platform-supported-content/modules/mendix-sso.md @@ -196,7 +196,7 @@ All files installed by Mendix SSO are marked with *.MendixSSO.RequiredLib*. Once ## Customizing Mendix SSO {#customizing} {{% alert color="info" %}} -In v2 of the [Mendix SSO module](/appstore/modules/mendix-sso/), there was a default implementation of end-user administration. This had dependencies on specific versions of [Atlas UI](/howto8/front-end/atlas-ui/) and was removed so that Mendix SSO v3.0 and above retain compatibility with all Mendix apps, whichever UI they are using. +In v2 of the [Mendix SSO module](/appstore/modules/mendix-sso/), there was a default implementation of end-user administration. This had dependencies on specific versions of Atlas UI and was removed so that Mendix SSO v3.0 and above retain compatibility with all Mendix apps, whichever UI they are using. {{% /alert %}} This section explains how to customize Mendix SSO in your apps and how to base your own user administration module on this section if you want to do things in a different way. diff --git a/content/en/docs/refguide10/installation/upgrading-from-9-to-10.md b/content/en/docs/refguide10/installation/upgrading-from-9-to-10.md index e520f0fcb9c..bdc42676b07 100644 --- a/content/en/docs/refguide10/installation/upgrading-from-9-to-10.md +++ b/content/en/docs/refguide10/installation/upgrading-from-9-to-10.md @@ -20,7 +20,7 @@ Before upgrading your app to Mendix 10, ensure the app is successfully [migrated ### Upgrading from Older Versions of Studio Pro -If your app is on a Studio Pro version below 9, you must upgrade in order of version. This means you must go from 7 to 8 (see details in [Moving from Desktop Modeler Version 7 to Studio Pro 8](/refguide8/moving-from-7-to-8/)), 8 to 9 (see details in [Moving from Mendix Studio Pro 8 to 9](/refguide9/moving-from-8-to-9/)), then 9 to 10. +If your app is on a Studio Pro version below 9, you must upgrade in order of version. This means you must go from 7 to 8, 8 to 9 (see details in [Moving from Mendix Studio Pro 8 to 9](/refguide9/moving-from-8-to-9/)), then 9 to 10. If your app is running on Mendix Cloud, you can check what version the app is currently on by referring to the [Control Center dashboard](/control-center/dashboard/). Alternatively, contact your Customer Success Manager to find out how to check the Mendix version of your app. diff --git a/content/en/docs/refguide10/modeling/xpath/_index.md b/content/en/docs/refguide10/modeling/xpath/_index.md index 96c88ae113b..784cde858f6 100644 --- a/content/en/docs/refguide10/modeling/xpath/_index.md +++ b/content/en/docs/refguide10/modeling/xpath/_index.md @@ -78,7 +78,7 @@ For details, see [XPath aggregate functions](/refguide10/xpath-aggregate-functio **How to find the right path to XPath** {{% alert color="info" %}} -This video was done with [Studio Pro 8](/refguide8/), but the concepts remain applicable. +This video was done with Studio Pro 8, but the concepts remain applicable. {{% /alert %}} {{< youtube sdabUY-w4ZU >}} diff --git a/content/en/docs/refguide8/_MAPPING.txt b/content/en/docs/refguide8/_MAPPING.txt deleted file mode 100644 index 1eaedad50e8..00000000000 --- a/content/en/docs/refguide8/_MAPPING.txt +++ /dev/null @@ -1 +0,0 @@ -There are document files in this folder that are mapped to the product. Refer to Mapping to Products for the names of these files and how to proceed. \ No newline at end of file diff --git a/content/en/docs/refguide8/_index.md b/content/en/docs/refguide8/_index.md deleted file mode 100644 index aa1bd220a69..00000000000 --- a/content/en/docs/refguide8/_index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Studio Pro 8 Guide" -url: /refguide8/ -description: "The various sections of the Mendix Studio Pro Guide provide details on the features and functionality of the Mendix Platform." -weight: 90 -no_list: false -description_list: true -cascade: - - content_type: "Studio Pro 8" - - mendix_version: 8 - - banner: "Studio Pro 8 has reached its end of support. To upgrade to a supported version, see Moving from Mendix Studio Pro 8 to 9." - - old_content: true - - hide_feedback: true - - notsitemap: true - - sitemap: - priority: 0.3 ---- - -{{% alert color="warning" %}} -With the Mendix 11.0.0 release in June 2025, Mendix 8 has reached its end of support. This means that Mendix 8 will no longer receive support, maintenance, or updates. To ensure continued access to the latest features and security enhancements, we recommend planning an upgrade to a more recent version of the platform. -{{% /alert %}} - -## Introduction - -The *Mendix Studio Pro 8 Guide* covers important topics concerning [Studio Pro](/refguide8/modeling/), the [Mendix Runtime](/refguide8/runtime/), and other components of the Mendix Platform. - -Before installing Studio Pro 8, please read [System Requirements](/refguide8/system-requirements/). For information on how to install Studio Pro, see [How to Install Mendix Studio Pro](/howto8/general/install/). - -If you have been using Desktop Modeler version 7, Mendix recommends reading [Moving from Desktop Modeler 7 to Studio Pro 8](/refguide8/moving-from-7-to-8/). - -If you are looking for step-by-step guides on performing various Mendix actions, browse the [Studio Pro 8 How-tos](/howto8/). - -## Studio Pro Functionality - -Studio Pro allows you to create, test, and run apps. - -### Modeling - -Modeling an app is the process of creating an app and involves creating pages, adding logic, configuring security, etc. For more information on what functionality you can use to model your app, see [App Modeling](/refguide8/modeling/). - -### Testing - -When it comes to testing your application, you first need to decide what you are going to test: integration with external services, app logic (microflows), etc. For more information on how to test your application, see [Testing](/howto8/testing/). - -### Deploying - -Studio Pro allows you to run and view your app locally or in the default environment. - -For more information on options for deploying your app, see [Deploying Apps](/deployment/). - -## Version Control - -[Version Control](/refguide8/version-control/) allows you to manage your app development and work on multiple development lines. For information on how Studio Pro handles versioning of apps, see the [Versioning a Project Deployed to the Cloud](/refguide8/using-version-control-in-studio-pro/#versioning-project) section in *Using Version Control in Studio Pro*. - -## Mendix Runtime - -The [Mendix Runtime](/refguide8/runtime/) executes the application model that is created in Studio Pro. It is included in the Studio Pro 8 Guide as it is uses the same version numbering. - -## Mobile - -Mobile app development allows you to create native mobile and hybrid apps and an important part of Studio Pro. For more information, see [Mobile](/refguide8/mobile/). - -## Guide Categories - -The *Studio Pro 8 Guide* is divided into the following categories: diff --git a/content/en/docs/refguide8/general/_index.md b/content/en/docs/refguide8/general/_index.md deleted file mode 100644 index bf6e8252085..00000000000 --- a/content/en/docs/refguide8/general/_index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "General Info" -url: /refguide8/general/ -weight: 10 -no_list: false -description_list: true ---- - -## Introduction - -Before installing Mendix 8, it is important to understand the [System Requirements](/refguide8/system-requirements/). - -If you have been using Desktop Modeler version 7, we advise reading [Moving from Desktop Modeler Version 7 to Studio Pro Version 8](/refguide8/moving-from-7-to-8/). - -## Documents in This Category diff --git a/content/en/docs/refguide8/general/developer-tools.md b/content/en/docs/refguide8/general/developer-tools.md deleted file mode 100644 index 3dd404de858..00000000000 --- a/content/en/docs/refguide8/general/developer-tools.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Developer Tool Recommendations" -url: /refguide8/developer-tools/ -weight: 60 -description: "Describes the best third-party tools to use when developing with Mendix." ---- - -## Introduction - -To make your development life a little easier, here is a list of helpful third-party tools that will speed up your app-development efforts: - -* [Linux m2ee scripts](https://github.com/mendix/m2ee-tools) – Mendix Runtime helper tools for GNU/Linux (for details on installation, see [Installing Mendix on GNU/Linux](https://github.com/mendix/m2ee-tools/blob/master/doc/README.md)) -* [Firefox DevTools](https://www.mozilla.org/en-US/firefox/developer/?utm_source=firebug&utm_medium=lp&utm_campaign=switch&utm_content=landingpage) – these developer tools replace [Firebug](https://getfirebug.com/), which is no longer being supported -* [Selenium](https://www.seleniumhq.org/) – tools for automating web browsers -* [Eclipse](https://www.eclipse.org/downloads/) – tools for writing and debugging Java actions (for more information, see [Using Eclipse](/refguide8/using-eclipse/)) -* [SOAP UI](https://www.soapui.org/) – REST and SOAP testing tools (for more information, see [How to Test Web Services Using SoapUI](/howto8/integration/testing-web-services-using-soapui/)) -* [Visual Studio Code](https://code.visualstudio.com/) – a powerful code editor (especially useful for maintaining your theme) diff --git a/content/en/docs/refguide8/general/moving-from-7-to-8/_index.md b/content/en/docs/refguide8/general/moving-from-7-to-8/_index.md deleted file mode 100644 index 4447750c827..00000000000 --- a/content/en/docs/refguide8/general/moving-from-7-to-8/_index.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: "Moving from Desktop Modeler Version 7 to Studio Pro 8" -linktitle: "Desktop Modeler 7 to Studio Pro 8" -url: /refguide8/moving-from-7-to-8/ -weight: 20 -description: "Provides details on updating your project from Desktop Modeler version 7 to Studio Pro 8, including sections on converting your project and deprecated features." ---- - -## Introduction - -When converting your Mendix app from Desktop Modeler version 7 to Studio Pro 8, there is a recommended series of steps you need to take. These are documented in [Converting Your App](#converting), below. - -For information about new features in Mendix 8, see [Studio Pro 8 release notes](/releasenotes/studio-pro/). - -## Making Changes to Your App Before Upgrading to Mendix 8, Studio Pro - -There may be changes which you should make to your app *before* you upgrade it to Mendix 8. - -### Java Version, Deprecated and Removed APIs {#deprecated-apis} - -Mendix 8 runs on Java 11, whereas Mendix 7 runs on Java 8. Make sure that your Java actions are compatible with Java 11. The official Java 8 to 11 migration guide can be found in the [Migrating From JDK 8 to Later JDK Releases](https://docs.oracle.com/en/java/javase/11/migrate/index.html#JSMIG-GUID-7744EF96-5899-4FB2-B34E-86D49B2E89B6) section of the *Oracle JDK Migration Guide*. - -Deprecated Java actions should be fixed in Mendix 7, before you migrate the app to Mendix 8. - -Fix the deprecations in your Java actions by importing your project into your Java IDE (Eclipse, for example) and reviewing and solving all the deprecations. - -Details of removed and deprecated APIs will be added to the *Breaking Changes* section of the [Studio Pro 8 release notes](/releasenotes/studio-pro/). - -### Atlas Compatibility - -Before moving to Mendix 8, make sure that you are using the latest Mendix 7 compatible Atlas version 1.2.4. By first updating Atlas to this version, you will prevent several errors related to design properties after your Mendix 8 migration. - -How to update to Atlas 1.2.4: - -1. Check if you customized anything in your Studio Pro Atlas UI Resource module, as updating Atlas will override all of that module's content. Move your customized content out of the Atlas UI Module before updating. -2. Check if you customized anything in the **theme** folder inside your Mendix project. If so, rename the **theme** folder to something else, like *theme_oldest*. -3. Update Atlas by opening the Marketplace inside Studio Pro, search for *Atlas UI Resources*, click the **All Versions** pane, and download **Atlas UI Resources v1.2.4**. -4. When prompted, choose to replace your existing Atlas module. - -{{% alert color="info" %}} You do not have to move any customized files from **theme_oldest** to **theme** yet, as after migrating to Mx8, you will update Atlas again which will create a new **theme folder**.{{% /alert %}} - -## Converting Your App {#converting} - -The following sub-sections explain the steps to take in converting your app from Mendix 7 to Mendix 8. - -### Backup Your Project - -Make sure that you have either committed your latest changes to Team Server, or taken a backup of your local project before you start the conversion. - -### Upgrade to the Latest Release of Version 7 {#upgrade} - -{{% alert color="warning" %}} -It is technically required for you to upgrade your app to the latest version of Mendix 7, which is 7.23. You can only convert your app to Mendix 8 from 7.23.x. -{{% /alert %}} - -To upgrade to Mendix 7, follow these steps: - -1. Download the latest patch release of Desktop Modeler 7.23. -2. Open your app in Desktop Modeler 7.23.x. -3. Allow it to upgrade the app, if necessary. - -### Review Your Mendix 7 Project - -Review your app in combination with the sections below and assess if further action needs to be taken before upgrading to Mendix 8. - -In particular, it is easier to fix deprecations in Java actions (see [Java Version, Deprecated and Removed APIs](#deprecated-apis)) in Mendix 7 before upgrading to Mendix 8. However, Float and Currency deprecation errors will be easier to fix in Mendix 8 instead (see the section [Elements of Type Float and Currency](#float-currency) below for instructions). - -### Save Version 7 Project - -Your app is now ready to be upgraded to Mendix 8. - -It is recommended that you backup/commit your project at this point so that you can return to it if necessary. - -You can now close the project in Desktop Modeler version 7. - -### Upgrade Your App to Version 8 - -Mendix will upgrade your app for you. - -Open the project in Mendix Studio Pro 8 and allow Studio Pro to update your app to version 8. - -### Review Errors, Warnings, and Deprecations in Studio Pro - -Review all error messages and messages about deprecated items and make changes where necessary. - -If you are using one, or both, of the deprecated data types Currency and Float you will see errors. See the section [Elements of Type Float and Currency](#float-currency) below for more information. - -### Upgrade All Widgets - -To minimize the chance of problems, you should update all widgets and other Marketplace models used by your project to the latest version. - -Check if there is a newer version of your Marketplace modules available in the Marketplace. Read the version release notes in the Marketplace to see whether you need to perform specific actions when upgrading. - -In general you should not remove and reimport modules, unless this is recommended in the release notes. If you do remove and reimport them, you may lose data or configuration related to the module. - -### Review and Test Your App - -Finally, review the sections below and ensure that you have made all the changes necessary. - -Test the app for any unexpected results. - -{{% alert color="success" %}} -Congratulations! Your app has been successfully upgraded to Mendix 8 and you can continue working as normal. -{{% /alert %}} - -## Elements of Type Float and Currency {#float-currency} - -The types Float and Currency were deprecated in Mendix 7, and have now been removed from Mendix 8. - -The following elements of type Float or Currency will report errors in version 8: - -* Attributes -* Constants -* Create variable actions -* Data set columns and parameters -* Microflow/nanoflow parameters and return types -* Java/JavaScript action parameters and return types -* The functions 'formatFloat', 'parseFloat' and 'toFloat' - -It is possible to fix most of the deprecation errors in one single action. To achieve this, do the following: - -1. In Studio Pro 8, find the error message which relates to the support of Currency and Float data types. - - {{< figure src="/attachments/refguide8/general/moving-from-7-to-8/currency-float-error.png" alt="Error message: currency and float no longer supported" class="no-border" >}} - -2. Right-click the error message. - - {{< figure src="/attachments/refguide8/general/moving-from-7-to-8/currency-float-change-options.png" alt="Change manually or automatically?" class="no-border" >}} - -3. Click **Convert all to Decimal** to convert all the attributes automatically. - - {{< figure src="/attachments/refguide8/general/moving-from-7-to-8/convert-to-decimal-warning.png" alt="Warning when converting all Float and Currency to Decimal" class="no-border" >}} - -4. Click **Convert all to Decimal** to perform the conversion. - -{{% alert color="warning" %}} -If any attributes have been converted during this process, the next time your app is run locally or deployed the database will be converted to support the new attribute types. - -**This database conversion could take a long time!** Mendix suggests that you first test the data conversion on a representative dataset, so that you can estimate how long it will take to convert your production database. -{{% /alert %}} - -## Using REST and Web Service Calls - -Mendix 8 introduces two [Custom Settings](/refguide8/custom-settings/) which relate to **Call REST Service** and **Call Web Service** activities. - -If you use either of these activities, it is recommended that you increase the values of `http.client.MaxConnectionsPerRoute` and `http.client.MaxConnectionsTotal` to reduce the possibility of performance issues for concurrent end-users. For more information, see the [General Settings](/refguide8/custom-settings/#general) of the *Custom Settings* documentation. - -## 64-Bit Studio Pro - -Mendix Desktop Modeler version 7 was 64-bit application but could also run on 32-bit. - -Mendix Studio Pro is a 64-bit application which will **only** run on 64-bit versions of Windows. This must be the 64-bit version of Windows 7, Service Pack 1, or above. - -## Java Code Generation {#java-code-generation} - -In Mendix Studio Pro 8, we are changing the way we generate Java code for Java actions and datasets. - -Mendix Desktop Modeler version 7 sometimes appended a postfix (for example, `Parameter1`) to the names of parameters of Java actions and datasets. This behavior was necessary to prevent name conflicts in the generated code. In the minor releases of Mendix Desktop Modeler 7, we introduced a number of fixes to prevent those conflicts from happening, making this behavior redundant. - -We also noticed that by attempting to prevent those name conflicts, we sometimes caused Java compilation failures, which seemed completely unrelated to what you were working on. Seeing that appending a postfix is now completely unnecessary and introduces quite a few problems on bigger app, we decided to remove it completely. - -What does that mean in practice? For most app, nothing changes and everything still works as it used to. But, in a limited number of cases, Mendix Desktop Modeler version 7 will have introduced a postfix for your parameter name. For example, a parameter called `Customer` might become `CustomerParameter1` in the generated Java code. This postfix will be removed when you migrate your app to Mendix Studio Pro 8. - -In these few cases you need to make a simple fix before your code will compile again: - -* If it is a Java action in a module downloaded from the Marketplace that is causing errors, just download it again, or update it to the latest version -* If it is your own Java action, then the fix is ever easier – just remove those postfixes from your Java code (in the previous example, `CustomerParameter1` just becomes `Customer` again). - -### Example of Differences - -In this example we have a Java action called `LogMessage`, which has a parameter called `Message`. In Mendix Modeler version 7 if you introduced a domain model entity also called `Message`, we would generate the following Java code for you (please note that some code is omitted for readability): - -```java - public LogMessage(IContext context, java.lang.String MessageParameter1) - { - super(context); - this.MessageParameter1 = MessageParameter1; - } - @java.lang.Override - public java.lang.Boolean executeAction() throws Exception - { - // BEGIN USER CODE - Core.getLogger("MyLogger").info(this.MessageParameter1); - // END USER CODE - } -``` - -As you can see, instead of naming the parameter `Message` now Mendix Modeler version 7 names it `MessageParameter1`. In the user code of the `executeAction()` method, `this.Message` is used to log a message. This means that the code won’t compile. - -Studio Pro 8 will generate the following code for you: - -```java - public LogMessage(IContext context, java.lang.String Message) - { - super(context); - this.Message = Message; - } - @java.lang.Override - public java.lang.Boolean executeAction() throws Exception - { - // BEGIN USER CODE - Core.getLogger("MyLogger").info(this.Message); - // END USER CODE - } -``` - -This code behaves as expected and works out of the box. However, if you previously changed your user code to comply with the way Mendix Modeler version 7 was generating this code, you just need to update your user code to use the new names of parameters. - -## Troubleshooting - -### Cannot Open Project: `Layout … has an invalid value …` - -Very rarely, you may receive a message similar to the one below when opening a project in Mendix Studio Pro 8 which needs to be upgraded from a previous version of Mendix. - -{{< figure src="/attachments/refguide8/general/moving-from-7-to-8/layout-import-message.png" alt="Layouts Error Message" class="no-border" >}} - -This happens when a layout has an invalid value for the **Layout type**. This will still cause an error, *even if the invalid layout has been excluded* from the project. - -See the image below for an indication of where you might find the error in your project. - -{{< figure src="/attachments/refguide8/general/moving-from-7-to-8/layout-error-location.png" alt="Location of Layouts Error" class="no-border" >}} - -To resolve this issue, use the previous version of Mendix to change the invalid **Layout type** (in the example above, `Legacy`) to a valid value. - -### DOM and Atlas UI Issues - -Mendix 8 comes with several improvements to its DOM structure. These DOM changes will affect the Sass styling of app. Because of these updates, Mendix 8 app are designed to be completed using [Atlas UI Resources](https://marketplace.mendix.com/link/component/104730) (v2.0.0 or higher). Upgrading your Atlas UI can cause issues with your app's theming. To troubleshoot either DOM or Atlas UI migration issues, consult the following documents: - -* [Troubleshooting DOM Changes](/refguide8/migration-dom-issues/) -* [Troubleshooting Atlas UI Changes](/refguide8/migration-atlas/) diff --git a/content/en/docs/refguide8/general/moving-from-7-to-8/migration-atlas.md b/content/en/docs/refguide8/general/moving-from-7-to-8/migration-atlas.md deleted file mode 100644 index e21e1eab599..00000000000 --- a/content/en/docs/refguide8/general/moving-from-7-to-8/migration-atlas.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Troubleshooting Atlas UI Changes" -url: /refguide8/migration-atlas/ -weight: 20 -description: "This document explains how to fix your styling when migrating a project from Mendix 7 to Mendix 8." ---- - -## Introduction - -When you upgrade to Mendix 8, your widgets' DOM structure will be changed. This means that the correlating Sass styling will not work as expected anymore. This document will allow you to make your theming compatible with Mendix 8. - -Each section in this document could apply to your app, but some sections may *not* apply. If a section does not apply to your case, you may skip it. - -{{% alert color="warning" %}}If you have added any content in the **Atlas_UI_Resource module**, you have to move that content out of the module. If you do not, it will be overwritten.{{% /alert %}} - -When your app is using unmodified Atlas UI resources, upgrading your app to Mendix 8 will automatically update your Atlas UI resources to version 2.1. If you did not make any changes in the custom folder, you are good to go and you can skip the rest of this guide. - -If you are using unmodified Atlas UI resources but you made changes to the custom folder, these changes are preserved and will be used by the new Atlas UI version. You will see a consistency error in this case. Proceed to the steps described in the [Working with a Modified Custom Folder](#modified) section below to resolve this error. - -If you are using a modified version of Atlas UI resources, Mendix cannot update it automatically. You will see a consistency error in this case. To resolve your theming issues, you need to update Atlas yourself. - -Follow the steps below to begin upgrading your Atlas UI Resources module: - -1. Download the latest [Atlas UI Resources](https://marketplace.mendix.com/link/component/104730) module (v2.0.0 or higher). -2. Import this module into your app and replace the old resource module. This will overwrite the layouts, page templates, and building blocks inside of the resource module. The **theme** folder related to your old resource module will be moved to **theme_old**. You will get a new **theme** folder with the latest changes. From here, you must choose one of the following based on if you have custom styling or not:
- * If you did not change anything in the old **theme** folder, you can safely remove **theme_old** and leave everything else as is. Your styling will work and you can stop with consulting this document.
- * If you did change anything in the old **theme** folder, you will have to do some manual work to align your styling. Consult the information below to decide what to do based on your needs. - -## Integrating the Old Theme Folder into the New One - -When migrating from Mendix 7 to Mendix 8, you must integrate **theme_old** into **theme** while adhering to several guidelines. Which guidelines you must follow vary based on your specific project. Consult the subsections below for instructions based on your unique case. - -{{% alert color="info" %}}If you customized any widget where the DOM structure has changed, consult [Troubleshoot DOM Changes when Migrating to Mendix 8](/refguide8/migration-dom-issues/) to ensure your custom styling works.{{% /alert %}} - -### Working with HTML Files - -If you have altered your HTML files, consult the instructions below. If you have not, you may ignore this subsection. - -If you changed any **index\*.html** files, make sure to do the following: - -* Apply the same changes you did in the old file to the new HTML file -* Make sure the **bootstrap.min.css**, **bootstrap-rtl.min.css**, and **mxui.css** imports are not there -* Make sure you do not import **styles/css/lib/lib.css** anymore -* Make sure you have put either `` or `{{themecss}}` inside of the `` tags - -If you changed any **login\*.html** files, complete the following actions: - -* Apply the same changes you did in the old file to the new HTML file -* Confirm the **bootstrap.min.css** and **mxui.css** imports are gone (if they are not, delete them) -* Make sure you do not import `styles/css/lib/lib.css` anymore -* Place either `` or `{{themecss}}` inside of the `` tags - -### Working with JSON Files - -If you have altered *settings.json* or *components.json* files, consult the instructions below. If you have not, you may ignore this subsection. - -#### Design Properties - -If you changed design properties in your theme, you must manually integrate them into the new Atlas UI. - -Design properties are stored in the `designProperties` section in the *settings.json* file. - -If you have custom design properties which have not been moved to the new Atlas UI theme, you will see consistency errors (error code **CE6083**) which will notify you about your project's missing design properties. - -Please move your custom design properties to the *settings.json* file of the new Atlas UI theme. - -### Additional CSS Files - -{{% alert color="warning" %}} -Changing `cssFiles` is not recommended. Please consider moving custom CSS files to your *theme/styles/web/sass/app/_custom.scss* file. -{{% /alert %}} - -If you changed `cssFiles` in *settings.json*, you must integrate your changes to the new *settings.json* file. - -By default Atlas UI version 1 includes two files: - -```javascript -"cssFiles": [ - "styles/css/lib/lib.css", - "styles/css/custom/custom.css" -], -``` - -Atlas 2.1.0, however, uses a single file: - -```javascript -"cssFiles": [ - "styles/web/css/main.css" -], -``` - -If your `cssFiles` section adds more files, you must include them in your new theme's *settings.json* file. - -If you changed hybrid mobile app imports in *components.json*, make sure to do the following: - -* Manually integrate your old *components.json* into the new folder -* Confirm the *bootstrap.min.css*, *bootstrap-rtl.min.css*, and *mxui.css* imports are gone (if they are not, delete them) -* Confirm that *styles/css/lib/lib.css* is changed to *styles/web/css/main.css* - -### Working with Custom Folder Files - -If you have altered your custom folders, consult the instructions below. If you have not, you may ignore this subsection. - -If you added, removed, or changed custom variables in a custom folder, copy your content from *theme_old/styles/sass/custom/_custom-variables.scss* to *theme/styles/web/sass/app/_custom-variables.scss*. - -If you added or changed custom styling in the custom folder, copy your content or files from *theme_old/styles/sass/custom/* to *theme/styles/web/sass/app/*. - -* In this case, also make sure that your old *custom.scss* file is renamed to *_custom.scss* - -### Working with Lib Folder Files - -If you have altered your *styles/sass/lib* folder, consult the instructions below. If you have not, you may ignore this subsection. - -If you changed any files in the *styles/sass/lib* folder, complete the actions below: - -* If you changed a file’s content or name, you must manually make the same changes in the new file and in the new theme folder (while also keeping the Mendix 8 [DOM changes](/refguide8/migration-dom-issues/) in mind) -* If you removed a file, no action is required - -If you added a file to the *lib/base* folder, copy that file from *theme_old/styles/sass/lib/base/* to *theme/styles/web/sass/core/base/*. You must also complete the following action: - -* Import the file into *theme/styles/web/sass/main.scss* under the `Base` group in alphabetic order - -If you added a file to the *lib/components* folder, copy that file from *theme_old/styles/sass/lib/components/* to *theme/styles/web/sass/core/widgets/*. You must also complete the following actions: - -1. Import the file into *theme/styles/web/sass/main.scss* under the `Widgets` group in alphabetical order -2. Cut all design properties and extra classes from your file (to be pasted later), leaving only the default styling -3. Create a new file in *theme/styles/web/sass/core/helpers/* with the same name -4. Paste those design properties and extra classes into this new file -5. Import the file into *theme/styles/web/sass/main.scss* under the import mentioned above - -If you added a file to the *lib/customwidgets* folder, copy your content from *theme_old/styles/sass/lib/customwidgets/* to *theme/styles/web/sass/core/widgetscustom/*. You must also complete the following action: - -* Import the file into *theme/styles/web/sass/main.scss* under the `Custom Widgets` group in alphabetical order - -If you added a file to the *lib/buildingblocks* folder, copy that file from *theme_old/styles/sass/lib/buildingblocks/* to *theme/styles/web/sass/resources/atlas_resources_default/buildingblocks*. You must also complete the following action: - -* Import the file into *theme/styles/web/sass/main.scss* under the `Building Blocks` group in alphabetical order - -If you added a file to the *lib/layouts* folder, copy that file from *theme_old/styles/sass/lib/layouts/* to *theme/styles/web/sass/resources/atlas_resources_default/layouts*. You must also complete the following action: - -* Import the file into *theme/styles/web/sass/main.scss* under the `Layouts` group in alphabetical order - -Make sure any custom or added Sass files are all imported in either *styles/web/sass/main.scss* or *styles/web/sass/app/_custom.scss*. - -After troubleshooting your issues with the guidance above, complete the following steps to test your migrated app: - -### Working with a Modified Custom Folder {#modified} - -1. Recompile your Sass to CSS. -2. Test your app to see if everything works as expected. -3. Delete *theme_old*. - -## Read More - -* [Troubleshoot DOM Changes](/refguide8/migration-dom-issues/) -* [Atlas UI](/howto8/front-end/atlas-ui/) diff --git a/content/en/docs/refguide8/general/moving-from-7-to-8/migration-dom-issues.md b/content/en/docs/refguide8/general/moving-from-7-to-8/migration-dom-issues.md deleted file mode 100644 index e7cfc4b4188..00000000000 --- a/content/en/docs/refguide8/general/moving-from-7-to-8/migration-dom-issues.md +++ /dev/null @@ -1,459 +0,0 @@ ---- -title: "Troubleshooting DOM Changes" -url: /refguide8/migration-dom-issues/ -weight: 10 -description: "This document explains the updated DOM structure for Mendix 8, and what that means for app's CSS." ---- - -## Introduction - -Among other improvements to the client in Mendix 8, the HTML of Mendix applications has also been updated. These changes make widgets more accessible, more consistent, and give you a cleaner markup to work with. - -However, these updates might impact your styling. The appearance of your application may be affected, as the widgets' Document Object Model structure has been updated. This reference guide will outline the differences between Mendix 7 and 8 as they pertain to the DOM and CSS. This document is only relevant for apps which employ custom CSS or modify existing Atlas UI CSS. - -## Updating Atlas - -When you upgrade to Mendix 8, DOM structure changes will also alter the correlating Sass styling files. This could make some of your styling not work as expected anymore. To make your styling compatible with Mendix 8, see [Troubleshoot Atlas UI Changes when Migrating to Mendix 8](/refguide8/migration-atlas/). - -## Streamlined Custom Themes - -Before Mendix 8, the client provided a large amount of default styling if your app lacked a theme. This made building your own theme difficult, as you needed to override the default styling. As of Mendix 8, all styling has been moved to Atlas UI. Now, building your own theme from scratch requires significantly less work. - -If you have already built your own theme from scratch in an earlier version of Mendix, you might depend on the default styling (specifically the Bootstrap files and the **mxui.css** file) not included in Mendix 8 applications by default. - -For this case, Mendix provides legacy **mxui.css** and Bootstrap files with defaults in this [GitHub repository](https://github.com/mendix/legacy-mxui-css). Download files from this repository to enable your custom theme. - -Things differ from case to case, but in general when migrating from Mendix 7 to 8 you will probably need to add the **mxui.css** file into Mendix 7's `theme` folder. If your app uses Bootstrap CSS through its custom theme, also add those files to the `theme` folder. To finish up, include the **mxui.css** and Bootstrap files in your **index.html** file. - -{{% alert color="info" %}} -If you get an error message `CE6103: We detected that you are not using Atlas UI for your theme. Please check 'Troubleshooting DOM Changes' to ensure your theme is fully compliant with Mendix 8. Right-click to see more options`, you can clear the message by right-clicking it and selecting **Mark as Resolved**. -{{% /alert %}} - -## Focus-Specific Class Removed - -Before Mendix 8, the client frequently applied `mx-focus` to the element receiving focus and removed `mx-focus` when the element lost focus. Because all supported browsers now have proper support for the `:focus` pseudo-class, these reapplications are no longer necessary. For more information on `:focus`, see Mozilla’s [:focus documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus). - -If your are using `mx-focus` in your theme, you should replace it with `:focus`. - -Code such as this: - -```css -.mx-listview-item.mx-focus { - /* your styling */ -} -``` - -Should be changed to: - -```css -.mx-listview-item:focus { - /* your styling */ -} -``` - -## Data Grid Markup Updates - -We made a number of updates to the data grid markup. Previously, the data grid was split into two separate tables: one containing the header and one containing the data. This made the data grid less accessible, because screen readers show these as two separate tables. Now the two tables have been merged into a single table. Furthermore, the `div` wrapping the two tables has been removed. - -Another data grid markup change is that the `div` containing the toolbar and the `div` containing the paging bar (both part of the control bar) are now in a logical order. Previously, additional CSS was needed to display them in the right order, and additional JavaScript was needed to dictate a logical tab behavior. The current structure now falls in line with [Web Content Accessibility Guidelines 2.1's criterion 1.3.2](https://www.w3.org/TR/WCAG21/#meaningful-sequence) by having [the DOM order follow the visual order](https://www.w3.org/TR/WCAG20-TECHS/C27.html). - -With new accessibility features implemented, now `div` containing pagination section (inside of control bar) has appropriate `role` attribute set. Buttons inside of this `div`, including the `div` itself, now has translatable `aria-label` attributes which can be set from Modeler's `System Texts` page with category name `Accessibility`. New `span` and `caption` elements added as a sibling to *`buttons` for pagination* and `thead` respectively. They are only visible to screen readers. - -This is the current markup of the data grid (unchanged code omitted): - -```html -
- -
- ... -
- - - - Currently showing(translatable text) 1 to 20 of 132 - - -
- ... -
-
- - - ... - - - - - ... - - -
Caption
-
-
-``` - -Additionally, a number of additional classes on the table have been removed, as they are easily accessed using element names. - -If you were styling your data grid in this way: - -```css -.mx-datagrid .mx-datagrid-head-table { - // your styling -} -.mx-datagrid .mx-datagrid-body-table .mx-datagrid-body tr td { - // your styling -} -``` - -You should rewrite the data grid styling using these guidelines: - -```css -.mx-datagrid thead { - // your styling -} - -.mx-datagrid tbody tr td { - // your styling -} -``` - -## List View Markup Changes - -The markup for list view widgets has also been changed. To simplify the styling, the following classes have been removed: - -* `mx-list` -* `mx-listview-list` -* `mx-listview-striped` -* `mx-listview-item` -* `mx-listview-search-input` -* `mx-listview-clear-button` - -For list views that are not in a select page for a reference or reference set selector, the list view's `mx-listview-selectable` has been removed. The unneeded `div` elements with class `mx-listview-content` around the contents of each list view item have also been removed. - -The order of the list view search bar's DOM elements has been corrected to be consistent with the visual order. The `div` element around the search input field has been removed. - -If you were styling your list view widgets this way: - -```css -.mx-listview-item { - // Your styling -} -.mx-listview-search-input input { - // Your styling -} -.mx-listview-clear-button { - // Your styling -} -``` - -You should rewrite your list view styling using these guidelines : - -```css -.mx-listview li { - // Your styling -} -.mx-listview-searchbar input { - // Your styling -} -.mx-listview-searchbar button { - // Your styling -} -``` - -## Scroll Container Markup Changes - -All classes starting with `mx-layoutcontainer` have been removed from scroll containers, as they are redundant with their `mx-scrollcontainer` counterparts. - -## Link Button Markup Changes - -The markup for link buttons has been made more consistent with other buttons: - -```html - - - Link button - -``` - -## Input Widgets Markup Changes - -Every input widget has an implicit form group structure wrapped around it. Before recent changes, an input widget’s DOM structure could appear disorganized depending on its settings. Now, the form group structure ensures that the input widget is properly aligned inside the data view and properly labeled. - -### Vertical and Horizontal Classes on DataView - -Previously, data view was rendering `form-horizontal` class on it when **Form orientation** was set to **Horizontal** and no such class if this option was set to **Vertical**. Now, `form-horizontal` or `form-vertical` are added on **Horizontal** and **Vertical** options respectively. - -This makes it easier to style forms (and inputs in them) with different orientations by targeting a class in your CSS selector. If you were previously relying on the presence or absence of `form-horizontal,` now you can simplify your CSS selectors by using `form-vertical`. - -This is how the DOM structure of the data view widget is organized now: - -```html -
-
- ... -
...
-
...
- ... -
-
- ... -
-
-``` - -### Form Group Structure - -Previously, if widget had the **Show caption** option set to **No**, form group structure was missing `form-group` class on its top level `div`: - -```html -
- -
-``` - -Now, the `form-group` class stays in place with extra `no-columns` class: - -```html -
- -
-``` - -If you have made custom styles using `.form-group` before, this might be a breaking change as `.form-group` matches with more elements now. You can now target form groups and elements inside them on only horizontal or only vertical forms using `.form-horizontal .form-group` or `.form-vertical .form-group` respectively. - -### Input Widget Type Classes - -Form groups now have special class name depending on their widget type: - -* `.mx-checkbox` -* `.mx-datepicker` -* `.mx-dropdown` -* `.mx-inputreferencesetselector` -* `.mx-radiobuttongroup` -* `.mx-referenceselector` -* `.mx-textarea` -* `.mx-textbox` - -### Examples of Form Group Layout - -The vertical form group input widget now has a label, input control, and an optional validation message on the same level: - -```html -
- - - - -
value
- - -
checkboom
-
-``` - -The horizontal form group input widget now has a label with `col-sm-{labelWith}`and `div.col-sm-{12-labelWith}`. Its label also has input control and an optional validation message inside: - -```html -
- -
- - -
value
- - -
checkboom
-
-
-``` - -This is the structure of an input widget, in either a horizontal or vertical data view, with **Show label** set to **No**. The input widget has an input control and an optional validation message: - -```html -
- - - - -
value
- - -
checkboom
-
-``` - -### Read-Only Controls - -Previously, non-editable input controls of input widgets with **Read-only style** set to **Text** could have been rendered using a `p` or a `label` element with a `form-control-static` class on them. - -Read-only controls with **Read-only style** set to **Text** are now rendered as the following: - -```html -
value
-``` - -### Input Widgets Structure - -Previously, some input widgets had a wrapper element surrounding their control. - -These redundant wrappers have been removed, and now bare controls are rendered wherever possible (except radio buttons in a radio buttons group, in which each individual control is wrapped in a `div`). - -### Examples of Input Controls - -A few examples of various input controls are listed below. - -Text box: - -```html - -``` - -Text area: - -```html - -``` - -Checkbox: - -```html - -``` - -Checkbox when **Label position** is set to **After control** (in this case the label on the form group is not shown): - -```html - - -``` - -Radio buttons: - -```html -
-
- - -
-
- - -
-
- - -
-
- - -
-
-``` - -Drop-down: - -```html - -``` - -## Date Picker Widget Changes - -### Input - -The following changes have been made to the date picker input widget: - -* The classes `mx-dateinput` and `mx-dateinput-input` have been removed in favor of the new `mx-compound-control` class -* The `mx-compound-control` class was introduced for input widgets made up of more than one element, such as a widget with a button next to the input -* The inner `
` element with class `mx-dateinput-input-wrapper` around the input was removed -* The ` -
-
-
-
January
- ... -
-
June
-
- - - -
-
January
- ... -
-
- -
-``` - -The year switcher now has the following structure: - -```html -
- 2018 - 2019 - 2020 -
-``` - -## Reference Selector and Input Reference Set Selector Markup Changes - -The following changes have been made to the reference selector markup: - -* The classes `mx-referenceselector` and `mx-referencesetselector` have been removed from the main `
` element in favor of the new `mx-compound-control` class, which was introduced for input widgets made up of more than one element (one common input widget with multiple elements is a button next to an input element). - -The following changes have been made to the input reference set selector markup: - -* The form group will now get the class `mx-referenceselector` or `mx-inputreferencesetselector` (note the `input` prefix) instead -* The inner `
` element (sharing a class ending with `-input-wrapper`) around the input was removed -* The ` - - First - Second - Third - - -``` - -The widget’s render hierarchy is as follows for uniform: - -```xml - - - - First - - - Validation feedback enumeration - - - - First <= Selected - - - Second - - - Third - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `containerDisabled` | Same properties as `container` | Overrides `container` styles if the drop-down is non-editable. | -| `label` | This has all TextStyle properties. | | -| `label` | `numberOfLines` | The maximum number of lines to wrap the label text. If the text is any longer it will be cut off with an ellipsis. Defaults to `1`. | -| `labelDisabled` | Same properties as `label` | Overrides `label` styles if the drop-down is non-editable. | -| `pickerIOS` | This has all ViewStyle properties. | | -| `pickerBackdropIOS` | This has all ViewStyle properties. | | -| `pickerTopIOS` | This has all ViewStyle properties. | | -| `validationMessage` | This has all TextStyle properties. | Styles the validation message (with Studio Pro 8.11).| -| `value` | This has all TextStyle properties | Styles the value button which toggle's dropdown and PickerIOS items. If placeholder is selected, placeholderTextColor will be applied | -| `useUniformDesign` | `boolean` | Enables new uniformDesign (with Studio Pro 8.11). | -| `iconStyle` | This has all TextStyle properties | Styles the arrow down icon next to the value (with Studio Pro 8.15).| -| `value` | `placeholderTextColor: string` | If placeholder is selected, placeholderTextColor will be applied (with Studio Pro 8.11).| -| `valueFocused` | Same properties as `value` | Overrides `value` styles if the dropdown box is focused. (with Studio Pro 8.15).| -| `valueContainer` | This has all ViewStyle properties & rippleColor | Styles the value button's container (with Studio Pro 8.11).| -| `valueContainerFocused` | Same properties as `valueContainer` | Overrides `valueContainer` styles if the dropdown box is focused (with Studio Pro 8.15).| -| `menuWrapper` | This has all ViewStyle properties | Styles the wrapper view surrounding all the menu items (with Studio Pro 8.11).| -| `itemContainer` | This has all ViewStyle properties | Styles all the item containers in dropdown menu including selected item container (with Studio Pro 8.11).| -| `item` | This has all TextStyle properties | Styles all the items in dropdown menu including selected item (with Studio Pro 8.11).| -| `selectedItem` | This has all TextStyle properties | Styles the selected item in dropdown menu (with Studio Pro 8.11).| -| `selectedItemContainer` | This has all ViewStyle properties | Styles the selected item's container in dropdown menu (with Studio Pro 8.11).| - -### Checkbox - -A checkbox input widget can be used to display and edit Boolean attributes and is rendered as a switch. This is how a checkbox widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/check-box.png" alt="checkbox" width="350" class="no-border" >}} - -The widget’s style properties structure is as follows: - -```xml - - - - - - - Feedback switch input - - - - - - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `containerDisabled` | Same properties as `container` | Overrides `container` styles if the text box is non-editable. | -| `input` | This has all TextStyle properties. | | -| `input` | `trackColorOn` | Custom color for the switch track when turned on. | -| `input` | `trackColorOff` | Custom color for the switch track when turned off. | -| `input` | `thumbColorOn` | Color of the foreground switch grip when turned on. If this is set on iOS, the switch grip will lose its drop shadow. | -| `input` | `thumbColorOff` | Color of the foreground switch grip when turned off. If this is set on iOS, the switch grip will lose its drop shadow. | -| `inputError` | This has the same properties as `input` | Overrides `input` styles if there are validation errors. | -| `inputDisabled` | This has the same properties as `input` | Overrides `input` styles if the checkbox is non-editable. | -| `label` | This has all TextStyle properties | | -| `label` | `numberOfLines` | The maximum number of lines to wrap the label text. If the text is any longer it will be cut off with an ellipsis. Defaults to `1`. | -| `labelDisabled` | Same properties as `label` | Overrides `label` styles if the checkbox is non-editable. | -| `validationMessage` | This has all TextStyle properties. | | - -The default class to style all checkbox inputs is named `Checkbox`. - -### Date Picker - -A date picker is an input widget that can be used to display and edit date or time attributes. This is how a date picker widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/date-picker.png" alt="date picker" width="300" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - - Content invalid - Validation feedback enumeration - iOS picker modal shadow container - iOS picker - iOS picker modal header - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `containerDisabled` | Same properties as `container` | Overrides `container` styles if the date picker is non-editable. | -| `label` | This has all TextStyle properties. | | -| `label` | `numberOfLines` | This is the maximum number of lines to wrap the label text. If the text is any longer, it will be cut off with an ellipsis (defaults to `1`.) | -| `labelDisabled` | Same properties as `label` | Overrides `label` styles if the date picker is non-editable. | -| `value` | This has all TextStyle properties | | -| `value` | `rippleColor` | This is the color of the ripple on Android, and will be applied only when the date picker is pressed (defaults to `rgba(0, 0, 0, 0.2)`). | -| `value` | `underlayColor` | This is the color while pressing the date picker on iOS, if not set it will be defaulted to opacity only. | -| `valueDisabled` | This has all TextStyle properties | Overrides `value` styles if the date picker is non-editable. | -| `placeholder` | This has all TextStyle properties | | -| `placeholderDisabled` | This has all TextStyle properties | Overrides `placeholder` styles if the date picker is non-editable. | -| `validationMessage` | This has all TextStyle properties | | -| `pickerBackdropIOS` | This has all ViewStyle properties | | -| `pickerIOS` | This has all ViewStyle properties | | -| `pickerIOS` | `color` | | -| `pickerTopIOS` | This has all ViewStyle properties | | - -The default class to style all date picker inputs is named `DatePicker`. - -### Reference selector - -The reference selector is an input widget that can be used to display and edit associations. For more information on this widget, see [Reference Selector](/refguide8/reference-selector/). This widget supports the same style properties and structure as the [drop-down](#drop-down) widget above. - -The default class to style all reference selector inputs is named `ReferenceSelector`. - -## File Widgets - -File widgets help your user app manage images and other files. For more information on these widgets, see [File Widgets](/refguide8/file-widgets/). - -### Image Viewer {#image-viewer} - -An image viewer can be used to display an image. This widget supports the same style properties and structure as the [Image](#image) widget above. - -The default class to style all image viewers is named `ImageViewer`. - -## Button Widgets - -Button widgets help your user perform actions. For more information about these widgets, see [Button Widgets](/refguide8/button-widgets/). - -### Action Button - -An action button can perform various actions such as calling a nanoflow, opening a page. - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/action-button.png" alt="action button" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - primary - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `container` | `rippleColor` | This is the color of the ripple on Android (defaults to `rgba(0, 0, 0, 0.2)`). | -| `container` | `underlayColor` | This is the color while pressing the button on iOS, if not set it will be defaulted to opacity only. | -| `containerDisabled` | Same properties as `container` | Overrides `container` styles if the button has on click action set and it cannot be executed or is set with `Disable during action`. | -| `caption` | This has all TextStyle properties. | | -| `captionDisabled` | Same properties as `caption` | Overrides `caption` styles if the button has on click action set and it cannot be executed or is set with `Disable during action`. | -| `icon` | This has all ViewStyle properties. | | -| `icon` | `size` | This is the size of the button icon (defaults to `12`). | -| `icon` | `color` | This is the color of the button icon. | -| `iconDisabled` | Same properties as `icon` | Overrides `icon` styles if the button has on click action set and it cannot be executed or is set with `Disable during action`. | - -The default class to style all actions buttons is named `ActionButton`. However, an action button in a header has the default class `ActionButtonHeader`. - -## Pages {#pages} - -To style pages, you can add classes to a page or its layout. The status bar and header are part of a page and can also be styled this way. - -```xml - - -
- - application content - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `statusBar` | `barStyle` | The style of the status bar, which can be either `dark-content` (black text) or `light-content` (white text). | -| `statusBar` | `backgroundColor` | The background color of the status bar (Android only). | -| `header` | `container` | This has all ViewStyle properties. | -| `header` | `title` | This has all TextStyle properties. | -| `header` | `backButtonText` | This has all TextStyle properties. | -| `header` | `backButtonIcon` | This has all ImageStyle properties. | -| `container` | This has all ViewStyle properties. | | - -The default classes for layouts and pages are `Layout` and `Page`. - -## Navigation {#navigation-widget} - -The navigation consists of the bottom bar (which allows users to navigate within your app) and the progress overlay (which can be used to show a loading indicator while waiting for something to load). This is how navigation could look like in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/nav-widget.png" alt="navigation widget" width="300" class="no-border" >}} - -The navigation style properties are as follows: - -```xml - - - - - - - - - - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `bottomBar` | `container` | This has all ViewStyle properties. | -| `bottomBar` | `label` | This has all TextStyle properties. | -| `bottomBar` | `selectedLabel` | This has all TextStyle properties. | -| `bottomBar` | `icon` | This has all TextStyle properties. | -| `bottomBar` | `selectedIcon` | This has all ViewStyle properties. | -| `progressOverlay` | `background` | This has all ViewStyle properties. | -| `progressOverlay` | `container` | This has all ViewStyle properties. | -| `progressOverlay` | `activityIndicator` | This is the same as the [activity indicator](#activity-indicator) widget. | -| `progressOverlay` | `text` | This has all TextStyle properties. | - -The default class to style the navigation is named `navigationStyle`. There is no support for custom class styling on navigation. - -## Add-On Widgets - -Add-on widgets are distributed through the [Native Mobile Resources](/appstore/modules/native-mobile-resources/) module, and are not shipped with Mendix Studio Pro. Other add-on widgets might also be distributed through app templates, as well as modules importing pages from other projects. - -### Activity Indicator {#activity-indicator} - -The activity indicator widget displays a circular loading indicator. This is how an activity indicator widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/activity-indicator.png" alt="activity indicator" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -```javascript - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `indicator` | `color` | This is the color of the indicator (defaults to `gray`). | -| `indicator` | `size` | Possible values for indicator are `large` and `small` (defaults to `large`). | - -The default class to style all activity indicators is named `com_mendix_widget_native_activityindicator_ActivityIndicator`. - -### App Events - -The app events widget allows you to set actions when your app’s network status is changed, and can let you set limits on action calls. This widget has no user interface so does not support any styling. - -### Background Image - -The background image widget enables layering one or more widgets on top of an image. - -The widget’s style properties are as follows: - -```javascript - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `image` | This has all ImageStyle properties. | | -| `image` | `svgColor` | Property to set the color of an SVG image (defaults to `black`). | - -The default class to style all background images is named `com_mendix_widget_native_backgroundimage_BackgroundImage`. - -### Badge - -The badge widget displays text or values as a badge. This is how a badge widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/badge.png" alt="badge" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - New - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `caption` | This has all TextStyle properties. | | - -The default class to style all badges is named `com_mendix_widget_native_badge_Badge`. - -### Barcode Scanner - -The barcode scanner widget allows your app to scan barcodes and QR codes. This widget renders a camera view in a styleable container. - -The widget's style properties are as follows: - -```javascript - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `mask` | This only allows the properties below. | | -| `mask` | `color` | Property to set the color of the mask border indicators (defaults to `#62B1F6`). | -| `mask` | `width` | Property to set the width of the barcode reader. | -| `mask` | `height` | Property to set the height of the barcode reader. | -| `mask` | `backgroundColor` | Property to set the background color of the mask (defaults to `rgba(0, 0, 0, 0.6)`). | - -The default class to style all barcode scanner widgets is named `com_mendix_widget_native_barcodescanner_BarcodeScanner`. - -### Feedback - -The feedback widget allows users to give direct feedback. This is how a feedback widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/feedback-two.png" alt="feedback" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -| Element | Style Properties | Description | -| --- | --- | --- | -| `floatingButton` | This has all ViewStyle properties. | | -| `dialog` | This has all ViewStyle properties. | | -| `title` | This has all TextStyle properties. | | -| `textAreaInput` | This has all TextStyle properties. | | -| `textAreaInput` | `placeholderTextColor` | This is the text color of the placeholder string. | -| `textAreaInput` | `selectionColor` | This is the highlight and cursor color of the text input. | -| `textAreaInput` | `underlineColorAndroid` | This is the underline color for Android devices. | -| `textAreaInput` | `numberOfLines` | This is the height of the text area is based on this number of text lines. | -| `switchLabel` | This has all TextStyle properties. | | -| `switchInput` | This has all TextStyle properties. | | -| `switchInput` | `trackColorOn` | This is the custom color for the switch track when turned on. | -| `switchInput` | `trackColorOff` | This is the custom color for the switch track when turned off. | -| `switchInput` | `thumbColorOn` | This is the color of the foreground switch grip when turned on. If this is set on iOS, the switch grip will lose its drop shadow. | -| `switchInput` | `thumbColorOff` | This is the color of the foreground switch grip when turned off. If this is set on iOS, the switch grip will lose its drop shadow. | -| `button` | `borderColor` | This is the color of dialog button borders. | -| `button` | `borderWidth` | This is the width of dialog button borders. | -| `button` | `color` | This is the color of dialog button text. | -| `buttonDisabled` | `color` | This is the color of dialog button text when disabled. | -| `activityIndicator` | `color` | This is the color of the activity indicator that is shown while feedback is being submitted. | - -The default class to style all feedback widgets is named `com_mendix_widget_native_feedback_Feedback`. - -### Floating Action Button - -The floating action button widget lets you customize the appearance and functionality of floating action buttons. The widget’s style properties are as follows: - -| Element | Style Properties | Description | -| --- | ---| --- | -| `container` | This has all ViewStyle properties. | | -| `button` | This has all ViewStyle properties. | | -| `button` | `size` | This is the radius of the button. | -| `button` | `rippleColor` | This is the color of the ripple on Android. | -| `buttonContainer` | This has all ViewStyle properties. | | -| `buttonIcon` | This has all ImageStyle properties. | | -| `secondaryButton` | This has all ViewStyle properties. | | -| `secondaryButton` | `size` | This is the radius of the secondary buttons. | -| `secondaryButtonIcon` | This has all ImageStyle properties. | | -| `secondaryButtonCaption` | This has all TextStyle properties. | | -| `secondaryButtonCaptionContainer` | This has all ViewStyle properties. | | - -The default class to style all floating actions buttons is named `com_mendix_widget_native_floatingactionbutton_FloatingActionButton`. - -### Maps - -The maps widget supports various digital map providers. This is how a maps widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/maps.png" alt="maps" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `loadingOverlay` | This has all ViewStyle properties. | | -| `loadingIndicator` | `color` | This is the color of the loading indicator. | -| `marker` | `color` | This is the color of the location marker. | -| `marker` | `opacity` | This is the opacity of the location marker. | - -The default class to style all map widgets is named `com_mendix_widget_native_maps_Maps`. - -### Notifications - -The notifications widget lets you display a custom message in your app. This widget has no user interface so does not support any styling. - -### Progress Bar - -The progress bar widget shows percentage of progress. This is how a progress bar widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/progress-bar.png" alt="progress bar" width="300" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `bar` | This has all ViewStyle properties. | | -| `fill` | `backgroundColor` | This is the background color of the filled progress bar portion. | -| `validationMessage` | This has all TextStyle properties. | | - -The default class to style all progress bars is named `com_mendix_widget_native_progressbar_ProgressBar`. - -### Progress Circle - -The progress circle widget displays progress in a circle using positive or negative values. This is how a progress circle widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/progress-circle.png" alt="progress circle" width="300" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `circle` | `size` | This is the radius of the progress circle. | -| `circle` | `borderWidth` | This is the border width of the progress circle. | -| `circle` | `borderColor` | This is the color of the progress circle border. | -| `fill` | `backgroundColor` | This is the color of the circle’s filled portion. | -| `fill` | `width` | This is the width of the progress circle. | -| `fill` | `lineCapRounded` | This determines if the rotating line’s front tip is rounded off or not. | -| `text` | This has all TextStyle properties. | | -| `validationMessage` | This has all TextStyle properties. | | - -The default class to style all progress circles is named `com_mendix_widget_native_progresscircle_ProgressCircle`. - -### QR Code - -The QR code widget generates a QR code based on a value, which a user can then scan. This is how a QR code widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/qr-code.png" alt="qr code" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `qrcode` | `size` | The size of the QR code. | -| `qrcode` | `color`| The color of the QR code. | -| `qrcode` | `backgroundColor` | The background color behind the QR code. | - -The default class to style all QR codes is named `com_mendix_widget_native_qrcode_QRCode`. - -### Range Slider {#range-slider} - -The range slider widget allows you to change a range of values using a slider with maximum and minimum bound values. This is how a range slider widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/range-slider.png" alt="range slider" width="300" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - - - - - - - - -``` - -| Element | Style Properties | Description | -| ---| --- | --- | -| `container` | This has all ViewStyle properties. | | -| `track` | This has all ViewStyle properties. | | -| `trackDisabled` | This has all ViewStyle properties. | | -| `highlight` | This has all ViewStyle properties. | | -| `highlightDisabled` | This has all ViewStyle properties. | | -| `marker` | This has all ViewStyle properties. | | -| `markerActive` | This has all ViewStyle properties. | | -| `markerDisabled` | This has all ViewStyle properties. | | -| `validationMessage` | This has all TextStyle properties. | | - -The default class to style all range slider inputs is named `com_mendix_widget_native_rangeslider_RangeSlider`. - -### Safe Area View - -The safe area view widget prevents content from being rendered in unwanted areas, such as behind rounded screen corners or notches. This widget is only supported on iOS apps. Note that `container` styling will only be applied to the safe area. - -The widget’s style properties are as follows: - -```xml -content -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | - -The default class to style all safe area views is named `com_mendix_widget_native_safeareaview_SafeAreaView`. - -### Slider - -The slider widget simply allows you to change a number value using a slider. This is how a slider widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/slider.png" alt="slider" width="300" class="no-border" >}} - -This widget supports the same style properties as the [range slider](#range-slider) widget above. - -The default class to style all slider inputs is named `com_mendix_widget_native_slider_Slider`. - -### Ratings - -The ratings widget allows users to rate an object from 0 to 5. This is how a ratings widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/ratings.png" alt="ratings" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - - - - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `containerDisabled` | This has all ViewStyle properties. | | -| `icon` | This has all ViewStyle properties. | | -| `icon` | `size` | The size of the icon. | -| `icon` | `color` | The color of the icon. | -| `icon` | `selectedColor` | The color of the icon when selected. | - -The default class to style all rating inputs is named `com_mendix_widget_native_rating_Rating`. - -### Toggle Buttons - -The toggle buttons widget allows you to set an enumeration attribute. This is how a toggle buttons widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/toggle-buttons.png" alt="toggle buttons" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - - Sattelite - - - - - - - Sattelite - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `containerDisabled` | This has all ViewStyle properties. | | -| `button` | This has all ViewStyle properties. | | -| `text` | This has all TextStyle properties. | | -| `activeButton` | This has all ViewStyle properties. | | -| `activeButtonText` | This has all TextStyle properties. | | -| `validationMessage` | This has all TextStyle properties. | | - -The default class to style all toggle buttons is named `com_mendix_widget_native_togglebuttons_ToggleButtons`. - -### Video Player - -The video player widget allows you to play video based on a URL, and is limited to MP4 only. This is how a video player widget could look in an app: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/video-player.png" alt="video player" width="300" class="no-border" >}} - -The widget’s style properties are as follows: - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `indicator` | `color` | The loading indicator color. | -| `video` | This has all ViewStyle properties. | | -| `errorMessage` | This has all TextStyle properties. | | -| `fullScreenVideoPlayer` | This has all ViewStyle properties. | Android only | -| `controlBtnContainerStyle` | This has all ViewStyle properties. | Android only | -| `fullScreenVideoStyle` | This has all ViewStyle properties. | Android only | -| `fullScreenActivityIndicatorStyle` | This has all ViewStyle properties. | Android only | - -The default class to style all video players is named `com_mendix_widget_native_videoplayer_VideoPlayer`. - -### Web View - -The web view widget allows you to embed static or dynamic websites in your app. The widget’s style properties are as follows: - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `errorContainer` | This has all ViewStyle properties. | | -| `errorText` | This has all TextStyle properties. | | - -The default class to style all web views is named `com_mendix_widget_native_webview_WebView`. - -### Animation - -The animation widget allows you to animate a container. You can make the content wiggle, move, change size, and more. - -The widget’s style properties are as follows: - -```xml - - {content} - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | - -The default class to style all animation widgets is named `com_mendix_widget_native_animation_Animation`. - -### Introduction Screen - -This introduction screen widget displays paginated contents you can swipe through, and offers buttons on each page to proceed or go back: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/intro-screen.gif" alt="intro screen" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - content - - - - - - Skip - - - Back - - - Next - - - Done - - - - - - content - - - Skip - - - Back - - - 4 / 5 - - - Next - - - Done - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `fullscreenContainer` | This has all ViewStyle properties. | | -| `popupContainer` | This has all ViewStyle properties. | | -| `paginationContainer` | This has all ViewStyle properties. | | -| `paginationText` | This has all TextStyle properties. | | -| `dotStyle` | This has all ViewStyle properties. | | -| `activeDotStyle` | This has all ViewStyle properties. | | -| `buttonsContainer` | This has all ViewStyle properties. | | -| `container` | This has all ViewStyle properties. | Meant for buttonSkip, buttonDone, buttonPrevious, and buttonNext. | -| `caption` | This has all ViewStyle properties. | | -| `icon` | `size` | The size of the icon. | -| `icon` | `color` | The color of the icon. | - -The default class to style all into screen widgets is named `com_mendix_widget_native_introscreen_IntroScreen`. - -### List View Swipe - -The list view swipe widget can make a list view interactive by adding swipe gestures and extra buttons in the background behind a list item: - -{{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/list-view-swipe-buttons.gif" alt="list view swipe" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - - {Left background} - - {Foreground} - - {Right background} - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `leftAction` | This has all ViewStyle properties. | | -| `leftAction` |`panelSize` | The number of pixels and the combined size of the background buttons. | -| `leftAction` |`threshold` | The number of pixels to accept the swipe action. | -| `rightAction` | This has all ViewStyle properties. | | -| `rightAction` |`panelSize` | The number of pixels and the combined size of the background buttons. | -| `rightAction` |`threshold` | The number of pixels to accept the swipe action. | - -The default class to style all animation widgets is named `com_mendix_widget_native_listviewswipe_ListViewSwipe`. - -### Bottom Sheet - -The bottom sheet widget creates a set of options while blocking interaction with the rest of the screen or a draggable surface anchored to the bottom of the screen. There are two customizable variations: - -* Modal bottom sheet: - - {{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/modal-bottom-sheet.gif" alt="modal bottom sheet" width="350" class="no-border" >}} - -* Expanding bottom sheet: - - {{< figure src="/attachments/refguide8/mobile/native-mobile/native-styling-refguide/expanding-bottom-sheet.gif" alt="expanding bottom sheet" width="350" class="no-border" >}} - -The widget’s style properties are as follows: - -```xml - - - - - - - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | This has all ViewStyle properties. | | -| `containerWhenExpandedFullscreen` | This has all ViewStyle properties. | Only available if `Expading` and `Enable full screen` are enabled. | -| `modal` | This has all ViewStyle properties. | | -| `defaultStyle` | This has all TextStyle properties. | Available when `Default` is selected as style for basic items. | -| `primaryStyle` | This has all TextStyle properties. | Available when `Primary` is selected as style for basic items. | -| `dangerStyle` | This has all TextStyle properties. | Available when `Danger` is selected as style for basic items. | -| `customStyle` | This has all TextStyle properties. | Available when `Custom` is selected as style for basic items. | - -The default class to style all bottom sheet widgets is named `com_mendix_widget_native_bottomsheet_BottomSheet`. - -### Popup Menu - -The popup menu widget allows you to show a context menu exactly where the user taps. - -The widget’s style properties are as follows: - -```xml - - - - - - - - - - - - - - - - - - - - -``` - -A main object has four objects. - -| Element | Style Properties | Description | -| ----------------------------| --- | ---------------------------------------------------------------------------------------------------------------- | -| basic | BasicItemStyle |Styles basic items. | -| custom | CustomItemStyle |Styles custom items. | -| buttonContainer | This has all ViewStyle properties. | Styles the wrapper view of triggerer since there could be multiple elements, and it has to be wrapped in a view. | -| container | This has all ViewStyle properties. | Styles the wrapper view around the whole menu. | - -#### BasicItemStyle - -| Element | Style Properties | Description | -| ---------------------------| ---- | ------------------------------------------------ | -| containerStyle | This has all ViewStyle properties. | Styles the wrapper container around a basic item. | -| itemStyle | ItemStyle | Styles the basic items. | -| dividerColor | `string` | Styles the divider color. | - -#### ItemStyle - -| Element | Style Properties | Description | -| ----------------------------------------| ----- | ------------------------------------------------------------------------------------------------ | -| ellipsizeMode | `head`, `middle`, `tail`, or `clip` | Styles how the text will be clipped if its too long. | -| rippleColor | `string` | Styles the color of touch feedback when item is tapped. Works for both iOS and Android platforms. | -| defaultStyle | This has all TextStyle properties. | Styles all basic menu items which have the `default` style selected. | -| primaryStyle | This has all TextStyle properties. | Styles all basic menu items which have the `primary` style selected. | -| dangerStyle | This has all TextStyle properties. | Styles all basic menu items which have the `danger` style selected. | -| customStyle | This has all TextStyle properties. | Styles all basic menu items which have the `custom` style selected. | - -#### CustomItemStyle - -| Element | Style Properties | Description | -| ---------------------------| ---- | ------------------------------------------------ | -| containerStyle | This has all ViewStyle properties. | Styles the wrapper container around a custom item. | -| itemStyle | `rippleColor: string` | Styles the color of touch feedback when item is tapped. Works for both iOS and Android platforms. | -| dividerColor | `string` | Styles the divider color. | - -The default class to style all popup menus is named `com_mendix_widget_native_popupmenu_PopupMenu`. - -### Carousel - -The carousel widget allows you to show swipeable items in a carousel. - -The widget’s style properties are as follows: - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -Main object has to have three objects called `container`, `cardLayout`, and `fullWidthLayout`. `cardLayout` and `fullWidthLayout` will be applied automatically depending on selected layout in widget properties. - -```text -export myCarouselStyle = { - container: ViewStyle // - cardLayout: ...LayoutStyle, - fullWidthLayout: ...LayoutStyle -} -``` - -| Element | Style Properties | Description | -| -----------------------|-------------------------------- | ---------------------------------------------------------------------------------------------- | -| container | This has all ViewStyle properties. | Styles the view surrounding the carousel widget. For best results, make sure to give a fixed `height`. | -| cardLayout | LayoutStyle | Styles the carousel when the layout is set to card | -| fullWidthLayout | LayoutStyle | Styles the carousel when the layout is set to full width. | - -#### LayoutStyle - -| Element | Style Properties | Description | -| -----------------------|-------------------------------- | ---------------------------------------------------------------------------------------------- | -| slideItem | This has all ViewStyle properties. | Styles the view surrounding each slide, including inactive slides. | -| inactiveSlideItem | `opacity: number, scale: number` | `inactiveSlideOpacity` and `inactiveSlideScale`, will allow inactive slides smaller and faded. | -| indicator | `color: string` | Styles the loading indicator which will be shown while the carousel is loading. | -| pagination | Pagination | Styles pagination container, dots, active dots, and text. | - -#### Pagination - -| Element | Style Properties | Description | -| ---------|------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | -| container | This has all ViewStyle properties. | Styles the main view around pagination, regardless of text or dot. | -| dotStyle | All ViewStyle properties + `color: string` | Styles all the pagination dots. | -| inactiveDotStyle| All ViewStyle properties + `opacity: number; scale: number; color: string` | Additional styles for inactive dots. Will be merged with `dotStyle`. | -| dotContainerStyle | This has all ViewStyle properties. | Styles the view around individual pagination dots. | -| text | This has all TextStyle properties. | Will be applied when there are more than five elements in carousel, in which case pagination buttons become text like **1/5**. | - -The default class to style all popup menus is named `com_mendix_widget_native_carousel_Carousel`. - -### Line Chart - -The [line chart](https://github.com/mendix/widgets-resources/blob/master/packages/pluggableWidgets/line-chart-native) widget renders a scalable line graph based on static and dynamic data sets. - -The widget consists of the following elements: - -```xml - - - - - - - - - - - - - - - - - - - - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `errorMessage` | All [TextStyle](https://reactnative.dev/docs/text-style-props) properties. | | -| `chart` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `grid` | `backgroundColor` | Applies a color to the grid background (string). | -| `grid` | `dashArray` | Applies a pattern of dashes and gaps to the grid lines (string containing a [dash pattern](https://www.w3.org/TR/SVG11/painting.html#StrokeDasharrayProperty)). | -| `grid` | `lineColor` | Applies a color to the grid lines (string). | -| `grid` | `lineWidth` | Applies a width to the grid lines (number). | -| `grid` | `padding` | Applies padding to all sides of the grid (number). Use it to make axis value labels visible. | -| `grid` | `paddingBottom` | Applies padding to the bottom side of the grid (number). Use it to make axis value labels visible. | -| `grid` | `paddingHorizontal` | Applies padding to the horizontal sides of the grid (number). Use it to make axis value labels visible. | -| `grid` | `paddingLeft` | Applies padding to the left side of the grid (number). Use it to make axis value labels visible. | -| `grid` | `paddingRight` | Applies padding to the right side of the grid (number). Use it to make axis value labels visible. | -| `grid` | `paddingTop` | Applies padding to the top side of the grid (number). Use it to make axis value labels visible. | -| `grid` | `paddingVertical` | Applies padding to the vertical sides of the grid (number). Use it to make axis value labels visible. | -| `xAxis` | `color` | Applies a color to the axis value labels (string). | -| `xAxis` | `dashArray` | Applies a pattern of dashes and gaps to the axis line (string containing a [dash pattern](https://www.w3.org/TR/SVG11/painting.html#StrokeDasharrayProperty)). | -| `xAxis` | `fontFamily` | Applies fonts to the axis value labels (string). | -| `xAxis` | `fontSize` | Applies a size to the axis value labels (number). | -| `xAxis` | `fontStyle` | Applies a font style to the axis value labels ("normal" or "italic"). | -| `xAxis` | `fontWeight` | Applies a font weight to the axis value labels ("normal" or "bold" or "100" or "200" or "300" or "400" or "500" or "600" or "700" or "800" or "900"). | -| `xAxis` | `lineColor` | Applies a color to the axis line (string). | -| `xAxis` | `lineWidth` | Applies a width to the axis line (number). | -| `xAxis` > `label` | All [TextStyle](https://reactnative.dev/docs/text-style-props) properties. | | -| `xAxis` > `label` | `relativePositionGrid` | Positions the axis label at the bottom or right side of the grid ("bottom" or "right"). | -| `yAxis` | All `xAxis` element styles. | | -| `yAxis` > `label` | All [TextStyle](https://reactnative.dev/docs/text-style-props) properties. | | -| `yAxis` > `label` | `relativePositionGrid` | Positions the axis label at the top or left side of the grid ("top" or "left"). | -| `legend` > `container` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `legend` > `item` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `legend` > `indicator` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `legend` > `label` | All [TextStyle](https://reactnative.dev/docs/text-style-props) properties. | | -| `lines` | `lineColorPalette` | Provides colors to lines that do not have a line color configured (string with list of colors separated by ';'). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `line` | `dashArray` | Applies a pattern of dashes and gaps to the graph line (string containing a [dash pattern](https://www.w3.org/TR/SVG11/painting.html#StrokeDasharrayProperty)). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `line` | `ending` | Applies a flat or rounded line end to the graph line ("flat" or "round"). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `line` | `lineColor` | Applies a color to the graph line (string). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `line` | `lineWidth` | Applies a width to the graph line (number). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `markers` | `backgroundColor` | Applies a background color to the markers of the graph line (string). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `markers` | `borderColor` | Applies a border color to the markers of the graph line (string). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `markers` | `borderWidth` | Applies a border width to the markers of the graph line (string). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `markers` | `display` | Influences whether markers are displayed. When displayed, it positions the markers of the graph line on top or underneath the line ("false" or "underneath" or "onTop"). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `markers` | `size` | Applies a size to the markers of the graph line (number). | -| `lines` > `customLineStyles` > `any_custom_line_style_name` > `markers` | `symbol` | Applies a symbol to the markers of the graph line ("circle" or "diamond" or "plus" or "minus" or "square" or "star" or "triangleDown" or "triangleUp"). | - -The default class to style all line chart widgets is named `com_mendix_widget_native_linechart_LineChart`. - -### Bar Chart - -The [bar chart](https://github.com/mendix/widgets-resources/blob/master/packages/pluggableWidgets/bar-chart-native) widget renders a horizontal bar graph based on static and dynamic data sets. - -The widget consists of the following elements: - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -| Element | Style Properties | Description | -| --- | --- | --- | -| `container` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `errorMessage` | All [TextStyle](https://reactnative.dev/docs/text-style-props) properties. | | -| `chart` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `grid` | `backgroundColor` | Applies a color to the grid background (string). | -| `grid` | `dashArray` | Applies a pattern of dashes and gaps to the grid lines (string containing a [dash pattern](https://www.w3.org/TR/SVG11/painting.html#StrokeDasharrayProperty)). | -| `grid` | `lineColor` | Applies a color to the grid lines (string). | -| `grid` | `width` | Applies a width to the grid lines (number). | -| `grid` | `padding` | Applies padding to all sides of the grid (number). This makes axis value labels visible. | -| `grid` | `paddingBottom` | Applies padding to the bottom side of the grid (number). This makes axis value labels visible. | -| `grid` | `paddingHorizontal` | Applies padding to the horizontal sides of the grid (number). This makes axis value labels visible. | -| `grid` | `paddingLeft` | Applies padding to the left side of the grid (number). This makes axis value labels visible. | -| `grid` | `paddingRight` | Applies padding to the right side of the grid (number). This makes axis value labels visible. | -| `grid` | `paddingTop` | Applies padding to the top side of the grid (number). This makes axis value labels visible. | -| `grid` | `paddingVertical` | Applies padding to the vertical sides of the grid (number). This makes axis value labels visible. | -| `xAxis` | `color` | Applies a color to the axis value labels (string). | -| `xAxis` | `dashArray` | Applies a pattern of dashes and gaps to the axis line (string containing a [dash pattern](https://www.w3.org/TR/SVG11/painting.html#StrokeDasharrayProperty)). | -| `xAxis` | `fontFamily` | Applies a font type to the axis value labels (string). | -| `xAxis` | `fontSize` | Applies a size to the axis value labels (number). | -| `xAxis` | `fontStyle` | Applies a font style to the axis value labels ("normal" or "italic"). | -| `xAxis` | `fontWeight` | Applies a font weight to the axis value labels ("normal" or "bold" or "100" or "200" or "300" or "400" or "500" or "600" or "700" or "800" or "900"). | -| `xAxis` | `lineColor` | Applies a color to the axis line (string). | -| `xAxis` | `lineWidth` | Applies a width to the axis line (number). | -| `xAxis` > `label` | All [TextStyle](https://reactnative.dev/docs/text-style-props) properties. | | -| `xAxis` > `label` | `relativePositionGrid` | Positions the axis label at the **bottom** or **right** side of the grid. | -| `yAxis` | All `xAxis` element styles. | | -| `yAxis` > `label` | All [TextStyle](https://reactnative.dev/docs/text-style-props) properties. | | -| `yAxis` > `label` | `relativePositionGrid` | Positions the axis label at the **top** or **left** side of the grid. | -| `legend` > `container` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `legend` > `item` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `legend` > `indicator` | All [ViewStyle](https://reactnative.dev/docs/view-style-props) properties. | | -| `legend` > `label` | All [TextStyle](https://reactnative.dev/docs/text-style-props) properties. | | -| `domain` > `padding` | `x` | Applies a number of pixels of padding to add the beginning and end of the X axis domain (number). | -| `domain` > `padding` | `y` | Applies a number of pixels of padding to add the beginning and end of the Y axis domain (number). | -| `bars` | `barColorPalette` | Provides colors to bars that do not have a bar color configured (string with list of colors separated by ';'). | -| `bars` | `barsOffset` | Determines the number of pixels each bar in a group should be offset from its original position on the Y axis (number). This is only applicable when presentation mode is **Grouped**. | -| `bars` > `customBarStyles` > `any_custom_bar_style_name` > `bar` | `ending` | Specifies a radius to apply to each bar. | -| `bars` > `customBarStyles` > `any_custom_bar_style_name` > `bar` | `color` | Applies a color to the bar (string). If bars are configured to have labels, the labels will be the same color as the bar. | -| `bars` > `customBarStyles` > `any_custom_bar_style_name` > `bar` | `width` | Applies a width to the bar (number). | -| `bars` > `customBarStyles` > `any_custom_bar_style_name` > `label` | `fontFamily` | Applies a font type to the bar label (string). | -| `bars` > `customBarStyles` > `any_custom_bar_style_name` > `label` | `fontSize` | Applies a size to the bar label (number). | -| `bars` > `customBarStyles` > `any_custom_bar_style_name` > `label` | `fontStyle` | Applies a font style to the bar label (**normal** or **italic**). | -| `bars` > `customBarStyles` > `any_custom_bar_style_name` > `label` | `fontWeight` | Applies a font weight to the bar label ("normal" or "bold" or "100" or "200" or "300" or "400" or "500" or "600" or "700" or "800" or "900"). | - -The default class to style all bar chart widgets is named `com_mendix_widget_native_barchart_BarChart`. - -## Read More - -* [How to Style Your Mendix Native Mobile App](/howto8/mobile/how-to-use-native-styling/) -* [How to Implement Native Mobile Styling](/howto8/mobile/native-styling/) -* [Design Properties Documentation](/apidocs-mxsdk/apidocs/design-properties/) diff --git a/content/en/docs/refguide8/mobile/native-mobile/native-svg.md b/content/en/docs/refguide8/mobile/native-mobile/native-svg.md deleted file mode 100644 index a7174e5301c..00000000000 --- a/content/en/docs/refguide8/mobile/native-mobile/native-svg.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "Working with Vector Graphics" -url: /refguide8/native-svg/ -weight: 80 -description: "Learn how to integrate SVGs into your native mobile apps." ---- - -## Introduction - -When building a native mobile application, you may want to use vector images for icons or other illustrations. For this purpose, you can use Scalable Vector Graphics (SVGs). This reference guide will provide guidance for working with SVGs in native mobile apps. - -## Optimizing SVGs {#optimizing} - -When exporting an SVG from an editor, you will often produce an SVG with several unnecessary elements. These elements increase file size, decrease performance, and can cause unwanted side effects. Therefore it is recommended that you run your SVG through an SVG-optimization tool. - -To optimize your SVGs, you can either run them through an online tool such as [SVGOMG](https://jakearchibald.github.io/svgomg/) or use a local tool such as [SVGO](https://github.com/svg/svgo). - -{{% alert color="info" %}}Some users have experienced an issue where SVGs are not visible in the Make It Native testing app. When deploying changed SVG images, it may be necessary to clean the deployment folder first. In Studio Pro, click on **App** > **Clean Deployment Directory**. When recompiling, any new images will now become visible in the Make It Native app.{{% /alert %}} - -## Unsupported Elements - -SVGs can contain several kinds of elements. However, not all of them are supported in native mobile apps. Unsupported elements will have no effect and should be removed. The following SVG elements are *not* supported for native mobile apps: - -* Complex gradients -* Animations -* Video -* JavaScript code -* CDATA elements -* `