Skip to content

Revert "Updating SPA samples to use public npm types" #49

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 1 commit into from
Apr 29, 2024
Merged

Revert "Updating SPA samples to use public npm types" #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 0 additions & 16 deletions .gitignore
View file
Open in desktop

This file was deleted.

176 changes: 59 additions & 117 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,117 +1,59 @@
# Single Page Application (SPA) SuiteApp Samples

This repository contains sample SuiteApps that use single page applications (SPAs). These SPAs are part of SuiteApp projects created using SuiteCloud Development Framework (SDF), and are built using the UI components available in the NetSuite User Interface Framework (UIF).

These samples use the SPA SuiteApp project template that contains a TypeScript compiler, which enables you to develop SuiteApps using JSX and `import` rather than `require`. It also enables you to use JavaScript or TypeScript in your script files.

Each sample SuiteApp contains `ESLint` and `Prettier` configuration files, and you can configure them using the `inspect` and `lint` npm scripts available in each SuiteApp. Using both is highly recommended to ensure adherence to coding standards.

## Availability
The Single Page Application feature in NetSuite is available by request only. Currently, this feature can be enabled only for SDN partners with a publisher ID. This feature requires the use of SuiteCloud Development Framework (SDF) SuiteApp projects and SuiteScript 2.1. For information about the requirements to use this feature and how to request access, see [Single Page Applications](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_161244635803.html#Single-Page-Applications).

## Environment Setup

### NetSuite Account Setup

1. Go to `Setup > Company > Enable features`.
1. Click the `SuiteCloud` subtab.
1. Enable the following features:
- `Client SuiteScript`
- `Server SuiteScript`
- `Token-based Authentication`
- `OAuth 2.0`
- `SuiteCloud Development Framework`
1. Set up SuiteCloud Development Framework (SDF). For more information, see [SuiteCloud Development Framework Setup](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4724784139.html#SuiteCloud-Development-Framework-Setup).
1. Enable all the features detailed in the project's `manifest.xml` file.

### SuiteCloud Command Line Tools

1. Install NodeJS https://nodejs.org/en/ if you don't have it installed.
1. Open console and install the SuiteCloud CLI: `npm i -g @oracle/suitecloud-cli`.

### SuiteCloud Development Tools
Set up your preferred development tool. You can choose from the following SuiteCloud Software Development Kit (SDK) tools:
- [SuiteCloud Extension for Visual Studio Code](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/book_159223417590.html#SuiteCloud-Extension-for-Visual-Studio-Code)
- [SuiteCloud IDE Plug-in for WebStorm](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/book_1529085902.html#SuiteCloud-IDE-Plug-in-for-WebStorm)
- [SuiteCloud CLI for Java](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/book_1558706585.html#SuiteCloud-CLI-for-Java)
- [SuiteCloud CLI for Node.js](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/book_1558706016.html#SuiteCloud-CLI-for-Node.js)


## Sample SuiteApps

There are several SuiteApps in the repository including basic Hello World apps, apps demonstrating basic NetSuite UIF
principles, and complex apps that demonstrate full-scale NetSuite UIF features and use SuiteScript to handle NetSuite data.

SuiteApps written in Javascript are marked with `(JS)` at the end of the description, and those written in TypeScript are marked with `(TS)`.

- [Airport 360](./airport360) - Sample 360-type SuiteApp that demonstrates the use of various NetSuite UIF features such as routing, side menu, state management, asynchronous loading, and SuiteScript APIs (TS)
- [Basics - Routing](./basics-routing) - Demonstrates the basic principles of routing (TS)
- [Basics - State Management](./basics-state-management) - Demonstrates the basic principles of state management (TS)
- [Hello World - JS](./helloworld-js/) - Minimal 'Hello World!' app (JS)
- [Hello World - TS](./helloworld-ts/) - Minimal 'Hello World!' app (TS)
- [Item 360](./item360/) - Sample 360-type SuiteApp that demonstrates common SPA patterns and data handling using SuiteScript (TS)

### NetSuite UIF TypeScript Type Declarations

The SuiteApps use the NetSuite UIF TypeScript type declarations ([@netsuite-uif-types](https://www.npmjs.com/package/@oracle/netsuite-uif-types)). Type declarations allow the TypeScript compiler to validate the usage of NetSuite UIF APIs and provide you with a rich IntelliSense experience in various IDEs. The use of NetSuite UIF type declarations is configured in the following files:

In the `package.json`:
```json
devDependencies: {
"@oracle/netsuite-uif-types": "^5.0.0",
"typescript": "^5.2.0"
}
```

In the `tsconfig.json`:
```json
{
"compilerOptions": {
"typeRoots": [
"node_modules/@types",
"node_modules/@oracle/netsuite-uif-types"
]
}
}
```

### Project Structure
SPA source files must be transpiled and converted before you can deploy a SuiteApp project with SPAs. A specific folder structure is required to ensure that the conversion process creates the correct output.

The SuiteApps in this repository use the required folder structure to implement SPAs, which includes the following files and folders:
- `/src/SuiteApps/{ApplicationID}/{SpaFolder}` contains the sources for the SPA and the `assets` folder for static assets.
- `/test` contains unit tests and test stubs.
- `/src/manifest.xml` and `/src/deploy.xml` contain the configuration of the SuiteApp.
- `/src/Objects/custspa_xxx.xml` contains the object definition for the `singlepageapp` SDF custom object.
- `/src/FileCabinet/SuiteApps/{ApplicationID}/{SpaFolder}` contains the transpiled and converted sources that are pushed to NetSuite.

### Build Setup
The SuiteApps also contain a `gulpfile` that implements the build and bundle steps to convert SPA source files. The tasks are defined in the `package.json` and are available using npm. It is also possible to configure the source concatenation and minification in the `gulpfile` using the `concatenateScripts` and `minifyScripts` variables.

To build the SuiteApp:
1. Open a terminal or command line.
1. Navigate to the directory of the corresponding app folder.
1. Run `npm i` to install build dependencies.
1. Optionally, run `npm run lint` to invoke linters.
1. Run `npm run build` to build the project. This task runs the TypeScript compiler on the files in `src/SuiteApps/{ApplicationID}/{SpaFolder}` and saves the result in a new `build` directory.
1. Run `npm run bundle` to bundle the built app. This task takes the transpiled sources from the `build` directory, bundles them together and minifies them. The result is saved in `src/FileCabinet/SuiteApps/{ApplicationID}/{SpaFolder}` and is ready to be deployed to the target NetSuite account.

### SuiteApp Deployment

1. Log in to your development environment.
1. Set up the SuiteCloud account.
- For SuiteCloud Extension for Visual Studio Code, see [Setting Up Accounts in SuiteCloud Extension for Visual Studio Code](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_160147609118.html#Setting-Up-NetSuite-Accounts-in-SuiteCloud-Extension-for-Visual-Studio-Code)
- For SuiteCloud IDE Plug-in for WebStorm, see [SuiteCloud IDE Plug-in for WebStorm Account Setup](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1530731998.html#SuiteCloud-IDE-Plug-in-for-WebStorm-Account-Setup)
- For SuiteCloud CLI for Java, see [authenticate](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157052592790.html#authenticate)
- For SuiteCloud CLI for Node.js, see [account:setup](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_89132630266.html)
1. Deploy the built SuiteApp to the target NetSuite account. Run `npm run deploy` or refer to the following topics for tool-specific instructions.
- For SuiteCloud Extension for Visual Studio Code, see [Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud Extension for Visual Studio Code](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_160147342366.html#Deploying-a-SuiteCloud-Project-to-Your-NetSuite-Account-with-SuiteCloud-Extension-for-Visual-Studio-Code)
- For SuiteCloud IDE Plug-in for WebStorm, see [Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud IDE Plug-in for WebStorm](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1539789992.html#Deploying-a-SuiteCloud-Project-to-Your-NetSuite-Account-with-SuiteCloud-IDE-Plug-in-for-WebStorm)
- For SuiteCloud CLI for Java, see [deploy](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4788673412.html#deploy)
- For SuiteCloud CLI for Node.js, see [project:deploy](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_156044636320.html#project%3Adeploy)
1. Open the single page application in your NetSuite account by going to `Customization > Scripting > Single Page Applications`.

## Links
- [Single Page Applications](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_161244635803.html#Single-Page-Applications)
- [SuiteCloud CLI](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_1558708800.html#SuiteCloud-CLI-for-Node.js-Guide)
- [SuiteCloud Development Framework](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/book_4702638251.html#SuiteCloud-Development-Framework)
![image](https://user-images.githubusercontent.com/52827300/220511950-34c148c4-b8f8-452e-b01d-201070f0cd0a.png)

# NetSuite SuiteCloud Samples

This repository holds a variety of sample projects meant to demonstrate the ways that account customization projects can be created on [NetSuite's SuiteCloud platform](https://www.netsuite.com/portal/platform.shtml). Each folder represents an independent project with its own README.md file for detailed descriptions of the use case and customization.

## Prerequisites
* You will need access to a NetSuite account that can be used with test data, such as a NetSuite sandbox account or trial/demo/training account.
* You will need one of the following tools from the SuiteCloud Developer Toolkit:
* [SuiteCloud Extension for Visual Studio Code](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_159223155621.html)
* [SuiteCloud Plug-in for Webstorm](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1529431804.html)
* [SuiteCloud Node CLI](https://github.com/oracle/netsuite-suitecloud-sdk)
* [SuiteCloud Java CLI](https://github.com/oracle/netsuite-suitecloud-sdk)
* Existing knowledge of NetSuite, SuiteScript, and the SuiteCloud Development Framwork is helpful but not required.

## Installation

You can download a folder as a complete SDF account customization project. After you download the project, you can either open it using an IDE that offers the NetSuite SuiteCloud IDE Plug-In or Extension, such as WebStorm or Visual Studio Code, or you can connect it to a NetSuite account using Node CLI or Java CLI. In the IDE, you can see each of the customization objects (the scripts, custom fields, and saved search) represented as an XML file. Using the SuiteCloud IDE Plug-In or Extension, you can then choose to deploy the entire solution to your account for testing.

While the script deployments in the project default to Testing mode, the custom fields and saved search may be visible to others in your account. Use caution when choosing the NetSuite account and account type to download and test.


For information about deploying the project from the IDE to your account, see:

[Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud IDE Plug-in for WebStorm](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1539789992.html)

[Deploying a SuiteCloud Project to Your NetSuite Account with SuiteCloud Extension for Visual Studio Code](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_160147342366.html)

This project utilizes a custom set of configurable JavaScript linting rules to automatically fix and format your code. You can optionally install ESLint into your local environment to receive code suggestions and find potential issues. For more information, see [ESLint](https://eslint.org/).

## Documentation

NetSuite's online documentation can be found in the Oracle Help Center at [docs.oracle.com](https://docs.oracle.com/en/cloud/saas/netsuite/index.html). The platform documentation can be found here:
- SuiteCloud Platform Customization - https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_1529088392.html

User guides in downloadable PDF format for NetSuite are listed here: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/preface_3710621755.html

## Examples

SuiteCloud Development Framework (SDF) Tutorial - https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4702655701.html
SuiteCloud Customization Tutorials - https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_159163143019.html

## Contributing

This project is not accepting external contributions at this time. For bugs or enhancement requests, please file a GitHub issue unless it’s security related. When filing a bug remember that the better written the bug is, the more likely it is to be fixed. If you think you’ve found a security vulnerability, do not raise a GitHub issue and follow the instructions in our [security policy](./SECURITY.md).

## Security

Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.

## License
Copyright (c) 2023 Oracle and/or its affiliates The Universal Permissive License (UPL), Version 1.0.

Released under the Universal Permissive License v1.0 as shown at
<https://oss.oracle.com/licenses/upl/>.

## Disclaimer

The sample code included herein is provided on an "as is" basis, without warranty of any kind, to the fullest extent permitted by law. Oracle + NetSuite Inc. does not warrant or guarantee the individual success developers may have in implementing the sample code on their development platforms or in using their own Web server configurations. Oracle + NetSuite Inc. does not warrant, guarantee or make any representations regarding the use, results of use, accuracy, timeliness or completeness of any data or information relating to the sample code. Oracle + NetSuite Inc. disclaims all warranties, express or implied, and in particular, disclaims all warranties of merchantability, fitness for a particular purpose, and warranties related to the code, or any service or software related thereto. Oracle + NetSuite Inc. shall not be liable for any direct, indirect or consequential damages or costs of any type arising out of any action taken by you or others related to the sample code.
14 changes: 7 additions & 7 deletions spa-suiteapp-samples/airport360/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Airport 360 - Sample Single Page Application (SPA) SuiteApp

This sample SPA SuiteApp demonstrates a working example of a 360-type SuiteApp. It shows a complete example that uses various NetSuite User Interface Framework (UIF) features such as routing, side menu, state management, asynchronous loading, and SuiteScript APIs.
This sample SPA SuiteApp demonstrates a working example of a 360-type SuiteApp. It shows a complete example that uses various NetSuite UI Framework (UIF) features such as routing, side menu, state management, asynchronous loading, and SuiteScript APIs.

The Airport 360 SuiteApp features a `Dashboard` page that provides information about the next departing flights, and informs you about closed gates and unassigned flights. Flights without assigned gates are highlighted on the list, so you can easily see which ones require action.

Expand All @@ -12,20 +12,20 @@ You can assign or change the gate for a specific flight from the list on the `Fl
+ `npm i` to install required dependencies
+ `suitecloud account:setup` to set up the account where the app is to be deployed; or for local setup, add `-d` to use NetSuite domain
+ `npm run build` to build the project inside a new `build` directory
+ `npm run deploy` to bundle the built app into the `/src/FileCabinet/SuiteApps` folder and deploy it into the configured account
+ `npm run deploy` to bundle the built app into the `FileCabinet` folder and deploy it into the configured account

For more information, see also [SPA Build Setup](../README.md#build-setup) and [SPA SuiteApp Deployment](../README.md#suiteapp-deployment).

## Application Structure

This sample SPA SuiteApp has the following structure:
SPA SuiteApps have the following structure:
- `/src/SuiteApps` contains the sources of the SuiteApp and the `assets` folder for static assets.
- `/test` contains unit and end-to-end tests that you can run using using different npm tasks.
- `/src/manifest.xml` and `/src/deploy.xml` contain the configuration of the SuiteApp.
- `/src/Objects/custspa_xxx.xml` contain the object definition for the `singlepageapp` SDF custom object.
- `/types` contains TypeScript type declarations that will provide you with code completion for NetSuite UIF classes.
- `/src/manifest.xml`, `/src/deploy.xml`, and `/src/Objects/custspa_xxx.xml` contain the configuration of the SuiteApp.
- `/build` contains the source files processed by the TypeScript compiler after running the `npm run build` task. The files can be cleaned by running the `npm run clean` task.
- `/src/FileCabinet/SuiteApps` contains the bundled and minified sources that are pushed to NetSuite. The files are generated by running `npm run bundle` and cleaned by running `npm run clean`.
- `/gulpfile.mjs` is a command line interface that provides the `build`, `bundle`, and `clean` npm tasks. It is possible to configure the source concatenation and minification here using the `concatenateScripts` and `minifyScripts` variables.
- `/gulpfile.js` is a command line interface that provides the `build`, `bundle`, and `clean` npm tasks. It is possible to configure the source concatenation and minification here using the `concatenateScripts` and `minifyScripts` variables.

## Application Entry Point

Expand All @@ -47,7 +47,7 @@ Testing is carried out using [Jest](https://jestjs.io/) for both unit and e2e (e
You can run unit tests out of the box. Before you start with e2e tests, you need to configure some of the files in the `/test` folder first:

1. Ensure you have set up an account using `suitecloud account:setup` and have a valid authentication ID.
2. Modify the `baseUrl` specified in `e2e/jest.config.json` to match the URL of your NetSuite account.
2. Modify the URL specified in `e2e/jest.config.json` to match the URL of your NetSuite account.
3. Look for the `.suitecloud-sdk` folder located in your root folder by default.
4. Copy the credentials from `.suitecloud-sdk/credentials` to `e2e/setup/credentials`. You can either copy the contents of the credentials file or simply replace the file.
5. Check that the `COMPANY_ID` in `e2e/constants/credential.ts` is correct.
Expand Down
1 change: 0 additions & 1 deletion spa-suiteapp-samples/airport360/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
"version": "1.0.0",
"description": "Hello World UIF SuiteApp - TS",
"devDependencies": {
"@oracle/netsuite-uif-types": "^5.0.0",
"@hitc/netsuite-types": "^2023.2.2",
"@typescript-eslint/eslint-plugin": "^5.50.0",
"@typescript-eslint/parser": "^5.50.0",
Expand Down
Loading