Sagar Ganatra's Blog

How to use the APP_INITIALIZER token to hook into the Angular bootstrap process

2019-06-24T19:00:00.000+05:30

I've been building applications using Angular as a framework of choice for more than a year and this post is not about another React vs Angular or the quirks of each framework. Honestly, I like Angular and every day I discover something new which makes development easier and makes me look like a guy who built something very complex in a matter of hours which would've taken a long time to put the correct architecture in place if I had chosen a different framework. The first thing that I learned in Angular is the use of the APP_INITIALIZER token.

The documentation at angular.io says - 'A function that will be executed when an application is initialized'. It does not spew any details on how to use this function and where to include it.

Sidenote: I must say the documentation could've been better with examples and a detailed explanation for the given feature could've helped. But hey, I can't hold this against you Angular :)

The APP_INITIALIZER token is used when you want to get the application's configuration details from an API and keep it ready before the application renders the page. For example, you would want to load the necessary language files before rendering any of the templates or you would want to resolve a remote API which provides information on the environment that the application is being run on. It's similar to how the 'resolve' attribute in the router's configuration is used to get data from the remote API and feed it into the route's 'data' source. In this case, the remote API is resolved first and then the application continues with the bootstrap process.

Here's an example of how the APP_INITIALIZER token is included in the application. The main module of the application - app.module.ts includes the APP_INITIALER in its 'providers' section:

Notice that the 'providers' section includes APP_INITIALIZER with the attribute 'useFactory' referring to factory function 'initApp'. Here's the definition of the initApp factory function:

The factory function is expected to return a Promise and only after the promise has resolved the application bootstrap process would continue. In the above code snippet, a delay of three seconds is added before the promise resolves. This blocks the bootstrapping of the application for three seconds. Similarly, you could use an HTTP service (from HttpClient) to request data from an API and only after the request is complete that the application bootstrap process would continue. However, to use Angular's HttpClient in the initApp factory function, include HttpClientModule in the imports section and also specify HttpClient as a dependency (deps) to the APP_INITIALIZER provider:

imports: [
BrowserModule,
HttpClientModule
],
providers: [{
provide: APP_INTIALIZER,
useFactory: initApp,
multi: true,
deps: [HttpClient]
}]
...

Next, update the initiApp factory function and use the instance of HttpClient to request data from a remote service:

The 'get' method on the HttpClient instance returns a Subscription (see RxJS) and the toPromise method is used to convert the Subscription to a Promise. If the factory method returns the subscription, the application would continue to bootstrap as if there was no APP_INITIALIZER token added to the module.

The source code for the above example is available at - https://github.com/sagar-ganatra/angular-app-initializer

My third book titled — ‘React-Router Quick Start Guide’ published!

2018-10-01T17:55:00.000+05:30

The title says it all. This is my third book with Packt Publishing and I wrote a book after four long years. In the last few months, I’ve spent my weekends writing this book and it was an arduous undertaking. Here’s the cover image:

I have used React and React-Router in many projects and during the course of writing this book I’ve learned a great deal about these frameworks/libraries. This book is all about the ‘React-Router’ library and how you can use it any React application (web or native).

The book covers the following topics:

Chapter 1, Introduction to React Router 4 and Creating Your First Route, is an introduction to the component-based architecture in React and how you can get started with creating routes using the Route component from React Router.

Chapter 2, Configuring Routes, Using Various Options in the Route Component, discusses various Route component props that can be used to match the requested URL location and how these matches can be used to render a component. Also, the chapter explains how routes can be added dynamically as the user traverses through the application.

Chapter 3, Using Link and NavLink Components to Navigate to a Route, talks about how to use the Link and NavLink components in React Router to allow you to navigate to routes defined in the application. This chapter also explains the higher-order component withRouter and how to prevent accidental transition using the Prompt component.

Chapter 4, Using Redirect and Switch Components, goes into how to use the Redirect component to redirect the user to a different route and the Switch component to match one route and redirect the user to a 404 page not found page if the requested location is not found.

Chapter 5, Understanding the Core Router and Configuring BrowserRouter and HashRouter Components, is an in-depth explanation of how the core router interface is used to update the sections of the screen and the browser’s history. The chapter also explains two router interfaces used in a web application: BrowserRouter and HashRouter.

Chapter 6, Using StaticRouter in a Server-Side-Rendered React Application, explores how to use the StaticRouter component to provide routing features on a server-side-rendered application. The chapter also explains how StaticRouter and BrowserRouter can be used to build an isomorphic web application.

Chapter 7, Using NativeRouter in a React-Native Application, details how to provide routing in a native mobile application developed with React Native using the NativeRouter component. The chapter also explains how you can integrate with the device’s back button using the BackButton component and provide deep linking support using the DeepLinking component.

Chapter 8, Redux Bindings with Connected-React-Router, examines how to use the connected-react-router library, which provides Redux bindings for React Router; the chapter explains how to read routing information from the router state in the Redux store and how to navigate by dispatching actions to the store.

You can buy a copy of this book here — https://www.packtpub.com/web-development/react-router-quick-start-guide

Using MobX to manage application state in a React application

2018-01-26T19:43:00.000+05:30

I have been writing applications using React and Redux for quite some time now and thought of trying other state management solutions out there. It's not that I have faced any issues with Redux; however, I wanted to explore other approaches to state management. I recently came across MobX and thought of giving it a try. The library uses the premise of `Observables` to tie the application state with the view layer (React). It's also an implementation of the Flux pattern wherein it uses multiple stores to save the application state; each store referring to a particular entity. Redux, on the other hand, uses a single store with top-level state variables referring to various entities.

On Redux vs MobX:

Redux uses functional programming approach to update the state:

(state, action) => newState;

It accepts two arguments - current state and an action and returns a new state. In Redux, the state is immutable i.e. to update the view, the state reference in the Redux store itself should be updated. For example, to add a new item to the cart you would:

(state, action) => {
return [...state.items, action.item];
}

instead of

return state.items.push(item);

MobX, on the other hand, uses an object-oriented approach to state management. A store in MobX is nothing but an instance of a class which has observable properties:

class Cart {
@observable itemsInBag = [];
@observable itemsInWishlist = [];
}

The decorator `@observable` (defined in `mobx` library) is used to declare a property in the class as an observable. It's initialized to an empty array and any changes to this array will let the observers know. In this case, the observer is our view component in React:

The above React component class has the `@observer` decorator, declaring that view component will get updated with the changes in the props. Notice `this.props.cart` in the component's render function, the observable property declared in the Cart class - itemsInBag is being observed by this React component. Any additions/deletions/updates in the observable property will rerender the observer component.

Here the view component gets an instance of the cart object as a prop from the parent container:

const cart = new Cart()
return (
<ShoppingCart cart={cart} />
)

The view component also has `this.props.cart.bagCount` instead of `this.props.cart.itemInBag.length`; this is on purpose. MobX provides decorators that can derive values from the state. In this case, the bagCount property is declared as a `@computed` property:

class Cart {
@observable itemsInBag = [];
@observable itemsInWishlist = [];

@computed get bagCount() {
return this.itesmsInBag.reduce((count, bagItem) => {
return count + bagItem.count;
}, 0);
}
}

The computed getter (get bagCount) function returns the number of items in the cart; it's executed every time the observable properties in the class are updated. This is very handy because the computation logic is present in the Cart class instead of it being in the View component. It means consistency in the model layer and the code remains DRY.

On setting up the environment for using ES7 decorators

I generally use `create-react-app` to quickly scaffold out the front-end and then modify it to add other libraries. However, it reported errors when I started to use the decorators (observable, observer and computed). Later I discovered that ES7 decorators are still at the proposal stage and are not part of the language yet and thus it's not supported in `create-react-app`. I had to use `yarn eject` to get all the configuration in my local setup and then add babel plugins to get the decorators working:

yarn add --dev babel-cli babel-preset-env babel-plugin-transform-decorators-legacy

and then added .babelrc file to the project's root directory:

{

"presets": ["env", "react", "stage-1"],

"plugins": ["transform-decorators-legacy"]

}

This should not report any errors when you start the app (using yarn start). Also, there's an option to use the function `extendObservable` to create an observable instead of using ES7 decorators:

extendObservable(this, {

itemsInBag: [],

get bagCount() {

return this.itemsInBag.length;

}

})

This is very much ES5 syntax; however, I really liked the ES7 decorators' syntax and I hope it gets accepted in the language.

