Portlet Scripts as XML Definitions

You can import portlet scripts from a target NetSuite account into your SuiteCloud projects. The portlet scripts can be used to dictate the behaviors and functionality of a custom portlet in the NetSuite dashboard. The portlet script object contains definitions provided by the portlet scripts.

The following portlet types are supported by SuiteCloud Development Framework (SDF):

LIST
FORM
HTML
LINKS

The custom portlet script object can be created in your SuiteCloud project and deployed to a target NetSuite account. A custom portlet script can also be imported from a NetSuite account into your SuiteCloud project. You can use a SuiteCloud project to create a full custom portlet workflow. This can be done by performing the following tasks:

Create a published dashboard object that includes a custom portlet. For more information, see Published Dashboards as XML Definitions
Use SuiteScript to create a portlet script that controls the behavior of the custom portlet. For more information, see SuiteScript 2.x Portlet Script Type
Add a portlet script object to create a script record for the portlet script, and apply it to the custom portlet. For more information, see Setting Values for a Portlet Script Object

For additional information, see:

Components of a Script Object

There are three components that are required for the script object:

The Scriptid Attribute: Provide a readable scriptid attribute for the script record and scriptdeployment structure by adding an underscore to the default value followed by a meaningful name for the object. The script record’s scriptid attribute must start with a customscript_ prefix and each scriptdeployment structure’s scriptid attribute must start with a customdeploy_ prefix.
The Script Record: Represented in XML by the object. The object contains several elements that define it, including the object name and a reference to the location of the script file.
The Script Deployment Record: Represented in XML by the scriptdeployments structure. A script object may contain multiple script deployments.

Components of a Portlet Script Object

The following components allow the portlet script object to work:

The Script Record: Represented in XML by the portlet script object. The object contains several elements that define it, including the name of the portlet script object, a reference to the location of the portlet script file, and the portlet type.

The following example shows a portlet script object named “Portlet Test 1”. The portlet script object also defines the portlet type as “HTML”, and references a portlet script file named “Portlet_test1.js”.

                <portlet scriptid="customscript_porlet_text1">
         <defaultfunction>testPortlet</defaultfunction>
         <name>Portlet Test 1</name>
         <notifyowner>T</notifyowner>
         <portlettype>HTML<portlettype>
         <scriptfile>[/SuiteScripts/Portlet_test1.js]</scriptfile>
         <scriptdeployments>
            <scriptdeployment scriptid="customdeploy_portlet_test1">
               <isdeployed>T</isdeployed>
               <loglevel>DEBUG</loglevel>
               <status>TESTING</status>
               <title>Portlet Test 1</title>
            </scriptdeployment>
         </scriptdeployments>
</portlet>

The Script Deployment Record: Represented in XML by the scriptdeployments structure. It is contained within the portlet script object where you can define certain values such as the title of your script deployment, and the status.

The following example shows a scriptdeployments structure with the title “Portlet Test 1” and a status value set to “TESTING”. This example only has one script deployment, but a portlet script object may contain multiple script deployments.

                <portlet scriptid="customscript_porlet_text1">
         <defaultfunction>testPortlet</defaultfunction>
         <name>Portlet Test 1</name>
         <notifyowner>T</notifyowner>
         <portlettype>HTML<portlettype>
         <scriptfile>[/SuiteScripts/Portlet_test1.js]</scriptfile>
         <scriptdeployments>
            <scriptdeployment scriptid="customdeploy_portlet_test1">
               <isdeployed>T</isdeployed>
               <loglevel>DEBUG</loglevel>
               <status>TESTING</status>
               <title>Portlet Test 1</title>
            </scriptdeployment>
         </scriptdeployments>
</portlet>

The Portlet Script: Can be imported or created using SuiteScript. The portlet script file must be stored in the File Cabinet of your SuiteCloud project.

The following example shows a Simple Form portlet script named formPortlet.js.

                /**
 *@NApiVersion 2.x
 *@NScriptType Portlet
 */
define(['N/search'],
    function(search) {
        function render(params) {
            var portlet = params.portlet;
            portlet.title = 'Simple Form Portlet';
            var fld = portlet.addField({
                id: 'text',
                type: 'text',
                label: 'Text'
            });
            fld.updateLayoutType({
                layoutType: 'normal'
            });
            fld.updateBreakType({
                breakType: 'startcol'
            });
            portlet.setSubmitButton({
                url: 'http://httpbin.org/post',
                label: 'Submit',
                target: '_top'
            });
        }
        return {
            render: render
        };
    });

