Forem: Serge van den Oever

VSCode tasks and parsing your custom output for problems

Serge van den Oever — Wed, 16 Feb 2022 00:00:00 +0000

Assume you have a Node.js script that validates your content for problems. It is nice to have some output to indicate these errors. For example as follows:

To identify that there is a problem (error or warning) it is possible to color the problem type, for example with the chalk library. I use a few simple functions to create these messages which I write to the output using console.log().

createWarningOrErrorString.ts: (note, this is TypeScript)

import * as path from "path";
import chalk from "chalk"; // use version 4 for TypeScript, until TypeScript 4.6 is available

export function createErrorString(message: string, errorType: string, filepath = "", line = 1, column = 1): string {
    const filepathString = filepath === "" ? "<nofile>" : path.join(process.cwd(), filepath);
    const errorMessage = `${chalk.bgRed("ERROR")}: ${filepathString}(${line},${column}): ${errorType} - ${message}`;
    return errorMessage;
}

export function createWarningString(message: string, errorType: string, filepath = "", line = 1, column = 1): string {
    const filepathString = filepath === "" ? "<nofile>" : path.join(process.cwd(), filepath);
    const warningMessage = `${chalk.bgYellow("WARNING")}: ${filepathString}(${line},${column}): ${errorType} - ${message}`;
    return warningMessage;
}

Assume we have an npm script validate as follows (where in my case validate.js is transpiled from validate.ts):

   "scripts": {
       "validate": "node validate.js"
   }

If we run npm run validate in a terminal window within VSCode we get the output including the error and warning messages, but they will not end up in the "Problems" panel is Visual Studio Code.

There are two reasons for that:

Visual Studio Code does not parse the output of commands executed in a terminal window
If custom errors and warnings are generated by the validate script, VSCode does not know how to parse these errors and warnings.

The solution to both problems are VSCode tasks.

A VSCode task is executed in a separate terminal task tab, named after the executing task:

The nice thing is that VSCode parses the output generated in this tab for problems.

But first we need to define a VSCode task for this:

.vscode/tasks.json:


{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Validate",
            "detail": "Validate all content and parse errors from output",
            "type": "npm",
            "script": "validate --silent",
            "problemMatcher": [
                {
                    "owner": "content-linter",
                    "fileLocation": ["autoDetect", "${workspaceFolder}"],
                    "pattern": {
                        "regexp": "^(ERROR|WARNING):\\s*(.*)\\((\\d+),(\\d+)\\):\\s+(.*)$",
                        "file": 2,
                        "line": 3,
                        "column": 4,
                        "severity": 1,
                        "message": 5
                    }
                }
            ],
            "options": {
                "statusbar": {
                    "label": "$(check-all) Validate",
                    "color": "#00FF00"
                }
            }
        }
    ]
}

Note that the above task configuration parses the errors/warning in the output, to show them in the "Problems" panel. So the line:

C:\P\competenceframework\packages\content\src\competenceframework-settings.json(1,1): SchemaValidationError - rings is not allowed.

Is parsed using the regular expression ^(ERROR|WARNING):\\s*(.*)\$(\\d+),(\\d+)\$:\\s+(.*)$.

Resulting in the following information in the "Problems" pane:

To run this task execute the task, press F1, select Tasks: Run Task, and next select the Validate task.

Note that the above task configuration contains some addition information in options. This drives the configuration of a VSCode extension Tasks to add tasks in the VSCode status bar:

I the above example I created two tasks in the status: Validate and Build.

Now you can start your tasks with a single click, parse the output, and show the results in the "Problems" pane.

Normally the "Problems" pane only shows problems in open files, but using tasks you can report on all problems that occured during the execution of the task.

VSCode has great documentation on tasks. Check it out!

Prevent useless npm error output in your project

Serge van den Oever — Wed, 16 Feb 2022 00:00:00 +0000

When you write a node script that can be executed through npm, is is convenient to have an error exit code when for example a validation error occurs.

Assume we have an npm script validate as follows:

   "scripts": {
       "validate": "node validate.js"
   }

If we run npm run validate We get output like:

Development mode: false
Current working directory: C:\P\competenceframework\packages\content
ERROR: C:\P\competenceframework\packages\content\src\competenceframework-settings.json(1,1): SchemaValidationError - rings is not allowed.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! @competenceframework/content@1.0.0 validate: `validate`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the @competenceframework/content@1.0.0 validate script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\serge\AppData\Roaming\npm-cache\_logs\2022-02-15T23_23_29_477Z-debug.log
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! competenceframework@1.0.0 validate: `cd packages && cd content && npm run validate`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the competenceframework@1.0.0 validate script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\serge\AppData\Roaming\npm-cache\_logs\2022-02-15T23_23_29_526Z-debug.log

A large part of the error output is useless, it is npm related.

To skip this output use the --silent flag when calling npm:

npm run validate --silent

The output will now be:

Development mode: false
Current working directory: C:\P\competenceframework\packages\content
ERROR: C:\P\competenceframework\packages\content\src\competenceframework-settings.json(1,1): SchemaValidationError - rings is not allowed.

If you run the script from a VSCode task validate, configured in .vscode/tasks.json it is possible to prevent the output as follows using the --silent flag:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Validate",
            "detail": "Validate all content and parse errors from output",
            "type": "npm",
            "script": "validate --silent",
            "problemMatcher": [
                {
                    "owner": "content-linter",
                    "fileLocation": ["autoDetect", "${workspaceFolder}"],
                    "pattern": {
                        "regexp": "^(ERROR|WARNING):\\s*(.*)\\((\\d+),(\\d+)\\):\\s+(.*)$",
                        "file": 2,
                        "line": 3,
                        "column": 4,
                        "severity": 1,
                        "message": 5
                    }
                }
            ],
            "options": {
                "statusbar": {
                    "label": "$(check-all) Validate",
                    "color": "#00FF00"
                }
            }
        }
    ]
}

It is also possible to suppress the npm error output in your project by adding a file .npmrc with the following content:

loglevel=silent

Using the above configuration the --silent flag is not required in the task configuration.

Chalk, TypeScript and Lerna

Serge van den Oever — Tue, 15 Feb 2022 00:00:00 +0000

After a lot of struggling with getting chalk to work with TypeScript I finally found (in the documentation) that you should just use version 4 of chalk! In the release notes it is stated that:

If you use TypeScript, you will want to stay on Chalk 4 until TypeScript 4.6 is out.

I can now use chalk as follows from TypeScript:

import chalk from "chalk";

console.log(chalk.red("This is red"));

Next problem: color output is stripped when using Lerna.

If you run lerna run doit --scope mypackage --stream all color output is stripped.

To fix this set the environment variable FORCE_COLOR=1.

For example in an npm script do the following:

   ...
   "run_doit_in_package_mypackage": "cross-env FORCE_COLOR=1 lerna run doit --scope mypackage --stream"
   ...

Next.js on Azure with Sitecore JSS

Serge van den Oever — Wed, 29 Dec 2021 00:00:00 +0000

With the Next.js on Azure solution as can be found in the open-source GitHub repository https://github.com/macaw-cad/nextjs-on-azure, we see the implementation of a Next.js solution connected to Sitecore JSS and all the future goodness as follows:

Core web trafic is handled by Azure CDN, which supports the required expiration headers for Next.js. When Incremental Static Regeneration (ISG) is needed for a specific page, this is handled by a consumption-based Azure function. Assets like images are currently streamed through Azure functions as well, and are cached in the Azure CDN. When Experience Edge is used, the CDN of Experience Edge will fullfill this function for assets.

For more information see my blog post Next.js on Azure, and an example on how to use it for Sitecore JSS.

Next.js on Azure, and an example on how to use it for Sitecore JSS

Serge van den Oever — Tue, 28 Dec 2021 00:00:00 +0000

Next.js, developed by Vercel, runs best on Vercel. Problem is: it is difficult to "sell" to customers who commited to Microsoft Azure as their cloud platform to use Vercel (at the time of writing 178 employees) as an additional cloud provider for only the frontend application. Customers like insurance companies do for example a lot of checks on Azure before they even dare to go to the cloud on Azure, let alone they will embrace an additional cloud provider they never heard of.

This is why we started a Macaw Innovation Board project at in June 2021 to research how we could run Next.js in the best way on Azure, and use this approach as a core setup for future Sitecore JSS projects.

The implementation is created with the following assumptions:

The Next.js server end-points must be completely implemented using consumption-based Azure functions
The implementation should support Incremental Static Generation (ISG) to ensure rerendering of pages in case of page changes in the Sitecore CMS
The Azure CDN is used, with support for page expiration in combination with ISG

The results

The results of our research can be found in the open-source GitHub repository https://github.com/macaw-cad/nextjs-on-azure.

It provides the following headstart code and examples:

Next.js basic example

basic-nextjs-azure-functions - the Next.js website running from an Azure function for the basic website example
basic-nextjs-example - the Next.js code for the basic website example

Next.js Sitecore Headless example with JSS

jss-nextjs-app-azure-functions - the Next.js website running from an Azure function for the Sitecore headless JSS example
basic-nextjs-app - the Next.js code for the Sitecore headless JSS example

React UI components

ui-components - a core set of React UI components and styling to be used in custom-built websites

Blog posts

My colleague Erwin Smit, who did most of the implementation work, wrote a great set of blogposts explaining a lot of the things happening in the code base.

Checkout his list of posts:

And some nice additional posts on functionality showcased in the GitHub repository https://github.com/macaw-cad/nextjs-on-azure:

Run Gulp 4 tasks programmatically from NodeJS

Serge van den Oever — Sun, 01 Nov 2020 00:00:00 +0000

I want to use the power of the Gulp functions like the series(), parallel(), src(), dest(), pipe(), the globbing, an the plugin model within my node application. And it is easy to do. But I can tell you... it took me hours to find out, and the missing link was that I forgot two brackets: (). The gulp.series() and gulp.parallel() give back a function that must be executed:

const {series} = require('gulp');

// simple gulp task
const helloTask = done => {
  console.log('hello from helloTask');
  done();
}

console.log('start');
series(helloTask)();
console.log('end');

The import part is series(helloTask)(). But the output was still in the wrong order:

start
end
hello from helloTask

This is because everything in Gulp is asynchronous. We need to wait for the completion of the series before continuing.
This can be achieved using a promise, and awaiting the promise. If we want to await a promise we need to execute that code from an async function:

const gulp = require('gulp');

// simple gulp task
const helloTask = done => {
  console.log('hello from helloTask');
  done();
}

async function gulpTaskRunner(task) {
  return new Promise(function (resolve, reject) {
    gulp.series(task, (done) => {
      console.log("Gulp task completed");
      resolve();
      done();
    })();
  });
}

async function app() {
  console.log('start');
  await gulpTaskRunner(helloTask);
  console.log('end');
}

app();

In this way we can create a simple gulpTaskRunner() function that can be executed from within your node application.

And the output is now as follows:

start
hello from helloTask
Gulp task completed
end

Processing multipart/form-data in NodeJS Azure function with HttpTrigger

Serge van den Oever — Fri, 25 Sep 2020 00:00:00 +0000

Introduction

Microsoft's answer to the JAM-stack hosting platforms like Netlify and Cloudflare Workers is Azure Static Web Apps.

All platforms provide similar ingredients, but they have big differences in the details. First about the similar ingredients:

Hosting of static content, made available globally through a CDN
Compute to enable you to build HTTP endpoints like API's and webhooks - written with NodeJS or other languages
Support for CI/CD
Management for domain configuration, authentication/authorization, environment settings and much more

One of those big differences in the details I stumbled upon was in handling the posting of a form with multipart/form-data to support both form fields and files. In my case I needed to handle a set of fields and a set of images.

The long-winded road to nirvana

I started out with Netlify as the platform of choice for my solution because it is simple and free. After a lot of trials and (always) errors I stumbled upon a discussion thread that made clear that the (crippled) implementation on Netlify functions does not support posting of binary data. The underlying AWS Lambdas do have support, but this support is not enabled for Netlify. Another hugely annoying thing of Netlify functions is that there is no information on how to debug Netlify functions with VSCode. You only see ramblings like this discussion thread on the topic, and some pointer in the right direction in this discussion thread. This should be part of the documentation! Debugging using console.log() is so... 90's.

My next step was Azure Static Web Apps, which has the backing for compute through the really mature Azure Functions. First of all: VSCode has great support for creating, managing and debugging Azure Static Web Apps and the underlying functions through the Azure Static Web Apps extension for Visual Studio Code.

But most important: it can handle POST messages with binary data!

Because parsing multipart/form-data is a tricky piece of work I tried a lot of npm package of which others reported success with. An often used npm package is parse-multipart as described in the blog post Multipart/form-data processing via HttpTrigger using NodeJS Azure functions and this discussion thread. I did only get it working when I only had file fields, but with a mixture of text and file fields it completely crashed on me. After investigating other packages like multiparty and multer and many others that didn't work either, I even tried the code of Parsing post data 3 different ways in Node.js without third-party libraries but could not get it working.

nirvana

To cut a long story short, I finally got it working. I stumbled upon a low-level package busboy (what's in a name!) that describes itself as A node.js module for parsing incoming HTML form data. From the documentation I could not get it working because it only describes how to hook into the streaming model of getting data, that is applicable in an Express or http package based situation using req.pipe(busboy). In an Azure function the request body is already completely loaded.

After digging through the source code of the package I found some tests that used exactly the approach that I needed by using the undocumented call busboy.write(request.body, function() {}); where I can pass-in the body data that we already have available in the Azure Function. This brought me to the following code. I log information about all the fields that we find, and I write, as a test, the files to disk in a temp folder to check if the server can process binary files correctly. When you run this same code in a Netlify function everything seems to work, but you will get crippled files!

Processing multipart/form-data in NodeJS Azure function with HttpTrigger:

import { AzureFunction, Context, HttpRequest } from "@azure/functions"
import * as Busboy from 'busboy';
import * as fs from 'fs';

function getTime() {
    return (new Date()).toISOString().substr(11, 8);
}

function log(s) {
    console.log(`${getTime()}: ${s}`);
}

const httpTrigger: AzureFunction = async function (context: Context, request: HttpRequest): Promise<void> {
    var busboy = new Busboy({ headers: request.headers });
    busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
        log(`File [${fieldname}]: filename: '${filename}', encoding: ${encoding}, mimetype: ${mimetype}`);
        file.on('data', function(data) {
          log(`File [${fieldname}]: filename: '${filename}', got ${data.length} bytes`);
          fs.writeFileSync('c:\\temp\\' + filename, data);
        });
        file.on('end', function() {
          log(`File [${fieldname}]: filename: '${filename}', Finished`);
        });
    });
    busboy.on('field', function(fieldname, val, fieldnameTruncated, valTruncated, encoding, mimetype) {
        log(`Field [${fieldname}]: value: ${val}`);
    });
    busboy.on('finish', function() {
        log('Done parsing form!');

        context.res = {
            status: 200, 
            body: { result: "done" }
        };
    });
    busboy.write(request.body, function() {});
};

export default httpTrigger;

A sample for containing fields and image:

<form action="http://localhost:7071/api/handlePostData" method="post" enctype="multipart/form-data">
  <label for="fname">First name:</label>
  <input type="text" id="fname" name="fname"><br><br>
  <label for="lname">Last name:</label>
  <input type="text" id="lname" name="lname"><br><br>
  <label for="selfie">Selfie:</label>
  <input type="file" accept="image/*" capture id="selfie" name="selfie"><br><br>
  <input type="submit" value="Submit">
</form>

Check the Busboy documentation for more information on configuration options and the handling fields and files.

Netlify functions - continue after completion

Serge van den Oever — Mon, 21 Sep 2020 17:54:15 +0000

Netlify functions are a powerful beast for all your API needs. But what if I want to return as soon as possible from my API call to keep my web UI responsive, but still need to do something like sending out an e-mail? Enter the "classic" function style that makes this possible.

https://docs.netlify.com/functions/overview/ can be used used to provide a API for your web site. You can buid your functions with JavaScript.

There are two common ways to write your Netlify function. The "modern" style and the "legacy" style:

// modern JS style - encouraged
export async function handler(event, context) {
  return {
    statusCode: 200,
    body: JSON.stringify({ message: `Hello world ${Math.floor(Math.random() * 10)}` })
  };
}

// legacy callback style - not encouraged anymore, but you'll still see examples doing this
exports.handler = function(event, context, callback) {
// your server-side functionality
callback(null, {
  statusCode: 200,
  body: JSON.stringify({
    message: `Hello world ${Math.floor(Math.random() * 10)}`
  })
});
};

I would encourage you to use the modern style, except when you want to return a result as soon as posible, but continue processing in the function. This can only be done with the legacy style, as follows:

function continueAfterDoneTest.js:

function getTime() {
  return (new Date()).toISOString().substr(11, 8);
}

exports.handler = (event, context, callback) => {
  console.log(`${getTime()}: THE FUNCTION HAS STARTED`);
  setTimeout(function () {
    console.log(`${getTime()}: THE TIMEOUT IS COMPLETED`)
  }, 5000);

  callback(null, { statusCode: 200, body: `${getTime()}: FUNCTION COMPLETED` });
};

Function output in the terminal:

◈ Creating Live Tunnel for 8ddb4b97-be43-46aa-855c-0d05999a8ec9

   ┌────────────────────────────────────────────────────────────┐
   │                                                            │
   │   ◈ Server now ready on https://idnv-3ea026.netlify.live   │
   │                                                            │
   └────────────────────────────────────────────────────────────┘

Request from ::1: GET /.netlify/functions/continueAfterDoneTest
12:40:00: THE FUNCTION HAS STARTED
Response with status 200 in 8 ms.
12:40:05: THE TIMEOUT IS COMPLETED

Output in the browser at url https://idnv-3ea026.netlify.live/.netlify/functions/continueAfterDoneTest:

12:40:00: FUNCTION COMPLETED

You will see this output in the browser directly, while the last line in the terminal output comes 5 seconds later.

How the Sitecore SXA team writes SXA components

Serge van den Oever — Mon, 13 Jul 2020 21:13:20 +0000

When you look at the out-of-the-box Sitecore SXA components you can see that the Sitecore SXA team writes most SXA components using jQuery and a small utility API called XA (eXperience Accelerator). In this post, I will dissect how Sitecore writes components and I will show you how to write a simple clock component in TypeScript using the XA API.

Introduction

If you look at the HTML code of an SXA page you will see something like the following scripts loaded at the end of the page body:

<script src="/componentlibrary/-/media/Base-Themes/Core-Libraries/scripts/optimized-min.js?t=20200616T160435Z"></script>
<script src="/componentlibrary/-/media/Base-Themes/XA-API/Scripts/optimized-min.js?t=20200616T160435Z"></script>
<script src="/componentlibrary/-/media/Base-Themes/Main-Theme/scripts/optimized-min.js?t=20200616T160436Z"></script>
<script src="/componentlibrary/-/media/Base-Themes/Components-Theme/Scripts/optimized-min.js?t=20200616T160436Z"></script>
<script src="/componentlibrary/-/media/Themes/DigitalMarketingPlatform/ComponentLibrary/ComponentLibrary/scripts/pre-optimized-min.js?t=20200527T181257Z"></script>

Sitecore loads a set of themes as part of an SXA site. These themes can be of type:

Base Themes - The out-of-the-box building blocks provided by Sitecore
Themes - An either out-of-the-box theme containing styling (Basic2 or Wireframe) or your custom theme that can be assigned to an SXA site
Extension Themes - additional extensions that can be assigned on top of a selected theme through selecting a module in your SXA site. See the blog post Use Extension Themes in the Sitecore Experience Accelerator by Mark van Aalst for more information on extension themes

Dissecting

Themes live in the Sitecore Media Library folder. If you investigate this folder you will see that Sitecore provides the separate JavaScript files in the Scripts folder of a theme. These files are automatically minified and bundled to a file optimized-min.js by Sitecore SXA using the Asset optimizer. It is also possible to do the optimization and bundling yourself. In that case a file pre-optimized-min.js must be placed in the Scripts folder of your theme. When this file is available it will be served, instead of combining the JavaScript files in the folder. This means also that it does not work to add an additional JavaScript file to the Scripts folder and expect it to be loaded by the browser because it will not be included in the resulting bundle. It is possible to add additional bundles in the Scripts folder and reference these bundles explicitly from the HTML code by including a script reference in a page design, a partial design or the metadata partial design; we have done this successfully with ReactJS bundles.

Note that if the theme assigned to an SXA site does not have a CSS bundle, the wireframe CSS bundle will be returned.

When you look at the out-of-the-box Sitecore SXA components you can see that the Sitecore SXA team writes most SXA components using jQuery (part of the xaquery.js file) and that they use a small utility API called XA (eXperience Accelerator).

If we look at the above-loaded JavaScript files we will see the following:

Base Theme: Core-Libraries

Located at: /sitecore/media library/Base Themes/Core Libraries

Consists of the following JavaScript libraries:

ie-origin-fix
xaquery
moment
lo-dash
modernizr
galleria-157
fullcalendar
gcal
jqueryuitouch-punchmin
hammer
backbone-min
typeahead
jquerymCustomScrollbar
flash-polyfill
mediaelement-and-player
dailymotion
facebook
soundcloud
twitch
vimeo

Base Theme: XA-API

Located at: /sitecore/media library/Base Themes/XA API

Consists of the following JavaScript libraries:

Base Theme: Main-Theme

Located at: /sitecore/media library/Base Themes/Main Theme

Consists of the following JavaScript libraries:

observer
partial-design-highlight

Base Theme: Components-Theme

Located at: /sitecore/media library/Base Themes/Components Theme

Consists of the following JavaScript libraries:

accessibility
component-accordions
component-archive
component-breadcrumb
component-carousel
component-container
component-disqus
component-facebook
component-flash
component-flip
component-fullcalendar
component-galleria
component-language-selector
component-navigation
component-overlay
component-snippet
component-social
component-tabs
component-toggle
component-video
component-video-playlist
details-polyfill
fixheight
search-fixheight

Theme: ComponentLibrary

Locates at: /sitecore/media library/Themes/DigitalMarketingPlatform/ComponentLibrary/ComponentLibrary

Consists of our own pre-optimized code. See SXA Umbrella for an example on how to do this.

Especially the XA API base theme and the Component Theme base theme are of interest to see how an SXA component can be written.

SXA API

The SXA API is a small utility library for writing a jQuery based SXA component.

The code of xa.js is small and provides functionality for:

initialization, with the ability to register pre-initialization and post-initialization handlers
cookie functions
a query string utility function
a function to register a DOM-changed callback function

Actually nothing you could not have written yourself.

The code of xa.js is as follows:

var XA = XA || (function ($, document) {
    var api = {}, onPreInitHandlers, onPostInitHandlers, modules = {};
    onPreInitHandlers = new Array();
    onPostInitHandlers = new Array();
    api.register = function (name, api, init) {
        modules[name] = {
            name: name,
            api: api,
            init: init || api.init || (function () { })
        };
    };
    api.hasPageModes = function () { return !!(window.Sitecore && window.Sitecore.PageModes); };
    api.registerOnPreInitHandler = function (handler) { onPreInitHandlers.push(handler); };
    api.registerOnPostInitHandler = function (handler) { onPostInitHandlers.push(handler); };
    var initScheduled = false;
    api.init = function () {
        if (!initScheduled) {
            initScheduled = true;
            XA.ready(function () {
                try {
                    for (var name in modules)
                        if (modules.hasOwnProperty(name)) {
                            $xa.each(onPreInitHandlers, function (i, h) { h.process(name, modules[name]); });
                            modules[name].init();
                            $xa.each(onPostInitHandlers, function (i, h) { h.process(name, modules[name]); });
                        }
                }
                finally {
                    initScheduled = false;
                }
            });
        }
    };
    api.ready = function (fn) {
        $(document).ready(fn);
    };
    api.component = {};
    api.connector = {};
    api.cookies = {
        createCookie: function (name, value, days) {
            if (days) {
                var date = new Date();
                date.setTime(date.getTime() + (days * 24 * 60 * 60 * 1000));
                var expires = "; expires=" + date.toUTCString();
            }
            else {
                expires = "";
            }
            document.cookie = name + "=" + value + expires + "; path=/";
        },
        readCookie: function (name) {
            var nameEQ = name + "=";
            var ca = document.cookie.split(';');
            for (var i = 0; i < ca.length; i++) {
                var c = ca[i];
                while (c.charAt(0) == ' ') {
                    c = c.substring(1, c.length);
                }
                if (c.indexOf(nameEQ) == 0) {
                    return c.substring(nameEQ.length, c.length);
                }
            }
            return null;
        },
        removeCookieWarning: function () {
            var cookieWarning = $xa(".privacy-warning");
            cookieWarning.remove();
        }
    };
    api.queryString = {
        getQueryParam: function (variable) {
            if (variable != null) {
                variable = variable.toLocaleLowerCase();
            }
            var query = window.location.search.substring(1);
            var vars = query.split("&");
            for (var i = 0; i < vars.length; i++) {
                var pair = vars[i].split("=");
                if (decodeURIComponent(pair[0].toLocaleLowerCase()) === variable) {
                    return decodeURIComponent(pair[1]);
                }
            }
            return null;
        }
    };
    var MutationObserver = window.MutationObserver || window.WebKitMutationObserver;
    var eventListenerSupported = window.addEventListener;
    api.dom = {
        observeDOM: function (obj, callback) {
            if (MutationObserver) {
                var obs = new MutationObserver(function (mutations) {
                    if (mutations[0].addedNodes.length || mutations[0].removedNodes.length)
                        callback();
                });
                var options = {
                    childList: true,
                    subtree: true
                };
                obs.observe(obj, options);
            }
            else if (eventListenerSupported) {
                obj.addEventListener('DOMNodeInserted', callback, false);
                obj.addEventListener('DOMNodeRemoved', callback, false);
            }
        }
    };
    return api;
})($, document);
XA.init();

The Flip SXA component

One of the simpler out-of-the-box SXA components is the Flip SXA component. It is nice that the SXA team has kept the documentation and comments in the code, which helps in understanding what is going on.

The code for component-flip.js is as follows:

/**
 * Component Flip
 * @module Flip
 * @param  {jQuery} $ Instance of jQuery
 * @return {Object} List of flip methods
 */
XA.component.flip = (function($) {
    /**
     * This object stores all public api methods
     * @type {Object.<Methods>}
     * @memberOf module:Flip
     * @
     * */
    var api = {
            /**
             * equalSideHeight set css "min-height" property with value that is
             * equal to size of bigger flip side 
             * @param {jQuery<DOMElement>} $el  Root DOM element of Flip component wrapped by jQuery 
             * @memberof module:Flip
             * @method equalSideHeight
             */
            equalSideHeight: function($el) {
                var side0 = $el.find(".Side0"),
                    side1 = $el.find(".Side1"),
                    slide0Height = this.calcSlideSizeInToggle(side0),
                    slide1Height = this.calcSlideSizeInToggle(side1),
                    maxHeight = Math.max(slide0Height, slide1Height);
                $el.find(".flipsides").css({ "min-height": maxHeight + "px" });
                side0.add(side1).css({ bottom: 0 });
            },
            /**
             * calcSlideSizeInToggle calculates size of slide content
             * @param {jQuery<DOMElement>} $slide Slide DOM Element of flip component
             * @memberof module:Flip
             * @method calcSlideSizeInToggle
             * @return {number} size
             */
            calcSlideSizeInToggle: function($slide) {
                var child = $slide.find(">div"),
                    size = 0;
                child.each(function(pos, el) {
                    size += $(el).outerHeight(true);
                });
                size += parseInt($slide.css("padding-top"));
                size += parseInt($slide.css("padding-bottom"));
                return size;
            },
            /**
             * equalSideHeightInToggle method that called from component toggle 
             * to make all slides inside same height
             * @param {jQuery<DOMElement>} $el  Root DOM element of Flip component wrapped by jQuery 
             * @memberof module:Flip
             * @method equalSideHeightInToggle
             */
            equalSideHeightInToggle: function($el) {
                var side0 = $el.find(".Side0"),
                    side1 = $el.find(".Side1"),
                    slide0Height = this.calcSlideSizeInToggle(side0),
                    slide1Height = this.calcSlideSizeInToggle(side1),
                    maxHeight = Math.max(slide0Height, slide1Height);
                $el.find(".flipsides").css({ "min-height": maxHeight + "px" });
                side0.add(side1).css({ bottom: 0 });
            }
        };

    function detectMobile() {
        return "ontouchstart" in window;
    }
    /**
     * calcHeightOnResize method calls
     * ["equalSideHeight"]{@link module:Flip.equalSideHeight} method
     * for all initialized Flip components
     * @memberOf module:Flip
     * @method
     * @alias module:Flip.initInstance
     * @private
     */
    function calcHeightOnResize() {
        var flip = $(".flip.initialized");
        flip.each(function() {
            api.equalSideHeight($(this));
        });
    }
    /**
     * initInstance method binds toggling "active" class for component
     * an Flip element
     * @memberOf module:Flip
     * @method
     * @param {jQuery} component Root DOM element of flip component wrapped by jQuery
     * @alias module:Flip.initInstance
     */
    api.initInstance = function(component) {
        // Set tabindex=0 for first header
        component.find('[class*="Side0"]').attr("tabindex", "0");
        //
        if (component.hasClass("flip-hover") && !detectMobile()) {
            component.hover(
                function() {
                    component.addClass("active");
                },
                function() {
                    component.removeClass("active");
                }
            );
        } else {
            component.on("click", function() {
                component.toggleClass("active");
            });
        }
    };
    /**
     * init method calls in a loop for each
     * flip component on a page and runs Flip's
     * ["initInstance"]{@link module:Flip.api.initInstance},
     * ["equalSideHeight"]{@link module:Flip.equalSideHeight} methods.
     * Added watcher to "resize" event on window that call
     * ["calcHeightOnResize"]{@link module:Flip.calcHeightOnResize}
     *
     * @memberOf module:Flip
     * @alias module:Flip.init
     */
    api.init = function() {
        var flip = $(".flip:not(.initialized)");
        $(window).on("resize", function() {
            calcHeightOnResize();
        });
        flip.each(function() {
            var $flipModule = $(this).find(".flipsides");
            $flipModule.find(".Side0").attr("tabindex", "0");
            api.initInstance($(this));
            $(this).addClass("initialized");
            api.equalSideHeight($(this));
        });
    };
    return api;
})(jQuery, document);

XA.register("flip", XA.component.flip);

A nice trick used in the registration of components on the page is how in the api.init() function a check is done for the class initialized on each of the elements with the class flip, so the component is not initialized twice. This is important when working in the experience editor where new flip components can be added to the page already containing flip components.

Writing SXA components using TypeScript

Within our company we write almost all of our front-end code using TypeScript. This is also possible for SXA components using the XA API. Below I provide a first take for writing a type definition file xa.d.ts for the XA API library. See https://github.com/macaw-interactive/sxa-umbrella/blob/master/local_modules/sxa-types/xa.d.ts for the latest version:

interface HashTable<T> {
    [key: string]: T;
}

export interface XAComponent {
    initInstance?: (component: JQuery, module: JQuery) => void
    init?: () => void;
}

export interface XAStatic {
    //
    register: (name: string, api?: any, init?: () => void) => void;
    hasPageModes: () => boolean;
    registerOnPreInitHandler: (handler: () => void) => void;
    registerOnPostInitHandler: (handler: () => void) => void;
    init: () => void;
    ready: (fn: () => void) => void;

    component: HashTable<XAComponent>;
    connector: any;
    cookies: {
        createCookie: (name: string, value: string, days: number) => void,
        readCookie: (name: string) => string | null,
        removeCookieWarning: () => void
    },
    queryString: {
        getQueryParam: (variable: string) => string
    },
    dom: {
        observeDOM: (obj: Node, callback: () => void) => void
    }
}

Writing an SXA component in TypeScript

As an example of a SXA component written in TypeScript I provide a simple clock component called xaclock below. See https://github.com/macaw-interactive/sxa-umbrella/blob/master/Media%20Library/Themes/DigitalMarketingPlatform/ComponentLibrary/ComponentLibrary/src/components/xaclock/xaclock.ts for the latest version:

import { XAStatic, XAComponent } from 'sxa-types/xa';
declare var XA: XAStatic;

import './xaclock.scss';

/**
 * Component XaClock
 * @module XaClock
 * @param  {jQuery} $ Instance of jQuery
 * @return {Object} List of XaClock methods
 */
XA.component.xaClock = (function ($) {
    /**
    * This object stores all public api methods
    * @type {Object.<Methods>}
    * @memberOf module:XaClock
    * @
    * */
    var api: XAComponent = {};

    function clockUpdate(component: JQuery) { 
        const stateContainer = component[0]; // unwrap
        const showTwelve: boolean = jQuery.data(stateContainer, "showTwelve");
        const hourShiftData: string | undefined = component.attr("data-hourshift");
        const hourShift = isNaN(parseInt(hourShiftData, 10)) ? 0 : parseInt(hourShiftData, 10);
        var date = new Date();
        component.css({ 'color': '#fff', 'text-shadow': '0 0 6px #ff0' });
        function addZero(x: number | string) {
            if (x < 10) {
                return x = '0' + x;
            } else {
                return x;
            }
        } 

        function twelveHour(x: number) {
            if (x > 12) {
                return x = x - 12; 
            } else if (x == 0) {
                return x = 12;
            } else {
                return x; 
            }
        }

        var hours = (date.getHours() + hourShift) % 24;
        if (showTwelve) hours = twelveHour(hours);
        var h = addZero(hours);
        var m = addZero(date.getMinutes());
        var s = addZero(date.getSeconds());

        component.text(h + ':' + m + ':' + s)
    }

    /**
    * initInstance method of a XaClock element
    * @memberOf module:XaClock
    * @method
    * @param {jQuery} component Root DOM element of XaClock component wrapped by jQuery
    * @param {jQuery} xaClockModule XaClock inner DOM element of XaClock component wrapped by jQuery
    * @alias module:XaClock.initInstance
    */
    api.initInstance = function (component, xaClockModule) { 
        const stateContainer = component[0]; // unwrap
        jQuery.data(stateContainer, "showTwelve", false);
        $(component).click(() => {
            let showTwelve: boolean = jQuery.data(stateContainer, "showTwelve");
            showTwelve = !showTwelve;
            jQuery.data(stateContainer, "showTwelve", showTwelve);
            console.log("showTwelve:", showTwelve);
        });
        clockUpdate(component);
        setInterval(() => clockUpdate(component), 1000);
    };

    /**
     * init method calls in a loop for each
     * XaClock component on a page and runs XaClock's
     * ["initInstance"]{@link module:XaClock.api.initInstance} methods.
     * @memberOf module:XaClock
     * @alias module:XaClock.init
     */
    api.init = function () {
        var $xaClocks = $(".xaClock:not(.initialized)");
        $xaClocks.each(function () {
            var $xaClockModule = $(this);
            // @ts-ignore
            api.initInstance($(this), $xaClockModule);
            $(this).addClass("initialized");
        });
    };

    return api;
})(jQuery);

XA.register("xaclock", XA.component.xaClock);

And a SCSS file xaclock.scss containing the styling:

.xaClock {
    margin: auto;
    top: 0;
    left: 0;
    bottom: 0;
    right: 0;
    width: 200px;
    height: 60px;
    color: #35e00a;
    border: 2px solid #999;
    border-radius: 4px;
    text-align: center;
    font: 50px/60px Helvetica;
    background: linear-gradient(90deg, #000, #5555);
}

Transpiling and bundling the code

Using TypeScript and SASS is nice, but brings the burden of doing transpilation, minification and bundling. That is why I wrote tooling to support a good front-end developer workflow for Sitecore SXA: SXA Umbrella - the project structure and tools to optimize the front-end team development workflow in any Sitecore SXA project (plug plug). Have a look at the extensive documentation in the Github repository, try it out and let me know if it works for you.

Note that the XA API TypeScript type definitions and the xaclock example component are included in the starter template of SXA Umbrella.

From SXACLI to enhancements to SXA Umbrella

Serge van den Oever — Mon, 04 May 2020 15:07:55 +0000

After investing a lot of time and effort in working with Sitecore SXACLI and creating enhancements on the standard SXACLI tooling I decided that it was time for a different approach. Please meet SXA Umbrella!

With Sitecore 9.3 a new set of tooling was introduced to improve the front-end developer workflow: SXA CLI. As described by Sitecore:

SXA CLI is a useful command-line tool to automatize tasks for an SXA project. This topic describes how to add a theme using SXA CLI. This can be convenient if you want to have more control over your assets and use a version control system, such as Git.

For us, it is important tooling because it provides a developer-first approach for our front-end developers in SXA development.

Because the out-of-the-box functionality was insufficient for our development workflow we extended the standard SXA CLI tooling into SXACLI-enhancements, and solved most of the issues we had with the out-of-the-box SXA CLI tooling. We now had things like:

support for a team-based development cycle
a way to fix the default provided theme SASS into Webpack compatible SASS
Webpack for transpilation of code and styling
Full support for TypeScript

But there were still some things "sub-optimal":

Support for only a single theme, and Scriban for the rendering variants of a single site
No support for grids, base themes and extension themes (although these could be seen as a theme as well)
A big and old code-base where we didn't use 90% of the code because he handled all the heavy lifting using Webpack

So time for a big make-over! Welcome to SXA Umbrella - Project structure and tooling to optimize front-end team development workflow in any Sitecore SXA project. The Github repository contains a lot of documentation and a getting started guide. Please let me know if it works for you or if you miss features.

Happy SXA front-end coding - the right way!

Sitecore 9.3 - uninstall site installed with Sitecore Install Assistant

Serge van den Oever — Tue, 31 Mar 2020 06:59:28 +0000

If you are still one of those losers like me that install their Sitecore 9.3 on their local machine with the Sitecore Install Assistant (SIA) instead of in a fancy set of docker containers using Docker Compose, and if you are an even bigger loser (like me) that you mess up your Sitecore installation or even worse forgot your Sitecore admin password, welcome to this life-saver post to uninstall your installation in seconds!

There is a great post by Scott Gillis of The Code Attic, a Sitecore Technology MVP, where he provides a great uninstall script for SharePoint 9.3 sites installed with the Sitecore Install Assistant. The post has the humble name Sitecore 9.3 Uninstall Script, but it saved my life after some stupid mistakes like messing up my Sitecore installation and forgetting my admin password.

I had to do some, probably for most Sitecore devs obvious, steps that I will document here as my external memory, so I will not forget them:

Open the Sitecore 9.3 Uninstall Script and read it!
Open this file, press the Raw button, copy the contents and save it to a file named Sitecore-Uninstall-SIA.ps1 in a convenient place (in my case next to the Sitecore Install Assistant installation folder).
Open a PowerShell shell
The script depends on the SitecoreFundamentals PowerShell module which I did not have installed on my system. I installed it with the following commands:

  Register-PSRepository -Name sc-powershell -SourceLocation https://sitecore.myget.org/F/sc-powershell/api/v2
  Install-Module -Name "SitecoreFundamentals" -RequiredVersion "1.1.0" -Repository "sc-powershell" -Force

Get a list of installed sites using the following PowerShell command to search the history of sites installed with the Sitecore Install Assistant:

  Select-String -Path "$env:USERPROFILE\sitecore.installassistant\Sitecore-InstallConfiguration_*.txt" -Pattern "\[SitecoreXP0_CreateWebsite\]\:\[Create\] "

Which in my case came back with:

  Sitecore-InstallConfiguration_1576455425.txt:711:[SitecoreXP0_CreateWebsite]:[Create] sergesc.dev.local
  Sitecore-InstallConfiguration_1581641373.txt:710:[SitecoreXP0_CreateWebsite]:[Create] habitathomesc.dev.local
  Sitecore-InstallConfiguration_1585527079.txt:725:[SitecoreXP0_CreateWebsite]:[Create] sxastyleguidesc.dev.local

Run the uninstall script using .\Sitecore-Uninstall-SIA.ps1 to uninstall the latest installed Sitecore site, or with -SIALogFile "$env:USERPROFILE\sitecore.installassistant\Sitecore-InstallConfiguration_1585527079.txt" to uninstall a specific Sitecore site
Have your SQLServer (localhost in my case), SqlAdminUser (sa in my case), and SqlAdminPassword ready, make sure you are uninstalling the right site and GO!

Please do this at your own risk:-)

Note that you can remove the SIA log file and corresponding files with the same number after you successfully removed your site. Don't remove the remaining log files, you need them for new uninstalls.

Fixing "sgen.exe" filename or extension is too long

Serge van den Oever — Tue, 25 Feb 2020 14:20:12 +0000

When you build a C# project in Visual Studio and get the error Error MSB6003 The specified task executable "sgen.exe" could not be run. System.ComponentModel.Win32Exception (0x80004005): The filename or extension is too long you can fix it by going to the properties of the C# project, and on the Build tab set the Generate serialization assembly to off.

Apply this setting to both the Debug and Release configuration, otherwise it works locally (Debug), but fails on your build server (Release).

See XML Serializer Generator Tool (Sgen.exe) for more information on the tooling.