@shareflex/forms-sdk

Welcome to the Shareflex Forms SDK

This SDK is available as npm package (@shareflex/forms-sdk). It allows you to develop "Bottom Code" for Shareflex Forms Modern UI, i.e. Javascript files stored in the FormConfiguration library folder configured for a SharePoint List, running together with the forms stored there. You can use the code examples (see the snippets folder) as well as the type information (see the @types folder) to develop comfortably with Intellisense and proofing. See also the accompanying Online Help which has introduction texts, shows snippets associated with API members and comes with search capabilities, as well as the internal Yammer forum for dev support.

How to - using Javascript

The easiest way is to write Javascript which is directly run in the browser. Note: All snippets are ES6, which is not supported by IE11. If necessary, you need to transpile them to ES5 using a tool chain of your choice.

1. Create a new folder for your solution, which will contain all the Bottom code files for all lists in your current project.
2. Open the new project folder in Visual Studio Code.
3. Add the SDK package as a development dependency by executing the following commands on the terminal in VSCode: npm init -y npm i @shareflex/forms-sdk --save-dev For this to work you need to have npm installed (run the NodeJS setup - install LTS 10, not 12) The first command will create a default package.json (just for dependency package handling, you won't publish your project as npm package ever), the second command will create a node_modules folder and download the SDK into it. You can update to the newest SDK simply by running npm update regularly (note that since the SDK does not follow semantic versioning, every year you need to manually adjust the version in the package.json, as it won't update major versions automatically - use Ctrl+Space inside the version string to check for the latest available version).
4. It is recommended to install the Portal Systems Visual Studio Code Extensions (VSCX), which make it easy to synchronize the .js Files with the FormConfiguration library in the SharePoint.
5. For Intellisense and proofing, create a jsconfig.json file in the root of your project folder and insert the following JSON:

    {
        "compilerOptions": {
            "target": "es6",  /* target is ES6 browsers (IE11 requires ES5 transpilation, but Promise/fetch are already polyfilled) */
            "module": "commonJS",  // relevant for type annotations /* @type {import('../node_modules/xyz')} */someArg in the js code
            "lib": [ "es2016", "dom", "es6" ],  // libraries that are globally loaded in the environment at runtime (browser)
            "strict": true,  // always
            "checkJs": true,  // proofing
            "noImplicitAny": false  // require no explicit typing in javascript
        }, 
        "include": [
            "**/*"  // your code files in any directory
        ], 
        "exclude": [
            "node_modules",  // don't recompile code from packages
            "dist"  // don't ever look at the output
        ], 
        "files": [
            "node_modules/@shareflex/forms-sdk/@types/globals.d.ts"  // include the SF api global object
        ]
    }
   

6. Test by creating a ui.js in a src/FormConfiguration/MyList folder and typing SF. into it - you should see a list of available API members. If you mistakenly forget a parameter in a API method call, you should see the error being highlighted.
   Hint: With externally loaded scripts having functions accepting a SF parameter, as opposed to using the global SF object (which does not exist externally), you need to specify the type of the parameter, in order to get Intellisense, like this: On top of your function, declare the parameter to be of the right type, using a JSDoc comment:

     /**
      * 
      * @param {SF} SF 
      */
     function HelloWorld(SF) {
         ...
     }
   

7. After editing your .js Files, sync/upload it to the FormConfiguration folder (the one which was setup for the list, make sure it is registered as a Bottom script for the right form scope and content type, or create the initial file using the Designer) and it will be loaded with the form (make sure that Shareflex' Caching is off, otherwise you don't see your changes!).
8. You can press F12 on all members and again on their sub members to see typings and documentation. External packages such as Fabric UI are not by default installed. Open the package.json of the SDK and see the development dependencies. Transfer those needed into your project's package.json devDependencies section and run npm i to install these packages to get the typings.

How to - using Typescript & webpack

If you want to develop using Typescript and/or use external packages and pack everything into a transpiled and minified bundle file using webpack, follow these instruction to create your project folder for your solution.

1. Create a new folder for your project solution.
2. Open the new folder in Visual Studio Code.
3. Create a package.json directly in the folder and insert the following JSON (adjust appropriately):

    {
        "name": "my-solution-name", 
        "version": "0.1.0",
        "private": true,
        "main": "dist/bundle.js",
        "scripts": {
            "build": "webpack",
            "ship": "webpack --mode=\"production\" --devtool=\"\" --output-filename=\"bottom.js\""
        },
        "author": "Portal Systems AG",
        "license": "ISC",
        "dependencies": {},
        "devDependencies": {
            "@shareflex/forms-sdk": "^2021.11.21", 
            "@microsoft/sp-http": "1.10.0",
            "@types/es6-promise": "~0.0.33",
            "@types/react": "16.8.8",
            "@types/react-dom": "16.8.3",
            "es6-promise": "^4.2.6",
            "office-ui-fabric-react": "6.189.2",
            "react": "16.8.5",
            "react-dom": "16.8.5",
            "ts-loader": "^5.4.5",
            "typescript": "^3.4.5",
            "webpack": "^5.4.3",
            "webpack-cli": "^3.3.2"
        },
        "resolutions": {
            "@types/react": "16.8.8"
        }, 
        "//": "(packages that are already provided by Shareflex (available either as global objects or through the API) are listed as dev dependencies, e.g. React, to not package it again, but to have the typings available for compilation)"
    }
   

4. Run npm i on the terminal in VSCode to install all the development dependencies, most importantly the SDK package, into a node_modules folder (150MB): For this to work you need to have npm installed (run the NodeJS setup - install LTS 10, not 12) You can update to the newest SDK simply by running npm update regularly (note that since the SDK does not follow semantic versioning, every year you need to manually adjust the version in the package.json, as it won't update major versions automatically - use Ctrl+Space inside the version string to check for the latest available version).
5. It is recommended to install the Portal Systems Visual Studio Code Extensions (VSCX), which make it easy to upload the resulting bundle.js to the FormConfiguration library in the SharePoint.
6. Create a tsconfig.json file in the root of your project folder and insert the following JSON:

    {
        "compilerOptions": {
            "target": "es6",  /* target is ES6 browsers (IE11 requires ES5, Promise/fetch are polyfilled) */
            "module": "commonjs",  /* generate module loading code for NodeJS, to be consumed by webpack for bundling */
            "lib": [ "es2016", "dom", "es6" ],  // libraries that are globally loaded in the environment at runtime (browser)
            "outDir": "dist",  // where your compiled .js files ends up
            "sourceMap": false,  // no .map file generation
            "declaration": false,  // no d.ts file generation
            "strict": true,  // always
            "allowJs": false, 
            "checkJs": false, 
            "jsx": "react",  // for React tags
            "noFallthroughCasesInSwitch": true,  // always check
            "strictNullChecks": true,  // better leave this on
            "noImplicitAny": true,  // force type annotating in TypeScript
        }, 
        "include": [
            "src/**/*"  // put all your code files into a "src" directory
        ], 
        "exclude": [
            "node_modules",  // don't recompile code from packages
            "dist"  // don't ever look at the output
        ], 
        "files": [
            "node_modules/@shareflex/forms-sdk/@types/globals.d.ts"  // include the SF api global object
        ]
    }
   

7. Test by creating a bottom.ts file in a src folder and typing SF. into it - you should see a list of available API members. If you mistakenly forget a parameter in a API method call, you should see the error being highlighted.
8. Create a webpack.config.js file in the project folder with the following content (no change required):

    module.exports = {
        mode: "development",  // don't adjust for production here, use `npm run ship` on command line (which runs `webpack --mode="production" --devtool="" --output-filename="bundle.js"`)
        devtool: "inline-source-map",  // source code directly contained for debugging
   
        // if you want to bundle a file that can be executed as Bottom Code: 
        output: { filename: "bundle.debug.js" },  // in /dist
   
        // if you want to bundle an EcmaScript-Module which can be loaded using import(URL).then(exports => { ... });: 
        //output: { filename: "bundle.debug.js", libraryTarget: 'module', module: true },  // in /dist
        //experiments: { outputModule: true }, 
   
        // if you want to bundle a UMD/AMD-Module which can be loaded using window['require']([URL], exports => { ... });: 
        //output: { filename: "bundle.debug.js", libraryTarget: 'umd' },  // in /dist
   
        entry: "./src/bottom.ts",  // main
        resolve: { extensions: [".ts", ".tsx", ".js"] },
        module: {
            rules: [
                { test: /\.tsx?$/, loader: "ts-loader" },  // transpile .ts and .tsx files
            ]
        }, 
        externals: {  // do not bundle these, since already provided by the SharePoint environment
            'react': 'React', 
            'react-dom': 'ReactDOM', 
        }, 
    }; 
   

9. To transpile your .ts files into Javascript .js files and also bundle all resulting files into one minimized bundle.js using webpack, run the script defined in the package.json by entering: npm run build or npm run ship (for production) on the terminal. It will start at the src/bottom.ts file (entry point), discover all imported modules from other files, transpile Typescript into Javascript and use webpack to bundle everything into a single output file in dist/bundle.js. This resulting file is the Bottom code running in the browser. Upload the dist/bundle.js to the FormConfiguration folder for the SharePoint list (make sure it is registered as a Bottom script for the right form scope and content type, or create the initial file using the Designer). NOTE: If you bundle gets too large, store it in some other document library and load it as an external Bottom script (using SF.runScript(URL)). Also make sure that Shareflex' Caching is off, otherwise you don't see your changes!
10. You can press F12 on all members and again on their sub members to see typings and documentation. External packages such as Fabric UI are not by default installed. Open the package.json of the SDK and see the development dependencies. Transfer those needed into your project's package.json devDependencies section and run npm i to install these packages to get the typings. External packages to be bundled (not already included globally in the page) need to be listed in the dependencies section instead.

Please remember the following general guidelines:

• Your code should never manipulate the page's DOM elements. ShareflexForms uses React, and any manipulations by you will vanish with the next rendering. Also, your code is not alone on the page, and can run on the AllItems page or on the stand-alone SitePage, so do not assume anything except what the Shareflex API provides you with.
• Your code should not create any global objects, because several instances of Shareflex can run in the same page (the page never reloads and opens panels which each have their isolated bottom code, which must not interfere with other code). If you must exchange something, e.g. between two Bottom scripts, use the SF.customFormState, or define and import EcmaScript Modules.
• Do not load libraries such as jQuery and don't use classic code such as psLib. If you must have third-party libraries, use SF.ensureGlobalScripts to load them (this makes sure they are loaded only once).
• All necessary functionality should be provided by the Shareflex API (if it isn't, please consider requesting a new utility method). Same for any bugs in functionality or type definitions, please contact us.
• You must use the React framework provided by Shareflex, without bundling it yourself (use the parameter and controls provided by SF.registerPlaceholder).
• ES6 features (such as const, arrow (=>) functions, async/await or Array.find won't work in ES5 browsers like IE11. You need to transpile to ES5 to support these.
• There are however polyfills in place for system objects and methods such as fetch and Promise (these will work in IE11 as well).