Tailwind CSS is a highly customizable, low-level CSS framework that gives you all of the building blocks you need to build bespoke designs without any annoying opinionated styles you have to fight to override.

The goal of the framework is to provide a set of utility classes that help you define the structure and layout of your web application. It is unlike Bootstrap and Foundation because the entire focus of those frameworks is to provide a basic set of components to define a unified look of your website. So my goal is to set out and see if these frameworks work together well to build a simple web application.

In order to learn this framework, I will also be utilizing VueJS and Vuex to create a simple Todo application, which is not the focus of this post. I will take time to highlight some of the code used in building the application, but my main goal is to build an application that I can utilize Tailwind CSS to style the application. This means there are a few prerequisites you will need if you plan to follow along.

• Node JS will need to already be installed on your computer. You can visit https://nodejs.org/ to download the latest LTS version (at the time of this writing, 12.16.1)
• Visual Studio Code will be used as the primary editor. You can use any other editor you wish, but I find that Visual Studio code offers a lot of features that help with this type of development. I will include a list of extensions I’m using at the end of this article as well.
• Vue CLI will be used to scaffold the project. This can be installed with node package manager (npm) by executing the following command at a command prompt: npm install -g @vue/cli

Starting a Vue Project with Vue CLI

Begin by opening up a command line on your computer. Navigate to the path where you will create the project and add a new folder. Navigate to the new folder and type the following command: vue create tailwind-todo. This will invoke Vue CLI which will walk you through setting up the new project. Follow the screenshots below to set the options for the project:

Begin by manually selecting the options.

Next, make sure Babel, Vuex, CSS Pre-processors, and Linter / Formatter are selected as pictured.

Babel is a transpiler that converts ES2016+ JavaScript into JavaScript that is executed by the browser. Vuex is a state management library that holds the executing state of the application. CSS Pre-processors allow you to utilize SASS/SCSS or other CSS stylesheet pre-processor frameworks. Linter / Formatter helps enforce coding standards and best practices.

Select a Sass/SCSS processor. I prefer node-sass, but you can use any other if you want. Tailwind CSS uses PostCSS, which is why a CSS Pre-Processor is selected. We will use a Vue CLI plugin to enable the use of PostCSS.

I prefer to have linting turned on and use error prevention only. This will let me know if there are code issues as files are saved, primarily during hot module replacement.

Lint on save is the default option, but feel free to change based on your needs.

Use dedicated config files for various utility settings. I just find this easier to review and change when needed. The defaults in these files should work with this application.

If you want, feel free to make this a preset, but I’m not going to step through how that is done.

Vue CLI will now start to scaffold the project and install all dependencies needed. Once the project is ready you will see a message with information on how to start up the site.

At this point, if you chose to run the project you should be able to open a browser and see a basic Vue application running in a browser.

Including NPM Packages and Vue CLI Plugins

Now that we have a project scaffolded, Tailwind CSS needs to be installed. There is a Vue CLI plugin that enables Tailwind in projects which makes this much easier to do. Execute the following command: vue add vue-cli-plugin-tailwind and wait for the installation to prompt you concerning a configuration file. Select the minimal configuration.

You can learn more about configuring Tailwind CSS here: https://tailwindcss.com/docs/configuration

The project is almost set and ready to go, but a few more packages will be used. Execute the following command to use npm to install the final dependencies: npm install –save @mdi/font shortid

This installs a stylesheet with some icons and a utility to generate short unique id’s.

Cleaning the Slate

With the project scaffolded and all dependencies installed, run Visual Studio Code by typing code . at the command line. If Visual Studio Code is installed on your computer, it should start and already be pointed at the newly scaffolded project.

First, open the src folder and then open App.vue. This is the starting point for the application’s UI/UX, or the root component of the application.

Replace the content with the following:

<template>
  <div id="app">
  </div>
</template>
<script>
export default {
  name: "App",
  components: {
  },
  data: function() {
    return {
    };
  },
  computed: {
  },
  mounted() {
  },
  methods: {
  }
};
</script>
<style lang="postcss">
</style>

If the site is previewed at this point, it will be a completely empty site.

Next, in the src/components folder go ahead and remove HelloWorld.vue. This is a sample component that we won’t be using on our application.

Finally, in the src folder, open main.js and set the content to the following:

import Vue from 'vue'
import App from './App.vue'
import store from './store'
import './assets/tailwind.css'
import '@mdi/font/css/materialdesignicons.css';

Vue.config.productionTip = false
new Vue({
  store,
  render: h => h(App)
}).$mount('#app')

This file bootstraps the application and gets everything started. Notice that the CSS file for tailwind is included. This was done by the Vue CLI Tailwind plugin. Next, the icon CSS file is imported which allows use of the icons in the application.

The application is ready to be developed. The process will be to first create the application and verify that everything works. Don’t worry, it will be ugly for a little while. Once the application is completed and Tailwind is used to style the application, it should start to look a lot better.

Vuex

This project will make use of Vuex to handle state management. Vuex is based on the principles of the Flux state management pattern. The idea is to control the way state is changed in the application through a predictable means.

At a high level, a Vuex store will include the following properties:

• State -The current state of the application at any given point. In most implementations of the flux pattern, state should never be modified directly.
• Mutations – Definitions of how state changes throughout the application life. Mutations are the mechanism by which state is changed in the application.
• Actions – Asynchronous methods that commit mutations within the application. The primary difference is that a mutation can never by asynchronous, while actions can be either synchronous or asynchronous. 
• Getters – Computed properties based on the current state of the application. Vuex allows for both property based and method based computed properties. 

Based on the description of a mutation, you might be tempted to execute them directly. There is nothing that would prevent you from doing so — but I would recommend using actions so that error handling can be done in a predictable fashion with JavaScript promises. You will see this pattern used in the application, even though we are not using an external data store (and we aren’t explicitly handling errors).

The first thing that needs to be done when setting up a Vuex store is to set what the state will look like. This is also where default values must be set. In this application, an array of tasks will be our only state property. To do this, open index.js in src/store. You will see a very basic Vuex store already defined with the properties listed above (state, mutations, actions). Getters will not be present. They will need to be added to the store, which will be done later.

State

Navigate to the state property and add a property named tasks with a default blank array. It is important in Vuex to set the default value of the store to the value that is expected at runtime. This will become the initial value of the state object at runtime.

state: {
  tasks: []
},

Mutations

Mutations are simply functions declared within the store. However, when actions commit mutations, a string is passed so the store knows which mutation to commit. In order to simplify this, many developers will often define mutations as constants in a separate file and then utilize those constants to define the mutations for the application.

To create constants for the mutations needed for the application, add a file to the store folder named mutationTypes.js. Open the new file and add the following code:

export const ADD_TASK = 'ADD_TASK';
export const COMPLETE_TASK = 'COMPLETE_TASK';
export const CLEAR_TASK = 'CLEAR_TASK';
export const REMOVE_COMPLETED_TASKS = 'REMOVE_COMPLETED_TASKS';
export const UPDATE_TASK = 'UPDATE_TASK';
export const REMOVE_TASK = 'REMOVE_TASK';

This file defines multiple constants that will be utilized to define the mutations in the application. The application will be able to add a task (ADD_TASK),, complete a task (COMPLETE_TASK), clear the completed status of a task (CLEAR_TASK), remove all completed tasks (REMOVE_COMPLETED_TASKS), update a task (UPDATE_TASK), and remove a single task (REMOVE_TASK). For the purposes of this article, all of the mutations related to removing tasks will be skipped. Once the pattern is understood, feel free to see if you are able to implement them yourself within the application.

Back in the src/store/index.js file, the mutationTypes.js file needs to be imported. Include the following line at the top of the file with the other import statements. Also, go ahead and import shortid since it will be used to create id’s for tasks as they are added by actions.

import shortid from 'shortid';
import * as Mutation from './mutationTypes';

Next, we will use the capabilities of ES2016+ to name the mutations as functions within the application. Here’s the code:

mutations: {
    [Mutation.ADD_TASK](state, payload) {
      // payload should be the full task, including an id
      state.tasks.push(payload);
    },
    [Mutation.UPDATE_TASK](state, payload) {
      // payload should include the index and the updated task
      state.tasks.splice(payload.index, 1, payload.updatedTask);
    },
    [Mutation.REMOVE_TASK](state, payload) {
      // payload should include the index of the task to remove
      state.tasks.splice(payload.index, 1);
    },
    [Mutation.COMPLETE_TASK](state, payload) {
      let task = state.tasks[payload.index];
      task.complete = true;
    },
    [Mutation.CLEAR_TASK](state, payload) {
      let task = state.tasks[payload.index];
      task.complete = false;
    },
    [Mutation.REMOVE_COMPLETED_TASKS](state) {
      let filteredTasks = state.tasks.filter(t => !t.complete);
      Vue.set(state, 'tasks', filteredTasks);
    }
  },

Each mutation makes use of state by passing the state argument. Additionally, for mutations that must make modifications to data a payload is passed to the mutation as well. Inside Chrome with the Vue Developer Tools installed, anytime mutations occur they can be visualized. Additionally, the Vue developer tools allow you to rewind state, replay mutations, and preview the current state.

Looking at the code, the add task mutation should include a payload made up of a task object. The task object is simply pushed into the existing array. This is why it is a good idea to initialize the state of the application by setting default values for state.

In the update, remove, complete, and clear mutations a similar pattern is exposed. The payload includes an index which is the index of the task. This is used to splice the new data into the tasks array, or splice date out of the tasks array.

Finally, the remove completed tasks mutation makes use of the Vue.set() method to set the state of the tasks to only incomplete tasks. This is done because a limitation to the current reactivity detection of Vue objects and arrays. Using Vue.set() insures all reactivity hooks are executed upon the change of a complex object or array. (see: https://vuex.vuejs.org/guide/mutations.html#mutations-follow-vue-s-reactivity-rules)

Getters

Getters are computed properties based on the current state of the store. This app will include two, a filtered list of completed tasks and a filtered list of active tasks. Here’s the code:

getters: {
    completedTasks: (state) => {
      return state.tasks.filter(t => t.complete);
    },
    activeTasks: (state) => {
      return state.tasks.filter(t => !t.complete);
    }
  },

A new property is added to the root store named getters. Each getter is a function that utilizes state as the first property. In both of the getters for the task store, the array.filter() function is used to return a new array of tasks that match the supplied criteria (in this case, if complete is set to true or false respectively).

Actions

The most complex section of the store is the actions section. Remember earlier that I recommend that all actions be returned as promises so that error handling can be accomplished in a more unified way. Each action will commit a mutation. Once the mutation is committed successfully, the promise will be resolved. If there are any errors during execution — the promise will be rejected along with an error object.

Here is the code:

actions: {
    addTask({ commit }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var newTask = { ...payload, id: shortid() };
          commit(Mutation.ADD_TASK, newTask);
          resolve();
        } catch (e) {
          reject(e);
        }
      })
    },
    updateTask({ commit, state }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var taskIndex = state.tasks.findIndex(t => t.id === payload.id);
          if (taskIndex === -1) {
            reject(new Error(`Task id ${payload.id} was not found`));
          } else {
            commit(Mutation.UPDATE_TASK, { index: taskIndex, updatedTask: payload });
            resolve();
          }
        } catch (e) {
          reject(e);
        }
      });
    },
    removeTask({ commit, state }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var taskIndex = state.tasks.findIndex(t => t.id === payload);
          if (taskIndex === -1) {
            reject(new Error(`Task id ${payload} was not found`));
          } else {
            commit(Mutation.REMOVE_TASK, { index: taskIndex });
            resolve();
          }
        } catch (e) {
          reject(e);
        }
      });
    },
    completeTask({ commit, state }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var taskIndex = state.tasks.findIndex(t => t.id === payload);
          if (taskIndex === -1) {
            reject(new Error(`Task id ${payload} was not found`));
          } else {
            commit(Mutation.COMPLETE_TASK, { index: taskIndex });
            resolve();
          }
        } catch (e) {
          reject(e);
        }
      });
    },
    clearTask({ commit, state }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var taskIndex = state.tasks.findIndex(t => t.id === payload);
          if (taskIndex === -1) {
            reject(new Error(`Task id ${payload} was not found`));
          } else {
            commit(Mutation.CLEAR_TASK, { index: taskIndex });
            resolve();
          }
        } catch (e) {
          reject(e);
        }
      });
    },
    removeCompletedTasks({ commit }) {
      return new Promise((resolve, reject) => {
        try {
          commit(Mutation.REMOVE_COMPLETED_TASKS);
          resolve();
        } catch (e) {
          reject(e);
        }
      });
    }
  },

The addTask action is a function that combines the payload, which should be a complete task object, with a randomly generated id. The new task is used as the payload to commit the ADD_TASK mutation. Since mutations are handled synchronously, the promise is resolved. When resolving the promise, it would also be possible to return the task. However, since the state is automatically maintained by the Vuex store, the UI will automatically be updated whenever a task is added.

If there are any errors adding the task, then the promise is rejected. In this case, an error object is always supplied which can be utilized by any calling component to be displayed in the application.

This pattern provides a controlled way to make sure that each mutation should be successful. This application can use the promise.then().catch() pattern to deal with successful and unsuccessful requests to execute actions. This becomes even more important when working with external data or API’s within the application. 

Final Vuex Store

Here’s the full code for the store:

import Vue from 'vue'
import Vuex from 'vuex'
import shortid from 'shortid';
import * as Mutation from './mutationTypes';
Vue.use(Vuex)
export default new Vuex.Store({
  state: {
    tasks: []
  },
  mutations: {
    [Mutation.ADD_TASK](state, payload) {
      // payload should be the full task, including an id
      state.tasks.push(payload);
    },
    [Mutation.UPDATE_TASK](state, payload) {
      // payload should include the index and the updated task
      state.tasks.splice(payload.index, 1, payload.updatedTask);
    },
    [Mutation.REMOVE_TASK](state, payload) {
      // payload should include the index of the task to remove
      state.tasks.splice(payload.index, 1);
    },
    [Mutation.COMPLETE_TASK](state, payload) {
      let task = state.tasks[payload.index];
      task.complete = true;
    },
    [Mutation.CLEAR_TASK](state, payload) {
      let task = state.tasks[payload.index];
      task.complete = false;
    },
    [Mutation.REMOVE_COMPLETED_TASKS](state) {
      let filteredTasks = state.tasks.filter(t => !t.complete);
      Vue.set(state, 'tasks', filteredTasks);
    }
  },
  getters: {
    completedTasks: (state) => {
      return state.tasks.filter(t => t.complete);
    },
    activeTasks: (state) => {
      return state.tasks.filter(t => !t.complete);
    }
  },
  actions: {
    addTask({ commit }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var newTask = { ...payload, id: shortid() };
          commit(Mutation.ADD_TASK, newTask);
          resolve();
        } catch (e) {
          reject(e);
        }
      })
    },
    updateTask({ commit, state }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var taskIndex = state.tasks.findIndex(t => t.id === payload.id);
          if (taskIndex === -1) {
            reject(new Error(`Task id ${payload.id} was not found`));
          } else {
            commit(Mutation.UPDATE_TASK, { index: taskIndex, updatedTask: payload });
            resolve();
          }
        } catch (e) {
          reject(e);
        }
      });
    },
    removeTask({ commit, state }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var taskIndex = state.tasks.findIndex(t => t.id === payload);
          if (taskIndex === -1) {
            reject(new Error(`Task id ${payload} was not found`));
          } else {
            commit(Mutation.REMOVE_TASK, { index: taskIndex });
            resolve();
          }
        } catch (e) {
          reject(e);
        }
      });
    },
    completeTask({ commit, state }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var taskIndex = state.tasks.findIndex(t => t.id === payload);
          if (taskIndex === -1) {
            reject(new Error(`Task id ${payload} was not found`));
          } else {
            commit(Mutation.COMPLETE_TASK, { index: taskIndex });
            resolve();
          }
        } catch (e) {
          reject(e);
        }
      });
    },
    clearTask({ commit, state }, payload) {
      return new Promise((resolve, reject) => {
        try {
          var taskIndex = state.tasks.findIndex(t => t.id === payload);
          if (taskIndex === -1) {
            reject(new Error(`Task id ${payload} was not found`));
          } else {
            commit(Mutation.CLEAR_TASK, { index: taskIndex });
            resolve();
          }
        } catch (e) {
          reject(e);
        }
      });
    },
    removeCompletedTasks({ commit }) {
      return new Promise((resolve, reject) => {
        try {
          commit(Mutation.REMOVE_COMPLETED_TASKS);
          resolve();
        } catch (e) {
          reject(e);
        }
      });
    }
  },
  modules: {
  }
})

Components

Vue applications consist of one or more components. Each component has the ability to utilize the Vuex store. In this application, there will be a single component that interacts directly with the store. All other components will utilize other mechanisms in view to state management and user interactions. The remaining components for this application include a form to create tasks, a unified way to display tasks, and a way to display a list of tasks.

TaskForm.vue

The task form will be used to create and edit tasks. The requirements of the form is to allow the user to enter the name of a task and press enter to confirm it. Optionally, the user may press escape to cancel any pending changes. For mobile users, a button will be used to allow cancelling changes.

To begin, create a new file named TaskForm.vue in the src/components folder. This file is a single page Vue component which will include the template, code, and styling for the component.

Start by putting the following code into the file:

<template>
  <div class="taskForm">
    <input
      type="text"
      v-model="name"
      placeholder="Task Name (i.e. Wash Dishes)"
      @input="$emit('update:taskName',$event.target.value)"
      @keyup.enter="$emit('save:changes',$event.target.value)"
      @keyup.esc="$emit('cancel:changes')"
    />
    <button type="button" @click.stop="$emit('cancel:changes')">
      <span class="mdi mdi-close-circle-outline"></span>
    </button>
  </div>
</template>

This creates a new DIV with the class taskForm. Inside the DIV is an INPUT and a BUTTON. If you are new to view, you may see some syntax that you may not understand. v-model binds a property to an element. This is a two-way binding and will change as the value of the input is updated. Additionally, there are multiple attributes with an @ at the start of it. These are event-handlers. All of these event handlers raise custom events using Vue’s built in $emit function. These custom events can be handled by other components.

The keyup events in the form make use of event modifiers. This simplifies the code required by the developer. In this component, the enter key and the escape keys are handled independently and raise custom events that can be handled by parent components via the $emit() function in Vue.

Now, add the following to the file after the template section. This is the script for the component and is used to handle behavior and state.

<script>
export default {
  props: {
    taskName: {
      type: String,
      default: ""
    }
  },
  data: function() {
    return {
      name: this.taskName
    };
  },
  watch: {
    taskName(newName) {
      this.name = newName;
    }
  }
};
</script>

There is single property that is passed into the component, named taskName. The property is also used to initialize the internal state of the component returned by the data function.

The internal state of the component is tracked independently of the property. However, the component should respond to any external changes that occur due to property changes. This is accomplished by the watch function. This function simply watches taskName and applies detected changes to the internal state.

The property taskName is a string value that is passed to the component upon initialization. Additionally, since this component can be used to edit an existing task, that change should be explicitly tracked by an intentional desire of the user. To accomplish this, the data function returns the state of the current component. In this case, a name property is the only state value in the component. This becomes important later on when the component is used to cancel changes.

TaskItem.vue

Create another new file named TaskItem.vue in the src/components folder. Add the following template to the file:

<template>
  <div class="taskItem" :class="{'done':complete}">
    <button type="button" @click.stop="onCompleteTask" v-if="!complete" :disabled="editMode"></button>
    <button type="button" @click.stop="onClearTask" v-else :disabled="editMode">
      <span class="mdi mdi-check"></span>
    </button>
    <div v-if="editMode" class="taskItemForm">
      <TaskForm
        :taskName="taskName"
        @cancel:changes="onCancelChanges"
        @save:changes="onSaveChanges"
        ref="taskForm"
      ></TaskForm>
    </div>
    <div v-else @click.stop="editMode=true" class="taskName">{{taskName}}</div>
  </div>
</template>

The template is pretty simple. The idea is to allow a user to click on the name of a task to be able to edit the name. The user may also click on the button to toggle the task’s complete state. Notice this time, many of the custom events are handled directly by methods on this component.

Also, notice the use of the TaskForm component in the template. The form will be used any time a user wants to make changes to the task. The task form uses a colon (:) prior to an attribute. This is a shorthand for a v-bind Vue directive which dynamically sets the value passed to the associated property on the TaskForm component. 

The code required for the TaskItem is a little more involved. Place the code into the script section:

<script>
import TaskForm from "./TaskForm";
export default {
  components: {
    TaskForm
  },
  props: {
    taskId: {
      type: String,
      required: true
    },
    taskName: {
      type: String,
      required: true
    },
    complete: {
      type: Boolean,
      required: true
    }
  },
  data: function() {
    return {
      editMode: false
    };
  },
  watch: {
    editMode(newValue) {
      if (newValue) {
        this.$nextTick(function() {
          document.querySelector("input", this.$refs.taskForm.$el).select();
        });
      }
    }
  },
  methods: {
    onSaveChanges(newName) {
      this.editMode = false;
      this.$emit("update:task", {
        id: this.taskId,
        name: newName
      });
    },
    onCancelChanges() {
      this.editMode = false;
    },
    onCompleteTask() {
      this.$emit("complete:task", this.taskId);
    },
    onClearTask() {
      this.$emit("clear:task", this.taskId);
    }
  }
};
</script>

The TaskItem component has properties for the taskId, taskName, and complete. These properties are all marked as required as well, meaning there will be an error displayed if they are not provided to the component at runtime.

This component has a single state object named editMode. The editMode state controls whether the component is in an editable state or a non-editable state. Something worth calling out in this component is the watcher. The component watches the editMode state. If the component enters edit mode, this function fires to make sure the input on the taskForm is selected. This is done by waiting on Vue to update the DOM and then calling the select function on the input using the $nextTick Vue function.

Finally, there are a few methods that are called by events raised in the application. The reason many of these methods are in place are to augment the event arguments and change internal state of the component.

TaskList.vue

The final component used in the application is the TaskList. Create a new file in src/components named TaskList.vue. The template should be:

<template>
  <div>
    <div v-for="task in tasks" :key="task.id">
      <TaskItem
        :taskId="task.id"
        :taskName="task.name"
        :complete="task.complete"
        @complete:task="$emit('complete:task',$event)"
        @clear:task="$emit('clear:task',$event)"
        @update:task="$emit('update:task',$event)"
      ></TaskItem>
    </div>
    <div v-if="!hasTasks">
      <p>{{message}}</p>
    </div>
  </div>
</template>

This template uses the v-for binding in Vue to iterate over each task to create a new task item.

Additionally, the code for this is fairly simple as well:

<script>
import TaskItem from "./TaskItem";
export default {
  components: {
    TaskItem
  },
  props: {
    tasks: {
      type: Array,
      default: function() {
        return [];
      }
    },
    message: {
      type: String,
      default: "No tasks"
    }
  },
  computed: {
    hasTasks() {
      return this.tasks.length > 0;
    }
  }
};
</script>

The script starts be importing the TaskItem and registering it for use within the component. The properties of this component include a message and tasks. Finally, there is a computed property so the component can display a message in the event there are no tasks.

Putting everything together, getting the app running.

At this point, all files can be closed. However, make sure App.vue in the src folder is open. This is the core of the application and will manage everything in the Todo application.

First, set the template:

<template>
  <div id="app">
    <h1>Tailwind Todo</h1>
    <div id="tabs">
      <div class="tab" :class="{'active':activeTab==='all'}" @click.stop="activeTab='all'">All Tasks</div>
      <div
        class="tab"
        :class="{'active':activeTab==='active'}"
        @click.stop="activeTab='active'"
      >Active Tasks</div>
      <div
        class="tab"
        :class="{'active':activeTab==='closed'}"
        @click.stop="activeTab='closed'"
      >Completed Tasks</div>
    </div>
    <div id="list">
      <h2 v-if="activeTab==='active'||activeTab==='all'">Tasks</h2>
      <h2 v-else>Completed Tasks</h2>
      <TaskList
        :tasks="visibleTasks"
        @complete:task="onCompleteTask"
        @clear:task="onClearTask"
        @update:task="onSaveChanges"
      ></TaskList>
    </div>
    <div id="newForm">
      <h2>New Task</h2>
      <TaskForm
        @save:changes="onAddTask"
        @cancel:changes="onCancelAddTask"
        :taskName.sync="taskName"
        :addMode="true"
      ></TaskForm>
    </div>
  </div>
</template>

This is a fairly simple template, but let me call out a few things. First, there div with the id tabs is set to contain three additional tabs. These are all individual tabs used in the application to change which tasks are visible. The .active class is applied dynamically as each tab is activated. Clicking on the tab will dynamically set the activeTab to the associated value (i.e. clicking Active sets activeTab to active).

For the app, the code is a bit more complex so each section will be added and explained bit by bit.

First, add the following imports to a script section:

import { mapState, mapGetters, mapActions } from "vuex";
import TaskList from "./components/TaskList";
import TaskForm from "./components/TaskForm";

Each of the items that are imported, mapState, mapGetters, and mapActions, are helper functions within Vuex. These take care of the details of mapping the state within the Vuex store to the app. mapState and mapGetters will map any state or getters as a computed values in the component. This facilitates communication between the component (App.vue) and the Vuex store.

Next, the components used within the application are imported. Those need to be registered in a components property:

export default {
  name: "App",
  components: {
    TaskList,
    TaskForm
  },
}

The application template has a couple of state objects that need to be made available in the app state. The first is the active tab, and the second is the name of a task to be added to the application.

data: function() {
    return {
      activeTab: "all",
      taskName: ""
    };
  },

Vuex provides the remaining state of the application. All of the vuex state comes into the application as computed properties. Remember, the mapState and mapGetter functions are used to get state and computed values from the store into the component:

computed: {
    ...mapState(["tasks"]),
    ...mapGetters(["activeTasks", "completedTasks"]),
    visibleTasks() {
      if (this.activeTab === "active") return this.activeTasks;
      if (this.activeTab === "closed") return this.completedTasks;
      return this.tasks;
    }
  },

Using the spread operator (…), mapState brings in all of the tasks. mapGetters brings in the two getters defined in the Vuex store. These will be mapped to properties with the same name inside the app. Next, an application specific computed property is defined named visibleTasks. All this does is determine which property to return to be displayed in the TaskList component.

We bring in actions in the same way, but they live within the methods property of the application:

methods: {
    ...mapActions([
      "addTask",
      "updateTask",
      "removeTask",
      "completeTask",
      "clearTask",
      "removeCompletedTasks"
    ])
  }

We can utilize these actions within out own code in the application. Here are the remaining methods:

    onCompleteTask(taskId) {
      this.completeTask(taskId);
    },
    onClearTask(taskId) {
      this.clearTask(taskId);
    },
    onSaveChanges(e) {
      let task = this.tasks.find(t => t.id === e.id);
      this.updateTask({ ...task, name: e.name });
    },
    onAddTask(newName) {
      this.addTask({ name: newName, complete: false }).then(() => {
        this.taskName = "";
      });
    },
    onCancelAddTask() {
      this.taskName = "";
    },

Notice in the method onAddTask, the promise resolution clears the current task name. The idea is that once the task has been added, the application needs to be ready to accept a new task.

Finally, providing a few sample tasks to review in the app can be done when the app is mounted. This is a method called during the Vue lifecycle:

mounted() {
    this.addTask({ name: "Sample Task 1", complete: false });
    this.addTask({ name: "Sample Task 2", complete: false });
    this.addTask({ name: "Sample Task 3", complete: true });
  },

Here’s the full script for the app:

<script>
import { mapState, mapGetters, mapActions } from "vuex";
import TaskList from "./components/TaskList";
import TaskForm from "./components/TaskForm";
export default {
  name: "App",
  components: {
    TaskList,
    TaskForm
  },
  data: function() {
    return {
      activeTab: "all",
      taskName: ""
    };
  },
  computed: {
    ...mapState(["tasks"]),
    ...mapGetters(["activeTasks", "completedTasks"]),
    visibleTasks() {
      if (this.activeTab === "active") return this.activeTasks;
      if (this.activeTab === "closed") return this.completedTasks;
      return this.tasks;
    }
  },
  mounted() {
    this.addTask({ name: "Sample Task 1", complete: false });
    this.addTask({ name: "Sample Task 2", complete: false });
    this.addTask({ name: "Sample Task 3", complete: true });
  },
  methods: {
    onCompleteTask(taskId) {
      this.completeTask(taskId);
    },
    onClearTask(taskId) {
      this.clearTask(taskId);
    },
    onSaveChanges(e) {
      let task = this.tasks.find(t => t.id === e.id);
      this.updateTask({ ...task, name: e.name });
    },
    onAddTask(newName) {
      this.addTask({ name: newName, complete: false }).then(() => {
        this.taskName = "";
      });
    },
    onCancelAddTask() {
      this.taskName = "";
    },
    ...mapActions([
      "addTask",
      "updateTask",
      "removeTask",
      "completeTask",
      "clearTask",
      "removeCompletedTasks"
    ])
  }
};
</script>

Tailwind Styling

At this point, open a command prompt and navigate to the folder where the project is stored. If you are using Visual Studio Code, you can press <Ctrl>-<Shift>-<~> to open a terminal already test to the current folder. Type npm run serve and then open a browser to the url indicated. You should find the application works, but you will discover that it isn’t very usable. That’s where Tailwind CSS should help.

App.vue

Again, start with App.vue. Add a style section at the bottom of the file for styling. Make sure that the type is PostCSS:

<style lang="postcss">
</style>

This will allow styles to be created for the application. First, create a style for the body tag of the application:

body {
    @apply bg-blue-800 flex justify-center content-center h-screen items-center;
}

The way Tailwind CSS works is through the use of the @apply. The details are better explained on the Tailwind CSS site, but in the above rule, a blue background is applied and the body is set to use a CSS flexbox. All of the content is centered and the body is set to the full height of the current screen.

This does little more than center the application on a blue background.

There are several div’s in the template of App.vue that can be leveraged. First, create a rule for the root tag of App.vue:

#app {
  @apply rounded bg-gray-200 p-8 border border-blue-900 shadow-md flex flex-col flex-grow;
  min-width: 320px;
  max-width: 800px;
}

This sets the background to a gray color with some padding. It also includes a border that is rounded with a box-shadow.  Additionally, the CSS flexbox is used and set to columns instead of rows. The app is starting to look better:

Next, the tabs need to be addressed. If you look back at the template, we have a container div with the id #tabs and children divs with the class .tab. Using these, we can build several styles to control how the tabs look:

#tabs {
  @apply flex justify-between mb-4;
}
#tabs .tab {
  @apply bg-gray-400 p-2 rounded flex-grow mr-10 text-center;
}

This will apply some basic styles to the tabs. First, the outer container is set to flex with space between each child. There is a bottom margin applied to provide some additional whitespace at the bottom of the container.

Each tab is set to grey with a rounded background. The text is centered in each tab and a margin is applied to the right of each tab.

However, no margin should be applied to the last tab in the collection. This can easily be done with CSS rules:

#tabs .tab:last-child {
  @apply mr-0;
}

The active tab should be indicated using a different color. Again, this is accomplished through standard CSS rules:

#tabs .tab.active {
  @apply bg-blue-700 text-gray-300;
}

The application now has a much better look, but there is still a lot of improvement needed.

In the template, we have a couple of different headers used. Finish out styling by creating styles for those as well.

#app h1 {
  @apply text-3xl text-blue-700 font-bold mb-3 self-center;
  text-shadow: 3px 3px 7px rgba(0, 0, 0, 0.3);
}
#app h2 {
  @apply text-xl text-gray-600 font-medium mb-3;
}

Notice that you can easily mix standard css properties with the PostCSS apply method as well. The application is definitely improved, but the application isn’t as usable as it needs to be. It might be tempting to continue to apply styles in this area, but in larger applications it is often better to use another feature of Vue — scoped styles.

TaskForm.vue

The first component to tackle is the form. The input needs some additional padding and the cancel button needs to be called out. However, we may not want all inputs in our application to use this new style. Let’s scope them to this component only by adding a style section that is scoped:

<style lang="postcss" scoped>
</style>

Notice the scoped attribute in the style tag. This instructs Vue CLI to target any styles contained within this component to only get applied to the component. This insures when styles are applied, they will be scoped to all instances of this component but will not override any other styles in the application.

The container for the form component has the class .taskForm. Using this, we can begin to style the form:

.taskForm {
  @apply flex justify-center items-center;
}
input {
  @apply flex-grow p-1 rounded-md;
}

First, the form will be set to use the CSS flexbox. The input will be allowed to grow. It also has some padding and a rounded border.

Next, the button needs some attention. Since the styles are scoped, just simple create a rule for the button:

button {
  @apply p-1 rounded-md bg-red-800 ml-2;
  width: 32px;
  height: 32px;
}
button:active, button:focus {
  @apply outline-none;
}
button span {
  @apply text-red-200;
}

Again, using CSS pseudo selectors, the default outline around an active control is removed. Since there is an icon inside the button, it needs to be included. Notice that the style definition remains fairly simple — but if you look at the rules that are generated using Chrome Developer Tools, you will see an identifier used to target just those items in the application.

This is how all buttons within this component are styled and do not cause conflicts with other buttons in the application.

Finally, adding a little interactivity to the input might be good as well. When the input is focused, make the background a blue color with a heavier outline. Here’s the rule:

input {
  @apply transition-all duration-150;
}
 input:focus,  input:active {
  @apply bg-blue-200 outline-none shadow-outline;
}

Now the input will have a short animated transition with a blue background and a heavier outline:

Additionally, if you click on any existing tasks they will show a similar styling. This was done within a single component. As the component is reused throughout the application, all instanced will have the same styles applied.

TaskItem.vue

Now that the form looks better, the form items need to be adjusted. Open TaskItem.vue and add a style element to the end of the file. Again, make sure this is a scoped style tag.

<style lang="postcss" scoped>
</style>

First, apply a few styles from Tailwind to make sure the items are displayed similarly as the form.

.taskItem {
  @apply flex items-center my-4;
}

If you look at the app at this point, you’ll notice everything is starting to line up, but there is no way to complete a task because the button has no width applied.

To address this, apply styles to the button element. Remember, this is a scoped item so the styles will not affect the form button in any way.

button {
  @apply p-1 rounded-full bg-white border border-gray-400 mr-2;
  width: 32px;
  height: 32px;
}
button span {
  @apply text-green-500;
}

The button now has a defined width and height which allows the user to click to either mark the task completed or incomplete.

Notice that the original form button remains the same:

There is one more problem to correct. If you click on the name of a task, the form is now collapsed and doesn’t fill the entire area.

The fix is simple, apply a flex-grow to the form. At the same time, go ahead and add a style that changes the display of completed tasks.

.taskItem.done .taskName {
  @apply text-gray-600;
  text-decoration: line-through;
}
.taskItem .taskName,
.taskItem .taskItemForm {
  @apply flex-grow;
}

At this point, the application should be running successfully. Users should be able to add tasks, update tasks, mark tasks as complete or incomplete, and filter tasks. Feel free to explore how to add the final actions to the application. This includes the ability to remove a single task and the ability to remove all completed tasks.

The full source code for this example can be found on GitHub: https://github.com/cquick/tailwind-vuex-vue-todo-sample

Final Thoughts

One of the main reasons I investigated using Tailwind CSS is because so many of the web applications that I have worked on in the past make use of frameworks like Bootstrap, Foundation, or other similar frameworks. The biggest challenge faced in a lot of these frameworks is the strong opinion on the way things must look. While these frameworks allow for rapid prototyping of applications and getting something up and running fairly quickly, there comes a point in the lifecycle of some sites, especially if they are public facing, when they really need to stand apart from their competitors or more closely match design standards of the organization. It’s at this point when customization of the site starts to get hard.

I have often found myself and my team writing multiple style rules to override the way the base framework looks. This can be error prone and quite difficult for maintenance as it can lead to a lot of extra style rules that may not be needed. This is why I found Tailwind CSS a compelling prospect. It declares itself as a low-level CSS framework without strong opinions. 

I did find working with Tailwind introduced new challenges that I didn’t expect. First, it was really difficult to force myself to use their predefined styles. Second, I didn’t completely agree with the styles that were available. For example, padding and margins were either less than I desired or far more than I wanted. I also found widths to be a bit frustrating at times as well, which is why there are explicit widths set on the icon buttons in the application. However, one of the real advantages I found using Tailwind is not having to remember how much rounding I was using in different places and the application of colors. In the end, it provided a consistent website as I didn’t have to remember that I needed 0.25rem of padding — I just applied p-1 and got it across all components in the application.

Would I use Tailwind CSS again? Probably not. It might be useful for someone who isn’t as familiar with CSS properties, but for me I still find it much easier to use raw CSS or SCSS stylesheets. I found myself wrestling with styles much more than I would have liked that I knew I could declare quickly and just move forward, as I spent a lot of time digging through the documentation to find things like applying the CSS flexbox to a div. Let’s face it, it’s really not much more difficult to write a CSS rule with display: flex vs @apply flex.

However, one thing that I really appreciate about Vue are the scoped style rules. This brings the style for the component and the design of the component into one place, with the assurance that styles from other places won’t override the way the component should appear. You can also use SCSS mixins, functions, and variables within the style tag of components, so unifying things like colors, padding, shadows, fonts, and font weights can all be declared as assets to be utilized by the various components of the application.

Visual Studio Code Extensions:

• Tailwind CSS (https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
• Vetur (https://marketplace.visualstudio.com/items?itemName=octref.vetur)

When I first started creating components with KnockoutJS, there wasn’t any specific pattern established for handling state, properties, computed values, subscribed listeners, and event bindings. In hind-site, it began creating challenges when maintaining code as each developer had a different way to organize their code.

I took some time about 18 months ago and began to define a pattern that could be used when developing components and view models within the application. The hope was to improve the quality of the code produced and to help when maintaining the code in the future. Having unified patterns can help teams in several ways, from reviewing requirements to final code reviews. It can produce a common vocabulary and starting point for adding or updating the functionality of the application, and can help on-board new developers to the project.

Code Pattern Evolution

Other projects that I worked on over the past several years have involved ReactJS and VueJS. I spent some significant time exploring and using both frameworks to produce applications for clients. I have learned a lot of valuable insight into the patterns that both of these libraries utilize.

One thing that I initially struggled to understand in ReactJS is the unidirectional flow of state. The idea that state has to be updated in response to an event or activity was a continual battle through the early stages of learning the framework. However, the ability to trace how state has changed in a controlled fashion gives React a very predictable method of altering state. This makes debugging and testing much easier as you can quickly see how state has changed for any given React component. It becomes even more powerful when you combine it with a state management library like Redux.

I have been watching VueJS over the past several years as well. Earlier this year, I used VueJS to replace an aging time reporting application that my company uses. One of the things that I grew to love about VueJS is the structured approach to building components. Coming from building components with KnockoutJS, this really helped me form an opinion on the way it should be done.

I took ideas from both ReactJS and VueJS that ended up creating a structured approach for the application in two major areas:

1. Develop a standardized way to build components and view models
2. Insure all requests for external data is handled outside of components and view models

Standardized Structure

Both VueJS and React have a specific way in which to declare components or view models. Using these frameworks as a model, I started by standardizing the internal structure of view models and components. Each view model now begins with a structure that looks like the following:

define('SomeViewModel', ['knockout'], function (ko){
	function SomeViewModel(options) {
		 var self = this;

		 self.state = {
			 buttonClickCount: ko.observable(0)
		 };
		 self.calc = {
			 hasBeenClicked: ko.pureComputed(function(){
				 var count = ko.unwrap(this.state.buttonClickCount);
				 return count > 0;
			 }, self)
		 };
		 self.listeners = {};

         self.onButtonClick = self.onButtonClick.bind(self);
	}

	SomeViewModel.prototype.dispose = function (){
		// example to iterate over any assigned listeners
		// and then dispose of them -- code has not been tested
		Object.keys(this.listeners).forEach(function (key) {
			this.listeners[key].dispose();
		});
	};

    SomeViewModel.prototype.onButtonClick = function (data, e) {
		// handle state change here
		var currentCount = ko.unwrap(this.state.buttonClickCount);
		currentCount += 1;
		this.state.buttonClickCount(currentCount);
	};

	return SomeViewModel;
});

View models now have state, calc, and listeners properties. state holds the internal state of the view model/component. calc is used to store any calculated values based on the internal state of the view model. listeners is a place to easily register additional subscriptions for Knockout observables which can then be later cleaned up by the dispose function.

Components have a very similar approach, but there is now a props property that holds incoming values for the component. The incoming props are often observables from the view model. In this scope, state is intended to contain values that are only applicable to the current component.

As an example, this component has a property on the state object called collapsed that can be used to indicate the collapsible state of the component. Notice that props has the incoming parameters for the control’s label and the initial value. Since KnockoutJS utilizes two-way binding, the component can simply bind to the property. Additionally, all bindings that are handled by events are bound to the component view model so the reference to this is always the component’s view model.

define('MyAwesomeComponent',
	['knockout', 'text!./myawesomecomponent.template.html'],
	function (ko, template) {

	function MyAwesomeComponent(params, componentInfo) {
		var self = this;

		self.$root = componentInfo.element;

		self.props = {
			label: params.Label,
			value: params.Value
		}

		self.state = {
			collapsed: ko.observable(false)
		}

        self.onToggle = self.onToggle.bind(self);
	}

	MyAwesomeComponent.prototype.onToggle = function (data, event) {
		var collapsed = ko.unwrap(data.state.collapsed);
		data.state.collapsed(!collapsed);
	};

	function MyAwesomeComponentFactory(params, componentInfo) {
		var component = new MyAwesomeComponent(params, componentInfo);
		return component;
	}

	return {
		viewModel: {
			createViewModel: MyAwesomeComponentFactory
		},
		template: template
	}
});

Additionally, all components now make use of the createViewModel factory method so it becomes possible to pass in the context of the component. This allows easy discovery of the bound HTML element if needed.

By going to this strategy, other developers who have joined the team are quickly able to come to an understanding of the intent of the code. Developers know when they see state, the intent is to store state of the component or view model. When they see calc, they know these are all computed values. In components, when they see props it is inferred this is where I will find all of my passed in parameters for the component. listeners contains any subscribed listeners.

Handling External Data

In an attempt to make the code more succinct and easier to read, I made a concerted effort to remove XHR request code from inside of view models so that the view model is much more a representation of state. This means that modules were introduced to handle loading external data into the model.

Based on ideas of one-way data flow from ReactJS, I employed a one way data flow for the retrieval of data from the API. The idea is the view model will make a request for data, a data manager class will execute a request to get the data from an API and resolve a promise that executes a callback function when the data is retrieved. The callback on the view model updates the observable contained in the state. This gets rid of many nested anonymous functions that plagued the code previously.

My data manager is only concerned with creating and resolving XHR requests. The project is using the Swagger Client JavaScript library which reads the Swagger specification and generates strongly typed method names. An intermediary module is used to load and manage the swagger client. The simplified code is here, but this module is used by all of the page data manager modules.

define('SwaggerClientManager', ['swagger'], function (swagger) {
	function SwaggerClientManager(clientConfigUrl, readyCallback) {
		var self = this;

		self.clientConfigUrl = clientConfigUrl;
		self.readyCallback = readyCallback;

		self.Client = null;

		self.__init();
	}

	SwaggerClientManager.prototype.__init = function() {
		var self = this;

		new swagger({url: self.clientConfigUrl, usePromise: true})
			.then(function (client) {
				self.Client = client;
				self.readyCallback();
			}, function (reason) {
				throw new Error('Unable to load client specification');
			});
	};

	return SwaggerClientManager;
});

Swagger-client.js creates a JavaScript object that exposes all of the methods of the client as strongly typed properties. This makes building the page data manager class much easier. The data manager just needs to have some callback functions passed in as arguments to the constructor so they can be called as API requests are completed. Then the data manager prepares and executes the request to the swagger-client.js module.

define('DataManager', ['SwaggerClientManager'], function ($httpClient) {
	function GenericDataManager(clientConfigUrl, readyCallback, dataLoadedCallback, dataLoadErrorCallback) {
		var self = this;

		self.isReady = false;

		self.onReadyCallback = readyCallback;
		self.dataLoadedCallback = dataLoadedCallback;
		self.dataLoadErrorCallback = dataLoadErrorCallback;

		self.onReady = self.onReady.bind(self);

		self.$http = new $httpClient(clientConfigUrl, self.onReady);
	}

	GenericDataManager.prototype.onReady = function() {
		this.isReady = true;
		this.onReadyCallback();
	};

	GenericDataManager.prototype.LoadData = function () {
		var self = this;
		self.$http.Client.apis.Widgets.CustomerWidgetsByCustomerIdGet({customerId: 'ABC'})
			.then(function (response) {
				self.dataLoadedCallback(response);
			})
			.catch(function (err) {
				self.dataLoadErrorCallback(err);
			});
	};

	return GenericDataManager;
});

Now everything can be put together. The highlighted code shows how the data manager is now incorporated into the view model.

define('DataDrivenViewModel', ['knockout', 'DataManager'], function (ko, $dataManager){
	function DataDrivenViewModel(options) {
		 var self = this;
		 
		 self.state = {
			 externalData: ko.observableArray([]),
			 errors: ko.observableArray([])
		 };
		 
		 self.calc = {
			 hasData: ko.pureComputed(function(){
				 var count = ko.unwrap(this.state.externalData).length;
				 return count > 0;
			 }, self),
			 hasError: ko.pureComputed(function() {
				 var errors = ko.unwrap(this.state.errors);
				 return errors.length > 0;
			 }, self)
		 };
		 
		 self.listeners = {};
		 
		 // ensure context of this is the instance of DataDrivenViewModel
		 self.onClientReady = self.onClientReady.bind(self);
		 self.onDataLoaded = self.onDataLoaded.bind(self);
		 self.onDataLoadError = self.onDataLoadError.bind(self);
		 
		 self.dataManager = new $dataManager(
			options.clientConfigUrl, 
			self.onClientReady,
			self.onDataLoaded,
			self.onDataLoadError);
	}
	
	DataDrivenViewModel.prototype.onClientReady = function() {
		// the context of this will be the instance of DataDrivenViewModel
		this.dataManager.LoadData();
	};
	
	DataDrivenViewModel.prototype.onDataLoaded = function(data) {
		this.state.externalData(data);
	};
	
	DataDrivenViewModel.prototype.onDataLoadError = function(error) {
		this.state.errors.push(error);
	};
	
	DataDrivenViewModel.prototype.dispose = function (){
		// example to iterate over any assigned listeners
		// and then dispose of them -- code has not been tested
		Object.keys(this.listeners).forEach(function (key) {
			this.listeners[key].dispose();
		});
	};
	
	return DataDrivenViewModel;
});

The view model state has two properties, externalData and errors. Both state properties are Knockout observables, so Knockout will maintain the state of the UI/UX when bound to the HTML on the page.

Using the prototype interface, functions are registered to handle the necessary callbacks for the data operations. onClientReady is called when the data manager successfully initializes the swagger client instance. When the method is called, the view model then makes a request to the data manager to load the necessary data. Once the data manager has loaded the data successfully, the onDataLoaded function is called and passes an argument containing the data retrieved. This argument is used to override the data currently in the externalData property. If there are any errors retrieving data, the onDataLoadError function is called and a new error is added to the errors observable.

If the data needed to be saved, the first task is to create a method on the GenericDataManager to handle calling the API to store the state. At a minimum, a completed callback should be added and then the DataDriveViewModel would need to have a method to handle the callback. Finally, the view model will need a method to invoke saving the data.

2020 Roadmap

For this project, I have already described how it was moved from RequireJS to Webpack. This has allowed the team to begin getting familiar with how webpack works and how to use it to bundle the final client-side scripts. However, it would be ideal if we could also migrate the script more into ES6 and totally remove all dependencies on RequireJS. So this year, I hope to start transitioning the code toward this direction.

One thing that has been sorely lacking in the project over the past several years is a unit testing the various modules and components in the project. While the team has been fairly good at catching errors before they reach production, inevitably some bugs have been missed. By incorporating unit testing, the goal will be to improve overall code quality and make sure that newly introduced components and modules do not break existing functionality. So, this year I hope to be able to begin testing portions of the client script, and start incorporating those tests within the build pipeline as well.

Project Background

The project started around 3 years ago with the technology stack that was available at the time, which included:

• ASP.Net MVC with ASP.Net Core
• KnockoutJS
• RequireJS

The web site hosts multiple single page applications built using Knockout as the client framework and RequireJS for dependency injection. Early on, this framework worked well and made it relatively easy for developers to know where to go to update the client files and how those files were loaded into each page of the application.

However, as the application continued to grow, RequireJS began to make more XHR requests for dependencies needed by the application. This began to impact the overall performance of the application and page load times started to steadily increase. As an example, one page in the application could take up to a minute to fully load all dependencies and data. However, most of the load time for the page was simply getting all of the required dependencies.

Another of the challenges faced with this framework has always been client side builds. Initially, Visual Studio’s Bundler & Minifier extension was used to bundle all JavaScript and CSS files. However, maintaining the bundleconfig.json file became a difficult task and dreaded by all developers who worked on the project. This doesn’t even include the extra load on Visual Studio to parse and build those files.

Both the performance of the site, and the difficulty of building the client made it clear a new solution was needed. Additionally, users of the application began reporting performance issues at a much more regular cadence. Added to this challenge was changes to Bower, which was used early on for 3rd party dependencies. The requirements of the new build system were simple:

1. Reduce the number of XHR calls for scripts and dependencies for the client pages to improve performance of the application.
2. Remove the dependence on bower in favor of a more widely used package management tool.
3. Improve the developer experience and reduce the required maintenance of build scripts.

Reducing XHR Calls

One of the largest problems we had with this project is the number of calls required for a single page to be presented. The project used KnockoutJS components which require a backing view-model and a template. Each component defined in the solution had a JavaScript file and an HTML snippet file in the same folder. This was done to help with maintenance of the individual components, giving developers a way to target changes to specific components functionality, or presentation. During the build done by Azure DevOps, the HTML files were simply copied into the scripts folder of the application and retrieved by RequireJS by relative paths at runtime.

Initially, each page only loaded a few HTML templates, so the impact of these loading times was fairly low. However, as the application continued to grow, some pages required up to twenty different HTML snippets. These snipped were necessary just to render HTML on the page as part of the Knockout component. This didn’t include other dependencies like third party scripts or true requests for data. Loading the HTML snippets was causing blocking behavior in the browser, which significantly delayed the loading of application data.

As a first initiative, the goal was to create one bundle per application page which should include all of the dependencies for the page and all of the HTML snippets as modules that returned string values. I began by using Node.js and used the r.js script delivered as part of the require.js optimizer options to create the required bundles. This worked great, and there was an immediate improvement in performance. The page that took upwards of a full minute to load was now returning in less than 5 seconds, including the calls necessary to retrieve data for the page.

However, a new problem quickly emerged. The scripts required to create the client script bundles took several minutes to run. This made it difficult for developers to make a single change to a file. Each change required the developer to wait for all of the client files to be built before they could resume any debugging tasks. This slowed down the progress of development significantly. But, the performance gains were a step in the right direction. The client was literally “wowed” by the performance of these pages, even on slower networks.

Bower to NPM

At the time the project was started, Bower was a fairly widely used package management platform. It is still maintained, but other package management software has taken precedence and are now much more widely supported than Bower. Bower was replaced with NPM and all third party libraries were able to be located and associated with the project.

Our organization has started using webpack to handle the bundling of client side frameworks in other projects, so my knowledge of webpack has improved significantly over the last two years. This made webpack an ideal candidate.

Additionally, webpack is able to parse and understand the define and require statements used by require.js throughout the project. So very little had to be touched to get things running.

However, after creating a quick webpack.config.js file and running it against the project it was evident additional work would be required as the initial run of webpack resulted in multiple missing modules. This is because all of the dependencies in the project are referenced based on the module name, not the module path.

This ended up being a fairly simply fix, as webpack’s config allows the specification of aliases for the resolution of modules. One of the first steps taken was to define a modules file that developers could utilize to declare components, modules, and view-models for the application so they could be references by the module name. The folder structure included separate files to define various modules which are then combined by an index.js file using ES2015 JavaScript syntax.

const path = require('path');

const workingDirectory = path.resolve(__dirname, '../../app_scripts/modules');

/* This is a list of all modules used to handle and manage data */
const dataModules = {
    "CoreDataManagerModule": path.resolve(workingDirectory, "data/coredatamanager.module.js"),
    "CustomersDataManager": path.resolve(workingDirectory, "data/customersdatamanager.module.js"),
};

const jsModules = {
    "ConsoleLogger": path.resolve(workingDirectory, "consolelogger.js"),
    "DateFormatConstants": path.resolve(workingDirectory, "dateformatconstants.js"),
    "FileUploadHandlerModule": path.resolve(workingDirectory, "fileuploadhandler.module.js"),
    "GlobalComponentRegistration": path.resolve(workingDirectory, "GlobalComponentRegistration.js"),
    "LocalStorageManager": path.resolve(workingDirectory, "localstoragemanager.js"),
    "RandomStringModule": path.resolve(workingDirectory, "randomstringgeneratormodule.module.js"),
    "SwaggerClientManagerModule": path.resolve(workingDirectory, "swaggerclientmanager.module.js"),
    "SwaggerSpecLookup": path.resolve(workingDirectory, "swaggerspeclookup.module.js"),
    "visualizationColors": path.resolve(workingDirectory, "visualizationcolorsmodule.js")
};

/* This combines all of the modules into a single export */
module.exports = {
    ...dataModules,
    ...jsModules
};

Once all of the modules were defined in this way, they could be used within the webpack.config.js file.

const path = require("path");
const webpack = require('webpack');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

// pull definitions of all modules from definition folder
const assets = require("./build/client_asset_definitions");

// ... other code ... //
module.exports = env => {
    // ... other code ... //

    return {
        // ... other code ... //
        resolve: {
            alias: {
                'domReady': 'requirejs-domready',
                'text': 'requirejs-text',
                'config': path.resolve(workingDirectory, 'config.js'),
                'charts': 'chart.js',
                'swagger': 'swagger-client',
                'customBindings': path.resolve(workingDirectory, 'customBindings.js'),
                'slick': 'slick-carousel',
                ...assets
            }
        },
    // ... other code ... //
    };
};

This corrected the mapping of many of the modules within the application. The final challenge in getting the configuration to work was getting all of the HTML template files incorporated into the build. The default text! dependency would not work correctly without making use of a loader. The loader selected was the html-loader. An alias was created so that the html-loader would be used to emit the correct template for consumption by webpack.

const path = require("path");
const webpack = require('webpack');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

// ... omitted code ... //
// Export the configuration
module.exports = env => {
    // ... omitted code ... //

    return {
        resolve: {
            alias: {
                'domReady': 'requirejs-domready',
                'text': 'requirejs-text',
                'config': path.resolve(workingDirectory, 'config.js'),
                'charts': 'chart.js',
                'swagger': 'swagger-client',
                'customBindings': path.resolve(workingDirectory, 'customBindings.js'),
                'slick': 'slick-carousel',
                ...assets
            }
        },
        resolveLoader: {
            alias: { 'text': 'html-loader' }
        },
    // ... omitted code ... //
    };
};

Line 14 declares that the text dependency should use the node module requirejs-text and the loader to utilize is the html-loader, as seen on line 24. Now the HTML templates are included within the webpack bundles and continue to reduce the number of required XHR requests.

Finally, the application has multiple entry points that need to be defined. In an effort to reduce the overhead of maintaining multiple files, scripting was utilized to search for the files and dynamically create the entry points for the application.

In the application, all of the entry points have the extension .bootstrapper.js and are stored in one of two folders in the client source scripts. The script simply needed to crawl the two folders and find all of the associated scripts to create the app entry points. Since they are contained within two folders, this was very easy to do just using NodeJS. Additionally, developers can easily add a new bootstrapper script into these folders and know they will be picked up the next time a webpack build is executed.

const fs = require('fs');
const path = require('path');

const userBootstrappersDir = path.resolve(__dirname, '../../app_scripts/bootstrappers');
const adminBootstrappersDir = path.resolve(__dirname, '../../app_scripts/bootstrappers/admin');

// Read the list of files from the directoris
let userFiles = fs.readdirSync(userBootstrappersDir, { withFileTypes: true });
let adminFiles = fs.readdirSync(adminBootstrappersDir, { withFileTypes: true });

// Declare an object to hold all entry points
var entryPoints = {};

userFiles.forEach((f) => {
    if (f.isFile()) {
        var nameReplace = f.name.replace(".bootstrapper.js", ".page");
        entryPoints[nameReplace] = path.resolve(userBootstrappersDir, f.name);
    }
});

adminFiles.forEach((f) => {
    if (f.isFile()) {
        var nameReplace = f.name.replace(".bootstrapper.js", ".page").replace('admin_', 'admin.');
        entryPoints[nameReplace] = path.resolve(adminBootstrappersDir, f.name);
    }
});

// Export all entry points defined
module.exports = entryPoints;

With all of the entry points defined, it was simply a matter of referencing them in the webpack.config.js file. Additionally, we have one external reference that is not able to be retrieved using npm (the project presents maps with a third party mapping tool that does not deliver an NPM package). It is declared as an external dependency so that webpack doesn’t attempt to pull it into the bundles. The dependency is instead declared with a traditional script tag on the pages that need it.

const path = require("path");
const webpack = require('webpack');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

// pull definitions of all modules from definition folder
const assets = require("./build/client_asset_definitions");

// pull all bootstrappers from bootstrappers folder
const entryPoints = require("./build/bootstrapper-resolver");

// Set the working directory and the output directory
const workingDirectory = path.resolve(__dirname, 'app_scripts');
const outDirectory = path.resolve(__dirname, 'wwwroot/js/dist');

// Export the configuration
module.exports = env => {
    const plugins = [];
    // ... omitted code ... //

    return {
        mode: !env ? 'development' : env.production ? 'production' : 'development',
        entry: entryPoints,
        output: {
            path: outDirectory,
            publicPath: '/js/dist/',
            filename: '[name].js'
        },
        resolve: {
            alias: {
                'domReady': 'requirejs-domready',
                'text': 'requirejs-text',
                'config': path.resolve(workingDirectory, 'config.js'),
                'charts': 'chart.js',
                'swagger': 'swagger-client',
                'customBindings': path.resolve(workingDirectory, 'customBindings.js'),
                'slick': 'slick-carousel',
                ...assets
            }
        },
        resolveLoader: {
            alias: { 'text': 'html-loader' }
        },
        plugins: plugins,
        externals: {
            'maps': 'Microsoft'
        }
    };
};

Better Developer Experience

ASP.Net Core includes middleware to handle running a node service for the specific purpose of handling webpack recompilation. This package was included in the project and referenced within the startup for the application.

if (env.IsEnvironment("Local")) {
      app.UseDeveloperExceptionPage();

      app.UseBrowserLink();
      app.UseWebpackDevMiddleware(new WebpackDevMiddlewareOptions());
}

Now, as developers make changes to the files referenced by webpack, updates happen immediately and are can be quickly accessed by reloading each page. Eventually, the desire is to get hot module replacement working as well so that all JavaScript code changes occur and are available within the client without any need to reload.

As you can see, this wasn’t as difficult a process as it seemed when it first came up. The projection was for the work to take well over a week to complete and to get all pages working. However, in just under 3 days all of the code had been converted and testing began. Of course, there were bugs, but most of those came from improperly referenced dependencies that had been in use for years on the project.

Opportunity Knocks

A new project is a great opportunity to begin exploring new ideas, and I had the opportunity presented to me by a colleague who had a client that wanted to build a new application, but they wanted to avoid having any downstream customers that might opt to customize the code. This meant the customer wanted to avoid the use of the big component libraries.

Our company has used KnockoutJS in several projects over the years, so it was in consideration as part of the technology stack. After watching a video by Steve Sanderson, I saw this as an opportunity to put my knowledge of KnockoutJS to work in building this new application using an approach to Web Components.

I do want to take a moment to mention some of the other libraries used with this project include ChartJS, Bing Maps V8, RequireJS, Material Design Lite, Swagger JavaScript Client, and jQuery.

Architecting a Pattern

One of the first challenges I faced was how granular I should get when breaking apart the wireframes for building the application. The first page I needed to build was an overview dashboard which included a map, several counters, a couple of graphs, and a grid of contextual data related to system activities.

The first pass at decomposing the wireframe ended up with multiple small components that would be put together into a single large component. The components for the first page included a map widget, a counter widget, a double counter widget, a small graph widget, a large graph widget, and a data grid widget. The large component became the dashboard component which utilized all of the smaller components.

Now that each of the elements were decomposed, it became necessary to determine how to build a folder hierarchy that helped future developers understand what each file did. I also wanted to make sure my build system could easily aggregate changes across the application, as each page’s javascript in the application needed to be compiled down to a single file.

The resulting structure is outlined below.

• App_Scripts
  •  Components
    • WidgetOne
      • WidgetOne.component.js
      • WidgetOne.registration.js
      • WidgetOne.template.html
    • WidgetTwo
      • WidgetTwo.component.js
      • WidgetTwo.registration.js
      • WidgetTow.template.html
  • Modules
    • ModuleOne.module.js
    • ModuleTwo.module.js
  • AdminViewModels
    • AdminPageOne.model.js
    • AdminPageTwo.model.js
  • ViewModels
    • ViewModelOne.model.js
    • ViewModelTwo.model.js
  • config.js
  • PageOne.page.js
  • PageTwo.page.js

All of the application scripts are stored in the app_scripts folder of the project. At the root level of this folder are all of the initialization scripts for the pages. The components folder holds all of the components for the application. There are two areas for view models, one holds all of the view models used for administrative pages while the other holds all the view models for non-administrative pages. The modules folder holds any modules used within the application. This folder has modules that handle HTTP requests, authentication, etc.

Configure Bundling

The project is using Visual Studio 2017 with the new bundleconfig.json file being used to define all of the bundles.

Bundling Scripts for Each Page

One of the early challenges I noticed in building a bundle per page was the extreme number of duplicate entries in the application. This helped me identify how to better structure the bundling so adding a new component to the application wouldn’t always require a visit to every bundle configuration definition in the file.

The first bundle that would be included on all page bundles is the core bundle.

  // CORE JS BUNDLES
  {
    "outputFileName": "js_build/core.js",
    "inputFiles": [
      "app_scripts/modules/sessionstoragemanager.js",
      "app_scripts/modules/snackbarmanager.module.js",
      // ... MORE CORE ITEMS ... //
      "app_scripts/components/alertpanel/alertpanel.component.js",
      "app_scripts/components/alertpanel/alertpanel.registration.js"
    ],
    "minify": { "enabled": false }
  },

Now I can simply include the core bundle into my page bundle.

  {
    "outputFileName": "wwwroot/js/app/admin_UserList.page.js",
    "inputFiles": [
      "app_scripts/config.js",
      "app_scripts/customBindings.js",
      "js_build/core.js", // HERE IS THE CORE BUNDLE //
      "app_scripts/AdminModels/users_List.model.js",
      "app_scripts/admin_UserList.page.js"
    ]
  },

Inside my project, when the bundles are built the files will include all of the scripts I’ve defined for that page. The only thing that remained in setting up bundling was getting the html templates into the application.

HTML Templates

In order to get the templates for the components, I am using the RequireJS Text plug-in. All of the templates are stored in the root of the output folder. This is also handled pretty easily by updating the bundleconfig.json file.

  {
    "outputFileName": "wwwroot/js/app/alertpanel.template.html",
    "inputFiles": [ "app_scripts/components/alertpanel/alertpanel.template.html"],
    "minify": {
      "enabled": true,
      "isFragmentOnly": true,
      "removeHtmlComments": true
    }
  }

Now my templates and scripts are all within the js/app folder on my server.

A Simple Component

Back to the components, I started with a very simple component that would display a tile that includes a counter, a label, and a subtitle. The first step I took was defining the template in the smallcounter.template.html file.

<div class="client-small-widget mdl-shadow--2dp">
    <div class="client-small-widget--counter"></div>
    <div class="client-small-widget--subtitle-text"></div>
    <div class="client-small-widget--title-text"></div>
</div>

 
The small counter card is very simple and includes a div to contain the value, a div to contain the title, and a div to contain the text.

Knockout Components are defined as an object definition. Since I’m using RequireJS in the project, I declare the component as a RequireJS module definition in the file smallcounter.component.js.

define('smallCounter', ['knockout', 'text!./js/app/smallCounter.template.html'], function (ko, htmlString) {
    function SmallCounter(params, componentInfo) {
        this.title = params.title;
        this.value = params.value || ko.observable(0);
        this.subtitle = params.subtitle;
    }

    return { viewModel: SmallCounter, template: htmlString };
});

Knockout will pass a params object to the component when the component is bound to the model. This object contains all of the parameters that were passed to the component through the markup where the component is used.

Now I revisit the template and add the Knockout bindings to the markup.

<div class="att-small-widget mdl-shadow--2dp">
    <div class="att-small-widget--counter" data-bind="text: value"></div>
    <div class="att-small-widget--subtitle-text" data-bind="text: subtitle"></div>
    <div class="att-small-widget--title-text" data-bind="text: title"></div>
</div>

The counter div has the text bound to the value property of the component, the subtitle is bound to the subtitle property, and the title is bound to the title property.

Finally, to make the component easy to use, it needs to be registered as a component with Knockout. This is where the registration JavaScript file comes into focus. I created a final file named smallcounter.registration.js and placed the following code within the file.

require(['smallCounter', 'knockout'], function (counter, ko) {
    ko.components.register('client-small-counter', smallCounter);
});

Using the Component

Now that the component is completed, I wanted to test it out and make sure that it behaves as I expected it to behave. The easiest way is to use it on a page.

I created a simple test page that used the component binding defined in the regitration file.

<html>
   <head>
      <script src="require.js" data-main="/js/app/samplepage.page"/>
   </head>
   <body>
      <client-small-counter params="value:value, title:'Test', subtitle:'Value Test'">
      </client-small-counter>
   </body>
</html>

along with the page bundle script. The script for the page instantiates a simple view model that is used to pass values to the component.

require(['knockout', function(ko){
     var simpleModel = {
          value: ko.observable(121)
     };

     ko.applyBindings(simpleModel);
});

When the page is run, a div is placed on the page and all of the values are bound as expected.

If you want to see a simple sample of the idea that was the starting place for this component, you can view the CodePen here.

Getting More Complex

Now that some of my simple components were up and running, it was time to get a little more complex. I needed a component that incorporates Bing Maps to render a map for use within the application. This was not as trivial as the simple counter demonstrated above.

One of the challenges with the Bing Maps API is the fact that the component is loaded dynamically by its own module loader. However, I need to know when the map modules are loaded so I can handle different operations of the component.

Thankfully, KnockOut has a pattern that allows you to get some more information about components when they are created. It is also at this time you can inject your own methods to the component.

Within the module definition for the map, I used the following definition.

define('BingMapComponent', 
['knockout','text!./js/app/map.template.html', 'jquery', 'maps'],
function (ko, htmlTemplate, $) {
   function MapComponent(params, componentInfo) {
   }

   function MapComponentFactory(params, componentInfo) {
   }

   return {viewModel: { createViewModel: MapComponentFactory }, template: htmlTemplate };
}

This component makes use of a function to create the component. I’m not going to go into all the details of the Bing Maps API, but here is the code that is used to create the map within the component.

define('BingMapComponent', 
['knockout','text!./js/app/map.template.html', 'jquery', 'maps'],
function (ko, htmlTemplate, $) {
   function MapComponent(params, componentInfo) {
       /// ... component details would be here ... ///
   }

   function MapComponentFactory(params, componentInfo) {
      var element = $(componentInfo.element);
      var mapContainer = $("<div/>");
      mapContainer.appendTo(element);

      var component = new AssetLocationMapComponent(params, componentInfo);

      function checkReadyState() {
         if (Microsoft.Maps && Microsoft.Maps.Map && Microsoft.Maps.Location && Microsoft.Maps.Pushpin && Microsoft.Maps.Point) {
            injectMap();
         } else {
            setTimeout(checkReadyState.bind(this), 150);
         }
      }

      function injectMap() {
         var options = {
           credentials: params.key
         };

         var map = new Microsoft.Maps.Map(mapContainer[0], options);
         var clusterLayer;

         Microsoft.Maps.loadModule('Microsoft.Maps.Clustering', function () {
            clusterLayer = new Microsoft.Maps.ClusterLayer([], {
            clusteredPinCallback: component.__generateClusterOptions,
            gridSize: 100
         });
         map.layers.insert(clusterLayer);
         component.placePins();
      });
      component.setMap(map);
      component.setDefaultView();
      if (params.trackViewChanges) {
             component.registerTrackViewChanges();
      }
   }

   checkReadyState();

            return component;   
   }

   return {viewModel: { createViewModel: MapComponentFactory }, template: htmlTemplate };
}

There is a lot going on in the code above. First the element that contains the component is discovered with jQuery. A new div is added to the element and the component is created. Because I don’t know when the modules will be available, I set up a function to check every 150ms to make sure all the modules I need for the map area available. Once they are available, the map is injected into the component. You will see some calls to various methods on the component. These methods do things like set up any pushpins that are in the data collection for the map, register the map to store it’s last state for the user to a storage location, set up the default view based on the last stored information for that user. This is all possible because the map API is now available to the component.

The Value of Components

The big value of using components in this application have come in the form of enhancements to the system. Early on, I defined a component to contain all the necessary markup to create a text box using Material Design Lite. This was wrapped up in a component so anywhere I needed a text box on a form, I would just include it in the page instead of having to copy and paste all of the markup for the MDL text box.

While there isn’t a lot of markup to create a text box for MDL, there are some situations where custom validation was needed and this was not handled as easily by the standard out of the box MDL text box. All of this custom functionality was wrapped up into a component and used throughout the application.

A new requirement was registered by the client where they wanted a label to appear below the text box with some help text. If I had not wrapped up my textboxes into a component, I would need to visit every page that would have help text and add additional HTML markup to support it. However, I was using the component so I simply added it to the component, exposed a new parameter, and updated the text boxes that needed the help text.

Prior to the update, my component was defined this way.

HTML

<div class="client-form--field client-form--textField">
    <div class="client-form--field-control">
        <div class="mdl-textfield mdl-js-textfield mdl-textfield--full-width mdl-textfield--floating-label" data-bind="css:{isInvalid: hasErrors() === true }">
            <input class="mdl-textfield__input" type="text" data-bind="textInput: value, attr: {id: componentId}, hasFocus: hasFocus, event: {blur: handleBlurValidation}" />
            <label class="mdl-textfield__label" data-bind="html: displayLabel, attr:{for:componentId}"></label>
            <!-- ko if:hasErrors()-->
            <!-- ko foreach: errors -->
            <span class="mdl-textfield__error" data-bind="text:$data" style="visibility: visible;"></span>
            <!-- /ko -->
            <!-- /ko -->
        </div>
    </div>
</div>

JavaScript

define('TextBoxComponent', ['knockout', 'text!./js/app/textbox.template.html', 'jquery'], function (ko, htmlString, $) {
    function TextBoxComponent(params, element) {
        var self = this;
        var el = $(element);
        var mdlInputBox = el.find(".mdl-textfield");

        // capture parameters
        self.value = params.value || ko.observable();
        self.label = ko.observable(ko.unwrap(params.label)) || ko.observable();
        self.isRequired = params.isRequired || false;
        self.maxLength = params.maxLength || -1;
        self.minLength = params.minLength || -1;
        self.hasFocus = params.hasFocus !== undefined ? ko.observable(ko.unwrap(params.hasFocus)) : ko.observable(false);
        self.trackChanges = params.trackChanges || ko.observable(false);

        self.displayLabel = ko.pureComputed(function () {
            var isRequired = ko.unwrap(self.isRequired);
            if (isRequired) {
                return ko.unwrap(self.label) + " <b>*</b>";
            }
            return ko.unwrap(self.label);
        }, self);

        self.originalValue = ko.observable(ko.unwrap(self.value));
        self.hasEdits = ko.pureComputed(function () {
            return ko.unwrap(self.value) !== ko.unwrap(self.originalValue);
        }, this);

        self.hasErrors = ko.observable(false);
        self.errors = ko.observableArray([]);
		self.hasErrors = ko.pureComputed(function(){
			returh this.errors().length > 0;
		},self);

        self.trackChangesListener = self.trackChanges.subscribe(function (newValue) {
            if (newValue) {
                self.originalValue(ko.unwrap(self.value));
            }
        }, this);

        self.valueChangeListener = self.value.subscribe(function (newValue) {
            self.__validate();
            if (newValue && newValue !== '') {
                mdlInputBox.addClass('is-dirty');
            } else {
                mdlInputBox.removeClass('is-dirty');
            }
        });

        self.componentId = ko.observable(self.__createUniqueId());

    }

    TextBoxComponent.prototype.handleBlurValidation = function (item, e) {
        item.__validate();
    };

    TextBoxComponent.prototype.__createUniqueId = function () {
        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
            var r = Math.random() * 16 | 0, v = c === 'x' ? r : (r & 0x3 | 0x8);
            return v.toString(16);
        });
    };

    TextBoxComponent.prototype.__validate = function () {
        var item = this;
        if (!ko.unwrap(item.trackChanges)) {
            return;
        }
        item.errors.removeAll();
        item.hasErrors(false);
        if (item.isRequired && ko.unwrap(item.value) === '') {
            item.errors.push(ko.unwrap(item.label) + " is required.");
            item.hasErrors(true);
            return;
        }
    };

    function TextBoxComponentFactory(params, componentInfo) {
        var el = componentInfo.element;
        var component = new TextBoxComponent(params, el);
        return component;
    };

    return { viewModel: { createViewModel: TextBoxComponentFactory }, template: htmlString };
});

The change to the component was really easy at this point.

HTML

<div class="client-form--field client-form--textField">
    <div class="client-form--field-control">
        <div class="mdl-textfield mdl-js-textfield mdl-textfield--full-width mdl-textfield--floating-label" data-bind="css:{isInvalid: hasErrors() === true }">
            <input class="mdl-textfield__input" type="text" data-bind="textInput: value, attr: {id: componentId}, hasFocus: hasFocus, event: {blur: handleBlurValidation}" />
            <label class="mdl-textfield__label" data-bind="html: displayLabel, attr:{for:componentId}"></label>
            <!-- ko if:hasErrors()-->
            <!-- ko foreach: errors -->
            <span class="mdl-textfield__error" data-bind="text:$data" style="visibility: visible;"></span>
            <!-- /ko -->
            <!-- /ko -->
            <!-- ko ifnot: hasErrors -->
            <!-- ko if: hasHelpText -->
            <span class="mdl-textfield__hint" data-bind="text: helpText"></span>
            <!-- /ko -->
            <!-- /ko -->
        </div>
    </div>
</div>

JavaScript

define('TextBoxComponent', ['knockout', 'text!./js/app/textbox.template.html', 'jquery'], function (ko, htmlString, $) {
    function TextBoxComponent(params, element) {
        var self = this;
        var el = $(element);
        var mdlInputBox = el.find(".mdl-textfield");

        // capture parameters
        self.value = params.value || ko.observable();
        self.label = ko.observable(ko.unwrap(params.label)) || ko.observable();
        self.isRequired = params.isRequired || false;
        self.maxLength = params.maxLength || -1;
        self.minLength = params.minLength || -1;
        self.hasFocus = params.hasFocus !== undefined ? ko.observable(ko.unwrap(params.hasFocus)) : ko.observable(false);
        self.trackChanges = params.trackChanges || ko.observable(false);
        self.helpText = params.helpText || '';
        self.hasHelpText = ko.pureComputed(function () {
            return ko.unwrap(this.helpText);
        }, self);
		
        self.displayLabel = ko.pureComputed(function () {
            var isRequired = ko.unwrap(self.isRequired);
            if (isRequired) {
                return ko.unwrap(self.label) + " <b>*</b>";
            }
            return ko.unwrap(self.label);
        }, self);

        self.originalValue = ko.observable(ko.unwrap(self.value));
        self.hasEdits = ko.pureComputed(function () {
            return ko.unwrap(self.value) !== ko.unwrap(self.originalValue);
        }, this);

        self.hasErrors = ko.observable(false);
        self.errors = ko.observableArray([]);
		self.hasErrors = ko.pureComputed(function(){
			returh this.errors().length > 0;
		},self);

        self.trackChangesListener = self.trackChanges.subscribe(function (newValue) {
            if (newValue) {
                self.originalValue(ko.unwrap(self.value));
            }
        }, this);

        self.valueChangeListener = self.value.subscribe(function (newValue) {
            self.__validate();
            if (newValue && newValue !== '') {
                mdlInputBox.addClass('is-dirty');
            } else {
                mdlInputBox.removeClass('is-dirty');
            }
        });

        self.componentId = ko.observable(self.__createUniqueId());

    }

    TextBoxComponent.prototype.handleBlurValidation = function (item, e) {
        item.__validate();
    };

    TextBoxComponent.prototype.__createUniqueId = function () {
        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
            var r = Math.random() * 16 | 0, v = c === 'x' ? r : (r & 0x3 | 0x8);
            return v.toString(16);
        });
    };

    TextBoxComponent.prototype.__validate = function () {
        var item = this;
        if (!ko.unwrap(item.trackChanges)) {
            return;
        }
        item.errors.removeAll();
        item.hasErrors(false);
        if (item.isRequired && ko.unwrap(item.value) === '') {
            item.errors.push(ko.unwrap(item.label) + " is required.");
            item.hasErrors(true);
            return;
        }
    };

    function TextBoxComponentFactory(params, componentInfo) {
        var el = componentInfo.element;
        var component = new TextBoxComponent(params, el);
        return component;
    };

    return { viewModel: { createViewModel: TextBoxComponentFactory }, template: htmlString };
});

After the change, I just visit the pages and add the helpText parameter and it will show up on the control with minimal effort.

            <client-text-box params="label: 'Item ID',
                          value:ItemId,
                          isRequired:true,
                          hasFocus: true,
                          trackChanges: dataLoaded,
                          helpText: 'This can be any unique identifier'">
            </client-text-box>

Wrap Up

Now that I have had a chance to create my own components using KnockoutJS, I can honestly say that I am convinced this is a great pattern for web applications. I can see why it is used as part of the strategy for the Microsoft Azure Portal and why they are at the heart of frameworks like Angular and React.

However, this journey wasn’t without some initial challenges and frustrations. Listed below are just a few of the more notable challenges that frustrated me early on.

• Bundling and Configuration
  This took some time to really understand. With a goal of having every page with script specific to that page all bundled into a single file, setting up the initial bundle for a page was tedious and error-prone. There have been a number of times that I have created a new component and struggled to get it working because I had typed an incorrect path for one of the bundles. Some of this challenge was alleviated when I created core bundles, but the HTML templates still prove to be a challenge as they are bundled independently of the JavaScript.
• File Sprawl
  One challenge I didn’t anticipate is the large number of files I needed to have open at times to make changes to my application. At times, a single edit form in the application would require me to have five or six files open. This became confusing at times, especially when I needed to modify several pages.
• Team Member Understanding
  I did not anticipate some of my team having difficulties understanding how components worked. I had several conversations throughout the project with various team members where I thought I had explained the purpose and value proposition of using them, only to find out later that I didn’t do as good a job as I had hoped. I’m still working with my team to communicate the benefits that I experienced on this project using components, which is part of the reason I attempted this post.

I have learned a lot over the past three or so months as I’ve worked through building this application. I am hoping to take some of the lessons learned forward into future projects where I hope it will streamline the development of applications for other clients.

The workflow definition language is used when building Azure Logic Apps. Since Microsoft Flow makes use of Logic Apps, we can leverage this to do the calculation. The key to using these functions is understanding how to pass them into your flow actions. This is where I had my biggest disconnect, so I will share what I’ve learned to this point. I’m sure there are better ways to do these steps, but I’m just at the beginning of discovering how.

First, I logged into Microsoft Flow and created a new flow. When working on solving new problems, my goal is to build something very simple that solves my immediate problem and then back up to include it in the final solution. This flow is the simple solution, so I called it Simple Time Calculation Testing. The idea is to send a notification with an updated (and formatted) time 15 days from the time the flow ran.

To start, I added a recurrence trigger set to run every 15 minutes. The frequency doesn’t really matter as I will typically run it each time I want to test it.

I read on the Flow Community Board that the Data – Compose operation can be used to execute the workflow definition language formulas. Using this information, I added a Data – Compose action to my flow and set it to use add 15 days to the current time. The trick here is to use a single @ and enclose the entire function call in quotes.

"@formatDateTime(adddays(utcnow(),15),'D')"

The formula starts with a call to formatDateTime. Notice the second formula, adddays, is not preceeded by @, nor is the third function utcnow. This call will get the current date and time using the utcnow function. It will then have 15 days added to it by the addays function. Finally, it is formatted into the long date format by using the second parameter of the formatDateTime function.

In the image above, the flow has already run so the quotes do not appear. When the block was added, it originally had the quotation marks.

Now we have a flow that runs every 15 minutes and gets the current time formatted in a long date. To see the date, I added a notification block to send an email of the contents. The final flow appears below.

Testing the flow, I get the expected result in an email notification.

In summary, as you can see here it is possible to make use of the Workflow Definition Language from Logic Apps within your Microsoft Flows. The challenge I’ve found is just simply knowing what you CAN do as the documentation leaves you with the impression that you are limited to what is provided in the available triggers and actions. As you can see here, Microsoft Flow does have some hidden capabilities that you can leverage as a developer within your organization.

I understand building relationships, but I need to be able to do more than use a relationship in a lookup. I need to be able to display related records from an entity based on a currently selected entity in a parent table.

For example, say I am building a work order tracking system for techs and customers. I have a work order entity and a work order history entity I would like to use. The work order tracks the original request from the customer while the history tracks the individual touch points a tech has made with the customer. I have a screen that displays the details of the work order. I want to be able to display the full history of the work order (and add more records) by going from the currently selected entity. This scenario is almost entirely missing, and in my opinion a much more common use of relationships in entities.

Are there plans to support related data in a much more comprehensive manner? If not, this could be a very limiting factor with using both the common data model and PowerApps since a lot of data structures make use of relationships to expose related data.

Before we begin, let me introduce you to Microsoft Flow. It is a new service currently in preview that allows you to “Create automated workflows between your favorite apps and services to get notifications, synchronize files, collect data, and more.” If you have used web sites like IFTTT or Zapier, you may be familiar with the general idea of Microsoft Flow. These tools allow you to build workflows between various internet based applications.

For example, I have an IFTTT recipe that automatically puts my cell phone on silent any time I reach my office building and another IFTTT recipe that notifies me if my Nest thermostat detects my house has reached 80 degrees (uh oh, time to call the A/C repairman). The focus of these tools is to make it easy for a user to automate a small task.

I’ve already mentioned a few tasks that I commonly have another internet automation tool complete for me, so what is different about Microsoft Flow? Yes, in a lot of ways it looks to be yet another internet automation entry into a flooded space of alternatives. The key difference for this service, in my opinion, it that it is focused on automation in the enterprise. This means it taps into the power of Azure and O365. Using gateways, it also has the potential to connect to on-premise enterprise systems extending the reach of flows beyond those currently on the market. This makes it quite clear it is not just another entry into the space.

From the homepage of flow, there is an option to see my flows (You must be logged in with a Work or School account to see this option, sign-up is free!).

This takes me to the screen to create a new blank flow or select a flow from an existing template. There are a large number of templates that you can use to start building flows. If you have not previously connected to a service represented in the template, you will be required to create the connection before you can continue.

Creating a blank flow loads the designer and prompts for the trigger. After typing Twitter in the trigger box, the results are filtered making it easy to find the specific trigger needed.

As I mentioned previously, if the service has not yet been connected a request will be presented to create the new connection.

Simply sign into the service and then authorize Flow to be able to use it. This is a standard OAuth authorization request currently used across the web.

In my scenario, the service should be watching for Tweets containing Microsoft Flow. A basic understanding of how the service utilizes search lets me know the phrase will need to be contained within quotation marks. If the desire is to monitor for specific users or hashtags, the search team would be the users’ twitter name (i.e. @cquick) or the desired hashtag (#Rio2016).

This completes the configuration for the Flow Trigger. Unfortunately, there is no ability to currently test the flow to see what is returned. I hope that feature is added at some point because I can see scenarios where you might have triggers coming from a custom API (HTTP + SWAGGER) or Azure Service Bus and you need to make sure you are getting the correct data without running the flow first.

The next step in creating this simple flow is to add an action to take after the trigger is successfully run. Click on New Step and a couple of options are presented. (I have clicked on More so those options are visible as well).

By far, the most common action will either be adding some type of condition or going straight to some type of action. This shows there is an ability to iterate over multiple items that a single trigger could return.

In this simple flow, creating an action to Trello is the desired path. Clicking on Add an action presents the action window. It looks identical to the trigger so the same steps can be taken to locate the desired action. In this case, typing Trello provides the option for creating a new card.

Again, if the service has not yet been connected it will need to be connected and authorized before it can be used by Flow.

In this step, I encountered one of the bugs in the system. I could easily select a Trello board, but selecting the specific list failed. Remember, this is still a preview so there will be the occasional hiccup.

It is actually pretty easy to solve since Trello offers the ability to export a board as JSON data. I just need to export the data and look for the id of the list to use. Since that is outside the scope of the article, I’m not going to focus on each of the steps to accomplish the goal. I am mentioning it because I want to explain why the configuration of the flow shows a globally unique identifier instead of the friendly name of the Trello list.

Configuring the action is actually pretty easy (aside from the note above). The trigger passes data to the action. It is easy to identify the source when clicking on a text area. Flow attempts to give you quick access to the most commonly used properties from the trigger. In the screenshot, the action is configured to utilize the Flow Tweets board and a list has been specified. The title of each card will contain A new tweet by and then the name of the user. The description for the Trello card will be the content of the Tweet.

This completes the steps for my flow. Now the flow needs a name. This is done by clicking at the top of the flow on Untitled followed by typing the name of the flow.

Clicking Create Flow will create the flow and start monitoring for the trigger to be fired. You can review the status of all of your flows by clicking on the Activity tab at the top of the flow page. It looks like I maxed out my calls to the Twitter API. I guess I need to add a delay activity to my flow so that doesn’t happen again!

This was an example of a very simple flow. It demonstrates how easy it is to create a flow and get it working. I started by specifying a trigger, I added an action to take based on that trigger and then I saved the flow. At that point, it began creating cards on my Trello board (https://trello.com/b/Z66SUFfm).

In my opinion, this promises to be a great tool allowing business users to automate some of their day-to-day activities. It is pretty evident even in this preview, there are some really powerful templates being created:

If you look near the top of the ribbon, you will see a little icon that allows you to Focus Content. This icon simply calls a JavaScript function to toggle some CSS classes so the visitor gets a focused view of the content. This function can be used in your own calls to help highlight content on a page when the page loads.

This following snippet can be placed into a script editor web part and will cause the screen to go to focused mode when the content is loaded. When the visitor navigates away from the page, they will be returned to a non-focused view of the content.

window.addEventListener('unload',function() {
    SetFullScreenMode(false);
});

window.addEventListener('load',function() {
    SetFullScreenMode(true);
});

In many of the workflows I have built over the years with SharePoint based solutions, I have found this to be a very common requirement. It is easy to understand why there was some initial concern when the intern requested assistance because the Office 365 update item permissions activity in Nintex Workflow for O365 was not working as expected.

The activity is configured to break item inheritance, set the original author with read-only rights and allow a group containing approvers to have access to modify the item. When the workflow executes, it reaches the Office 365 update item permissions where it stops and logs: “An authentication error has occurred”. We attempted changing the credentials used by the activity and continued to receive the same error.

Nintex has a community portal that contains many questions and answers in the use of their products. A search on the portal revealed the following support thread: Office 365 Update Item Permissions – Group name. This thread describes the exact issue we faced, whenever the name of the group was typed directly into the Office 365 update item permissions activity, it fails to resolve the group by name.

In the thread, one of the Nintex employees (Eric Harris) mentions they utilized a workflow variable and set the group via a lookup to the variable. I created a simple list in our O365 tenant where Nintex Workflow is installed and created a very simple workflow. The workflow contains a text variable named Group and two activities. The first activity is to set a workflow variable and is configured to set the variable Group to one of the groups defined on the site. The second activity is the Office 365 update item permissions activity which is set exactly the same as the one in the approval workflow the intern is designing. Instead of typing the name of the group, a lookup to the Group variable is used. This test worked successfully and the permissions for the item in the list changed as intended.

I am still very involved in SharePoint and O365, building solutions around these products. I have also included Nintex Workflow and Nintex Forms in some of the newer solutions.

A old area that has been revisited recently is custom application development. The team at my company has been involved in more projects that involve custom applications for our clients. This has given me more exposure to plenty of new technologies, patterns and ways to deliver solutions.

Finally, I have also been investigating new opportunities for solutions built in O365/Azure with the introduction of products like PowerApps (in preview), Microsoft Flow (in preview), and Logic Apps (just to name a few).

That is why I am going to be refocusing the content of this blog to some degree. There will still be content around SharePoint and O365, but you will start to see more information and details around other technologies as well.

First, I want to apologize for such a long silence. Project work and life in general has kept me very busy over the last year, so it has been difficult to find a time to write new content.

This article describes a specific scenario I experienced as part of my standard project work. It hasn’t been extended or tested for other scenarios (yet!). Handle with care.

Since the release of SharePoint 2013, I have been doing a lot of customizations utilizing JSLink on lists and list views. One of the things that I really do not like about JSLink is all of the string concatenation that tends to happen when building the output for your JSLink customization. It is not a huge challenge when you are working with a small template or limited output, but when you start working with complex HTML strings, it can be a bit unwieldy.

In recent years, there have been a lot of JavaScript frameworks that solve this specific problem by providing a way to create a template, or representation of your UI, that is later dynamically populated and put into place. One of these tools is Handlebars.js. The challenge with using this framework is that it expects to have a script tag somewhere in the page that has an ID. One way to solve this challenge is to insert a script editor web part into your page with the content of the template. However, I would prefer to have my template isolated as a file that I can modify apart from the script running on the file. The challenge is how to get the template loaded dynamically so that Handlebars.js can make use of it.

After performing a search, I found a great article on how to dynamically load templates for Handlebars.js using JQuery by Gabor Szabo. The key is using the function with a callback outlined in the improved JavaScript code section of the article.

Using this article as my starting point, I began by building out my handlebars template and placing it in a document library named Site Assets on the site where I needed to use this script. I saved the template with a .handlebars extension (I could have easily just left it as HTML).

<div id="Vendor_Record">
	<h1>{{CompanyName}}</h1><h2>FEIN: {{FEIN}}</h2>
		<hr style="color:red;"/>
	<div class="address">
		{{WorkAddress}}<br/>
		{{WorkCity}}, {{State}} {{ZipCode}}
	</div>
	<div class="contact">
		{{ContactName}} {{{ContactEmailAddress}}}<br/>
		{{PhoneNumber}}
	</div>
	<div class="status">
		<table>
			<tr>
				<th>Category</th>
				<td>{{VendorCategory}}</td>
			</tr>
			<tr>
				<th>Status</th>
				<td>{{VendorStatus}} - {{ApprovalDeniedReason}}</td>
			</tr>
		</table>
	</div>
</div>

Now the hard part, getting JSLink to work with my template. In my final solution, I need to only show a single record and I am overriding the entire view. I’ll first include the code and then describe what each part of the code is doing.

var SomeCompany = SomeCompany || {};

SomeCompany.Product = SomeCompany.Product || {};
SomeCompany.Product.ViewVendorRecord = SomeCompany.Product.ViewVendorRecord || (function() {
	var itemID = null,
		divID = null,
		render = false,
		template;
		
	function getTemplateAjax(path, callback){
		if(!template){
			var source;
			$.ajax({
				url: path,
				cache: true,
				success: function(data) {
					//console.log(data);
					source = data;
					template = Handlebars.compile(source);
					if(callback) callback(template);
				}
			});
		} else
		if(template) {
			if (callback) callback(template);
		}
	};
	
	return {
		renderHeader: function (ctx) {
			return "<input type=\"hidden\" id=\"" + itemID + "\" value=\"" + encodeURI(JSON.stringify(ctx.ListData.Row[0])) + "\"/><hr/>";
		},
		renderFooter: function (ctx) {
			return "<hr/>";
		},
		renderItem: function (ctx) {
			return "<div id=\"" + divID + "\"></div>";
		},
		onPostRender: function (ctx) {
			var data = JSON.parse(decodeURI($("#" + itemID).val()));
			getTemplateAjax("/sites/Product/siteassets/handlebartemplates/vendor.handlebar", function(template) {
				$("#" + divID).html(template(data));
			});
		},
		onPreRender: function (ctx) {
			render = ctx.ListData.Row.length > 0;
			if(render){
				itemID = "item_" + ctx.ListData.Row[0].ID;
				divID = "div_" + ctx.ListData.Row[0].ID;
			}
		}
	};
})();

(function() {
	var overrideCtx = {};
	
	overrideCtx.Templates = {};

	overrideCtx.Templates.Header = SomeCompany.Product.ViewVendorRecord.renderHeader;
	overrideCtx.Templates.Item = SomeCompany.Product.ViewVendorRecord.renderItem;
	overrideCtx.Templates.Footer = SomeCompany.Product.ViewVendorRecord.renderFooter;
	overrideCtx.Templates.OnPostRender = SomeCompany.Product.ViewVendorRecord.onPostRender;
	overrideCtx.Templates.OnPreRender = SomeCompany.Product.ViewVendorRecord.onPreRender;
	overrideCtx.BaseViewID = 1;
	overrideCtx.ListTemplateType = 100;
	
	SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
})();

This code is setup so that it shouldn’t pollute the global namespace, something I advocated for in a previous post.

Lines 10-27: This is the function used to dynamically load the handlebars template. This is pretty much the same code presented in the article by Gabor Szabo I referenced earlier. The only change is that I store the template in a variable for the module.

Lines 30-32: The renderHeader outputs a single hidden input and stuffs the contents of the first item in the list into it. This could be omitted as I could perform the same action in the renderItem function (untested at the moment). The change would be to use ctx.CurrentItem instead of ctx.ListData.Rows[0] to get the data.

Lines 36-38: My only output in the renderItem is a div with an ID to be the target for Handlebars.js.

Lines 45-51: JSLink give you both an OnPreRender and OnPostRender function that fires for every item rendered in the list for the current view. The onPreRender function simply calculates a unique ID for each item and stores it for later use by the JSLink file. This is another area that would need changes in order to generate a unique ID for Handlebars.js to utilize as a target.

Lines 39-44: OnPostRender is responsible for making sure the template is loaded (line 41) and provides the callback function with will actually place the rendered content into the target DIV.

I want to stress that this code has only been tested rendering a single item in a list view (as this is the requirement for my project). I will continue to experiment to see if I can reuse this idea for rendering multiple items (or even individual fields) and post any findings. Please feel free to share any of your experiences as well.

Here’s a pretty good explanation over at StackOverflow. The answer discusses garbage collection as well as the dangers of placing everything in the global namespace. The common practice that I see is to wrap up your code into an immediately invoked function expression – if you study the basic code for a JS Link file, you’ll see that it makes use of an IIFE to get things rolling.

(function () {
	var override = {};
	
	override.Template = {};
	
	override.Template.Fields = {
		"Field": { 
			"View": function (ctx) {
					return ctx.CurrentItem.title + ": Overridden";
			}
		}; 
		
    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(override);
)();

The IIFE creates a JavaScript line that is immediately executed when the script is loaded. In the example above, a new variable named override is created which will be a JavaScript object. A template property is attached along with a fields object containing the override behavior for the JS Link file. The JS Link, when executed will return the title of the list item with :Overridden appended. This template is registered with the TemplateManager in SharePoint.

The typical approach to creating JS Link files is to add a bunch of individual functions that are called by the JS Link IIFE.

(function() {
	var overrideCtx = {};
	overrideCtx.Templates = {};
	
	overrideCtx.Templates.Fields = {
		'Budget_x0020_ID': {'View': budgetIDField },
		'Actuals':{'View': actualsField },
		'Budget':{'View': budgetField }
	};
	
	SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
})();

function budgetIDField(ctx){
	var html = "<div><strong>" + ctx.CurrentItem.Budget_x0020_ID + "</strong></div>";
	return html;
}

function toUSD(number) {
	/* implementation of conversion to USD */
    return '$' + dollars + '.' + cents.slice(0, 2);
}

function actualsField(ctx) {
	var amount = ctx.CurrentItem.Actuals;
	return toUSD(amount);	
}

function budgetField(ctx) {
	var amount = ctx.CurrentItem.Budget;
	return toUSD(amount);
}

Technically, this is not incorrect, but it definitely adds additional functions to the global namespace that may not need to be there. To move this out of the global namespace means that an IIFE needs to be created. Additionally, a typical practice that I’m getting into is to create a namespace object for storing specific JavaScript functions for a client or solution.

First, I check to see if I already have an object to store my functions that are specific to this solution.

This line will check the global namespace for an object named AwesomeJSLinkSolution. If a variable with the same name is found, it is used. Otherwise a new object is created. (This is good and responsible use of the global namespace.)

Next, the IIFE declaration is created:

With the IIFE, anything that I want to be scoped publically, must be returned. This includes functions and variables that may need to be used later by the solution.

There is also a helper function called toUSD that is used by the solution. Since this function is not necessary to be called from outside the scope of the IIFE, it can be declared directly inside the IIFE. The final code for the IIFE now looks like the following:

var AwesomeJSLinkSolution = AwesomeJSLinkSolution || {};

AwesomeJSLinkSolution.BudgetFields = (function () {
	
	function toUSD(amount) {
		/* convert amount */
		return amount;
	};

	return {
		budgetIDField: function (ctx) {
			var html = "<div><strong>" + ctx.CurrentItem.Budget_x0020_ID + "</strong></div>";
			return html;
		},
		actualsField: function (ctx) {
			var amount = ctx.CurrentItem.Actuals;
			return toUSD(amount);	
		},
		budgetField: function (ctx) {
			var amount = ctx.CurrentItem.Budget;
			return toUSD(amount);
		}
	}
})();

Now the functions that apply to this specific solution are no longer located in the global namespace. Additionally, a function that is specific to this JS Link file is not even accessible outside of the IIFE.

The only outstanding task it to modify the JS Link file. This is a matter of simply updating the function calls to use the new object created by the IIFE.

(function() {
	var overrideCtx = {};
	overrideCtx.Templates = {};
	
	overrideCtx.Templates.Fields = {
		'Budget_x0020_ID': {'View': AwesomeJSLinkSolution.BudgetFields.budgetIDField },
		'Actuals':{'View': AwesomeJSLinkSolution.BudgetFields.actualsField },
		'Budget':{'View': AwesomeJSLinkSolution.BudgetFields.budgetField }
	};
	
	SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
})();

The final file source is:

var AwesomeJSLinkSolution = AwesomeJSLinkSolution || {};

AwesomeJSLinkSolution.BudgetFields = (function () {
	
	function toUSD(amount) {
		/* convert amount */
		return amount;
	};

	return {
		budgetIDField: function (ctx) {
			var html = "<div><strong>" + ctx.CurrentItem.Budget_x0020_ID + "</strong></div>";
			return html;
		},
		actualsField: function (ctx) {
			var amount = ctx.CurrentItem.Actuals;
			return toUSD(amount);	
		},
		budgetField: function (ctx) {
			var amount = ctx.CurrentItem.Budget;
			return toUSD(amount);
		}
	}
})();

(function() {
	var overrideCtx = {};
	overrideCtx.Templates = {};
	
	overrideCtx.Templates.Fields = {
		'Budget_x0020_ID': {'View': AwesomeJSLinkSolution.BudgetFields.budgetIDField },
		'Actuals':{'View': AwesomeJSLinkSolution.BudgetFields.actualsField },
		'Budget':{'View': AwesomeJSLinkSolution.BudgetFields.budgetField }
	};
	
	SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
})();

JS Link Resouces

• Using JSLink with SharePoint 2013 by Pritam Baldota
• JS Link for SharePoint 2013 Web Parts–A Quick Functional Primer by Wesley Preston
• Set JS Link Webpart Property in SharePoint 2013

Setting the stage, let’s say I am working for a company that will be organizing a conference. This conference will be made up of several tracks with multiple sessions. Each room should only support one session per time slot. The conference organizer should not be allowed to double book a room. That would be bad. Based on the listed scenario, the logic to meet this requirement is:

1. Find out how many sessions are assigned to the room and slot.
2. If there is more than 1 session assigned to a room and a slot, don’t let a record get created.
3. Notify the person inserting or updating the record that the room is already occupied.

In the database, the following tables have already been created:

Rooms is simply a list of available rooms for the conference sessions. There is not much to show with this table.

Sessions are the individual conference break-out sessions. In this table there is a references to rooms and a reference to slots.

The final table, slots is just a simple list of the various time slots.

There is not an easy way to get a count of records with the built in data macros, but this is access and queries are great at this. A query is created that  to find out exactly how many sessions are registered for a specific slot and room combination. Adding a query is done by clicking on the Advanced button and selecting Query. (I would also recommend turning on the Navigation Pane so you can see the structure of the assets that make up the database.)

The only table that is needed for this query is the Sessions table since it holds the references to both the room and slot tables. Since the query needs to know what room and slot combination to check, two parameters that will be created. This will help later by providing an easy way to request the data from the query. Click on Parameters in the ribbon.

Two parameters need to be created, one for the ID of the room and another for the ID of the slot.

Also, this query is going to be used for calculations. Turn on the totals allows the selection of count and where that will be a part of the query.

The first column will be a simple count of the ID. The next two columns will be Where fields set to the room and slot and utilizing the parameters created previously.

I save the query and give it a really nice developer name: qryCountSessionInRoomAndSlot. Now it’s time to create the data macro that will be used to help enforce a single session per slot and room. Again, this is found on the advanced tab in the ribbon.

This data macro will need to take the ID of a slot and the ID of a room and execute the query that was created. This means two parameters will also need to be created in the data macro. This is done by clicking on Create Parameter and provided the details of the parameter. Here, I have added both parameters needed.

Now to execute some logic. This macro is going to execute the query, so the Look Up A Record action should be used. When the query is selected, it will automatically show the parameters needed for the query. These need to be mapped to the parameters that are going to be passed into the macro.

Finally, the macro needs to output the resulting data. This is done by using the SetReturnVar action. I set the name of the variable to be CountOfFilledSlots and the expression maps to the name of the column that is to be returned (in the query, this is CountOfID).

Save the data macro and give it a name. I called it GetRoomSlotCount. The data macro completes our requirement to find out how many records already exist for a specific slot and room. If we run this macro, it should return 0 or 1, which are good values since a room can either have a single assignment or doesn’t have an assignment at all. If it returns the value 2, we have a conflict that needs to be resolved. Now we need to enforce that only a single session can be assigned to a room and a slot utilizing this new data macro. Open the Sessions table in design view.

In the ribbon, there are three events that we can use to write macros against. Begin by clicking on On Insert – this will execute when new records are inserted into the table.

The first step in our logic is to execute the data macro that was created. The action needed is RunDataMacro and the macro to execute can be selected from a drop down. Once the macro is selected, it will provide the input and output parameters. They simply need to be mapped to the appropriate fields.

Notice that the output variable CountOfFilledSlots automatically requests to set a local variable. Just provide it a name that is meaningful so it can be used in the next step. The next step will be an If action. This evaluates a simple logical expression for a true or false evaluation. This macro will execute immediately after the record is updated or inserted into the table. This means, if we have a conflict the FilledSlots varialble will have a value greater than one.

Now, we need to take an action if the condition is satisfied. We want to raise an error which will cause a validation failure and will rollback the requested update or insert.

This completes the logic for the insert. We can just copy the same logic to the On Update event. In the application running in SharePoint, it’s time to create a record that will cause a conflict:

When the application detects a conflict when running in SharePoint 2013, the user receives an error message and has a chance to change the data to try again.

Clicking OK allows the record to be corrected.

SCRIPT5022: Sys.WebForms.PageRequestManagerParserErrorException: The message received from the server could not be parsed. Common causes for this error are when the response is modified by calls to Response.Write(), response filters, HttpModules, or server trace is enabled.
Details: Error parsing near ‘ebPartEditing|false|<script type=’text/j’.

This appears to be related to the ASP.Net Update Panel. After a little digging in the web part configuration, we found a way to correct the issue.

Begin by opening the search web part and click on configure query.

The Build Your Query dialog will appear. Go to the Settings page and change the loading behavior to async.

After this change was made, the sql report viewer web part began working properly again.

Overview

The solution will be a new search results page was created in the search center. The page search results web part will have a predefined search query focused on returning tasks, something like ContentType:Task will be a good starting point.

SharePoint 2013 search results are made up of control templates and item templates (there are others, but this will be the focus for this post). The control template is used to render the outer DOM elements for the search results, and this is a great place to initialize jQuery controls, like DataTables. The item template is used to render individual search results. Since the goal for the client is to render a list of tasks in a tabular format, the control template should create a standard HTML table. The item template will create the individual table rows from the returned search results.

Control Template

DataTables prerequisites are table that includes a thead and a tbody. To keep things simple, the table will initially only include the title of the task and the source site. The markup should appear something like the following:

<table>
<thead>
<tr>
<th>Task</th>
<th>Source Site</th>
</tr>
</thead>
<tbody><!-- ROWS HERE --></tbody>
</table>

This creates the necessary markup required by DataTables. The search results should simply be the individual rows, something like:

<tr><td><!-- TITLE --></td><td><!-- SITE NAME AND LINK --></td></tr>

Starting with an existing control makes it easy to get the necessary initial markup. I chose to start with the Control_List.html located in the control templates/content web parts folder of the master page gallery.

<html xmlns:mso="urn:schemas-microsoft-com:office:office" xmlns:msdt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882">
<head>

<title>Tasks Data Table</title>

<!--[if gte mso 9]><xml>
<mso:CustomDocumentProperties>
<mso:TemplateHidden msdt:dt="string">0</mso:TemplateHidden>
<mso:MasterPageDescription msdt:dt="string">This template uses jQuery DataTables to display task information.</mso:MasterPageDescription>
<mso:ContentTypeId msdt:dt="string">0x0101002039C03B61C64EC4A04F5361F385106601</mso:ContentTypeId>
<mso:TargetControlType msdt:dt="string">;#Content Web Parts;#</mso:TargetControlType>
<mso:HtmlDesignAssociated msdt:dt="string">1</mso:HtmlDesignAssociated>
<mso:CrawlerXSLFile msdt:dt="string"></mso:CrawlerXSLFile>
<mso:HtmlDesignPreviewUrl msdt:dt="string"></mso:HtmlDesignPreviewUrl>
<mso:HtmlDesignConversionSucceeded msdt:dt="string">True</mso:HtmlDesignConversionSucceeded>
<mso:HtmlDesignStatusAndPreview msdt:dt="string">http://connect.qrinc.com/poc/aip/_catalogs/masterpage/Display Templates/Content Web Parts/Control_TaskTable.html, Conversion successful.</mso:HtmlDesignStatusAndPreview>
</mso:CustomDocumentProperties>
</xml><![endif]-->
</head>

<body>
    <script>
    </script>

    <div id="Control_TaskDataTable">

<!--#_
if (!$isNull(ctx.ClientControl) &&
    !$isNull(ctx.ClientControl.shouldRenderControl) &&
    !ctx.ClientControl.shouldRenderControl())
{
    return "";
}
ctx.ListDataJSONGroupsKey = "ResultTables";
ctx["CurrentItems"] = ctx.ListData.ResultTables[0].ResultRows;
var $noResults = Srch.ContentBySearch.getControlTemplateEncodedNoResultsMessage(ctx.ClientControl);

var encodedID = $htmlEncode(ctx.ClientControl.get_nextUniqueId() + "_Table_");

var noResultsClassName = "ms-srch-result-noResults";
_#-->

<table class="artis-tasktable" id="_#= encodedID =#_">
	<thead>
		<tr>
			<th>Task</th>
			<th>Source Site</th>
		</tr>
	</thead>
	<tbody>
		_#= ctx.RenderItems(ctx) =#_
	</tbody>
</table>	

    </div>
</body>
</html>

Line 3: This changes the display name of the template as it appears in the content by search web part.

Line 9: Provides a clearer description of the display template.

Line 25: Changes the ID of the control.

Line 38: Changes the emitted control ID.

Lines 43-53: The table that will contain search results.

DataTables needs to be initialized after the content is put into the table. In a normal project, you might simply start with the standard jQuery $(document).ready(…), but this will not work with display templates. However, exploring how the Control_Slideshow.html handles this, this behavior can be handled.

ctx.OnPostRender = [];

ctx.OnPostRender.push(function () {
	$("#" + encodedID).dataTable(
	  {
           "bPaginate": true,
           "bLengthChange": false,
           "bFilter": false,
           "bSort": false,
           "bInfo": false,
           "bAutoWidth": false,
	       "bJQueryUI": true
          }
        );
});

ctx.OnPostRender allows us to hook into the execution lifecycle to add additional methods to execute once the control has finished rendering. This is a good place to hook in and initialize DataTables. However, we still need to include the script references or we will wind up with an error message instead of a working display template. In the script above between lines 21-23 we have a place to register scripts. Just simply include the necessary scripts and CSS:

<script type="text/javascript">
        $includeScript(this.url,"~sitecollection/style library/js/jquery-1.10.2.min.js");
        $includeScript(this.url,"~sitecollection/style library/js/jquery.dataTables.min.js");
        $includeCSS(this.url,"~sitecollection/style library/css/jquery.dataTables.css");
</script>

In this example, all of the scripts and css are located in the style library of the current site collection. Using the ASP.Net placeholder, we get the full URL to the current site collection. This will include the necessary scripts to render DataTables successfully.

The final markup:

<html xmlns:mso="urn:schemas-microsoft-com:office:office" xmlns:msdt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882">
<head>
<title>Tasks Data Table</title>

<!--[if gte mso 9]><xml>
<mso:CustomDocumentProperties>
<mso:TemplateHidden msdt:dt="string">0</mso:TemplateHidden>
<mso:MasterPageDescription msdt:dt="string">This template uses jQuery DataTables to display task information.</mso:MasterPageDescription>
<mso:ContentTypeId msdt:dt="string">0x0101002039C03B61C64EC4A04F5361F385106601</mso:ContentTypeId>
<mso:TargetControlType msdt:dt="string">;#Content Web Parts;#</mso:TargetControlType>
<mso:HtmlDesignAssociated msdt:dt="string">1</mso:HtmlDesignAssociated>
<mso:CrawlerXSLFile msdt:dt="string"></mso:CrawlerXSLFile>
<mso:HtmlDesignPreviewUrl msdt:dt="string"></mso:HtmlDesignPreviewUrl>
<mso:HtmlDesignConversionSucceeded msdt:dt="string">True</mso:HtmlDesignConversionSucceeded>
<mso:HtmlDesignStatusAndPreview msdt:dt="string">http://connect.qrinc.com/poc/aip/_catalogs/masterpage/Display Templates/Content Web Parts/Control_TaskTable.html, Conversion successful.</mso:HtmlDesignStatusAndPreview>
</mso:CustomDocumentProperties>
</xml><![endif]-->
</head>

<body>
    <script>
        $includeScript(this.url,"~sitecollection/style library/js/jquery-1.10.2.min.js");
        $includeScript(this.url,"~sitecollection/style library/js/jquery.dataTables.min.js");
        $includeCSS(this.url,"~sitecollection/style library/css/jquery.dataTables.css");
    </script>

    <div id="Control_TaskDataTable">

<!--#_
if (!$isNull(ctx.ClientControl) &&
    !$isNull(ctx.ClientControl.shouldRenderControl) &&
    !ctx.ClientControl.shouldRenderControl())
{
    return "";
}
ctx.ListDataJSONGroupsKey = "ResultTables";
ctx["CurrentItems"] = ctx.ListData.ResultTables[0].ResultRows;
var $noResults = Srch.ContentBySearch.getControlTemplateEncodedNoResultsMessage(ctx.ClientControl);

var encodedID = $htmlEncode(ctx.ClientControl.get_nextUniqueId() + "_Table_");

var noResultsClassName = "ms-srch-result-noResults";
ctx.OnPostRender = [];

ctx.OnPostRender.push(function () {
	$("#" + encodedID).dataTable(
	{
		"bPaginate": true,
        "bLengthChange": false,
        "bFilter": false,
        "bSort": false,
        "bInfo": false,
        "bAutoWidth": false,
		"bJQueryUI": true
     }
     );
});
_#-->

<table class="artis-tasktable" id="_#= encodedID =#_">
	<thead>
		<tr>
			<th>Task</th>
			<th>Source Site</th>
		</tr>
	</thead>
	<tbody>
		_#= ctx.RenderItems(ctx) =#_
	</tbody>
</table>	

    </div>
</body>
</html>

Item Template

Now attention is turned on the item template for the individual results. The item template will need to include managed properties to include in the final rendered result. Managed properties are defined either by a search administrator or by a site collection administrator.

Since we are keeping this simple, the item template will only include the Title of the task, a link to the task (available from the built in Title managed property), the title of the site (from the Site managed property) and a link to the site (from the SPSiteUrl managed property). The final template should look something like:

<tr>
	<td>
		<a href="TaskURL">Task Title</a>
	</td>
	<td>
		<a href="SiteURL">Site</a>
	</td>
</tr>

Again, I simply borrowed from an existing template to get started (Item_Default.html) to build the control. This gives me many of the managed properties I will need.

You will notice in the final markup that managed properties are mapped in a format similar to ‘Property'{Property}:’Property’. On MSDN, it is stated, “The property is a comma-delimited list of values that uses the following format: ‘property display name'{property name}:’managed property’.” The property display name is what will be displayed in the editing pane while the web part is being customized. The property name maps to a localized resource that is used for property binding. The managed property is a list of managed properties to use for the value.

<html xmlns:mso="urn:schemas-microsoft-com:office:office" xmlns:msdt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882">
<head>
<title>Data Table Task Row</title>

<!--[if gte mso 9]><xml>
<mso:CustomDocumentProperties>
<mso:TemplateHidden msdt:dt="string">0</mso:TemplateHidden>
<mso:ManagedPropertyMapping msdt:dt="string">'Link URL'{Link URL}:'Path','Task Title'{Task Title}:'Title','SecondaryFileExtension','ContentTypeId','ListItemID','SiteTitle','SitePath','Site','SPSiteURL'</mso:ManagedPropertyMapping>
<mso:MasterPageDescription msdt:dt="string">This Item Display Template will show a single task on a single row. This must be used with the Tasks Data Table control.</mso:MasterPageDescription>
<mso:ContentTypeId msdt:dt="string">0x0101002039C03B61C64EC4A04F5361F385106603</mso:ContentTypeId>
<mso:TargetControlType msdt:dt="string">;#Content Web Parts;#</mso:TargetControlType>
<mso:HtmlDesignAssociated msdt:dt="string">1</mso:HtmlDesignAssociated>
<mso:CrawlerXSLFile msdt:dt="string"></mso:CrawlerXSLFile>
<mso:HtmlDesignPreviewUrl msdt:dt="string"></mso:HtmlDesignPreviewUrl>
<mso:HtmlDesignStatusAndPreview msdt:dt="string">http://connect.qrinc.com/poc/aip/_catalogs/masterpage/Display Templates/Content Web Parts/Item_TaskTableRow.html, Conversion successful.</mso:HtmlDesignStatusAndPreview>
<mso:HtmlDesignConversionSucceeded msdt:dt="string">True</mso:HtmlDesignConversionSucceeded>
</mso:CustomDocumentProperties>
</xml><![endif]-->
</head>

<body>
    <script>
    </script>

    <div id="Item_DataTaskRow">
<!--#_
var encodedId = $htmlEncode(ctx.ClientControl.get_nextUniqueId() + "_row_");

var linkURL = $getItemValue(ctx, "Link URL");
linkURL.overrideValueRenderer($urlHtmlEncode);

var taskTitle = $getItemValue(ctx, "Task Title");
var siteTitle = $getItemValue(ctx, "SiteTitle");

var linkId = encodedId + "link";
var titleId = encodedId + "title";
var siteId = encodedId + "site";

_#-->
		<tr id="_#= encodedId =#_" data-listitemid="_#= ctx.CurrentItem.ListItemID =#_">
			<td><a href="_#= linkURL =#_" id="_#= linkId =#_" data-role="modalOpen">_#= taskTitle =#_</a></td>
			<td><a href="_#= ctx.CurrentItem.SPSiteURL =#_">_#= siteTitle =#_</a></td>
		</tr>
	</div>
</body>
</html>

Line 3: Changes the display name.

Line 8: Set the managed properties to include.

Line 25: Changes the ID of the control.

Line 40-43: The individual search results will be rendered with the template.

This will provide the final markup required. On the original search page, the content by search web part is changed to utilize the new control and item templates.

And the control is finally rendered and enhanced with DataTables:

More information:

• MSDN: SharePoint 2013 Design Manager display templates
• The Anatomy of SharePoint 2013 Display Templates

Be an over-achiever

• Build an Image Slider with SharePoint 2013 Search Results Web Part