Demo App - https://sagar-ganatra.github.io/react-mobx-shopping-cart/

GitHub repo - https://github.com/sagar-ganatra/react-mobx-shopping-cart/

On GraphQL and building an application using React Apollo

2018-01-23T16:47:00.001+05:30

When I visualize building an application, I would think of using React and Redux on the front-end which talks to a set of RESTful services built with Node and Hapi (or Express). However, over a period of time, I've realized that this approach does not scale well when you add new features to the front-end. For example, consider a page that displays user information along with courses that a user has enrolled in. At a later point, you decide to add a section that displays popular book titles that one can view and purchase. If every entity is considered as a microservice then to get data from three different microservices would require three http requests to be sent by the front-end app. The performance of the app would degrade with the increase in the number of http requests.

I read about GraphQL and knew that it is an ideal way of building an app and I need not look forward to anything else. The GraphQL layer can be viewed as a facade which sits on top of your RESTful services or a layer which can be used to talk directly to the persistent layer. This layer provides an interface which allows its clients (front-end apps) to query the required fields from various entities in one single http request.

GraphQL - On the Server

On the server side, GraphQL provides a schema language using which you can construct the domain model. In GraphQL terms, these are `types`, a `type` is used to represent an entity such as User, Course, Book etc. It looks something like this:

type CourseType {
id: ID!
name: String
level: Int
description: String
}

Here, each field in CourseType entity has a type indicating the value that it can hold (String, Float, Character, Int etc). Apart from the Scalar types, a field could also be used to declare the relationship between two types. For example, a StudentType can have a field `courses` to declare the courses that he/she has enrolled in:

type StudentType {
id: ID!
firstName: String
lastName: String
courses: [CourseType]!
}

Here the field `courses` is of type `[CourseType]!`. The array notation is used to indicate that a Student record can have a collection of courses i.e. a student can enrol in multiple courses(1-to-many relationship). The bang (!) is used to indicate that it's a required field.

Apart from defining types, one is required to specify what can be retrieved using a `Query` and what can be updated using `Mutation`.

type Query {
allCourses: [CourseType]
allStudents: [StudentType]
}

type Mutation {
createCourse(name: String, level: Int, description: String): CourseType
createStudent(firstName: String, lastName: String, courses: [CourseType]!): StudentType
updateCourse(id: ID!, name: String, level: Int, description: String): CourseType
.
.
.
}

Here types `Query` and `Mutation` are special types. They're not used to define an entity, rather they're used to specify the operations that you can perform on these entities. For example, `allCourses` in `Query` is used to declare that the client can use this to retrieve a list of courses (returns [CourseType]). A Mutation type, on the other hand, is used to indicate the operations that you can perform to update these entities. In the above example, createCourse, createStudent etc are the operations that you can perform to add or update records.

All the above types put together come to form the type definition for your schema and it gives a high-level overview of the domain model and the operations that you could perform on various entities. However, the business logic for how the data would be retrieved or updated is not present. To accomplish this, one is required to write resolvers. A resolver provides the implementation that maps to the operations declared in the schema. A sample resolver for the above example looks like this:

const resolvers = {
Query: {
allCourses: () => {
return COURSES;
}
},
Mutation: {
createCourse: (_, { input }) => {
let { id, name, description, level } = input;
COURSES.push({
id,
name,
description,
level
});
return input;
}
}
};

The resolvers object contains two properties Query and Mutation; under these, you would define the various operations that can be performed on the entities declared in the schema. Note, that the name of the operations would map to the ones specified in the schema (here allCourses in type Query and createCourse in type Mutation). The type definitions are independent of the language or the platform that you choose. However, the resolvers are written in the language of your choice; in this case JavaScript.

The type definitions and resolvers come together to define the executable schema which can then be used to define middleware in a Node + Express environment:

const schema = makeExecutableSchema({ typeDefs, resolvers});
app.use('/graphql',
bodyParser.json(),
graphqlExpress({
schema
}));

I've used `graphql-tools` and `apollo-graphql-express` modules to create the schema and the middleware which would accept incoming requests.

To test the server setup, you could make use of the GraphiQL interface which allows you to inspect the operations declared in the schema, add this:

app.use('/graphiql',
graphiqlExpress({
endpointURL: '/graphql'
}));

The graphiql interface provides us with a way to test the operations declared in `Query` and `Mutation` of our schema:

Here, the object notation on the left side allows me to specify the query method and the fields that I need from the `courses` model (id and name). The response from the server (on the right side) includes only the data that I have requested. Although the resolver itself returns the entire object, GraphQL ensures that only the requested data is returned in the response; thus reducing the size of the payload.

GraphQL - On the client side

On the client side, the first step would be to connect to the GraphQL server and wrap the root component with the Provider (ApolloProvider from `react-apollo`):

import React from 'react';

import ReactDOM from 'react-dom';

import { ApolloProvider } from 'react-apollo';

import { ApolloClient } from 'apollo-client';

import { HttpLink } from 'apollo-link-http';

import './index.css';

import App from './App';

const client = new ApolloClient({

link: new HttpLink({ uri: 'http://localhost:8080/graphql' })

})

ReactDOM.render(

<App />

</ApolloProvider>,

document.getElementById('root'));

Next, we use the `react-apollo` module which provides a higher-order function using which we can glue together a component with the result from a GraphQL query response:

import React, { Component } from 'react';
import { graphql } from 'react-apollo';
import gql from 'graphql-tag';
import Course from './Course';

class CourseList extends Component {
render() {
const { allCourses } = this.props.data;

if (!allCourses) return null;

return allCourses.map(course => {
return (
<Course key={course.id}
course={course} />
);
});
}
}

export default graphql(gql`
query CourseListQuery {
allCourses {
id
name
description
}
}
`)(CourseList);

Here the graphql higher-order function accepts two arguments - the GraphQL query and the view component that has to be updated with the query result. The result of the query response is passed to the component as props (this.props.data).

Next steps:

I've briefly read about `Relay` and I plan to experiment with it to see how it can be used to connect to a GraphQL server and compare it to see how it fairs with Apollo.

GitHub repo - https://github.com/sagar-ganatra/react-graphql-apollo-app

React Redux starter kit - Rekit

2017-07-28T21:39:00.001+05:30

I have been developing applications using React and Redux for quite some time now and I feel there are several starter kits out there. Although some add too much of boilerplate code, some include several libraries (to make it one kit that includes all) and some take the route of adding minimal boilerplate to include only the required libraries. I plan to write about these React-Redux starter kits/boilerplates in the coming weeks. This post focuses on a starter kit called Rekit. Rekit provides basic scaffolding and comes with a CLI that allows you to add features to your React application. Rekit focuses on application structure. It divides the application in terms of features, wherein each feature acts as a decoupled component and then assembled at the root level.

Since I mentioned the word 'boilerplate', a React-Redux application would have to include some boilerplate code before one starts to write any functional code. Even a simple application would need some boilerplate code added. A project created with Rekit has basic scaffolding and also includes boilerplate code such as configuring a store, adding middleware such as redux-thunk and router (react-router-redux), adding root path (/) to the list of routes and defining an App container where the route components would be rendered etc. It brings developer to a place where he's are ready to add functional code to the application.

Rekit follows feature oriented architecture to structure the application. Instead of building the application in terms of containers, components and actions; an application built with Rekit is organized in terms of features. Here, each feature is decoupled and would have its own set of containers, components, routes and actions. For example, consider an application that allows you to add a to-do and list the to-dos; it would have two routes - /add and /list, two containers - 'Add' and 'List' that connect to the Redux store and dispatch actions that update the state variables in the Redux store, actions - 'addTodo' and 'getTodos' that update and read from the Redux state. Also, the CLI allows you to create dumb components(view-only) that are then included in container's render method whose sole responsibility would be to display the values passed to it and invoke handlers defined in its parent container.

Rekit CLI makes it really easy to create an application and add features to it. After installing Rekit (npm i -g rekit), you can use rekit command to create a project.

rekit create todo-app

this would create a todo-app with package.json in it. Change the directory to the newly created project and then do 'npm i' to install the dependencies.

The next step would be to add a feature and a couple of Containers and Actions in the feature:

rekit add feature todo
rekit add component todo/List -c // -c flag to create a container component
rekit add component todo/Add -c
rekit add action todo/add

