docs.sheetjs.com/docz/docs/02-getting-started/01-installation/04-amd.md

249 lines
5.8 KiB
Markdown
Raw Normal View History

2022-06-11 17:21:26 +00:00
---
title: AMD (define)
2022-08-24 23:48:22 +00:00
pagination_prev: getting-started/index
2023-07-26 20:18:07 +00:00
pagination_next: getting-started/examples/index
2022-08-31 06:46:03 +00:00
sidebar_position: 4
2022-06-11 17:21:26 +00:00
sidebar_custom_props:
2022-06-22 19:25:24 +00:00
summary: NetSuite, SAP UI5, RequireJS
2022-06-11 17:21:26 +00:00
---
import current from '/version.js';
2023-04-29 11:21:37 +00:00
import CodeBlock from '@theme/CodeBlock';
2022-06-11 17:21:26 +00:00
Each standalone release script is available at https://cdn.sheetjs.com/.
2022-06-11 17:21:26 +00:00
`xlsx.full.min.js` supports AMD with name `xlsx` out of the box.
<p><a href={"https://cdn.sheetjs.com/xlsx-" + current + "/package/dist/xlsx.full.min.js"}>{"https://cdn.sheetjs.com/xlsx-" + current + "/package/dist/xlsx.full.min.js"}</a> is the URL for {current}</p>
2022-06-11 17:21:26 +00:00
2023-08-17 20:30:13 +00:00
:::note pass
2022-06-22 19:25:24 +00:00
When referencing by file name, AMD loaders typically omit the file extension.
2023-10-27 01:49:35 +00:00
The actual file name is `xlsx.full.min.js`, but the examples identify the script
using the name `xlsx.full.min`
2022-06-22 19:25:24 +00:00
:::
2023-06-25 09:36:58 +00:00
:::tip pass
2023-04-27 09:12:19 +00:00
[Watch the repo](https://git.sheetjs.com/SheetJS/sheetjs) or subscribe to the
[RSS feed](https://git.sheetjs.com/sheetjs/sheetjs/tags.rss) to be notified when
new versions are released!
:::
2022-06-11 17:21:26 +00:00
## NetSuite
2024-01-17 20:22:38 +00:00
After downloading the script and uploading to the file cabinet, a module alias
must be added to the `@NAmdConfig` configuration file:
```json title="JsLibraryConfig.json"
{
"paths": {
// highlight-next-line
"xlsx": "/path/to/xlsx.full.min"
}
}
```
2022-06-11 17:21:26 +00:00
2024-01-17 20:22:38 +00:00
Once added, SuiteScripts can reference the package using the name `xlsx`:
```js title="SuiteScript"
/**
* @NApiVersion 2.x
* ... more options ...
// highlight-next-line
* @NAmdConfig ./JsLibraryConfig.json
*/
// highlight-next-line
define(['N/file', 'xlsx'], function(file, XLSX) {
// ... use XLSX here ...
});
2022-06-11 17:21:26 +00:00
```
2024-01-17 20:22:38 +00:00
**More details are included in the [NetSuite demo](/docs/demos/cloud/netsuite#installation)**
2022-06-11 17:21:26 +00:00
:::caution Oracle Bugs
[NetSuite users reported](https://git.sheetjs.com/sheetjs/sheetjs/issues/3097)
errors that stem from an Oracle issue. A sample error message is shown below.
```
Fail to evaluate script: com.netsuite.suitescript.scriptobject.GraalValueAdapter@68d0f09d
```
**This is a NetSuite bug. Only Oracle can fix the bug!**
It is strongly encouraged to escalate the issue with Oracle support.
NetSuite users have reported success with the following workaround:
1) Open the script in a text editor and search for `define(` in the code.
There will be exactly one instance:
```js
define("xlsx",function(){
```
Replace the `xlsx` with `sheetjs`:
```js
define("sheetjs",function(){
```
2) Use the new name in the JSON configuration:
```json title="JsLibraryConfig.json"
{
"paths": {
// highlight-next-line
"sheetjs": "/path/to/xlsx.full.min"
}
}
```
3) Use the new name in the array argument to the `define` function call:
```js title="SuiteScript"
/**
* @NApiVersion 2.x
* ... more options ...
// highlight-next-line
* @NAmdConfig ./JsLibraryConfig.json
*/
// highlight-next-line
define(['N/file', 'sheetjs'], function(file, XLSX) {
// ^^^^^^^ ^^^^
// new module name same variable
// ... use XLSX here ...
});
```
:::
2022-06-22 19:25:24 +00:00
## SAP UI5
After downloading the script, it can be uploaded to the UI5 project and loaded
in the `sap.ui.define` call:
```js
sap.ui.define([
/* ... other libraries ... */
"path/to/xlsx.full.min"
], function(/* ... variables for the other libraries ... */, XLSX) {
// use XLSX here
})
```
2023-08-17 20:30:13 +00:00
:::warning pass
2022-06-22 19:25:24 +00:00
**Copy and pasting code does not work** for SheetJS scripts as they contain
Unicode characters that may be mangled. The standalone script should be
downloaded and manually uploaded to the project.
:::
2022-06-11 17:21:26 +00:00
## RequireJS
2023-08-17 20:30:13 +00:00
:::caution pass
2022-06-11 17:21:26 +00:00
2022-09-22 00:20:14 +00:00
The standalone script must be aliased to the path `xlsx`.
2022-06-27 02:05:36 +00:00
2022-06-11 17:21:26 +00:00
The `requirejs.config` function can define aliases through the `paths` key:
```js
requirejs.config({
paths: {
xlsx: [ './xlsx.full.min' ]
}
});
```
2022-06-27 02:05:36 +00:00
2022-09-22 00:20:14 +00:00
:::
After configuring the alias, app code can freely require `xlsx`:
2022-06-27 02:05:36 +00:00
```js
require(['xlsx'], function(XLSX) {
// ... use XLSX here
});
```
2022-08-30 22:12:52 +00:00
2023-10-19 05:23:55 +00:00
**See the [RequireJS demo](/docs/demos/frontend/bundler/requirejs) for details**
2022-08-30 22:12:52 +00:00
## Dojo Toolkit
Dojo has changed module loading strategies over the years. These examples were
2023-08-17 20:30:13 +00:00
tested with Dojo `1.17.3`. They are not guaranteed to work with other versions.
2022-08-30 22:12:52 +00:00
2023-11-28 07:05:59 +00:00
Live demos are included in ["Dojo Toolkit"](/docs/demos/frontend/dojo)
2022-08-30 22:12:52 +00:00
2023-08-17 20:30:13 +00:00
:::caution pass
2022-08-30 22:12:52 +00:00
The standalone scripts add `window.XLSX`, so it is recommended to use `_XLSX`
in the function arguments and access the library with `XLSX` in the callback:
```js
require(["xlsx"], function(
// highlight-next-line
_XLSX // !! NOTE: this is not XLSX! A different variable name must be used
) {
// highlight-next-line
console.log(XLSX.version); // use XLSX in the callback
})
```
:::
#### Synchronous Loading
2023-07-06 07:21:41 +00:00
When `async` is set to `false` or `0`, the scripts can be directly referenced in
`require` calls.
2022-08-30 22:12:52 +00:00
2023-04-29 11:21:37 +00:00
<CodeBlock language="html">{`\
2023-08-17 20:30:13 +00:00
<script src="dojo.js" data-dojo-config="isDebug:1, async:0"></script>
2022-08-30 22:12:52 +00:00
<script>
require([
// highlight-next-line
2023-04-29 11:21:37 +00:00
"https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"
2022-08-30 22:12:52 +00:00
], function(
// highlight-next-line
_XLSX // !! NOTE: this is not XLSX! A different variable name must be used
) {
// ... use XLSX here
2023-04-29 11:21:37 +00:00
});
</script>`}
</CodeBlock>
2022-08-30 22:12:52 +00:00
#### Asynchronous Loading
When `async` is enabled, Dojo will only understand the name `xlsx`. The config
object can map package names to scripts:
2023-04-29 11:21:37 +00:00
<CodeBlock language="html">{`\
2022-08-30 22:12:52 +00:00
<script>
// This setting must appear *before* loading dojo.js
dojoConfig = {
packages: [
// highlight-start
{
name: "xlsx",
// if self-hosting the script, location should be a folder relative to baseUrl setting
2023-04-29 11:21:37 +00:00
location: "https://cdn.sheetjs.com/xlsx-${current}/package/dist",
2022-08-30 22:12:52 +00:00
// name of the script (without the .js extension)
main: "xlsx.full.min"
}
// highlight-end
]
2023-04-29 11:21:37 +00:00
};
2022-08-30 22:12:52 +00:00
</script>
2023-08-17 20:30:13 +00:00
<script src="dojo.js" data-dojo-config="isDebug:1, async:1"></script>
2022-08-30 22:12:52 +00:00
<script>
require(["xlsx"], function(_XLSX) {
// ... use XLSX here
});
2023-04-29 11:21:37 +00:00
</script>`}
2023-07-26 20:18:07 +00:00
</CodeBlock>