The Custom Portlet: Can be created in the NetSuite UI, or in a SuiteCloud project. When the custom portlet is created, you can reference it in the custom script object.

For more information about:

Creating and deploying a portlet script, see Creating and Deploying a Portlet Script.
Creating a portlet script file, see SuiteScript 2.x Portlet Script Type
Using the portlet script file referenced in the example, see Simple Form Portlet Script Sample
Creating a custom portlet in the NetSuite UI, see Custom Portlets
Creating a custom portlet in a SuiteCloud project, see Published Dashboards as XML Definitions.

Setting Values for a Script Object

Each script object has a set of values that are required to successfully validate its script record and script deployment record.

The following elements are required to successfully validate your script record:

name —Provide a meaningful name for your script record.
scriptfile —Reference the appropriate script file. This must be a JavaScript file (.js).

The following element is required to successfully validate your script deployments:

status —Provide a value for the status element. The default value is TESTING. The only values accepted for all scripts except scheduled scripts are:
- RELEASED: The script will run in the accounts of all specified audience members.
- TESTING: The script will execute for the script owner and specified audience.
The remaining possible values for the status element are:
- COMPLETED
- INPROGRESS
- INQUEUE
- NOTSCHEDULED
- SCHEDULED

Setting Values for a Portlet Script Object

Provide a readable scriptid attribute for the portlet script object and scriptdeployment structure by adding an underscore to the default value, followed by a meaningful name for the object. The portlet object’s scriptid attribute must start with a “customscript_” prefix and each scriptdeployment structure’s scriptid attribute must start with a “customdeploy_” prefix.

The following elements are required to successfully validate your custom portlet object:

name- Provide a meaningful name for your portlet object.
scriptfile- Reference the appropriate portlet script file. This must be a JavaScript file (.js).
portlettype- Define which type of portlet script is being referenced. This element can be set to the following values:
- FORM
- HTML
- LIST
- LINKS

For more information about portlet script types, see:

The following elements are required to successfully validate your script deployments:

Title- Provide a meaningful title for your script deployment record.
Status- Provide a value for the status element. The default value is TESTING. Possible values are:
- COMPLETED
- INPROGRESS
- INQUEUE
- NOTSCHEDULED
- RELEASED
- SCHEDULED
- TESTING

For more information about:

portlet object fields and possible values, see portlet.
scriptdeployments structure fields and possible values, see scriptdeployment.

Example of a Portlet Script Object

The following example shows the contents of the SuiteScript/formPortlet.js file that is referenced in the portlet script object:

            /**
 *@NApiVersion 2.x
 *@NScriptType Portlet
 */
define(['N/search'],
    function(search) {
        function render(params) {
            var portlet = params.portlet;
            portlet.title = 'Simple Form Portlet';
            var fld = portlet.addField({
                id: 'text',
                type: 'text',
                label: 'Text'
            });
            fld.updateLayoutType({
                layoutType: 'normal'
            });
            fld.updateBreakType({
                breakType: 'startcol'
            });
            portlet.setSubmitButton({
                url: 'http://httpbin.org/post',
                label: 'Submit',
                target: '_top'
            });
        }
        return {
            render: render
        };
    });

The following example shows a custom portlet script object named “Portlet Object Example”. The object indicates the portlet type is Simple Form and references the Simple Form portlet script named “formPortlet.js”.

            <portlet scriptid="customscript_portletobject_example">
    <defaultfunction>testPortlet</defaultfunction>
    <name>Portlet Object Example</name>
    <notifyowner>T</notifyowner>
    <notifyadmins>F</notifyadmins>
    <portlettype>FORM</portlettype>
    <scriptfile>[/SuiteScripts/formPortlet.js]</scriptfile>
    <scriptdeployments>
        <scriptdeployment scriptid="customdeploy_portletobject_example">
            <isdeployed>T</isdeployed>
            <allemployees>T</allemployees>
            <allroles>T</allroles>
            <dashboardapp>F</dashboardapp>
            <loglevel>DEBUG</loglevel>
            <status>TESTING</status>
            <title>Portlet Object Example</title>
        </scriptdeployment>
    </scriptdeployments>
</portlet>

Note:

When you have successfully deployed your portlet script object to a target NetSuite account, you must create your custom portlet either in the NetSuite UI or in your SuiteCloud project. Now, you can go to your dashboard to display your custom portlet. For information, see Custom Portlets and Adding a Portlet to a Dashboard.

The following image shows how your custom portlet would appear in your dashboard after successfully deploying it to a target NetSuite account: