About the package @corprio/aspnetcore-site

https://www.npmjs.com/package/@corprio/aspnetcore-site

This package is created to share javascripts, css, and images for Corprio built-in
web applications.

Its main script is corprio.js, which is a module that provides useful functions such as
getting the current organizationID, configuring DevExtreme widgets, etc.

This npm package outputs everything inside the dist folder in the
root of the project Corprio.AspNetCore.Site, as configured in the package.json.
``



"files": [ "dist" ]





  As you can see, the dist folder contains three folders:

  - css

  - images

  - js



dist/css

This folder contains commonly used css files for Corprio apps.



The css files are distributed from the css 

folder by the bundleconfig.json.

Basically, each css file is copied over along with its minified version.

Below are brief descriptions of each file or folder in

dist/css





corprio.css

    

Styles used by

corprio.js





corprio-app.css

    

Styles used by corprio apps with the common layout navbar, sidebar.

This is used by partials found in the Views/Shared



Customized theme for devextreme

    

A customized theme for devextreme, made using https://devexpress.github.io/ThemeBuilder/.

Devextreme Metadata can be found in dx.material.corprio-scheme.json

This, along with override-dx-scheme.css which are 

additional styles to override the customized theme, are then bundled to output

this file.



After upgrading devextreme, need to run the ThemeBuilder to export the updated css file.

Open a node.js command prompt and execute



npx devexpress-dashboard-cli@23.2.5 build-theme --input-file dx.material.corprio-scheme.json



and then copy the files

1. dx.material.corprio-scheme.css

1. dx-analytics.material.corprio-scheme.css

1. dx-dashboard.material.corprio-scheme.css

to the css folder.



Note: In the above command replace 23.2.5 with the latest version number of devextreme.





localizedFonts

        

This folder contains css files to set the right fonts for the page's language.

    

Below is an example of what TC.css might look like.



body{

    font-family: 'Noto Sans', 'Noto Sans TC', Helvetica,Arial,sans-serif;

}





Depending on the thread's current culture, a different css file will be served.

C# helper functions can be found in LanguageHelper

so that apps can use it in the

_Layout

, like so.



To use

LanguageHelper

,

make sure the Nuget package for

Corprio.AspNetCore.Site

 is included.



icons

    

The files in this folder are required by devextreme icons



fonts



The font files in this folder are used as fallback fonts for

dx.material.corprio-scheme.css





dist/images



This folder contains the Corprio logo and icon images of Corprio apps.

These images are used in the home page of Corprio apps within a css animation.

The animation features Corprio as a suite of apps with the apps orbiting around it.

The animation code is a partial _OrbitingApps.cshtml



Note that in the future this is not the best way to share resources as part of it is 

from the npm package, and part of it is from the Nuget package. Hosting the images

from one source might be an alternative to look into.



dist/js



The main script in this folder is the corprio.js

or alternatively the corprio.bundle.js. This script contains

all the javascript helper functions that are commonly useful in our Corprio apps.



Everything in the

dist/js

 folder is generated from the ts folder by tasks

written in the gulpfile.js. Gulp is used to pipeline the transpiling and bundling

of the client-side resources for distribution. For more information: https://gulpjs.com/



To understand the output in the

dist/js, I will first explain the contents in the ts

 folder,

then go on to describe the gulp tasks. Lastly, we will take a look at how to use

corprio.js



from this package.



ts folder



This folder contains typescript modules and declarations that will be transpiled into javascript

for distribution.



$3

    

This is the main script that will transpile into

corprio.js

.

It is written as an ES6 module and aggregates by exporting from all modules.



Note that most exports are written as

 

export * as moduleName from './modules/moduleName.js'





so that calls can be made by

corprio.moduleName.moduleFunction()

. However due

to legacy reasons of how the corprio module used to be structured, 

some exports are written as

 

export { moduleFunction } from './modules/moduleName.js'





to expose the function in

corprio.moduleFunction()





Another note about the file name extension when importing and exporting.

Note that it is exported from

moduleName.js and not moduleName.ts

.

The reason is that ultimately, the typescript files will be transpiled into javascript files,

and in browsers, that extension is necessary for them to correctly request for the resources.

Typescript will not remap any

.ts imports into .js

 for you since it breaks their

principles according to this thread https://github.com/microsoft/TypeScript/issues/16577#issuecomment-754941937



> We are not going to implement features, even under a commandline flag, that imply changing JS semantics by rewriting it during emit





$3



This folder contains typescript ES6 modules that will be aggregated by

corprio.ts

.



$3

    

Scripts in this folder aims to add extension methods to existing javascript prototypes.

Because the script nature is not a module (no import or export keywords in file),

when using the extension, import it like so



import '../extensions/date.extensions.js'



$3

    

Modules in this folder aims to export another module that has been imported dynamically.

That other module may be a third-party module that is large in size, but not used often,

and therefore you wish to only import it when needed.



To learn more about dynamic imports: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import



In the example below, the exported function

retrieve

 will return a promise,

which will resolve to whatever the module

exceljs

 provides.



exceljs.ts



function resolve() {

    return import('exceljs')

        .then((ExcelJS) => {

            return ExcelJS;

    })

}



export { resolve }



It can then be used in another file like this:



import * as exceljs from '../dynamicImports/exceljs.js'



exceljs.retrieve().then((ExcelJS) => {

    //do something with ExcelJS

});





The reason for separating each dynamic import into another ES module is that it allows for 

treeshaking by webpack later on. Webpack treeshaking only works for ES modules currently.

Therefore if we do not separate the dynamic import, that module will also be included even

if it never had been used.



$3

    

This folder contains modules that load globalized messages used in

corprio.js

.



$3



This folder contains modules that load globalized messages used by Devextreme widgets.



$3

    

This folder contains modules that will load globalized messages in a certain culture

for both

corprio.js

 and Devextreme widgets. For example, in a page that is going to be 

served in simplified Chinese, and uses

corprio.js

 or Devextreme widgets, you may

include the script in the head.





Note that

type="module" must be included since the script has import

 statements,

which makes it a module.



To make it easier to use with the C# projects, use the

LanguageHelper

 from the 

Nuget package for this project

Corprio.AspNetCore.Site





$3

These scripts provide UI widgets such as the image uploader that we use in corprio.

They operate kind of like Devextreme's UI widgets. One thing that is different is

that even if you include the

corprio.js

 script, you cannot directly use the 

coWidgets accessing under jQuery

$('#id').coImageUploader(...)

.

That is because

corprio.js

 has no side-effects. It only exports a bunch of functions,

but doesn't run anything besides that. This is so that

corprio.js

 can be safely

tree-shaken.



So before you use any coWidgets, first initialize them by



corprio.coWidgets.useCoWidgets();





Or if you are only the coImageUploader



corprio.coWidgets.useCoImageUploader();



After that you can use the coWidgets by attaching them to an Html element



$('#id').coImageUploader({ optionName1: optionValue1, optionName2: optionValue2 })



Then access the instance like so



$('#id').coImageUploader('instance')





$3

    

This folder contains type declaration files, which are files ending in

.d.ts

.

These are not modules and do not transpile into javascript. They only exist in the typescript

world. The purpose of these files is to define the shape of certain modules or objects,

and declare them to be existent.



We must also tell typescript which type declaration files to include in our

tsconfig.json



{

    "compilerOptions": {

    "types": [ "jquery", "file-saver", "bootstrap", "node" ]

    },

    "include": [

        "ts/*/"

    ]

}





Here we told them to include

types

 for "jquery", "file-saver", "bootstrap", "node", which

comes from

node_modules/@types

 by default. And they types are there because we have included

them in the

package.json. Then, in the include

 config, we told typescript we want 

everything in the

 folder to be included in the project, so they will transpile, type-check,

work with everything in there. The

ts folder includes ts/declarations

 which is why

the declarations will be automatically included.





#### devextreme



The modules for

corprio.js

 use a lot of devextreme library but it never imported the code

for it anywhere. It is just assumed that whoever is using

corprio.js

 will also have

included the scripts for devextreme elsewhere. This is fine since javascript doesn't care

to type-check, but for typescript, it needs to know that devextreme library has somehow 

been included in order to type-check in your editor. That's what 

dx.all.d.ts does to declare devextreme types

to exist. The rest of the files in this folder are also used by devextreme as its 

dependencies.



The origin of these files are from the folder where Devextreme is installed, 

in the Lib folder. They are simply copied over into this project.



#### schema

    

Files in the folder aims to define the shape of objects used in Corprio, namely

the shape of objects pertaining to Corprio API, and the shape of StaticData.



##### Corprio API



The Corprio API consists of request paths, request methods, data it takes,

and data it returns. All of these have a predefined shape, as stated in our swagger

documentation. We can make use of these shapes with typescript to make ajax calls

a lot easier.



The schema.d.ts file declares the shape of Corprio

API so we can use the typings in our scripts. This file is generated from the 

swagger.json which has been manually downloaded

from https://api.corprio.com/swagger/v1/swagger.json. Currently, the entire process 

is manual, from downloading the

json

 file to running a command that generates the

d.ts

 file. Instructions on how to generate the file are detailed in the 

generate-schema.txt.



Now we can access the types by importing them.



import type { models, paths } from "@corprio/aspnetcore-site/dist/js/corprio" 



//get intellisense for the data model SalesOrderLine

var salesOrderLine: models['SalesOrderLine'];



//get intellisense for the requestBody for creating a product by ajax

var productData: paths['/v1/Product/{organizationID}']['post']['requestBody']['content']['application/json']

models and paths are exported from corprio.js

 which makes the typings available.

The models.d.ts simply re-exports the data model types

under another alias.



##### StaticData



In

corprio.js there are often references to the object StaticData

 but this 

variable has not been imported or defined anywhere in the module. 

That's why we have defined the shape and declared it in

staticData.d.ts

 so typescript will know it exists.

But what does it do, and where does it come from?

StaticData

 contains "static" data of the geographic world such as country list,

currency list, phone number formats, etc. However, if the object was truly static,

there should be a module or json file to define this object, and thus 

we can simply import it and there won't be the need to declare it.

So why is it declared? Because it isn't really static, despite the misleading name.



One reason is that the country list contains globalized names of the country, 

and so the object must be generated run-time depending on the thread's culture.

In fact, it is generated on server-side based on data models defined in the

Corprio.Global

 project, so as to keep the the server-side and client-side

static data in sync.



But aside from that, the main reason is that

StaticData

 also serves data

about the current organization being requested and provides it

under

StaticData.OrgInfo

. And that's not static at all, and therefore must be

generated server-side per request. That's being done by 

StaticDataViewComponent, which is a 

view component that generates and inserts the following



into the view, if the view file contains the view component



Now that we know where the actual

StaticData

 object comes from, how is the

staticData.d.ts

 able to know its shape? It doesn't. I generated it manually with

the npm package dts-generator.

I copied the contents of

StaticData

 at run-time then pasted

it into the command to generate the

.d.ts

 file.

        

#### corprio



Files in this folder aims to declare global variables for

corprio.js

.

That includes two things: global variables referenced by

corprio.js

 that we want 

typescript to know about, and the very

corprio

 module itself, if we want it

to be recognized globally.



##### globalVariables.d.ts



This file declares variables to exist globally in the

Window

 scope, that for one reason

or another exists by some other way. This includes

StaticData

 mentioned earlier.

It also includes some other variables that are here for legacy reasons. It is not a good 

practice, since there will be no way to ensure those dependencies actually exist at 

run-time. For future, please aim to have all dependencies imported by ES module syntax.



##### corprio.d.ts



This file declares

corprio to exist and defines its shape for corprio.js

.

Note: this is also here for legacy reasons. In the past,

corprio.bundle.js



used to be written as an immediately-invoked factory function that we set to a

var corprio. This corprio.bundle.js file is then included in the _Layout

,

and then we use it in our scripts everywhere else, assuming the

corprio

 variable

to exist, and getting zero intellisense for it. 

        

Now it is rewritten to be ES modules. When using it from other apps, we can simply

import the module into our script.



import * as corprio from "@corprio/aspnetcore-site/dist/js/corprio"



This not only ensures that

corprio

 exists in the context, but also

allows for treeshaking with webpack later on. When using it this way, there is no need for the

corprio.d.ts

 file to declare it.

        

However, because of our generous usage of referencing

corprio

 everywhere in the past,

it will be difficult to remove the

corprio.bundle.js script from _Layout

 because something

is probably going to die without it. And since it is still globally included,

this file

corprio.d.ts

 exists to declare it, so that you get intellisense in your

typescript files.



##### coWidgets.d.ts



This is the declaration file for corprio UI widget components, to make typescript

intellisense available when using coWidgets as jQuery extension methods.



gulpfile.js



Now that we understand all the contents in the

 folder, we can take a look at how

these contents are transformed to be the output in the

dist/js

 folder. The transformation

happens through gulp and the

gulpfile.js

 contains code that controls how it happens.



In gulp, each process is organized into tasks. They look like functions and always returns 

something. When exported, the tasks will be visible through Visual Studio's Task Runner Explorer

found under View > Other Windows > Task Runner Explorer.



Open it now and have a look. You should see on the left panel a list of tasks defined in the

Gulpfile.js

.

And on the right panel, any tabs showing currently running tasks and a Bindings tab that shows 

any bindings of which task would automatically run on certain events. If you right-click on a task

in the left panel, you can run the task or bind it to an event.



Let's go over what each task does.



- cleanDistJs



    Deletes the entire directory

dist/js





- processTs



    Processes the typescripts and outputs them into

dist/js





- refreshDistJs



    Runs

cleanDistJs and then processTs





- watchTs



    Watches for changes in the

 folder and processes them automatically



Some tasks may have the suffix

DEVELOPMENT or PRODUCTION

.

The

PRODUCTION tasks will generate both minified and non-minified versions of corprio.bundle.js

.

The

DEVELOPMENT

 tasks only generate non-minified scripts. That means when you are developing,

and want to quickly generate output to test, use the dev tasks. Otherwise use the pro tasks.

Remember to run the

refreshDistJs_PRODUCTION

 task before publishing the npm package

so you have to latest code transpiled.



You most likely want to know what

processTs

 does. Here's a breakdown:



1. Transpile all typescript ES modules in

 folder and outputs the javascript ES modules

    into the

dist/js

 folder, keeping the same folder structure. This will also generate

.d.ts

 files for each module. Then, watch for changes in modules to re-transpile.



2. Copies everything from

ts/declarations directly into dist/js/declarations

 without

    alteration. Then, watch for changes in

ts/declarations

 to re-copy.



3. Bundles all the modules in the

ts folder into one large module named corprio.bundle.js



    This module is a UMD module, meaning if this script is included in a page, then

corprio

 and its functions will be available globally for access. This is for

    backwards-compatibility and ease of use. Otherwise, it is better to use

corprio.js

,

    which is the ES module version.



    Note: Besides

corprio.bundle.js you may also notice files like 295.corprio.bundle.js

.

    These files are a result of dynamic imports. At first

295.corprio.bundle.js

 won't be loaded

    until it is needed. For instance, our corprio module has a function that makes use of 

    the third-party module

exceljs

. We don't want to pack it with our bundle because it is large.

    Wepback is smart and separates these dynamic imports into separate modules.



For further details on how each gulp task works, read the comments in the

gulpfile.js

.



Some things to note:



- Our gulp tasks use third-party npm modules as you can see in the

require

 statements.

    These must be included in the package.json

devDependencies

.



- Our gulp tasks depends on configurations in

tsconfig.json

 to properly transpile 

    and generate declaration files.



    {

      "compilerOptions": {

        "forceConsistentCasingInFileNames": true, //to keep file paths consistent. Without this tasks will throw error

        "noImplicitAny": false, //Currently false because we have yet to add types to all our modules

        "noEmitOnError": true, 

        "declaration": true, //keep true so that webpack can use it to generate declaration files

        "removeComments": false,

        "sourceMap": true, //for debugging purposes

        "target": "es6", //target es6 so that the output can be used by other modules for treeshaking

        "module": "esnext", //esnext so that we can use dynamic imports

        "moduleResolution": "nodenext",

        "outDir": "", //the correct output path is further configured in the gulpfile.js

        "types": [ "jquery", "file-saver", "bootstrap", "node" ] //include these types from node_module/@types

      },

        "include": [

          "ts/*/" //include these files for compilation

        ]

      }





Usage of the corprio module



Let's look at how you may use

corprio

 module in another project. 



There are two ways:

corprio.js and corprio.bundle.js

corprio.js

 is an ES module, and you may use it by importing them into your scripts.

This is the preferred way to use it, since ES modules are tree-shakable.



Alternatively you may use

corprio.bundle.js

 in your project.

This may be the case if you want include it once and be able to use it globally everywhere.

The downside is that

corprio.bundle.js

 is a UMD module which is not tree-shakable.

Also, dependencies are not as clear as if you use ES modules. Generally it is not the best

idea to inject variables into your javascript global scope.

corprio.bundle.min.js is just the minified version of corprio.bundle.js

. Use the minified

version for production. Use the non-minified version for development, so that you have the 

site-maps and variable names kept in tact to make debugging much easier.



$3



#### 1. Install @corprio/aspnetcore-site



First, make sure you have this package installed.



npm i @corprio/aspnetcore-site





#### 2. Include the type definitions in your tsconfig.json



If you're using typescript, include type definitions for corprio.js



{

  "compilerOptions": {

    "types": ["jquery", "file-saver", "bootstrap", "node"]

  },

  "include": [

    "node_modules/@corprio/aspnetcore-site/dist/js/*/"

  ], 

  "exclude": [

  //corprio.d.ts is excluded if you are using corprio.js by ES module import syntax

    "node_modules/@corprio/aspnetcore-site/dist/js/declarations/corprio/corprio.d.ts"

  ]

}





#### 3. Import corprio.js in your script



In your script file, import the module and use.



In myScript.js:



import * as corprio from "@corprio/aspnetcore-site/dist/js/corprio" 



//use its functions

var orgID = corprio.getCurrentOrgID();





Make sure that when you're including the script in your html, to write

type = "module"



unless you will further process your script.





#### 4. Treeshake your script with webpack (optional)



Since you are probably not using every function imported from corprio, 

it is a good idea to treeshake your scripts so that only what is used is being outputted.



More details in https://webpack.js.org/guides/tree-shaking/



$3





#### 1. Install @corprio/aspnetcore-site



First, make sure you have this package installed.



npm i @corprio/aspnetcore-site





#### 2. Include the type definitions in your tsconfig.json



If you're using typescript, include type definitions for corprio.bundle.js



{

  "compilerOptions": {

    "types": ["jquery"]

  },

  "include": [

    "node_modules/@corprio/aspnetcore-site/dist/js/*/"

  ]

}





#### 3. Include the corprio.bundle.js in html



In your html file, include the script





Or if it's an cshtml file such as your

_Layout

, you'll have to escape the '@' character





#### 4. Use in your scripts



You may then call functions from

corprio

 in the same page, since it is already

available in the global scope.



Product Tour

Follow the steps below to add Product Tour feature in an application.

1. Add a service class which implements IProductTourService in the application

1. Register the service class in ConfigureServices of the Startup class. For example

services.AddProductTour();



1. On all views which need the product tour function, run the script in the inside onload

corprio.page.initTour({
defaultTour: 'name of the tour',
autoStart: true
});



Recommend to name the tour using the syntax [application].[controller].[index] to avoid conflicts between different applications.  This is because the name is saved in cookies after the tour is loaded so that it will not run again automatically next time.



$3

1. Standard tour steps have been defined in the ProductTour class which can be shared by applications which use the standard layouts.

1. The library driver.js hard coded the font family in its CSS.  This makes the icons of devextreme and fontawesome cannot be shown. To resolve this, add special class when using icons in the tour content.

For fontawesome, add the class fontawesome, e.g.



For icons in devextreme, add the class dxicons, e.g.

How to deploy

Windows

To deploy your application which is based on Corprio.AspNetCore.Site or Corprio.AspNetCore.XtraReportSite, follows the stesp below.
1. Install the ASP.NET Core 8.0 runtime - Windows Hosting Bundle Installer. Url: https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-aspnetcore-8.0.1-windows-hosting-bundle-installer

About the package @corprio/aspnetcore-site



"files": [ "dist" ]





  As you can see, the dist folder contains three folders:

  - css

  - images

  - js



dist/css

This folder contains commonly used css files for Corprio apps.



The css files are distributed from the css 

folder by the bundleconfig.json.

Basically, each css file is copied over along with its minified version.

Below are brief descriptions of each file or folder in

dist/css





corprio.css

    

Styles used by

corprio.js





corprio-app.css

    

Styles used by corprio apps with the common layout navbar, sidebar.

This is used by partials found in the Views/Shared



Customized theme for devextreme

    

A customized theme for devextreme, made using https://devexpress.github.io/ThemeBuilder/.

Devextreme Metadata can be found in dx.material.corprio-scheme.json

This, along with override-dx-scheme.css which are 

additional styles to override the customized theme, are then bundled to output

this file.



After upgrading devextreme, need to run the ThemeBuilder to export the updated css file.

Open a node.js command prompt and execute



npx devexpress-dashboard-cli@23.2.5 build-theme --input-file dx.material.corprio-scheme.json



and then copy the files

1. dx.material.corprio-scheme.css

1. dx-analytics.material.corprio-scheme.css

1. dx-dashboard.material.corprio-scheme.css

to the css folder.



Note: In the above command replace 23.2.5 with the latest version number of devextreme.





localizedFonts

        

This folder contains css files to set the right fonts for the page's language.

    

Below is an example of what TC.css might look like.



body{

    font-family: 'Noto Sans', 'Noto Sans TC', Helvetica,Arial,sans-serif;

}





Depending on the thread's current culture, a different css file will be served.

C# helper functions can be found in LanguageHelper

so that apps can use it in the

_Layout

, like so.



To use

LanguageHelper

,

make sure the Nuget package for

Corprio.AspNetCore.Site

 is included.



icons

    

The files in this folder are required by devextreme icons



fonts



The font files in this folder are used as fallback fonts for

dx.material.corprio-scheme.css





dist/images



This folder contains the Corprio logo and icon images of Corprio apps.

These images are used in the home page of Corprio apps within a css animation.

The animation features Corprio as a suite of apps with the apps orbiting around it.

The animation code is a partial _OrbitingApps.cshtml



Note that in the future this is not the best way to share resources as part of it is 

from the npm package, and part of it is from the Nuget package. Hosting the images

from one source might be an alternative to look into.



dist/js



The main script in this folder is the corprio.js

or alternatively the corprio.bundle.js. This script contains

all the javascript helper functions that are commonly useful in our Corprio apps.



Everything in the

dist/js

 folder is generated from the ts folder by tasks

written in the gulpfile.js. Gulp is used to pipeline the transpiling and bundling

of the client-side resources for distribution. For more information: https://gulpjs.com/



To understand the output in the

dist/js, I will first explain the contents in the ts

 folder,

then go on to describe the gulp tasks. Lastly, we will take a look at how to use

corprio.js



from this package.



ts folder



This folder contains typescript modules and declarations that will be transpiled into javascript

for distribution.



$3

    

This is the main script that will transpile into

corprio.js

.

It is written as an ES6 module and aggregates by exporting from all modules.



Note that most exports are written as

 

export * as moduleName from './modules/moduleName.js'





so that calls can be made by

corprio.moduleName.moduleFunction()

. However due

to legacy reasons of how the corprio module used to be structured, 

some exports are written as

 

export { moduleFunction } from './modules/moduleName.js'





to expose the function in

corprio.moduleFunction()





Another note about the file name extension when importing and exporting.

Note that it is exported from

moduleName.js and not moduleName.ts

.

The reason is that ultimately, the typescript files will be transpiled into javascript files,

and in browsers, that extension is necessary for them to correctly request for the resources.

Typescript will not remap any

.ts imports into .js

 for you since it breaks their

principles according to this thread https://github.com/microsoft/TypeScript/issues/16577#issuecomment-754941937



> We are not going to implement features, even under a commandline flag, that imply changing JS semantics by rewriting it during emit





$3



This folder contains typescript ES6 modules that will be aggregated by

corprio.ts

.



$3

    

Scripts in this folder aims to add extension methods to existing javascript prototypes.

Because the script nature is not a module (no import or export keywords in file),

when using the extension, import it like so



import '../extensions/date.extensions.js'



$3

    

Modules in this folder aims to export another module that has been imported dynamically.

That other module may be a third-party module that is large in size, but not used often,

and therefore you wish to only import it when needed.



To learn more about dynamic imports: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import



In the example below, the exported function

retrieve

 will return a promise,

which will resolve to whatever the module

exceljs

 provides.



exceljs.ts



function resolve() {

    return import('exceljs')

        .then((ExcelJS) => {

            return ExcelJS;

    })

}



export { resolve }



It can then be used in another file like this:



import * as exceljs from '../dynamicImports/exceljs.js'



exceljs.retrieve().then((ExcelJS) => {

    //do something with ExcelJS

});





The reason for separating each dynamic import into another ES module is that it allows for 

treeshaking by webpack later on. Webpack treeshaking only works for ES modules currently.

Therefore if we do not separate the dynamic import, that module will also be included even

if it never had been used.



$3

    

This folder contains modules that load globalized messages used in

corprio.js

.



$3



This folder contains modules that load globalized messages used by Devextreme widgets.



$3

    

This folder contains modules that will load globalized messages in a certain culture

for both

corprio.js

 and Devextreme widgets. For example, in a page that is going to be 

served in simplified Chinese, and uses

corprio.js

 or Devextreme widgets, you may

include the script in the head.





Note that

type="module" must be included since the script has import

 statements,

which makes it a module.



To make it easier to use with the C# projects, use the

LanguageHelper

 from the 

Nuget package for this project

Corprio.AspNetCore.Site





$3

These scripts provide UI widgets such as the image uploader that we use in corprio.

They operate kind of like Devextreme's UI widgets. One thing that is different is

that even if you include the

corprio.js

 script, you cannot directly use the 

coWidgets accessing under jQuery

$('#id').coImageUploader(...)

.

That is because

corprio.js

 has no side-effects. It only exports a bunch of functions,

but doesn't run anything besides that. This is so that

corprio.js

 can be safely

tree-shaken.



So before you use any coWidgets, first initialize them by



corprio.coWidgets.useCoWidgets();





Or if you are only the coImageUploader



corprio.coWidgets.useCoImageUploader();



After that you can use the coWidgets by attaching them to an Html element



$('#id').coImageUploader({ optionName1: optionValue1, optionName2: optionValue2 })



Then access the instance like so



$('#id').coImageUploader('instance')





$3

    

This folder contains type declaration files, which are files ending in

.d.ts

.

These are not modules and do not transpile into javascript. They only exist in the typescript

world. The purpose of these files is to define the shape of certain modules or objects,

and declare them to be existent.



We must also tell typescript which type declaration files to include in our

tsconfig.json



{

    "compilerOptions": {

    "types": [ "jquery", "file-saver", "bootstrap", "node" ]

    },

    "include": [

        "ts/*/"

    ]

}





Here we told them to include

types

 for "jquery", "file-saver", "bootstrap", "node", which

comes from

node_modules/@types

 by default. And they types are there because we have included

them in the

package.json. Then, in the include

 config, we told typescript we want 

everything in the

 folder to be included in the project, so they will transpile, type-check,

work with everything in there. The

ts folder includes ts/declarations

 which is why

the declarations will be automatically included.





#### devextreme



The modules for

corprio.js

 use a lot of devextreme library but it never imported the code

for it anywhere. It is just assumed that whoever is using

corprio.js

 will also have

included the scripts for devextreme elsewhere. This is fine since javascript doesn't care

to type-check, but for typescript, it needs to know that devextreme library has somehow 

been included in order to type-check in your editor. That's what 

dx.all.d.ts does to declare devextreme types

to exist. The rest of the files in this folder are also used by devextreme as its 

dependencies.



The origin of these files are from the folder where Devextreme is installed, 

in the Lib folder. They are simply copied over into this project.



#### schema

    

Files in the folder aims to define the shape of objects used in Corprio, namely

the shape of objects pertaining to Corprio API, and the shape of StaticData.



##### Corprio API



The Corprio API consists of request paths, request methods, data it takes,

and data it returns. All of these have a predefined shape, as stated in our swagger

documentation. We can make use of these shapes with typescript to make ajax calls

a lot easier.



The schema.d.ts file declares the shape of Corprio

API so we can use the typings in our scripts. This file is generated from the 

swagger.json which has been manually downloaded

from https://api.corprio.com/swagger/v1/swagger.json. Currently, the entire process 

is manual, from downloading the

json

 file to running a command that generates the

d.ts

 file. Instructions on how to generate the file are detailed in the 

generate-schema.txt.



Now we can access the types by importing them.



import type { models, paths } from "@corprio/aspnetcore-site/dist/js/corprio" 



//get intellisense for the data model SalesOrderLine

var salesOrderLine: models['SalesOrderLine'];



//get intellisense for the requestBody for creating a product by ajax

var productData: paths['/v1/Product/{organizationID}']['post']['requestBody']['content']['application/json']

models and paths are exported from corprio.js

 which makes the typings available.

The models.d.ts simply re-exports the data model types

under another alias.



##### StaticData



In

corprio.js there are often references to the object StaticData

 but this 

variable has not been imported or defined anywhere in the module. 

That's why we have defined the shape and declared it in

staticData.d.ts

 so typescript will know it exists.

But what does it do, and where does it come from?

StaticData

 contains "static" data of the geographic world such as country list,

currency list, phone number formats, etc. However, if the object was truly static,

there should be a module or json file to define this object, and thus 

we can simply import it and there won't be the need to declare it.

So why is it declared? Because it isn't really static, despite the misleading name.



One reason is that the country list contains globalized names of the country, 

and so the object must be generated run-time depending on the thread's culture.

In fact, it is generated on server-side based on data models defined in the

Corprio.Global

 project, so as to keep the the server-side and client-side

static data in sync.



But aside from that, the main reason is that

StaticData

 also serves data

about the current organization being requested and provides it

under

StaticData.OrgInfo

. And that's not static at all, and therefore must be

generated server-side per request. That's being done by 

StaticDataViewComponent, which is a 

view component that generates and inserts the following



into the view, if the view file contains the view component



Now that we know where the actual

StaticData

 object comes from, how is the

staticData.d.ts

 able to know its shape? It doesn't. I generated it manually with

the npm package dts-generator.

I copied the contents of

StaticData

 at run-time then pasted

it into the command to generate the

.d.ts

 file.

        

#### corprio



Files in this folder aims to declare global variables for

corprio.js

.

That includes two things: global variables referenced by

corprio.js

 that we want 

typescript to know about, and the very

corprio

 module itself, if we want it

to be recognized globally.



##### globalVariables.d.ts



This file declares variables to exist globally in the

Window

 scope, that for one reason

or another exists by some other way. This includes

StaticData

 mentioned earlier.

It also includes some other variables that are here for legacy reasons. It is not a good 

practice, since there will be no way to ensure those dependencies actually exist at 

run-time. For future, please aim to have all dependencies imported by ES module syntax.



##### corprio.d.ts



This file declares

corprio to exist and defines its shape for corprio.js

.

Note: this is also here for legacy reasons. In the past,

corprio.bundle.js



used to be written as an immediately-invoked factory function that we set to a

var corprio. This corprio.bundle.js file is then included in the _Layout

,

and then we use it in our scripts everywhere else, assuming the

corprio

 variable

to exist, and getting zero intellisense for it. 

        

Now it is rewritten to be ES modules. When using it from other apps, we can simply

import the module into our script.



import * as corprio from "@corprio/aspnetcore-site/dist/js/corprio"



This not only ensures that

corprio

 exists in the context, but also

allows for treeshaking with webpack later on. When using it this way, there is no need for the

corprio.d.ts

 file to declare it.

        

However, because of our generous usage of referencing

corprio

 everywhere in the past,

it will be difficult to remove the

corprio.bundle.js script from _Layout

 because something

is probably going to die without it. And since it is still globally included,

this file

corprio.d.ts

 exists to declare it, so that you get intellisense in your

typescript files.



##### coWidgets.d.ts



This is the declaration file for corprio UI widget components, to make typescript

intellisense available when using coWidgets as jQuery extension methods.



gulpfile.js



Now that we understand all the contents in the

 folder, we can take a look at how

these contents are transformed to be the output in the

dist/js

 folder. The transformation

happens through gulp and the

gulpfile.js

 contains code that controls how it happens.



In gulp, each process is organized into tasks. They look like functions and always returns 

something. When exported, the tasks will be visible through Visual Studio's Task Runner Explorer

found under View > Other Windows > Task Runner Explorer.



Open it now and have a look. You should see on the left panel a list of tasks defined in the

Gulpfile.js

.

And on the right panel, any tabs showing currently running tasks and a Bindings tab that shows 

any bindings of which task would automatically run on certain events. If you right-click on a task

in the left panel, you can run the task or bind it to an event.



Let's go over what each task does.



- cleanDistJs



    Deletes the entire directory

dist/js





- processTs



    Processes the typescripts and outputs them into

dist/js





- refreshDistJs



    Runs

cleanDistJs and then processTs





- watchTs



    Watches for changes in the

 folder and processes them automatically



Some tasks may have the suffix

DEVELOPMENT or PRODUCTION

.

The

PRODUCTION tasks will generate both minified and non-minified versions of corprio.bundle.js

.

The

DEVELOPMENT

 tasks only generate non-minified scripts. That means when you are developing,

and want to quickly generate output to test, use the dev tasks. Otherwise use the pro tasks.

Remember to run the

refreshDistJs_PRODUCTION

 task before publishing the npm package

so you have to latest code transpiled.



You most likely want to know what

processTs

 does. Here's a breakdown:



1. Transpile all typescript ES modules in

 folder and outputs the javascript ES modules

    into the

dist/js

 folder, keeping the same folder structure. This will also generate

.d.ts

 files for each module. Then, watch for changes in modules to re-transpile.



2. Copies everything from

ts/declarations directly into dist/js/declarations

 without

    alteration. Then, watch for changes in

ts/declarations

 to re-copy.



3. Bundles all the modules in the

ts folder into one large module named corprio.bundle.js



    This module is a UMD module, meaning if this script is included in a page, then

corprio

 and its functions will be available globally for access. This is for

    backwards-compatibility and ease of use. Otherwise, it is better to use

corprio.js

,

    which is the ES module version.



    Note: Besides

corprio.bundle.js you may also notice files like 295.corprio.bundle.js

.

    These files are a result of dynamic imports. At first

295.corprio.bundle.js

 won't be loaded

    until it is needed. For instance, our corprio module has a function that makes use of 

    the third-party module

exceljs

. We don't want to pack it with our bundle because it is large.

    Wepback is smart and separates these dynamic imports into separate modules.



For further details on how each gulp task works, read the comments in the

gulpfile.js

.



Some things to note:



- Our gulp tasks use third-party npm modules as you can see in the

require

 statements.

    These must be included in the package.json

devDependencies

.



- Our gulp tasks depends on configurations in

tsconfig.json

 to properly transpile 

    and generate declaration files.



    {

      "compilerOptions": {

        "forceConsistentCasingInFileNames": true, //to keep file paths consistent. Without this tasks will throw error

        "noImplicitAny": false, //Currently false because we have yet to add types to all our modules

        "noEmitOnError": true, 

        "declaration": true, //keep true so that webpack can use it to generate declaration files

        "removeComments": false,

        "sourceMap": true, //for debugging purposes

        "target": "es6", //target es6 so that the output can be used by other modules for treeshaking

        "module": "esnext", //esnext so that we can use dynamic imports

        "moduleResolution": "nodenext",

        "outDir": "", //the correct output path is further configured in the gulpfile.js

        "types": [ "jquery", "file-saver", "bootstrap", "node" ] //include these types from node_module/@types

      },

        "include": [

          "ts/*/" //include these files for compilation

        ]

      }





Usage of the corprio module



Let's look at how you may use

corprio

 module in another project. 



There are two ways:

corprio.js and corprio.bundle.js

corprio.js

 is an ES module, and you may use it by importing them into your scripts.

This is the preferred way to use it, since ES modules are tree-shakable.



Alternatively you may use

corprio.bundle.js

 in your project.

This may be the case if you want include it once and be able to use it globally everywhere.

The downside is that

corprio.bundle.js

 is a UMD module which is not tree-shakable.

Also, dependencies are not as clear as if you use ES modules. Generally it is not the best

idea to inject variables into your javascript global scope.

corprio.bundle.min.js is just the minified version of corprio.bundle.js

. Use the minified

version for production. Use the non-minified version for development, so that you have the 

site-maps and variable names kept in tact to make debugging much easier.



$3



#### 1. Install @corprio/aspnetcore-site



First, make sure you have this package installed.



npm i @corprio/aspnetcore-site





#### 2. Include the type definitions in your tsconfig.json



If you're using typescript, include type definitions for corprio.js



{

  "compilerOptions": {

    "types": ["jquery", "file-saver", "bootstrap", "node"]

  },

  "include": [

    "node_modules/@corprio/aspnetcore-site/dist/js/*/"

  ], 

  "exclude": [

  //corprio.d.ts is excluded if you are using corprio.js by ES module import syntax

    "node_modules/@corprio/aspnetcore-site/dist/js/declarations/corprio/corprio.d.ts"

  ]

}





#### 3. Import corprio.js in your script



In your script file, import the module and use.



In myScript.js:



import * as corprio from "@corprio/aspnetcore-site/dist/js/corprio" 



//use its functions

var orgID = corprio.getCurrentOrgID();





Make sure that when you're including the script in your html, to write

type = "module"



unless you will further process your script.





#### 4. Treeshake your script with webpack (optional)



Since you are probably not using every function imported from corprio, 

it is a good idea to treeshake your scripts so that only what is used is being outputted.



More details in https://webpack.js.org/guides/tree-shaking/



$3





#### 1. Install @corprio/aspnetcore-site



First, make sure you have this package installed.



npm i @corprio/aspnetcore-site





#### 2. Include the type definitions in your tsconfig.json



If you're using typescript, include type definitions for corprio.bundle.js



{

  "compilerOptions": {

    "types": ["jquery"]

  },

  "include": [

    "node_modules/@corprio/aspnetcore-site/dist/js/*/"

  ]

}





#### 3. Include the corprio.bundle.js in html



In your html file, include the script





Or if it's an cshtml file such as your

_Layout

, you'll have to escape the '@' character





#### 4. Use in your scripts



You may then call functions from

corprio

 in the same page, since it is already

available in the global scope.



Product Tour

Follow the steps below to add Product Tour feature in an application.

1. Add a service class which implements IProductTourService in the application

1. Register the service class in ConfigureServices of the Startup class. For example

services.AddProductTour();



1. On all views which need the product tour function, run the script in the inside onload

corprio.page.initTour({
defaultTour: 'name of the tour',
autoStart: true
});



Recommend to name the tour using the syntax [application].[controller].[index] to avoid conflicts between different applications.  This is because the name is saved in cookies after the tour is loaded so that it will not run again automatically next time.



$3

1. Standard tour steps have been defined in the ProductTour class which can be shared by applications which use the standard layouts.

1. The library driver.js hard coded the font family in its CSS.  This makes the icons of devextreme and fontawesome cannot be shown. To resolve this, add special class when using icons in the tour content.

For fontawesome, add the class fontawesome, e.g.



For icons in devextreme, add the class dxicons, e.g.