Skip to content

Client API updates #9709

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Jul 3, 2025
Merged

Client API updates #9709

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
6974a0c
Updated docs that mention mx.session.getConfig("csrftoken") to use ge…
exec-astraea Jun 19, 2025
002e67b
Updated docs that use mx.data.create to use the new APIs
exec-astraea Jun 19, 2025
2de1bd5
Removed obsolete section on wrapping old APIs in promises
exec-astraea Jun 19, 2025
5aee559
Use window.reload() instead of mx.reloadWithState()
exec-astraea Jun 19, 2025
edc993b
Modernized JS syntax in the examples
exec-astraea Jun 23, 2025
591337e
Revise
quinntracy Jun 23, 2025
457d1eb
Revise
quinntracy Jun 23, 2025
47cd100
Revise
quinntracy Jun 23, 2025
4165acc
Change version wording
quinntracy Jun 23, 2025
ccd7a3a
Minor proofreading changes
MarkvanMents Jun 24, 2025
c41eab4
Proofread
MarkvanMents Jun 24, 2025
3a3598d
Clarify which code to use in Mx10.22 and below
MarkvanMents Jul 2, 2025
000194b
Correct version number error.
MarkvanMents Jul 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 10 additions & 41 deletions content/en/docs/howto/extensibility/best-practices-javascript-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,18 +183,17 @@ For information on how to use *Big.js*, consult the [big.js API](https://mikemcl
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);
}
});
import { create } from "mx-api/data"

try {
const cat = await create({ entity: "MyFirstModule.Cat" })
console.log("Object created on server:", cat);
} catch (err) {
console.error("Could not commit object:", err);
}
```

For more information on creating objects, consult the [Create](https://apidocs.rnd.mendix.com/10/client/mx.data.html#.create) section of the *Mendix Client API*.
For more information on creating objects, consult the [Create](https://apidocs.rnd.mendix.com/11/client-mx-api/module-mx-api_data.html#.create) section of the *Mendix Client API*.

#### Changing Objects

Expand Down Expand Up @@ -288,37 +287,7 @@ Use the following code to employ an asynchronous return for when your nanoflow n
}
```

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
Many APIs and functions are designed in an asynchronous way, and use callback functions or [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). A JavaScript action expects a promise to be returned. The promise should be resolved with the return value as expected in the action.

#### Understanding Promise API

Expand Down
109 changes: 49 additions & 60 deletions ...en/docs/howto/extensibility/build-javascript-actions/write-javascript-github.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ To create a JavaScript action that can search for users on GitHub, follow the st
const url = "https://api.github.com/search/users?q=" + query;
const response = await fetch(url); // Fetch returns a promise, gets the url and wait for result
const jsonData = await response.json(); // Transform to JSON
logger.debug("count results", jsonData.total_count); // log to the console a successful result
console.log("count results", jsonData.total_count); // log to the console a successful result
return []; // return an empty list for now...
// END USER CODE
}
Expand All @@ -104,6 +104,8 @@ To create a JavaScript action that can search for users on GitHub, follow the st
10. Finally, set a `Promise.all` return to wait for all promises to be resolved before the nanoflow can continue:

```javascript
import { create } from "mx-api/data"

export async function SearchGitHubUsers(query) {
// BEGIN USER CODE
if (!query) {
Expand All @@ -112,24 +114,19 @@ To create a JavaScript action that can search for users on GitHub, follow the st
const url = "https://api.github.com/search/users?q=" + query;
const response = await fetch(url);
const jsonData = await response.json();
logger.debug("count", jsonData.total_count);
console.log("count", jsonData.total_count);
const 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 not create object:" + error.message);
}
});
});
async function createGitHubUser(user) {
try {
const mxObject = await create({ entity: "HowTo.GitHubUser" });
mxObject.set("login", user.login);
mxObject.set("avatar_url", user.avatar_url);
return mxObject;
} catch(err) {
throw new Error("Could not create object:" + err.message)
}
}
// END USER CODE
}
Expand All @@ -140,6 +137,8 @@ To create a JavaScript action that can search for users on GitHub, follow the st
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
import { create } from "mx-api/data"

export async function SearchGitHubUsers(query) {
// BEGIN USER CODE
if (!query) {
Expand All @@ -148,30 +147,25 @@ To create a JavaScript action that can search for users on GitHub, follow the st
const url = "https://api.github.com/search/users?q=" + query;
const response = await fetch(url);
const jsonData = await response.json();
logger.debug("count", jsonData.total_count);
console.log("count", jsonData.total_count);
const 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 not create object:" + error.message);
}
});
});
async function createGitHubUser(user) {
try {
const mxObject = await create({ entity: "HowTo.GitHubUser" });
// Dynamically set attributes
mxObject.getAttributes()
.forEach(attributeName => {
const attributeValue = user[attributeName];
if (attributeValue) {
mxObject.set(attributeName, attributeValue);
}
});
return mxObject;
} catch(err) {
throw new Error("Could not create object:" + err.message)
}
}
// END USER CODE
}
Expand All @@ -196,9 +190,11 @@ To create a JavaScript action that can search for users on GitHub, follow the st

{{< figure src="/attachments/howto/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:
15. Your final step is updating the code. The new `userEntity` parameter has already been added. In the `create` function, set `userEntity` as the `entity` to be created. Then, add some documentation for future reference:

```javascript
import { create } from "mx-api/data"