+ todo-app
+ src
+ common
- configStore.js
- history.js
- rootReducer.js
- routeConfig.js
+ features
+ todo
+ redux
- actions.js
- add.js
- constants.js
- initialState.js
- reducer.js
- update.js
- Add.js
- Add.less
- index.js
- List.js
- List.less
- ListItem.js
- ListItem.less
- route.js
- style.less
+ images
+ styles
- index.html
- index.js
- Root.js
+ tests
+ tools

Rekit scaffolds the project with a basic setup which includes the entry point to the application in index.js, redux store and route configuration related files in common directory and it also includes a 'default page' as a feature (not shown above). It adds/updates directories and files in the project as and when you add a feature, component or an action.

On one action per file methodology:

Rekit makes it a mandate to create one action per file instead of several actions in a single file and calling it as a reducer. I was initially not comfortable with this approach but then by following through the application structure, it made more sense. Every action is defined in a file and it exports two functions – an action and a reducer.

The CLI then includes this file in feature’s root reducer file - todo/redux/reducer.js:

Notice the last line - return reducers.reduce((s, r) => r(s, action), newState); it returns the reducer function for each of the reducers defined in the feature. The feature root reducer was earlier imported into the application’s root reducer:

The CLI adds the import statements, updates the reducer list and keeps the application updated whenever a new feature is added or updated. I've been very happy with this starter kit so far, not to forget, it adds unit test files, linting rules and build configuration files. Also, there is an option to replace redux-thunk with redux-saga.

I've created a sample todo app and have posted the code on GitHub - https://github.com/sagar-ganatra/rekit-todo-app

Building your static site with Hugo, FlightJS, SASS and Gulp

2016-12-13T17:26:00.000+05:30

Hugo provides a good workspace for creating layouts and content. I'm very much satisfied with the options available to customise the site. However, Hugo does not have a say in how CSS and JavaScript should be structured so that it can be included on our site. In Hugo, the DOM nodes are already created and we need a mechanism which we can employ in adding event listeners to these DOM nodes.

SPA frameworks like Angular and React, create DOM nodes and define event listeners in the controller of the component. To attach event listeners to an existing DOM tree I came across a JavaScript framework called FlightJS. It's a framework created by folks at Twitter that helps in adding behaviour to the DOM nodes. It's a minimal framework which does not dictate how the DOM nodes should be rendered nor it dictates the other aspects of the web application, such as routing, request/response handling, structuring data so that other components can consume it etc. FlightJS provides only a mechanism that enables us to add behaviour to the existing DOM nodes.

This is exactly what I needed to build my static site. Let's take a look at how I have structured my site using SCSS, FlightJS and Gulp for building the static content:


--src

  --js

    --pages

      --home

        --index.js

    --vendor

      --flight.js

      --jquery.js

  --styles

    --pages

      --home

        --index.scss

      --vendor

        --index.scss

I have created an 'src' directory in my Hugo site which will contain all the JavaScript and SCSS files. Hugo's documentation suggests that we need to keep all static content (JavaScript, CSS, images, font files etc) in 'static' directory. Here 'src' directory will contain the development code i.e. unprocessed SCSS files and non-minified JavaScript files. The 'static' directory, on the other hand, will contain CSS code (processed SCSS) and minified JavaScript files which are production ready.

In our example, the FlightJS code can be included in 'js/pages/home/index.js' file. Here's the code which creates a FlightJS component, defines a 'click' event handler and attaches the component to an existing DOM node:

FlightJS has a dependency on jQuery and thus you see jquery.js present in the 'vendor' directory. A lot can be done with FlightJS, however, I'm restricting this post to build a proof of concept which demonstrates the minimal functionality.

The next step is to add a build process that compiles the SCSS files, compress and concatenates JS files and creates a hash for these files for browser cache busting. I'm using GulpJS to create a pipeline build and here's the sequence:

Compile SCSS files - compile 'pages' and 'vendor' files separately.
Concatenate the vendor related CSS files.
Move the generated files to 'static/css' directory.
Compress the JS files - 'pages' and 'vendor' files separately.
Move the generated files to 'static/js' directory.
Use 'gulp-hash' to create a hash for the generated JS and CSS files. Create a hash manifest file and place it in the 'data' directory (assets_js.json and assets_css.json).

The gulpfile.js used to build the pipeline can be referred here: https://github.com/sagar-ganatra/hugo_example/blob/master/gulpfile.js

After compiling and generating content in the 'static' directory, you can refer to these files in your layout templates:

<link href="{{ .Site.BaseURL }}css/vendor/vendor.css }}" rel="stylesheet" type="text/css">
<script src="{{ .Site.BaseURL }}js/vendor/vendor.js }}"></script>

Here the template variable {{ .Site.BaseURL }} would be replaced with the baseUrl defined in the config.toml file and when the generator creates the static files, it would be referring to the file '<site>/css/vendor/vendor.css' and '<site>/js/vendor/vendor.js'. Since we are creating adding a hash to these files, it would not be possible to refer to 'vendor.js' and 'vendor.css' files like this. However, we can use the manifest files created when generating a hash for referring these files.

As noted in the last step of the Gulp build process, we are creating manifest files 'assets_js.json' and 'assets_css.json' in the 'data' directory. The content is a JSON structure that contains hash references:


{

  "pages/home.js":"pages/home_4740e2cf.js",

  "pages/home_debug.js":"pages/home_debug_3f723556.js",

  "vendor/vendor.js":"vendor/vendor_f8da36b2.js",

  "vendor/vendor_debug.js":"vendor/vendor_debug_b3868b34.js"

}

Hugo can read files in the 'data' directory and it supports TOML, YAML and JSON file formats. Now we can modify our template to get the hash refernce from the asset files:


<link

    href="{{ .Site.BaseURL }}css/{{ index .Site.Data.code_assets.assets_css "vendor/vendor.css" }}"

    rel="stylesheet"

    type="text/css">

and


<script

    src="{{ .Site.BaseURL }}js/{{ index .Site.Data.code_assets.assets_js "vendor/vendor.js" }}">
</script>

The template variable '.Site.Data.code_assets.assets_js' will contain reference to the values in the file 'data/code_assets/asset_js.json' and the reference key 'vendor/vendor.js' would return the value assigned to it (vendor/vendor_f8da36b2.js).

Code is shared on my github repository here: https://github.com/sagar-ganatra/hugo_example

Hugo - On layouts and content organization

2016-12-08T18:43:00.001+05:30

Layouts in Hugo allow you to define the how the posts in the content directory would be displayed. In addition to defining layouts for the content posts, you can define the layout for the home page, define partials and include it in different layout templates, also define the default layout to be used in case the matching content type layout is not found.

The directory structure followed in Layouts imitates the directory structure of the content directory:


--layouts

  --_default

    --single.html

    --summary.html


  --pages

    --single.html

    --summary.html

--partials
--header.html

    --aside.html

  --index.html

The site's home page is defined in layout's index.html file. If you're building a blog, this page would list the recent posts. Hugo provides several Site level variables that you use it in this template file:

Notice that several template variables are used to create the home page. The one that will display recent posts is mentioned inside the body tag of the template:


{{ range .Data.Pages }}

  {{ if or (eq .Type "posts") (eq .Type "posts-series") }}

    <h3>

       <a href={{ .Permalink }}>{{ .Title }}</a>

     </h3>

     {{ .Render "summary" }}

  {{ end }}

{{ end }}

The range operator is used to iterate over an array; here the template variable .Data.Pages contain all the posts listed in the content directory. Inside the range loop, a condition is specified to see if the page if of a particular Type. The Type information is determined by the location of the post in the content directory. If the post is defined in the 'posts' directory then the type would be 'posts', similarly, if you have top level pages defined in 'pages' directory, then the type would be 'pages'. Alternatively, you can override the default Type by mentioning 'type' field in the front matter of the post(see the content organisation section below).

When listing posts, you would want to list only the summary information instead of the entire content of the post. The template {{ .Render "summary" }} is used when you have a separate template - summary.html defined to display the summary information. This template could display additional information such as published date, tags etc. If you would like to display only the summary without including any additional template then use the template variable {{ .Summary }}. Hugo will pick up the first 70 words from the content and display it as the summary of the post. Alternatively, you can insert a jump break by including  tag. Hugo will pick up all the content before this tag and display it as the summary of the post.

Let's take a look at summary.html defined in _default directory:


Published date: {{ .Date.Format "2 Jan, 2006" }}

{{ .Summary }}

{{ if .Truncated }}

  <a href="{{ .Permalink }}">Read more >> </a>

{{ end}}

Here we are using the template variable {{ .Summary }} to display the summary of the post. Also, we are displaying the published date and providing a link to the post if the content is truncated. The flag Truncated would be true if there are more than 70 words in the post or a  tag is inserted. Any template defined in 'layouts/_default' will be used as a default template to render the content. You can always define a different layout by creating a directory with its name matching the directory name in the content directory.

On content organisation:

Hugo organises the generated content in the same way as it's defined. However, you can override it by updating some of the fields in the front matter of the post. You can specify additional fields - 'slug', 'type', 'path' and 'url' to override the default.

For example, if you have written a couple of posts at 'posts/blog-post-1.md' and 'posts/blog-post-2.md', Hugo will generate the content in public directory at 'posts/blog-post-1/index.html' and 'posts/blog-post-2/index.html'. If you would like to rename 'blog-post-1' and 'blog-post-2' to something else specify the 'slug' field in the front matter:

+++

date = "2016-12-05T20:08:38+05:30"

draft = true

title = "blog post 2"

slug = "first-post"



+++

This post now can be accessed at '<site>/posts/first-post'.

You can also specify the 'url' field in the front matter and this will render the page at the given 'url'. For example, if you have top level pages defined under pages directory - 'pages/about-us' and 'pages/contact-us' and want to render them at the top level i.e. at '/about-us' and '/contact-us':


+++

date = "2016-12-05T20:08:38+05:30"

draft = true

title = "about us"

url = "/about-us"



+++

If both slug and url are specified then, url would take precedence. The url field in the front matter would take precedence over any other field.

As mentioned earlier, you can specify the type field in the front matter to override the default type assigned to the post. Consider you are writing a series of post on a particular topic and you have created a directory 'series-topic' under 'posts'. Here you can add the field 'type' in the front matter and provide a value say 'posts-series'. Using this type information you can easily get to the set of posts and display content as necessary.

Example source code can be found here - https://github.com/sagar-ganatra/hugo_example

On Static Site Generator - Hugo

2016-12-04T23:28:00.001+05:30

Over the last few weeks, I've been looking into a Static Site Generator - Hugo. A Static Site Generator is useful if you're building an application which does not require dynamic data to be served. A blog can be considered as a service which serves static content. Instead of storing the content in a database field, the content is stored in a file (HTML file). Thus when a page is requested the content is served immediately instead of it being generated on demand; resulting in accelerated response times and thus better user experience.

Hugo helps in generating a static site. It has got several features such as defining layouts for various types of content, displaying a list of related content, tagging content (taxonomies), using themes and also generating content from data in JSON, YAML or TOML files.

Hugo provides a Command Line Interface to generate content. After installing Hugo (brew install hugo), create a new site using the command

hugo new site hugo_bootstrap_example

Hugo creates a directory structure as detailed below:


--archtypes

--content

--data

--layouts

--static

--themes

All content should be present in the 'content' directory. If you are considering to build a blog, then this directory would contain all the blog posts. To create a new post use the command:

hugo new posts/blog-post-1.md

This will create a markdown file blog-post-1.md under 'content/posts' directory. The directory 'posts' is created if it doesn't exist. When you open the file, you'll notice that it contains some meta-data in it, it's called front matter. By default the front matter contains 'date' and 'title', here date being the created date and title being the file name:


+++

date = "2016-12-04T16:13:35+05:30"

title = "blog post 1"



+++

The front matter is enclosed in +++, any text that follows after the last '+++' will constitute the content or the body of the post. Hugo organises the output in the same way as it is declared i.e. to view the post you can access the URL <site>/post/blog-post-1. This can be changed by updating the front matter to include section, path and slug fields (more on this in the next post).

On Layouts:

Once you have defined the type of content that you want to render, you need to define how this content will be rendered. For example, if you have created two different types of content - 'posts' and 'pages' then you need to define views for 'posts' and 'pages' in the 'layouts' directory. This is required because Hugo does not know how to render the content. It took me some time to understand how Hugo does this; it looks up for templates defined in the layout directory and generates static files based on the number of files present in the 'content' directory. This also means that if you have defined content but the corresponding layout is missing, then no static file is generated for that type of content.

Note: If you would like to use the same layout for all types of content, then create a directory '_default' under layouts and then define the view templates under it.

Let's create a template for 'posts':


--layouts

  --posts

    --single.html

Here single.html is a template file, that defines how the post would look like when the user accesses the URL <site>/posts/blog-post-1. In addition to displaying the title and the content of the post, you can display the date on which the post was published:


<!DOCTYPE html>

<html>

<head>

  <title>{{ .Title }}</title>

</head>

<body>

  <h1>

    <a href="{{ .Permalink }}">

      {{ .Title }}

    </a>

  </h1>

  {{ .Content }}

  <h6>Published on: {{ .Date.Format "Mon 2, Jan 2016" }}</h6>

</body>

</html>

Hugo uses GO templates to generate the content. In the above example, 'Title', 'Permalink', 'Content' and 'Date' are template variables, which are used to generate static files based on the front matter and the content defined in the file 'blog-post-1.md'.

In addition to defining single post view, you can also define a list view (li.html) - a view to display a list of content posts instead of one single post and a summary view (summary.html) - to view only a part of the content.

Rendering the site using Hugo server:

Before we get to rendering the content on the browser, Hugo requires some configuration to display the content. This configuration contains site information such as the 'baseUrl', 'title', 'languageCode' and 'theme'. When you generate the site, you'll have the file 'config.toml' created, which contains the above configuration fields. All that is required is to provide the values for the above fields. Here's the example 'config.toml' file content:


baseurl = "localhost:1313"

title = "My New Hugo Site"

languageCode = "en-us"

theme = "ex_bootstrap_theme"

Hugo comes with a built-in web server and you can start it using the command:

hugo server

It starts the server at port 1313 and you can try the URL localhost:1313. This command will generate the static content and will watch for the file changes in directories generated by the hugo new site command.

On Themes:

A Theme, like Layouts, is used to define templates. There's not much difference between a theme and a layout, except that a theme should be created if you want to reuse it for a different site. This will enable you to encapsulate the look and feel of the site along with behaviour (JavaScript) and share it with others who can then follow the same convention to build the site.

I'm inclined towards using a theme over layouts only for the sole reason that it can be shared with other users.

Hugo does not ship with a default theme, however, a theme is required to run the server. You can download one of the many themes available at http://themes.gohugo.io/ or create your own theme using the command:

hugo new theme <theme_name>

Summary:

I really liked Hugo and I'm getting used to GO templates. There are tonnes of options available to customise the site and I'm still exploring these options. The biggest selling point is it's performance when generating static content. I haven't tested the site containing several pages, but it takes say about 12ms to generate a very small site with 4 pages in it, which is extremely fast.

Hugo does not dictate how your site should be styled, however, it provides a directory 'static' where all your CSS, Images and JavaScript files should be placed.

Learning ES6 - Arrow functions and the visibility of this and arguments scope in it

2016-02-17T20:01:00.001+05:30

Last week I looked at the use of let and const keywords in ES6. This week I have been looking at Arrow function expressions, which enable you to create functions without using the function keyword. They provide a shorter syntax to represent a function. I assumed that arrow functions only provide syntax sugar and all function expressions can be replaced with the new syntax. However, the scopes - this and arguments refers to the enclosing scope and not that of the caller.

Shorter syntax:

Functions with only a return statement can now be represented using a shorter syntax:

[1, 2, 3].map(x => x*x) (() => [1, 4, 9])()

In the first example, the arrow function expression takes only one parameter (x) and returns the square of that parameter. Notice that the expression does not have parentheses and does not use function brackets({}) or the return statement. To represent the expression 'x => x*x' in ES5, you would write:

function (x) { return x*x; }

In the next example, the arrow function expression does not take any parameters and thus you will need to specify empty parentheses followed by the fat arrow (=>)

In a case where more than one parameter is present then it is mandatory to use parentheses:

((x, y) => x + y)(3, 4)

In a case where the return value is represented using the object literal notation then the return value will have to be wrapped in a set of parentheses:

((x, y) => ({x, y}))(1, 2)

Notice that the return object is represented as {x, y} instead of {x: x, y: y}. This is another addition to language; here {x, y} translates to {x: x, y: y}. It is mandatory to specify parentheses because the object literal notation would be considered as start of the function body with the use of '{' and that would result in a syntax error.

Default value for parameters:

Arrow function expressions and functions now allow you to specify default values to the parameters:

((x=1, y=2) => x + y)(10); ((x=1, y=2) => x + y)(undefined, 10);

The default value for the second parameter - 'y' is 2 and when the function is invoked without specifying the second parameter then the default value is assigned to the parameter. In a case where the value for the first parameter is unknown then one has to specify 'undefined' when invoking the function.

The rest parameter allows you to design functions with variable parameters. Here's the signature of the function:

((x, y, ...rest) => rest.length)(1, 2, 3, 4, 5);

The '...<param_name>' notation is used to capture extra arguments passed to the function. Notice that it's different from the arguments scope; the rest parameter stores the remaining parameters whereas arguments scope would refer to all the parameters passed to the function.

this and arguments scope inside arrow function expression:

Although, it may appear that every function expression can now be replaced with an arrow function expression, be careful when you use this, arguments and super in it. Instead of referring to the caller, scopes - this and arguments would refer to the enclosing function scope.

Consider this example:

Using the function expression you would notice that this scope is available. However, inside the body of an arrow function this scope is undefined and thus would result in an error. An arrow function refers to enclosing function's this and arguments scope:

function Foo(x, y) { this.a = 1; setTimeout((x, y) => { console.log(this.a); //referrence to this is available. console.log(arguments); //prints 10, 11 })(5, 6); }; var bar = new Foo(10, 11);

I would use arrow function expressions in callback functions where reference to this scope is to be obtained from it's enclosing function scope. In may scenarios I would have written var self = this; and use self to refer to this scope inside the callback function. This was a hack and now it's no longer required.

Learning ES6 - using let, const and Temporal Dead Zone

2016-02-11T19:21:00.001+05:30

I've finally started to learn EcmaScript 6 (ES2015) and thought it would be good to start writing about it as I learn. There are a bunch of features in ES6 and a good place to start would be to learn the use of let and const. I haven't deep dived into all the features yet, but I eventually will. This post is about the use of let and const keywords to create variables. I'm a big fan var scope, but I think I'm going to abdicate var scoped variables in favor of let and const.

The primary difference between var and let scoped variables is it's visibility. A var scoped variable is visible throughout the function where as let scoped variable is visible only inside the block in which it is declared. Thinking about block scope now, I realize that many times I write if statements and declare variables as required. With var scope, the variable would be visible throughout the function where as with let scope, the visibility is limited to the block in which it's declared:

A let scoped variable is visible in the block in which it's declared and also in child blocks, unless the same named variable is declared in the child block as well. In this example, the variable 'a' (with value 10) is visible throughout the function but not inside function test. Inside function test, a variable with the same name is let scoped, thus overriding the visibility of variable 'a' at the parent function level. Notice that the let scoped variables are visible only in the block in which they are declared. The variables declared in the inner blocks will cease to exist once the execution crosses the block.

On Temporal Dead Zone (TDZ):

Variables declared with var scope are hoisted and return undefined when one tries to access it before it's definition. In case of let scoped variables, a ReferenceError is thrown. Although, this infers that the let scoped variables are not hoisted but they are indeed hoisted. See the note here: https://people.mozilla.org/~jorendorff/es6-draft.html#sec-let-and-const-declarations.

It mentions that:

"The variables are created when their containing Lexical Environment is instantiated but may not be accessed in any way until the variable’s LexicalBinding is evaluated."

From the above statement, a let scoped variable is instantiated meaning that the variable is hoisted but it's not available until a value is assigned to it. Another example, would be:

let a = b, b = 1;

Again a ReferenceError is thrown mentioning that 'b is not defined'. The Temporal Dead Zone starts when the block containing the let scoped variable is encountered and it ends when the definition of the variable is found. In TDZ, the variables would throw a ReferenceError even if the same variable is present in it's enclosing block i.e. the parent block.

On const:

A const scoped variable is similar to a let scoped variable except that it mandates a value to be assigned to it. Any attempt made to change the value of the variable would result in an error. For example, when you use a const variable in a for loop, an error is thrown when you try to increment the value:

for (const i=0; i < 3; i++) { console.log(i); }

One of the pitfalls I have observed with const scoped variables is that the value that it is bound to is not a constant:

const a = {x: 1}; a.y = 2; //valid const b = [1, 2, 3]; b.push(4); //valid

I'm not sure whether this is the right thing for constants. Although, one can make it non-writeable by using Object.freeze.

Going forward, I would use const for constant variables and for functions which are var scoped by default. Also, let seems to be a good choice over var for scoping variables.

On choosing Material Design for Angular over UI Bootstrap

2015-07-01T17:57:00.000+05:30

There are many UI frameworks out there - Bootstrap, Foundation, Semantic UI etc. I have used Bootstrap in the past, however I'm very much inclined towards using Material Design for Angular. There are many good reasons to use Material Design over Bootstrap or any other framework that you might consider.

When I say Material Design, I'm referring to Material Design for Angular - https://material.angularjs.org/. I have been using Angular in my applications and I've made that as a defacto framework to use for any front-end work I get. I don't consider any library to use in my project unless it also has an Angular implementation. Material Design for Angular and UI bootstrap, both are such libraries. So why choose Material Design over Bootstrap? I did search for this and couldn't see the comparison in terms of pros and cons or why one framework is more suited over the other. Thus, I'm jotting down my thoughts on why Material Design wins over Bootstrap.

User Experience:

Material Design delivers the wow effect; the click of a button, or selecting a checkbox, entering form details and everything else in the specification delivers great user experience. Bootstrap on the other hand is good if you are building very simple applications that look like they are made only to deliver the functionality and great user experience is not of high priority.

FlexBox:

CSS3 introduced FlexBox, which allows you to create layouts with ease. Even if I'm not inclined towards great user experience, I would chose Material Design for this feature only. Bootstrap uses floats for its grid system. I hate floats; floats were designed to wrap text around images. Floats come with a clear fix and adding more mark up or CSS for clear fix is like carrying extra luggage. Using display: inline-block is another alternative, but it expects you to write the markup in a certain way or add margin-left: -4px.

FlexBox should be used instead of floats or inline-blocks. I can't imagine writing my applications using anything other than FlexBox.

Syntax:

Material design provides several directives for managing layout, creating drop downs, form fields etc. The syntax used here is more semantic. Consider this code snippet:

<div layout="row"
     layout-align="center center">

   <div flex>
   <div flex>
   <div flex>
 
</div>

The above code snippet declares that you are creating a row and it has three elements with attribute 'flex' added to it. This will create a three column equal width layout. Please note, there's no extra CSS or class added to this. The markup is clean and who doesn't like clean markup.

In case of Bootstrap one will have to add classes to build the layout, I wouldn't like to copy the code and paste it, you can see it for yourself here - http://getbootstrap.com/css/#grid

Responsive:

Whilst both Material Design and Bootstrap provide you the ways to create responsive layouts, I prefer using Material Design. You only have to add certain attributes to the markup to change how it looks on different devices. For instance the above row based layout can be converted to a column based layout for a mobile device by adding layout-sm attribute:

<div layout="row"
     layout-align="center center"
     layout-sm="column">
 
</div>

Bootstrap uses classes instead.

Many would rather complain saying that Bootstrap is widely used and Material Design is not. That's true, because Material Design is new and you can't expect every Bootstrap website to be converted to Material Design in no time. The other reason that I've heard on not using Material Design is that one will have to learn it before becoming productive and it involves a big learning curve. I'm of the opinion that this is not true, it didn't even take me a day to get started with Material Design. Also, if you take a look at the syntax it's almost the same except that you would use directives instead of classes in Material Design.

When choosing a technology or a framework, there's no right or wrong. There are opinions and perspectives. As a developer you should have the freedom to chose what you like. However, I would advise that don't be afraid to try out something new. Don't constraint yourself to one library; it's always fun and a good learning experience when trying out different libraries.

Improvising Angular + Require template

2015-05-28T16:02:00.000+05:30

Sometime back I wrote a post on using Angular and Require to create a project template. The idea was to make the application more modular and broken down into multiple components that can be easily reused. I have made some more modifications to the template, especially the naming conventions used for files and minor changes to the structure of the project.

Here's the snapshot of the directory structure:

/components
   /login
      login.directive.js
      login.html
      login.module.js
      login.scss

/domain
      domain.module.js
      Players.js
      User.js

/services
      backendUrlsProvider.js
      common-services.module.js

The major change has been moving the stylesheets (scss files) for the various components inside the components directory and create <component>.module.js file inside the same directory. I have removed the modules directory which listed all the module files for the application. This change enables reusing the component by copying one single directory instead of copying multiple directories (scripts and styles).

The next change was to create a module for the models listed under domain directory. These models were associated with components but that didn't encourage reusability. By having one domain module that lists all domain services, it can be used across the application. Also, the idea is to have components being agnostic of the services. The components are responsible for rendering the views and they delegate the responsibility of calling a service to the parent controllers which are listed under pages directory (see previous post).

The services directory would contain a set of common services that can be used by components or services. I have added backendUrlsProvider.js file which is a constant service, providing a map between the service and the corresponding URLs:

return {
    login: '/user/login',
    register: '/user/register',
    players: '/players'
};

If there's a change in the URL then it would be updated here and no changes would be required to be made in the services files.

A new addition to the template is the use of the Gulp to generate the build. The build generation steps include: cleaning the dist directory, running jshint, compiling and minifying stylesheets, annotating Angular files using @ngInject, minifying HTML files, minifying JavaScript files using r.js optimizer, adding a new revision, using html-replace to inject JavaScript files and CSS stylesheets, removing mock modules reference when a Production build is generated.

Take a look at the code on Github: https://github.com/sagar-ganatra/angular-require-template

Angular + Require project template

2015-03-24T18:44:00.003+05:30

I've been working on an Angular project for good number months. There's a lot that I've learned and I've realized that the code I wrote could have been structured in a better way. I wanted to write this post sometime back, however I thought it would be better to create an application structure first and then post my learnings. I have posted all the code on github here - https://github.com/sagar-ganatra/angular-require-template. The template is still a work in progress, however the basic structure of the template is in place.

Motivation:
I always visualized a web page broken down into multiple components that are completely decoupled and components that can be reused. For example, a component or a widget that displays a chart does not have to know about the navbar in the page. It would however provide an interface through which external components would interact or change the state of it.

Why RequireJS?
In my Angular application's index.html file, I had included various script blocks that looked like this:

<script src="../bower_components/jquery/jquery.js"></script>
<script src="../bower_components/angular/angular.js"></script>
<script src="../bower_components/angular-bootstrap/ui-bootstrap-tpls.js"></script>
<script src="../bower_components/angular-cookies/angular-cookies.js"></script>
<script src="../bower_components/angular-route/angular-route.js"></script>

Here the script tags are included in such a way that the dependent files come first and then the others are listed. Every time I added a new script file in the project, I had to update the index.html file and ensure that the dependencies are always included first. Instead, I could use a RequireJS shim to declare the dependencies:

shim: {
    angular: {
        deps: ['jquery'],
        exports: 'angular'
    },
        
    angularMocks: {
        deps: ['angular']  
    },
        
    angularCookies: {
        deps: ['angular']
    },
        
    uirouter: {
        deps: ['angular']
    }
}

This is more declarative and less prone to errors.

This is not the only reason I would use RequireJS in my project, one of the other factors and the most important one is to provide structure to the application. I want my components to be independent or individual widgets that can be reused. When creating components I would make use of the directive interface which can then be included anywhere in the project. For example, the interface for a navbar could look like:

<navbar title="{{title}}"></navbar>

Here the navbar element has the title attribute which would then become a scope variable for the navbar directive. Essentially everything on the page would be a collection of directives which would then be compiled and the resultant HTML markup would be injected into the DOM:

Here the directive serves as a gateway to the service that we are trying to add to the application. A directive is an individual widget which is not aware of other directives used in the page and it's service agnostic. Here in our example, the playersList directive would consume list of players and perform some action when a player is selected. The directive would provide an interface and the page that wants to use the directive can then provide the data:

<div players-list
     players="players"
     on-player-select="showPlayerStats(playerId)"
     selected-player="selectedPlayerId">
</div>

Here the values provided to various attributes are defined in the controller scope. In this way, the directive remains agnostic of the data or the service that it should talk to.

In my project template, I've create a module for each directive. In this example, we would have two modules - navbarModule, playersStatsModule. I would include playersList and playerDetails directive into one single module because they serve as one entity. However, they are completely decoupled and don't interact with each other directly. The idea is to create modules that represent one single entity, which in this case is playerStats. The module definition would look like this:

define([
    'angular',
    'components/playerStats/directives/playersListDirective',
    'components/playerStats/directives/playersDetailDirective',
    'domain/Players'
],  function(ng, playersListDirective, playersDetailDirective, Players) {
        'use strict';
        
        return ng.module('playerStatsModule', [])
                 .directive('playersList', playersListDirective)
                 .directive('playersDetail', playersDetailDirective) 
                 .service('Players', Players);
                 
    }
);

Notice that there's one file playerStatsModule.js which declares dependency on the directives and the service. Also, the name is to the directive here in the module definition. This approach is the flip side of the approach that is generally followed when defining directives. Generally one would create a module first and then use the module reference in their directive definition; but the approach that I mentioned above makes the code more cleaner. Here's how the definition of the playersList directive would look like:

define(function() {
    'use strict';
    
    return function () {
        return {
            restrict: 'AE',
            templateUrl: './components/playerStats/partials/playersList.html',
            scope: {
                onPlayerSelect: '&',
                players: '=',
                selectedPlayer: '='
            }
        };
    };
});

It returns a function and then in the module a name is assigned to the directive.

Application structure:

/app

  - app.js

  - main.js

  - bootstrap.js

  - index.html
  /components
      /auth
      /login
      /navbar
      /playerStats
           /directives
                - playersDetailsDirective.js
                - playersListDirective.js
           /partials
                - playersDetails.html
                - playersList.html
  /domain
       -  Players.js
       -  User.js
  /modules
        - authModule.js
        - loginModule.js
        - navbarModule.js
        - pagesModule.js
        - playerStatsModule.js
  /pages
      /home
          /controllers
               - playersListController.js
               - playersStatsController.js
          /partials
               - playersList.html
               - playersStats.html
      /login

Notice that the services responsible for sending requests to the server are listed under domain. The pages directory lists various pages in the application and the partials listed under each page contain references to these components. In this way, pages handle the application logic (events, querying the service, etc) and individual component directives handle rendering logic.

In app.js, a module for the application is created. This module will declare dependency on various other modules in the source code in addition to third party modules:

define([
    'angular',
    /*mock module*/
    'mockModule',
    'mockServices',
    /* user defined modules */
    'modules/authModule',
    'modules/loginModule',
    'modules/navbarModule',
    'modules/playerStatsModule',
    /* pages module */
    'modules/pagesModule',
    /* include vendor dependencies here */
    'angularCookies',
    'angularMessages',
    'uirouter',
    'lumx',
], function (ng) {
    'use strict';
    
    var app = ng.module('playersApp', [
        'ngCookies',
        'ui.router',
        'lumx',
        'mockModule',
        'authModule',
        'loginModule',
        'navbarModule',
        'playerStatsModule',
        'pagesModule'
    ]);
});

The main.js file declares the shim configuration (mentioned before) and bootstrap.js would bootstrap the application by calling angular.bootstrap on the document object.

Other Goodies:

I'm taking help from lumx to implement Material design, Angular UI router to define states/routes in the application, Angular Mocks to mock services and Gulp for build.

Pending:

Unit testing using Jasmine and Karma.
Structure styles (CSS/SCSS).
Refine Gulp build system.
CI/travis.yaml

You can clone the repository and see how the application is structured and how it is currently styled.

Lazy loading AngularJS components using Providers

2014-08-19T15:36:00.000+05:30

I've been working on an Angular project for sometime now and I usually run across issues when building the application. In most of the example applications that I've seen, all application script files are loaded upfront i.e. all JavaScript files are loaded when the user accesses application. I get annoyed by this approach; why should all the components be loaded upfront when the probability of user accessing the entire application is very less. How does one architect a multi-page application using Angular? What would be the size of the application after minifying all the JavaScript files. Most importantly how does one load the components lazily. I've used RequireJS in my previous projects and it allows you to load components on demand; the idea is to load components based on the selected route. I've tried a similar approach with Angular using 'resolve' property in the $routeProvider.

The 'resolve' property in Angular can be used to resolve services but essentially it's a promise object that gets resolved. In my previous post, I've explained how the resolve property is used to invoke a route only after resolving a $http service. Similarly, you can load the controller and service components (JavaScript files) before invoking the route. In this example, I've used RequireJS to load the controller and service components:

In the above code snippet, files 'components/login/controllers/loginController' and 'components/login/services/loginService' are loaded using RequireJS. Once these files are loaded, the $rootScope.$apply function is called and the promise object is resolved in the callback handler. Although this seemed like a direct approach to resolving dependencies, Angular throws an error when you access the route. It throws 'function got undefined' error. The reason to this is, when Angular initializes or bootstraps the application, functions - controller, service etc,. are available on the module instance. Here, we are lazy loading the components and the functions are not available at a later point; therefore we must use the various provider functions and register these components. The providers are available only in the config method and hence we will have to store a reference of these providers in the config function when the application is initialized:

Here a reference to the $controllerProvider.register and $provide.service are stored in the 'app.components' object. Now when you create components, these reference variables should be used. For example, to create a 'loginController' component, the function signature would be:

app.components.controller('loginController');

At run-time the components are registered by Angular using the various provider services. Next step in refining this example is to use modules in r.js (RequireJS optimizer) to create single JavaScript files that define all the dependencies for the page.

Take a look at this git repo which contains two pages and components are loaded on demand - https://github.com/sagar-ganatra/angular-require-resolve/

AngularJS - Resolving data services before instantiating the Controller and Template

2014-06-30T18:19:00.000+05:30

I have been working on an Angular application for sometime now and I have started to like this approach to client-side development. It's a different approach when compared to developing applications using Backbone and Require. I was looking at routing in Angular and came across the 'resolve' property which can be used to resolve services before instantiating the Controller and it's corresponding template i.e. the domain models that are required for the View components are resolved first.

Look at a scenario where you are using a Search service to get a collection of objects that contain the search string. You can specify the route which will display the search results. When only the template and controller properties are specified, both are instantiated and the ng-view is updated with the specified template. The controller would specify dependency on the SearchService,use this service to query the back-end and then update one of the $scope variables with the response data.

While the SearchService is fetching results, you would see that the template being displayed inside the ng-view container with template variables and the same getting updated when the service returns data. This is not ideal; the search results should be available before you load the controller; and the template should display data instead of showing template variables. The 'resolve' property in the $routeProvider mentions a set of promises that should be resolved before instantiating the controller and the template. Only when all the promises are resolved, the controller and the template are instantiated. Also the promise reference is injected into the controller as a dependency. Using this promise one can directly update the values in the template instead of sending a request to the Search service.

Here's the code for the routeProvider :

Here the route '/search/:searchString', specifies the 'resolve' object which includes a promise - 'searchResults'. It queries the searchService and returns a promise. When the service is resolved the Controller - 'searchController' and the template - 'partials/search.html' are instantiated. The Controller gets the promise object:

Notice that the promise - 'searchResults' is injected into the Controller and it contains the response data. This can then be used to render the template.

My second book - 'Kendo UI Cookbook' released!!

2014-06-29T12:36:00.000+05:30

The title says it all. My second book titled 'Kendo UI Cookbook' was released last week. I have written over 50 recipes focusing on the Kendo UI application framework, widgets and data visualization components.

Here's the link from where you can buy the book - http://www.packtpub.com/kendo-ui-cookbook/book

On using PageJS as a Router and handling page refresh with pushState enabled

2014-04-29T16:11:00.000+05:30

I have been looking at PageJS as a Routing solution for my Backbone applications. PageJS allows you to specify multiple callback functions for a particular route and creates a context object based on the current state of the application. The context object contains valuable information that can be used in constructing View components and in triggering business work flows.

Let's consider a simple application that lists Customers and Orders; also the application provides a functionality to search for customers based on the given ID. In this example application, there would be three routes - orders, customers and search. Using PageJS you can specify the routes using the page function:

Here, page.base is used to set the base path. This is required if your application is in a particular directory under the web root. The other set of lines define the various routes in the application. The first argument is the path mapping and it is followed by callback functions that should be triggered when the route is encountered. In my application, I would like to load the page first which includes loading several View components, triggering an Ajax request to get data from a RESTful service etc. Once this is complete, I would like components on the page to get a notification about the page change. The path mapping '*' is executed when none of the above routes match. This is useful if you want to redirect the user to an error document or a 404 page. Let's see the callback functions:

Notice that the first function 'loadPage' takes two arguments; the context object 'ctx' and the next callback function 'next'. The loadPage function then tries to load the corresponding page assets by calling a function loadPage on the PageManager module. The last line calls the function next; this would ask PageJS to trigger the next callback function. In this example the function 'triggerPageChangeEvent' is called.

The loadPage function uses the information available in the context (ctx) object to make decision on which page to load. The context object contains the following fields:

- canonicalPath: "/backbone-router/search"
- hash: ""
- params: Array[0]
- path: "/search"
- pathname: "/backbone-router/search"
- querystring: ""
- state: Object
- path: "/backbone-router/search"
- title: "Backbone Router example"

A Context object is constructed at runtime when you navigate to a particular route. The state object is the pushState object and is available to the user to store application state variables. For example, if the user has searched for a Customer with ID 100, we can add this to the context's state:

context.state.selectedCustomer = this.model.toJSON();
context.save();

The save function will save the state of the application. If you look at the implementation in PageJS it uses replaceState function on the history object to save the state:

Context.prototype.save = function(){
history.replaceState(this.state, this.title, this.canonicalPath);
};

When the user clicks on the back or forward button, the Context's state would be available. An Internal function in PageJS - onpopstate is called in this case. However, when the user explicitly triggers the page change by clicking on the link then a new Context object is created.

When working on this application I ran into a problem, wherein on clicking on the refresh button the application would not load. For example, if your URL reads '/backbone-router/customers' and you click the refresh button, the application would not load, which is a correct behavior. The web server would not be able to find the directory 'customers' under 'backbone-router' and the default error document would be shown. This can be handled by redirecting the user to the parent directory i.e. '/backbone-router' and loading the application. I use Apache web server and I can include a '.htaccess' file in the same directory and specify the redirection rules:

<ifModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !index
RewriteRule (.*) index.html [L]
</ifModule>

The above redirection rule instructs the web server to redirect the user to index.html page if the file or the directory is not found. Now when you click on the refresh button, the index.html file would be loaded and the Context object would have the path field set to 'customers'. This will then load the required page.

RequireJS - Busting the browser cache with every deployment using Grunt targethtml plugin

2014-02-12T12:51:00.000+05:30

The projects that I work on have deployments to the QA very often; testing out the bug fixes and new features. Every time after the deployment, I ask the QA to clear the cache, since all JavaScript files are cached by the browser. This is really frustrating to QA and I needed someway to clear the cache with every deployment. This would be same in a continuous delivery project, wherein the client would be required to clear the browser cache.

I use RequireJS to bind the dependencies between various modules. Also, I use Grunt to manage the deployment workflow. The JavaScript code is optimized using RequireJS optimizer, which minifies and combines all the dependencies.

I referred to the RequireJS documentation and found that one can use 'urlArgs' property to bust the browser cache. If you refer to that example code, it uses the JavaScript Date object and assigns the time-stamp value to the urlArgs parameter. This works fine if you never want the Require modules to be cached by the browser. However, in a workflow where you would like these files to cleared from the cache only when there is a deployment then you can use a Grunt plugin - grunt-targethtml.

The target-html plugin parses the source html file and generates the content accordingly. In your source html file, you need to specify target tags that will be processed when Grunt is run:

Here, the target html code that will be processed by the Grunt plugin is included in a comment. It has an 'If statement' which declares that if the grunt build is being run with 'dist' as an option then include the below code. Notice that the script block also specifies a template variable - 'bustVersion'. When the html content is being generated this would be treated as string that needs to be replaced with a value.

In your target html configuration (in Gruntfile.js) you need to provide the value that will be assigned to this variable:

Here, the 'curlyTags' configuration includes a template string 'bustVersion' whose value is a scriptlet '<%= grunt.template.today("yyyymmdd") %>'. Also, the files configuration includes the mapping between the destination file and the source file. Here 'dist/index.html' is the destination file and 'dev/index.html' is the source file that will be processed.

When 'grunt dist' is run, the template string {{bustVersion}} is replaced with today's date (in 'yyyymmdd' format). The destination file will now have script tag specifying the RequireJS configuration - 'urlArgs' with the date generated using the scriptlet.

More on MVVM with Backbone Stickit plugin

2014-01-23T18:27:00.000+05:30

In my last post, I mentioned about two way binding a.k.a MVVM in Backbone using Backbone.Stickit plugin. The Stickit plugin does provide awesome two way binding, but in addition it includes several features that are very much apt when modifying state of model or the view. I've been using these features in my project regularly.

The bindings configuration is used to specify the binding between the view and model. When you specify this configuration, the model changes are observed and view is updated whenever there is a change and similarly any changes in the view would update the model. There are many scenarios where in the format of the model or view has to be changed. For example, the model stores a date in a specific format and the view has to display the same in a different format. The Stickit plugin provides methods - onGet and onSet which can be used in such scenarios:

Here, instead of providing a one to one mapping between the view element and the model attribute, an object containing the binding configuration is specified. The configuration has three attributes - observe, onGet and onSet. The 'observe' attribute specifies the model attribute that the view element should be mapped to. Before the view element is updated, the 'onGet' function is called, here the function formats the date value present in the model and the view is updated with the formatted value. Now when you change the date in the view, the 'onSet' method is invoked before updating the model. The 'onSet' method, formats the input date and updates the model. These two methods intercept the update of view and model; helping you to format data correctly.

The other feature that I use regularly when working with authorization piece is the use of 'visible' and 'visibleFn'. In a scenario where, based on the logged in user's credentials some part of the page would be hidden or shown to the user; this feature comes very handy.

Here the function assigned to 'visible' attribute is executed to check whether the logged in user is an 'admin'. It returns a boolean value and based on the whether it is true or false, the view element would be shown or hidden. The 'visibleFn' is optional, by default if 'visible' is true then the view element would have the style attribute 'display' set to 'block' and if false, the element would have 'display' property set to 'none'. If you want change the 'display' property from 'block' to say 'inline-block' or if you want perform an animation before hiding the element, then the 'visibleFn' should be specified.

Another feature that I have used in my projects is the use of 'selectOptions'. This feature is used to populate a 'select' element in the form with 'option' tags using a collection of objects.

Here 'selectOptions' specifies the collection attribute which contains an array of objects, each object with properties 'timeZoneName' and 'timeZoneId'. These properties are assigned to 'labelPath' and 'valuePath' attributes. When 'option' tags are generated, the label name and value of the option tag would be referencing these properties. The 'defaultOption' configuration is used to either specify the default value or define a placeholder for the select element. When you select an element from the 'select' drop down, the model attribute 'timezone' would be updated.

There are several other features in the Stickit plugin, like adding custom handlers, selectively updating the model or view - http://nytimes.github.io/backbone.stickit/

MVVM in BackboneJS using Backbone.Stickit

2013-11-11T18:17:00.000+05:30

I have been looking into various design patterns and trying to architect client side applications using it. More often than not the MVC pattern fits the requirement in most of the applications. However, I have found myself using MVVM (Model View - View Model) pattern along with MVC. I use MVVM pattern particularly when I have to maintain the state of the model on the client side. AngularJS provides great support by allowing you to extend the markup and tying the model right within the view (the markup). It also provides components that can be used to structure the application the MVC way and hence it's appropriately termed as MVW or MV* framework. However, I use BackboneJS in most of my applications and I have been able to maintain the state of the model using the Backbone.Stickit plugin.

When working with Backbone applications, the View's sole responsibility would be to render the model data and also re-render the parts of the view when the state of the model changes. The View listens to the model changes and executes a callback function when the state of the model has changed:

Here in the Backbone View's initialize method, the View is listening to the change in one the model's attribute and it executes the 'updateView' method whenever the 'modelAttribute' is updated. The 'updateView' function then refers to one of the nodes in the View and updates it with the value in 'modelAttribute'. This pattern can be repeated for various attributes in the model and the view can have several functions whose only responsibility is to update a DOM node in the View.

Similarly, when the user inputs data in form elements the same should be reflected in the model. To do that the View will have to declare event handlers:

This has to be repeated for other View elements and developer will be required to write boilerplate code. An alternative to this is to use a Backbone plugin called 'Stickit'. Backbone.Stickit abstracts the above functionality and provides a more cleaner way to bind the View's elements to the model's attributes. In a Backbone View you can define the binding between the model's attributes with the elements in the markup using the 'bindings' object:

Here in the bindings object, the keys are the View elements and the attributes in the model are specified as values. For example, the view element '.js-full-name' is bound to the model attribute 'fullName'. The bindings object provides a two way binding between the View elements and Model attributes. This means that whenever the user inputs some value in the form elements the Model attributes are updated and whenever the Model attribute is updated by some part of the application or by a service call the View elements are updated.

Once the View has compiled the client-side template and rendered it, the View elements should be bound to the Model's attributes. To do that invoke the stickit method on the view object (view.stickit()). I generally use the postRender method and invoke it after the render method has been executed. As the name suggests, the postRender method would execute a set of actions after rendering the template. In this case, call stickit on the view object - this.stickit(); where this refers to the current view.

The Stickit plugin provides several options to configure the bindings. I'll explain those in my next post.

Win a Free e-Book copy of my book - 'Instant Kendo UI Mobile'

2013-10-04T19:26:00.001+05:30

I'm giving away two copies of my book 'Instant Kendo UI Mobile'. All you need to do is to send me a message through the 'Contact Me' form, let me know how this book will benefit you and whether you can post a review as well. You can also message me on Twitter or Facebook.

You can find out about the book here - http://www.packtpub.com/kendo-user-interface-mobile/book

My first book titled 'Kendo UI Mobile' is here!!

2013-07-29T20:15:00.000+05:30

The title says it all. I had posted a couple of entries on Kendo UI earlier and was approached by Packt publishing to write on 'Kendo UI Mobile'. Writing a book was both a personal and a professional goal that I had set for myself. Today I have realized it and I feel accomplished. For almost everyone, first things are very special. Be it their first job, paycheck, girlfriend\boyfriend, marriage, first kid and anything that happens for the first time in their life. This is my baby and I'm going to celebrate my win today.

If you are planning to build a mobile website or an app using Kendo UI Mobile, this book should get you up and running. Here's the link to the page, from where you can learn about the book and buy it - http://www.packtpub.com/kendo-user-interface-mobile/book

Backbone Collections do not emit 'reset' event after fetch

2013-06-25T15:18:00.000+05:30

I recently upgraded my Backbone application to the 1.0 version of the library. When I ran the application, the Backbone View was not rendering anything on the browser screen. I noticed the XHR request being sent in the Network tab of Chrome Dev Tools. This meant that the Collection was fetching the data from the server. However, the 'render' function defined in Backbone View was not being called, which was attached as a callback handler for the 'reset' event on the Collection.

Here's the sample code:

I had a quick look at the Backbone documentation and came across the section 'Upgrading to 1.0'. The very first point there mentions that the 'reset' event is not triggered by default when the Collection is populated with data. One has to pass the key - 'reset' with value true when making a fetch call on the Collection. Now I had to update the code at places where the fetch call was being made. However, this can be avoided by making changes in the Collection. There are two ways of doing this: overriding the fetch method and resetting the collection in parse method. Let's see both of them:

Overriding the fetch method:

The fetch method is overridden here and as you can see from the above code, the 'reset' key is added to options and then the fetch method defined on the Backbone Collection's prototype is called.

Resetting the Collection in parse:

Whenever a response is received from the server, the parse method is called before sending a notification to the listeners. Here you can call the reset method passing the response as an argument. The Collection now has been reset with the data received from the server and View will receive a reset event.

Para - Para - Parallax

2013-06-19T12:25:00.000+05:30

I was listening to ColdPlay while developing a Parallax scrolling application and hence the title. Anyway, I was very much intrigued by the parallax scrolling model and wanted to try my hand on building one. The idea here was to show images of different transparency levels in such a way that when the user scrolls, one image would blend over the previous one.

Take a look at the application here.

WebRTC experiment - Recognizing hand gestures

2013-05-23T17:32:00.002+05:30

I have created a web application that recognizes hand gestures using WebRTC's getUserMedia API. Here's how it works: when you launch the application the browser will prompt you for the permission to access the camera. Click on 'Accept',and then swipe your hand from right to left and vice versa. You would see that the next image (or the previous image if you swipe from left to right) in the gallery slides through.

You can access the application here.

Please note, I have tested this application on Chrome only and not on other browsers. Also, I have used five images in this demo and it is obvious that no image would be shown if you swipe from right to left when the last image is being shown or when you swipe from left to right when the first image is shown. I have codenamed this application as 'Gesto' and hence the name in the URL of the application.