/*
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.
Expand All @@ -225,31 +221,24 @@ To create a JavaScript action that can search for users on GitHub, follow the st
const url = "https://api.github.com/search/users?q=" + query;
const response = await fetch(url);
const jsonData = await response.json();
logger.debug("count", jsonData.total_count);
const 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) {
const attributeValue = user[attributeName];
if (attributeValue) {
mxObject.set(attributeName, attributeValue);
}
});
resolve(mxObject);
},
error: function(error) {
reject("Could not create object:" + error.message);
}
});
});
async function createGitHubUser(user) {
try {
const mxObject = await create({ entity: userEntity });
// Dynamically set attributes
mxObject.getAttributes()
.forEach(attributeName => {
const attributeValue = user[attributeName];
if (attributeValue) {
mxObject.set(attributeName, attributeValue);
}
});
return mxObject;
} catch(err) {
throw new Error("Could not create object:" + err.message)
}
}
// END USER CODE
}
Expand Down
8 changes: 7 additions & 1 deletion content/en/docs/howto/security/best-practices-security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,13 @@ This authentication option is not available for Published Web Services and can o

If you choose this option, the API will expect a "X-Csrf-Token" HTTP request header to be set on each incoming request. This authentication option is particularly interesting for custom JavaScript and widget implementations.

The session token can be acquired by calling `mx.session.getConfig("csrftoken")` in JavaScript. This method call should be used before each API call to prevent cross-site request forgery (CSRF/XSRF).
The session token can be acquired by calling a Mendix Client API method to get the current CSRF token. This method should be called before each API call in your widget or JavaScript action to prevent cross-site request forgery (CSRF/XSRF).

```javascript
import getCSRFToken from "mx-api/session";

const token = getCSRFToken();
```

#### Authentication Option 3, Custom {#custom}

Expand Down
39 changes: 20 additions & 19 deletions content/en/docs/howto10/extensibility/best-practices-javascript-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,21 +180,22 @@ For information on how to use *Big.js*, consult the [big.js API](https://mikemcl

#### Creating Objects

Use the following code to create objects:
Use the following code to create objects in Mendix version 10.23 and above:

```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);
}
});
import { create } from "mx-api/data"

try {
const cat = await create({ entity: "MyFirstModule.Cat" })
console.log("Object created on server:", cat);
} catch (err) {
console.error("Could not commit object:", err);
}
```

For more information on creating objects, consult the [Create](https://apidocs.rnd.mendix.com/10/client/mx.data.html#.create) section of the *Mendix Client API*.
For more information on creating objects, consult the [Create](https://apidocs.rnd.mendix.com/10/client-mx-api/module-mx-api_data.html#.create) section of the *Mendix Client API*.
Comment on lines +186 to +196
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to keep the old information as well for those who are still using MTS versions of Mendix 10.


If you are using Mendix version 10.22 or below, you will need to use [`mx.data.create`](https://apidocs.rnd.mendix.com/10/client/mx.data.html#.create).

#### Changing Objects

Expand Down Expand Up @@ -290,11 +291,17 @@ Use the following code to employ an asynchronous return for when your nanoflow n

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.

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 Promises

A `Promise` object represents the eventual completion (or failure) of an asynchronous operation and its resulting value.
If you are using Mendix version 10.22 or below, you will need to use 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:
Use the following code in Mendix versions 10.23 or below to wrap a callback API in a promise:

```javascript
function AskConfirmation(question) {
Expand All @@ -314,12 +321,6 @@ function AskConfirmation(question) {
}
```

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 Fetch API:
Expand Down
Loading