ChocolateChip-UI

Functional Components

@composi/core is a JavaScrip Library for creating functional components. It accomplishes this use virtual nodes and a virtual DOM, similar to React. In fact, if you look at the function components, they will look just like React function components.

import { h, render } from '@composi/core' // Define functional component: function List(props) { return ( <ul> { props.data.map(item => <li key={item.id}>{item.value}</li>) } </ul> ) } // Render the component: render(<List data={things})/>, document.body)

As you can see in the above example, it uses the same pattern of passing values down using props, and the familar render function. One big difference is that @composi/core does not require special syntax for props--no need for camel-cased events (onClick) or special terms (className). Instead you use the normal standard HTML versions of properties.

Lifecycle Hooks

@composi/core also provides functional components with something React does not: lifecycle hooks. You put these directly on the element you want to track. @composi/core offers the following three lifecycle hooks:

onmount--gets passed a reference to the element that mounted

onupdate--gets passed a reference to the element that was updated, along with the old and new props.

onumnount--gets a reference to the component that will unmount.

Runtime Programs

Besdies these, @composi/core has a third function, run. This create a runtime environment which gives you a scaled down version of The Elm Architecture. This provides state management for functional components.

Every runtime program is an object with three methods:

const program = { init() { // Initialize the program with state and a subscription: return [state, effect] }, view(state, send) { // Render a functional component with the program's state: return render(<Component {...{state}}/>, document.body) }, update(msg, state) { // do something with state, then return it. // Returning state with get passed to view, // causing the component to re-render. return [state] } }

The init method is for setup for the program: setting default state and launching in effects, such as timers or fetching data.

The view method is for returning a presentation of the program's state. This is where we take the state and use it to render a functional component.

The update method is where all the business logic of the program resides. Like Redux, this consists of actions that can modify state according to the received messages that it receives from events in the view and then return the updated state.

Size Matters

@composi/core provies all the functionality that we discussed so far while weighing in a just under 3KB. It's really small. That means it load fast. You get virtual DOM, functional components, lifecycle hooks and Redux-style state managegment in a tiny footprint.

Install

Actually, you do want to install @composi/core. Instead you want to install the CLI for creating new projects: @composi/create-composi-app.

npm i -g @composi/create-composi-app

After installing, you can use it to create a new project:

create-composi-app 'MyProject'

This will create a new @composi/core project on your desktop. Open you terminal and cd to the new project. The run:

npm i

This will install the project's dependencies. When it's done, you can build and launch your new project:

npm start

Everything you need for developing your project you will find in its src folder:

|-src |-css |-images |-js

Any changes you make in these folder will cause the project to rebuild and reload in the browser.

Summary

@composi/core is a light-weight and powerful solution for solving many of the same problems that React addresses.

ChocolateChip-UI just launched version 5. This was a major upgrade. It was actually a complete rewrite–everything was rewritten in ES6 (ECMAScript 2015). The biggest change was moving widgets to ES6 classes. Also, the two main features of ChocolateChip-UI 4 – $.View and $.Model – were replaced by Component and State. If you’ve used $.View and $.Model, the move to Component and State is not drastic, but there are differences.

Let’s start with Component. On the surface its purpose and behavior is similar to ChocolateChip-UI’s $.View. You define a template bind some data. You render it to the screen with the render function. When the data changes, the changes are rendered to the DOM automatically. Where these two differ is in how they do this. Both $.View and Component expect a selector as the element that the result will be rendered to. Now let's see how they differ.

Render

ChocolateChip-UI Component does not use a template like the older $.View function. Instead it has a render function that returns a template. $.View used a special template language to define templates. It was something ChocolateChip-UI had been using for years. Version 5 threw that template language out. Instead, it uses ES6 template literals and tagged template literals. You define you component’s template by giving it a render function that takes data and returns an ES6 template literal:

const myCompo = new Component({ element: '#peopleList', render: (person) => html` <li>${ person.firstName } ${ person.lastName }</li>` })

Notice that in the above component’s render function, we’re using the tagged template literal html. This is provided by ChocolateChip-UI. You want to use it because it automatically escapes the data, preventing malicious script injection, and allows you to use map on arrays to data without having to end it with .join('') to avoid comma insertion in the result.

Because render is a function that returns a template literal, we can use JavaScript inside the render function as expected. For example, want to uppercase the last name? Easy, just put .toUpperCase() directly on the data:

const myCompo = new Component({ element: '#peopleList', render: (person) => html` <li>${ person.firstName } ${ person.lastName.toUpperCase() }</li>` })

Want to get the index of the loop to output numbering? That would be the second parameter of the render function, so we just need to add one, in this case, after the person parameter:

const myCompo = new Component({ element: '#peopleList', render: (person, idx) => html` <li>${ idx +1 }: ${ person.firstName } ${ person.lastName }</li>` })

JavaScript Before Returning

In the above examples the render function is immediately returning a template literal. In most cases that’s fine. But if you want to do some kind of data checks or other more complex processing before returning the template, you can do that before. In that case you use curly braces with the code:

// Only render a person if the last name is not Wobba: const myCompo = new Component({ element: '#peopleList', render: (person) => { // If the person's last name is Wobba, // don't render that person: if (person.lastName === 'Wobba') { return } else { return html` <li>${ person.firstName } ${ person.lastName }</li>` } } })

Rendering a Component

The above component has an element that it can render to and a render function with template. To make it happen we need to render it. When doing so, we need to pass it some data to use that matches the template. Let's pretend we have an array of person objects that have the properties firstName and lastName. To render the component, invoke its render function and pass the people arrays as the argument:

myCompo.render(people)

With that, the component will pass the people array to the render function and output the result by rendering list items in the list.

Below is a Codepen of a Component:

See the Pen Simple List v5 - No State by Robert Biggs (@rbiggs) on CodePen.

Reactivity with State

This works quite well, but it's missing one big feature: reactivity. If we change the people array, the component doesn't know about i. The component only displays the state of the people array at the time it was rendered. If we want the component to be synched to the state of the array, we need to do two things. First, encapsulate the data in a State object. Second, give the component a state property with the State object as its value. When we do this, the component uses the value of the State object when it renders. More importantly, State objects automatically trigger the rendering of components that use them. Here's the previous component updated to use state:

// Create State object with people array: const peopleState = new State(people) // Only render a person if the last name is not Wobba: const myCompo = new Component({ element: '#peopleList', state: peopleState, render: (person) => { // If the person's last name is Wobba, // don't render that person: if (person.lastName === 'Wobba') { return } else { return html` <li>${ person.firstName } ${ person.lastName }</li>` } } })

And here's a Codepen of the component using state:

See the Pen Simple List v5 by Robert Biggs (@rbiggs) on CodePen.

Default Values

Because we are using ES6, we can provide out component render function with default values. Doing so means your component will render without glitch, even if data is missing. Nothing special about providing default parameter values, just follow the ES6 convention:

const myCompo = new Component({ element: '#peopleList', render: (person = { firstName: 'John', lastName: 'Doe' }, idx = 0) => html` <li>${ idx +1 }: ${ person.firstName } ${ person.lastName }</li>` })

With the above code, if there is no data, the component will render "John Doe". If there is no index value, say you switch from an array to a single person object, the index value will still print out.

Learning More

I’m the author of ChocolateChip-UI, a framework for building hybrid mobile web apps. Over the years I've written libraries for DOM manipulation and animation. I write code every day, for hours. I’m chained to my NPM/Node build tools. Heck, I write my own build scripts. I’ve done Grunt, Gulp, NPM and straight up Node scripts. I bundle with whatever - Browserify, Webpack, JSPM. Sometimes I fall asleep at night with my laptop in my arms. And when I wake up in the morning I push the previous night’s code to Github. Sometimes I have trouble sleeping because I spend the whole night dreaming of coding while trying to figure out a weird bug I discovered the day before. And sometimes I even wake up with the solution.

I’m 67 years old, pushing 68. I have cataracts and glaucoma, so I sometimes have problems reading other people's code, or even my own. Sometimes I have dizzy spells. I have numbness in my feet that can make it hard for me to walk. Yeah, I'm getting old. But you know what? I’m not suffering from JavaScript fatigue. Every time I hear someone complain about JavaScript fatigue I feel like screaming. For me, JavaScript and its ecosystem are not moving fast enough. Don’t tell me I’m going to have to wait until I’m 72 before all the browsers that don’t support ECMAScript 2015 are gone. I want them gone like last month already. Sheesh! I want to see my beautiful ES6 code working with all its goodness in browsers now, not transpiled by Babel into ES5 mush for old fogie browsers. When I have to go back to ES5, I feel like I’m looking at the cave scrawls of Neanderthals. Don’t even get me started on async and await. Why has this taken this long???

For you new guys just starting out in life as Web developers and complaining about the JavaScript ecosystem, let me tell you something. I started on the Web back in ‘93. I had the ViolaWWW browser. Yup, that mouthful was it’s real name. There was HTML 1, and no image tags. The web was text only, nicely formatted with semantic markup because that’s all there was. And links. I still remember when the image tag was introduced by Marc Andreesen in 1994. It was shocking. Some digerati said it would be a disaster. We would be buried alive in an avalanche of cat pictures. Sadly, they were right. Oh yeah, and the font tag. This dinosaur still lives and functions in browsers today. Before HTML 4 we used it for all text. It had attributes that let you set a font's family, size and color. In those days all text on the web was enveloped in a tangled mesh of font tags. It wasn't untile CSS came into wide use in this milenium that use of the font tag fell by the way. It was formally deprecated from the HTML standard in 1998, but lives on in old content to this day.

Back in those days, before JavaScript, the Web was simpler, you could build a Website with static markup. Except that many businesses needed dynamic content. So they installed Apache on their servers with Perl, PHP, ASP and JSP. If you wanted to be a Web developer, you had to learn one of these. Perl was always the first choice for speed. Developers loved Perl because there were so many ways you something. This meant it was always a challenge to read and understand other developers' Perl scripts.

In 1994 I started using a new browser, Mosaic. It later became Netscape Navigator. In 1995 JavaScript shipped in Netscape Navigator, except that it was called LiveScript. That same year Microsoft shipped their own browser, Internet Explorer. A year later Microsoft added a scripting language called JScript to Internet Explorer. It was backward engineered from JavaScript, but it was not JavaScript. They shared things like variables, loops and conditionals, the standard stuff. After that, everything was different. I’m talking about the DOM. You could not implement a button click, a callback, or a DOM manipulation in the same way. Internet Explorer and Netscape Navigator had incompatible interfaces for their browser DOMs. In fact, they had different ideas about what constituted the DOM. To do anything cross-browser, you had to test the browser before branching off to browser-specific code. You could never duplicate the same experience in both browsers, their DOMs were that different.

Into this mess of incompatibilities was born the revolution of DHTML. That stands for Dynamic HTML, just so you know. It was like a dam burst. Everybody and their brother started writing DHTML libraries. There were thousands. Some were alright, but most were crap. Some were very focused on a single widget that tried to replicate the same interface and behavior across browsers, but this never turned out very good. Some libraries tried to be generic for things like animation. Thus tasteless and unnecessary animation thingies began to proliferate on the web, because why not? These were the 90s, when no one browser ruled the roost. So you had to support them all. During these wild times I also wrote DHTML libraries (blush). At the time, they seemed like the solution to the anarchy of Web development caused by incompatible DOM implementations.

To be honest, the failure of DHTML libraries was not their fault. They were working with such a nasty situation. You know, after you put enough lipstick on a pig, it stops looking like a pig with lipstick and more like a messy pile of lipstick. During these dark times, the W3C worked out the first recommendation for HTML4 and JavaScript 3 for browser vendors to implement. This included a proposal for a standarized DOM interface for browser vendors to follow. Netscape, who by 1999 had begun losing considerable marketshare to IE, was hard at work on a new version of Netscape Navigator that would support those proposed standards. Even Microsoft half heartedly embraced them while creating IE6. But since Microsoft had so much marketshare, they didn’t think they had to implement everything the standards body recommended. After all, it was only called a recommendation. They adopted some parts, and winged it with the rest. That’s how the unholy IE6 was conceived. Microsoft kept in support for a lot of the whacky things they had done in previous versions of IE. As a result, IE was incredibly buggy.

The choice to not fully accept standards would come back to haunt Microsoft, but much later. Meanwhile, in 2000 Netscape finally shipped Netscape Navigator 6. It had the real DOM. It made sense, it was easy to wire up events on elements, it was easy to style, and it was easy to change styles dynamically. It was what we had always wanted in a browser. What a breath of fresh air. But the developers who embraced Netscape Navigator 6 were a tiny group. Most developers were already developing websites that only worked with IE6. If it didn’t work with IE, nobody would bother with it. IE6 was job security. It was backed by Microsoft. The first round of browser wars were over. Microsoft won.

After the launch of Netscape Navigator 6, people started publishing tutorials about how to do things with the new DOM standard, things that you couldn’t do easily or at all in IE. But businesses only cared about what worked on IE6. You could never get a client to let you build a site that also supported Netscape 6: "But our customers prefer IE". This was partly Netscape’s fault. The Netscape browser, while supporting standards, was a horrible user experience. The browser was an interface to the world of Netscape, which included AOL. This meant constant nagging to view channels and ads, ads, ads. Sound familiar? Netscape Navigator was so bloated by the AOL parts that it took forever to load, and it was sluggish to use. In contrast, IE loaded quickly. And all the websites looked proper on it because developers made sure of that. There was no money to be made supporting Netscape Navigator.

During this time of darkness when the Internet stagnated under the dictatorship of IE6, Netscape decided to spin off an open source project called Mozilla. Some developers there took the Netscape browser, striped away all the AOL and Netscape branding and created a streamlined browser that supported the new standards. It shipped in 2002 and was called Phoenix. Later they changed the name to Firebird before finally settling on Firefox in 2004. Slowly Firefox clawed its way up from the depths of obscurity and irrelevance, changing the way people thought about the web as a platform. This would later lead to the birth of Safari and Chrome.

Firefox turned the browser market upside down, and even Microsoft was forced to support standards they didn’t create. But Microsoft wasn’t going to concede quietly. They took one more stab at trying to dominate the Web. Only this time they wanted to completely replace HTML and JavaScript with their own technology. HTML was a joke for presentation and JavaScript was the worst language in the world. So they created Silverlight. It ran on their .NET platform. For markup it used XAML, a variant XML, and their C# language for interaction. All those guys who only knew how to support IE took up Silverlight. I even did some work with it.

For a while it looked like Silverlight would replace HTML and JavaScript and Microsoft would determine what the Web platform was. But a funny thing happened. In 2007 Steve Jobs introduced the iPhone. It was touch-friendly. It had a desktop-quality browser. But there was no public SDK for making apps. Steve told everyone to user Web standards to write Web apps for the iPhone. The most significant thing about the iPhone browser was that it did not support plugins, so no Flash or Silverlight. That earthquake knocked the foundation out from underneath Flash and Silverlight. They would never recover.

With the rise of Firefox, Safari and Chrome, Web developers no longer had to be on Windows. They could work on the Mac or Linux. This resulted in a tectonic shift of Web developers from Windows to other platforms. Minds were opened and developers explored their options and tried new ways of doing things. It was like that quote from Mao: “Letting a hundred flowers blossom and a hundred schools of thought contend…”

And here we are today. Deelopers are complaining about JavaScript fatigue. You don’t realize how lucky you are. Browsers follow standards. And most standards originate from developers who are looking to make our craft better. From my perspective, we are in a Golden Era of Web development. Yeah, there’s a lot going on. That’s not new. JavaScript is not static, it’s a moving target. Every new feature will nudge developers to think how to do things differently. Then they will come up with new patterns and libraries and frameworks. Do you need to learn everything that comes along? Well do you have to listen to all music that gets produced?

Here’s a strategy. Do exactly what you need to be doing right now. But on the side, when you have some spare time, check out other libraries and frameworks. That means just read about them. Pick one that you find interesting. Download it. Look at some examples. Does it make sense to you? Do you find the approach interesting? Look for some tutorials. Keep it simple. No need to rush in. After a couple of weeks you'll realize if it’s not for you. At least you will have learned something. Go read blogs, explore Github. Wonder off the beaten track. You won’t get mugged. You can always go back to what you were doing before. One thing though, you can't be complacent. If you’re unwilling to learn new things, you’ll wind up like the IE only guys - out of work.

JavaScript fatigue is not the fault of JavaScript or the Web. These are only getting better. Your fatigue means there’s something wrong with you. What are you doing that’s causing you such fatigue? Are you just bored? Have you lost interest in Web development? What has changed? Maybe you could use a career change. People change careers all the time. There’s nothing wrong with that. In fact there’s plenty good about it. But please, don't blame us for your fatigue. It's like runners in a marathon blaming the other runners for their fatigue.

CSS flexbox has been around for a while. ChocolateChip-UI uses flexbox to handle placement of things in layouts, navbars, tabbars, toolbars, etc. But ChocolateChip-UI also has a number of classes that let you create a grid of items.

To create a grid, just put the class grid on a div:

<div class='grid'></div>

Next we need to create some columns. We do that by putting the class col on some divs:

<div class='grid'> <div class='col'>1</div> <div class='col'>2</div> <div class='col'>3</div> </div>

If we want some columns to have a different width than others, we can give our columns flex classes. These set flex values on the columns, by which they take up available space based on their flex values. There are ten classes for defining column flex values:

<div class='col flex-1'></div> <div class='col flex-2'></div> <div class='col flex-3'></div> <div class='col flex-4'></div> <div class='col flex-5'></div> <div class='col flex-6'></div> <div class='col flex-7'></div> <div class='col flex-8'></div> <div class='col flex-9'></div> <div class='col flex-10'></div>

Live Examples

See the Pen Grids 1 by Robert Biggs (@rbiggs) on CodePen.

Another example with varied flex values:

See the Pen Grids 2 by Robert Biggs (@rbiggs) on CodePen.

Using flex values, you can create some interesting layouts. Below are columns using a total value of 6 and 10:

Flex 6 Based Grid

See the Pen Grids 7-gutterless by Robert Biggs (@rbiggs) on CodePen.

Flex 10 Based Grid

See the Pen Grids 4 by Robert Biggs (@rbiggs) on CodePen.

Equal Height Columns

The columns in a grid will automatically be of the same height. This means if one column has more content than another, the height of the grid row will exapand to accomodate that column. The other columns in the row, even though they have less content, will also expand to fill the new row height. This works like cells in a table row.

Example of Equal Height Columns

See the Pen Grids 6 by Robert Biggs (@rbiggs) on CodePen.

Grid Gutters

So far all our examples have the columns and rows up against each other. You can add some gutters to your grid. This will put space between the rows and columns. To do so you can use two classes: gutter-5 and gutter-10.

// Grid with 5px gutter between columns: <div class='grid gutter-5'> <div class='col flex-1'></div> <div class='col flex-2'></div> <div class='col flex-1'></div> </div>

Grid with Gutters

See the Pen Grids 7 by Robert Biggs (@rbiggs) on CodePen.

Flex Wrap

Having responsive columns withs is great, but sometimes you may actually want your columns to wrap to form another row. This is often the case when a mobile device is in portrait mode. You can tell a grid row to wrap its columns using the wrap class on it:

<div class="grid wrap"> <div class="col flex-1"><p>1</p></div> <div class="col flex-1"><p>1</p></div> <div class="col flex-1"><p>1</p></div> <div class="col flex-4"><p>4</p></div> <div class="col flex-5"><p>5</p></div> <div class="col flex-3"><p>3</p></div> <div class="col flex-1"><p>1</p></div> <div class="col flex-1"><p>1</p></div> </div>

See the Pen Grids 5 by Robert Biggs (@rbiggs) on CodePen.

Centering Columns to a Grid

You can center your columns in a grid. Putting the class center on a grid will force the columns to be centered.

See the Pen Grids 8 by Robert Biggs (@rbiggs) on CodePen.

Fixed Width Columns

You can also have columns with fixed widths if you need to. Just put a class on the column whose width you want to be constant, then define that class, giving the column the width you want. You'll also need to set the column's flex value to none:

.fixedFixed200 { width: 200px; -webkit-box-flex: none; -webkit-flex: none; flex: none; }

See the Pen Grids 9 by Robert Biggs (@rbiggs) on CodePen.

ChocolateChip-UI is about views. These are objects that define a component of your app. This might be a simple list, or a complex widget for user interaction. Views are the means by which you render data in your app. The encapsulate behavior, structure and appearance into a reusable component.

Create a View

You create your view object with ChocolateChip-UI's view factory. How you view object works is determined by the options you provide the factory. Since a view will usually be anchored to an element, the first and most important option to provide is the element property:

var myView = $.View({ element: '#myList' });

Although you can use any selector as the value of the element property, it's usually best to use the id. This enables your view object to more accurately target its element. Using generic selectors could have unexpected results depending on your app's markup.

Templates

After designating the element that a view is anchored to, you need to provide a template. There are so many ways to do this. Some people like to have their templates in place where they will be rendered, like Mustache templates. ChocolateChip-UI lets you do this in three ways: with an inline script tag, with inline template tag or with the template defined inline.

Script Tag

You can define your view's template in the markup where it will render using a script tag. You still need to tell your view the id of the parent element. When the document load, ChocolateChip will examine the element. If it has a script tag, it will extract the contents to use as its template. Make sure you give the script tag a type of text/x-template, otherwise the browser will think it is a normal JavaScript script tag and try to process the code, resulting in an exception being thrown.

<ul id='myList' class='list'> <script type='text/x-template'> <li> <h3>{= data }</h3> </li> </script> </ul>

Template Tag

We could also use a template tag just like the script tag, excep that we don't have to use the type="text/x-template" on it. Be aware that if you need to support older Android devices running Jelly Bean, template tags are not supported. You can use some JavaScript to set all template tags to display none:

<style> template: { display: none; } </style>

Here's a template tag template:

<ul id='myList' class='list'> <template'> <li> <h3>{= data }</h3> </li> </template> </ul>

Inline Template

You can also put the template right in the markup, raw. This looks a little cleaner. The only thing to bear in mine is that occassionally the user might see the template before ChocolateChip-UI can process it. For those situations you want to put a class of cloak on the parent element. This will hide the element until ChocolateChip-UI finishes processing it.

//Notice the cloak class on the element: <ul id='myList' class='list cloak'> <li> <h3>{= data }</h3> </li> </ul> </pre

Template in View

Although the previous approach work, the result is that the template and the view are disconnected. When you're examining a view to see how its working, you have to go back to the document markup to see its template. When you have a lot of views, this gets complicated. Therefore we recomment defining the templates directly in your view object. This means you only have one place to look for all the things involving the view. You have two ways to define a string template: a normal JavaScript string with escaped new lines, or an ES6 template literal. If you are targeting older versions of Android and iOS, you'll need to use standard JavaScipt strings and escape the required characters. However, if you create your project with the -j flag so that it supports ES6 modules, you can use template literals. The build process will convert them into standard JavaScript strings for older browsers.

Here is the previous template as a JavaScript string inside the view:

// Standard JavaScript string template: var myView = $.View({ element: '#myList', template: "<li>\ <h3>{= data }</h3>\ </li>" });

If you have a complex template, you're going to need a lot of back slashes. By using ES6 template literals, you can have a cleaner looking template. Back ticks indicate a template literal:

// ES6 Template Literal: var myView = $.View({ element: '#myList', template: `<li> <h3>{= data }</h3> </li>` });

Render that View

Now that we have a view with and element and template, we can give it some data and render it to the browser. For that we use the render method. We can pass the data we want the view to use as its argument:

// Render the view: var myData = ['One', 'Two','Three']; myView.render(myData);

The above will create three list items with One, Two and Three as their content. We can pass in a string, a number, an object or an array for the list to use. The only requirement is that the data match the template. But what is the data is more complex, like in an object? Let's look and an object:

var person = { name: 'Joe', job: 'Mechanic', age: 32 }

If we try to feed that to our view, the template will not be able to process it and will output [object Object]. Because the object has properties with values, we have to tell the template to process the properties. So, to output the name and job in a template, we would have to add those to our data property with dot notation:

// Access object properties: var myView = $.View({ element: '#myList', template: `<li> // access the name property: <h3>{= data.name }</h3> // access the job property: <h4>{= data.job }</h4> </li>` });

Now if we pass our view this person object, it will output the name and job:

myView.render(person)

Variables

So far we've been using the generic term data in our templates. This works, but it does reflect the data were rendering. ChocolateChip-UI lets you provide your view with a variable property to define what term you use in the view's template. Since we are using an object called person, it would be nice to be able to use that in our template. So we can modify our template to do so:

// The person object: var person = { name: 'Joe', job: 'Mechanic', age: 32 }; // Define view: var myView = $.View({ element: '#myList', template: // Define a variable to use in the template: variable: 'person', // Use "person" instead of data: `<li> // access the name property: <h3>{= person.name }</h3> // access the job property: <h4>{= person.job }</h4> </li>` }); // Render the view with the person object: myView.render(person)

As you can see, variables can make it easier to read a template.

Binding Data to a View

So far our views have been dependent on us passing data as an argument of the render method. This is alright for trivial situations, but we can actually tell a view what data it should use. Then we can just render the view. Whenever we do so, it will always use the designate data. We tell a view what data to use with its data property:

// The person object: var person = { name: 'Joe', job: 'Mechanic', age: 32 }; // Define view: var myView = $.View({ element: '#myList', template: variable: 'person', // Designate the data to use: data: person, `<li> <h3>{= person.name }</h3> <h4>{= person.job }</h4> </li>` }); // Render the view, // it will automatically use the person object. myView.render()

Once we've told a view what data to use, if we make changes to that data, when we render the view, it will update with those changes. Even though a view can be bound to a dataset, we can override this at any time by passing in data to its render method, just as we did earlier. However, as soon as we render the view without any arguments, it will use its designated data source.

In our previous example we've been rendering the view with a simple object. ChocolateChip-UI is intelligent about rendering data. It examines it to see if it is a single object and tries to match up the object's properties to its template properties. But if you instead provide an array of similar objects, ChocolateChip-UI will loop though it and do the same with each object in the array. These means you template will work with a single object, an array of one object, or an array of many objects. Below is our previous example, except that the person object is now a people array of person objects:

// The people array of person objects: var people = [ { name: 'Joe', job: 'Mechanic', age: 32 }, { name: 'Ellen', job: 'Teacher', age: 29 }, { name: 'Sam', job: 'Developer', age: 22 } ]; // Define view: var myView = $.View({ element: '#myList', template: variable: 'person', // Designate the data to use: data: people, `<li> <h3>{= person.name }</h3> <h4>{= person.job }</h4> </li>` }); // Render the view, // it will automatically use the person object. myView.render()

The above example will create three list items with the properties of each person object.

$.view.index

When your data is an array, internally ChocolateChip-UI loops over the array. That is hidden from you so you have no way to capture the loop index value. To get around this, ChocolateChip-UI provides the $.view.index value. You can use this in your template to output a repeating numerical value in your template. Unlike JavaScript look that start with 0, $.view.index starts with 1. Here's how to use it:

// Define view with increasing index value: var myView = $.View({ element: '#myList', template: variable: 'person',] data: people, `<li> // output loop index: <h3>{= $.view.index}. {= person.name }</h3> <h4>{= person.job }</h4> </li>` });

The above template will render the three array items with and index output of 1,2 and 3.

startIndexFrom

As we mentioned, $.view.index starts from 1. You can tell a view to start from whatever number you want, even a negative number. You do so by passing the desired start value to the view's startIndexFrom property:

// Define view with increasing index value: var myView = $.View({ element: '#myList', template: variable: 'person', data: people, // Start index counting from 10: startIndexFrom: 10, `<li> // output loop index: <h3>{= $.view.index}. {= person.name }</h3> <h4>{= person.job }</h4> </li>` });

Because we set the view to start counting from 10, the view items with have 10, 11 and 12. If we gave startIndexFrom a negative value, such as -2, it would count -2, -1 and 0.

safeHTML

By default ChocolateChip-UI escapes any markup in your data. This helps protect your app for script injection attacks. This is especially important in cases were your data comes from external sources or is provided by user input. However, sometimes you might want to have data with markup that gets rendered for stylistic purposes, such as bold and italic text. You can tell a view to not escape html in data setting the safeHTML property to true:

// Notice the formatting tags in the data: var people = [ { name: '<b>Joe</b>', job: '<i>Mechanic</li>', age: 32 }, { name: '<b>Ellen</b>', job: '<i>Teacher</i>', age: 29 }, { name: '<b>Sam</b>', job: '<i>Developer</i>', age: 22 } ]; var myView = $.View({ element: '#myList', template: variable: 'person', data: people, // Tell view to render markup in data: safeHTML: true, `<li> // output loop index: <h3>{= person.name }</h3> <h4>{= person.job }</h4> </li>` });

Because we set safeHTML to true, the names will be bold and the jobs will be italic, otherwise they would be escaped, displaying the names and jobs surrounded by the format tags.

Data Binding With Models

So far we've been rendering our view with plain JavaScript. When we modify that data, we need to execute the view's render method to display the changes. We can make this update happen automatically if we put our data in a model and bind the view to it. Creating a model is easy, you just provide the data you were using with the view as the argument of the model:

// Turn your data into a model: var people = [ { name: 'Joe', job: 'Mechanic', age: 32 }, { name: 'Ellen', job: 'Teacher', age: 29 }, { name: 'Sam', job: 'Developer', age: 22 } ]; var peopleModel = $.Model(people);

To bind a view to a model, we assign the model to the view's model property. This means we don't need the data property any more.

// Turn your data into a model: var people = [ { name: 'Joe', job: 'Mechanic', age: 32 }, { name: 'Ellen', job: 'Teacher', age: 29 }, { name: 'Sam', job: 'Developer', age: 22 } ]; var peopleModel = $.Model(people); // Define view: var myView = $.View({ element: '#myList', template: variable: 'person', // Bind this view to this model: model: peopleModel, `<li> <h3>{= person.name }</h3> <h4>{= person.job }</h4> </li>` });

The advantage to bindig the view to a model is that whenever we do something to the model that changes its data, the bound view will immmediately render to reflect those changes. There are some operations that do not cause a bound view to render. You can read about them in the [documentation](https://chocolatechip-ui.github.io/v4/docs/models/models-api.html) and on the [wiki](https://github.com/chocolatechip-ui/chocolatechipui/wiki/3.-Models).

Events

You can also use a view to register events for user interation, such as when the user taps a list item or button. By default the events are delegated on the view's anchor element. To define events on a view, you use the view's events property. This takes an array of event objects. The event object expects and event property, and a callback. You can also provide an optional element to desinate a child element of the view. For example, if your view is rendering inside a list, you could register a tap on the list item as follows:

// Define view: var myView = $.View({ element: '#myList', template: variable: 'person', model: peopleModel, `<li> <h3>{= person.name }</h3> <h4>{= person.job }</h4> </li>`, // Delegate a tap event to the list items: events: [ { event: 'tap', element: 'li', callback: function(e) { // `this` is the tapped list item: alert($(this).text()) } } ] });

Styles Object

ChocolateChip-UI lets you define styles that are scoped to the view using the view's styles property. The fist level of styles go directly to the view's element, using whatever selector you used to designate it. That's why it's best to always use an id to designate a view's element. This will make it easier to override any inherited styles. You define the styles using key/value pairs of CSS properties and values. The values must always be quoted. Properties do not need to be quoted, unless they are hyphenated. You can avoid needed to quote a hyphenated CSS property by using its camel case version.

// Define view: var myView = $.View({ element: '#myList', template: variable: 'person', model: peopleModel, `<li> <h3>{= person.name }</h3> <h4>{= person.job }</h4> </li>`, // Define a style object for the view: styles: { 'background-color': 'red' } });

We could also use:

styles: { backgroundColor: 'red' }

The above style definition would put a red background color on the list itself. If we wanted to target the list items or the H3s, we need to use their selectors nested in the style object. This works similar to nest selectors in LESS and SASS. Note that the child selectors need to be quoted!

// Define view: var myView = $.View({ element: '#myList', template: variable: 'person', model: peopleModel, `<li> <h3>{= person.name }</h3> <h4>{= person.job }</h4> </li>`, // Define a style object for the view: styles: { border: 'solid 1px red', margin: '20px', // style the list items: '> li': { backgroundColor: 'ivory' // Style the list item's H3 '> h3': { color: 'blue' } } } });

If you are using the standard layouts and widgets provided by ChocolateChip-UI, you probably won't need to provide your view's a style object. However, if you are creating custom layouts, then defining styles directly on the view makes porting that view to other projects easier. When you define a style on your view, ChocolateChip-UI creates a virtual stylesheet for it.

ChocolateChip-UI 4, a framework for making web apps, has just been release. This is a no nonsense framework. It really strives to keep things simple. Version 4 is a major update - so many new features. Here’s a list:

Views

Models

Data Binding

Mediators

Data Formatting

Form Validation

Local Data Persistence

Routing

Support for ES6

Fetch

ChocolateChip-UI 4 is a complete rewrite using ES6. It is transpiled with Babel to ES5 so you can run it in any browser. Its layouts and widgets have been overhauled as well. Layouts now include the ability to create cards for presenting chunks of data. It also has an updated Android theme with support for Material Design ripples when the user taps interactive elements.

KISS

While other app frameworks are becoming more complex, requiring time to wrap your head around concepts o functional reactive programming, type systems, etc. ChocolateChip-UI is striving to keep things simple. If you’re a developer that wants to make an app and doesn’t want to spend time figuring out the development ecosystem of supporting libraries, ChocolateChip-UI has your back. You can literally stick with plain old JavaScript like you always have and ChocolateChip-UI will provide you with layouts and widgets to make your app happen.

chui

OK, so let’s see how to make this happen. The fastest way to get started is to install the NPM module chui. This command line tool will let you create a starter project depending on what you want. Chui can make a really simple project, or a more complex one using wigets. It can set up your project so you can use ES6 modules to build your app, and it can turn your code into a hybrid app for Android and iOS.

To install it, just run the following in your terminal:

npm install -g chui

On Linux and macOS you may need to use sudo with that, depending on how you have NPM set up. Once you’ve installed chui, you’re ready to make create your first project. You can tell chui what kind of project you want with arguments. You can indicate which platform - Android or iOS, or what type of app - basic, navigation list, slideout menu, or tabbar. To indicate a platform you use -o and for type of project you use -t. Most importantly, you need to provide a name for you project with the -n argument. If no platform is provided, chui defaults to iOS. If no type is provided, it defauls to basic. So let’s make an app:

chui -n myApp

This will create a project on your desktop named “myApp” that targets iOS and has the most basic structure. Open the folder and double click on the index.html file. It will open in the browser with a simple list. This is defined in the app.js file inside the js folder. Open the app.js file in your editor. You see a simple view defined:

$(function() { var ListView = $.View({ element: "#list", template: "<h3>Item {= data }</h3>" }); ListView.render(["One","Two","Three"]) });

The above function uses a DOM ready function to load the view. The view’s element attribute defines where the view gets rendered. The template defines the markup that will get output. And the render function passes a simple array to use. Since the array has three items, it will render three list items.

There are many other options that you can use in a view, but will look at those later. This simple example shows you the building blocks of a ChocolateChip-UI app: chui.min.js, a css theme (chui-ios-min.css or chui-android.min.css) and an app.js file for you code.

As I mentioned, you can create various types of projects. Below are some possible ones:

chui -n myApp -o android -t navigation chui -n myApp -o ios -t slideout chui -n myApp -o android -t tabbar

That’s it for the basics. If you want to see examples so that you know what ChocolateChip-UI has to offer, just run this command:

chui -e

This will output a folder called “Chui Examples” on your desktop. Open it and you’ll find a bunch of double clickable files. Open them in a code editor and you will see how the layouts are put together and how the widgets were set up.

If you want some more than just demos of widgets, something that shows you how to put an app together, just run this command:

chui -r

This will output a folder called “Chui Reference Apps” on your desktop. Open it and you’ll find two folders: basic and jspm. For now, ignore the jspm folder. We’ll talk about that in an upcoming post. Open the basic folder. Inside you’ll find four folders:

Fragranž

SFCoffeee

TodoMVC

Vino

Fragranž shows how to put together a typical product purchase app for colognes. SFCoffee is an information app about coffeeshops in San Franciso. TodoMVC is based on the famous TodoMVC project. The difference is this was completely redesigned as a mobile app. Vino is an app that explores the wines of Norther California. Each project has an app.js file inside its js folder.

We saw that Truck's mediators are an event-based module for controlling how data flows through an app. But control isn't just handled by mediators. Truck also provides a dispatch system consisting of dispatchers and receivers. Like mediators, this is event-based. You dispatch a handle and any receivers immediately respond. When you dispatch a handle, you can also pass along some relevant data for the receiver.

The dispatcher is much simpler that the mediator pattern. It can best be described as a Pub/Sub module. Creating a pair of dispatchers and receivers is easy. Let's start with a dispatcher. It takes a handle as the primary argument, and any kind of data as the second, optional argument:

//Dispatcher with only handle: $.dispatch('my-handle-here'); // Dispatcher with data: $.dispatch('my-handle-here','I just did it!');

Defining dispatchers without receivers is not going to result in anything happening. So let's create some receivers. These take two arguments, the handle and a callback. The first argument in the callback is any data that was passed with the handle by the dispatcher. Put some though into the handles you use. You can namespace them or even use rest-like paths. Let's setup some receivers:

// Define a receiver for a handle: $.receive('my-handle-here', function() { console.log('I just received the handle: my-handle-here'); });

With the above receiver defined, whenever we dispatch the handle 'my-handle-here', it will respond by logging the message. Since the receiver doesn't handle data, it will ignore any data passed. It's simply responding to the dispatch of the handle.

Now let's setup a receiver that captures data:

// Define a receiver for data: $.receive('my-handle-here', function(data) { if ($.type(data) === 'string') { console.log('The data is: ' + data); } });

Notice that we are capturing the data and doing some type checking. The receiver is setup to only handle string data. You could define a receiver to handle multiple types of data with some conditional logic. Or you can define separate receivers to handle the different data types. That’s totally up to you.

So far our receivers have all been unnamed. But you can also name a receiver by asigning it to a variable like so:

// Define a named receiver: var myReceiver = $.receive('my-handle-here', function(data) { if ($.type(data) === 'string') { console.log('The data is: ' + data); } });

If you mave multiple receivers responding to the same handle, giving the receivers meaningful names helps clarify what they are doing.

Finally, the last piece of the dispatch system, the ability to cancel a receiver. This is basically pulling the plug on the receiver. Once you cancel a receiver, it will never respond to its handle for the current life cycle of the app. However, when the app is restarted, canceled receivers will once again be operational.

Only named receivers can be canceled, so if this is something you think you will need to do, make sure you name your receivers. To cancel a receiver, pass its variable directly to the $.cancelReceiver method:

// Cancel a receiver: $.cancelReceiver(myReceiver);

TruckJS is an MVC framework. The controller layer consists of mediators. Data flow in a TruckJS app is uni-directional. An app can have four legs: views, models, remote data and local data. Between these, the mediator manages the flow from one to the other. Notice the image below:

For any of the four parts to interact with the others, they will have to go through the mediator layer. The remote data, local data, view and model cannot talk to each other, but the mediators can talk of all of these.

Mediators are event based. They listen. The other parts of the app get the attention of a mediator by using a handle, which is in effect an event. The handle is like that used by truckers to identify each other on the open road. A mediator listens for a specific handle. If a model dispatches a handle with some data, any mediator listening for that handle will receive the data and can do something, such as update a view. Similarly, a user interaction in a view can dispatch a handle with some data to a mediator, which can then update a model, post it to a server or put it in the local data store. Mediators are at their best when they are focused on performing a single task. If you’ve created a mediator that does many things, you should break it down into several independent mediators. Let the main mediator inoke the other mediators as need. Bear in mind that this is about events, so structure you code with that in mind to create patterns that are decoupled, elegant and partical for your purpose.

One way to enable a mediator to execute other mediators is to use the $.Mediator.dispatch(). This takes two arguments, a handle and some optional data to pass along. When you dispatch a handle in this way, all mediators that are listening to that handle will run, unless they have been stopped or killed.

Because they are event based, mediators are run asynchronously. And a mediator can invoke another mediator to perform a task outside the original mediator’s domain.

When you bind a view to a model, TruckJS creates a type of mediator that listens to the model and updates the view when the model changes. Similarly, when you set a model to automatically persist itself in the local data store, TruckJS creates a mediator to listen to the model and put its changes into the local store.

myMdtor.init(function(data) { // Dispatch a handle to run all listening mediators: $.Mediator.dispatch('myModel-handle', 'some data here'); });

Setup

To create a mediator you use the $.Mediator() method with a handle for the mediator to listen for.

var MyMtor = $.Mediator('myModel-handle');

init(callback)

Once you have created a mediator you can initialize it. This defines what a mediator will do when it runs. If any data has been passed along with the handle, it will be available to the init callback as the first argument.

// Define a callback for the mediator: MyMtor.init(function(data) { if (data && data.length) { data.forEach(function(item) { console.log(item); }); } });

run()

You use the run method to run a mediator. In the following example we create a mediator and then run it:

// Create a mediator: var MyMtor = $.Mediator('my-handle'); // Init the mediator: MyMtor.init(function(message) { console.log(message); }); // Run the mediator: MyMtor.run('This is a message');

stop(after)

If you have a complex app, you will have many mediators, and some mediators may run other mediators. This could get very busy. Truck allows you to stop a mediator. There are two ways to stop a mediator, immediately or after a designated number of times. If you fire stop() on a mediator, it will stop immediately. However, if you provide a number value, stop(20), the mediator will stop after running the designated number of times.

// Stop the mediator immmediately: MyMtor.stop(); // Stop the mediator after 10 runs: MyMtor.stop(10);

Although you have stop the mediator, you can restart it at any time. See restart() below:

restart(time)

If you’ve stopped a mediator, you can use this method to restart it. There are two ways to restart a mediator: immediately or after a designated time has transpired. The time is indicated in seconds.

// Restart the mediator immediately: MyMtor.restart(); // Restart the mediator in 10 seconds: MyMtor.restart(10);

isStopped()

If you’re not sure if a mediator is stoppped or not, you can query it with this method to find out. It returns a boolean value:

if (MyMtor.isStopped()) { MyMtor.restart(); }

getCount()

You can find out how many times a mediator has run. This can give you an important insight into how your code is running. Each run increases the count:

var count = MyMtor.getCount(); if (count > 100) { MyMtor.stop(); }

resetCount()

If a mediator’s count has gotten really large, you may want to reset the count to zero. You can do that with this method.

MyMtor.resetCount();

stopCount()

Perhaps you really don’t care how many times your mediator is running. In that case you can tell the mediator to stop keeping track of the count.

MyMtor.stopCount();

getHandle()

In case you forgot what handle a mediator is using, you can query it to find out.

var handle = MyMtor.getHandle(); if (handle === 'my-model-handle') { console.log('This mediator is for MyModel.'); }

kill()

Once you’ve set up a mediator, it will run until the app shuts down. However, there may be cases where you want a mediator to have a short lifetime. Using this method, you can kill a mediator, afterwhich it cannot be run again. Killing a mediator is final during the current life cycle of the app. When the app restarts, killed mediators will again run.

MyMtor.kill();

hasBeenKilled()

Using this method, you can find out if a mediator has been killed.

if (MyMtor.hasBeenKilled()) { console.log('We can run this any longer!'); }

$.Mediator.dispatch(handle, data)

This method lets you dispatch a handle and data to all mediators listening to that handle. They will run depending on whether they have not been stopped, etc.

Truck’s $.Model method is an object factory that provides encapsulation and abstraction. When you initialize a new model, this method returns an object with your data stored in its private scope. The data is then only accessible through the model’s accessor methods.

Although it has become a fashion for web frameworks to eschew models in favor of using raw JavaScript objects, this has several disadvantages. First and foremost - the data can be easily and inadvertently modified without your knowledge. Secondly, implementing data binding will require workarounds involving cloning of the data to compare against the original and polling to run the comparison. Truck does not have this problem because it has real models. The methods that modify a model’s data also publish those changes to the system. So the system just needs a passive subscription service to listen for changes published by the models. This event-based approach makes Truck’s data binding very light and efficient.

Creating a model is quite simple. You need to provide the model two things: data and a handle. The handle is used by the system to identify the model. When the model changes, it notifies the system using this handle. Any mediators listening for this handle will intercept the model’s changes. Normal we like to name a model handle with the post fix "-handle".

var data = [1,2,3,4,5]; var MyDataModel = $.Model(data, 'my-data-handle');

Objects or Arrays

Models are of two types - objects or arrays. Use an array when your data is key value pairs. Use an array when your data is a collection of similar items:

var obj = {name: 'Joe', age: 32}; var MyObjModel = $.Model(obj, 'my-obj-model'); var people = [ {name: 'Joe', age: 32}, {name: 'Sam', age: 26}, {name: 'Mary', age: 25} ]; var PeopleModel = $.Model(people, 'people-handle');

Empty Models

You can create empty models in which you can put data later. Provide and empty object or array and a handle:

// Empty object model: var MyObjModel = $.Model({}, 'my-obj-model'); // Empty collection object: var PeopleModel = $.Model([], 'people-handle');

You can use the model methods to add content to an empty model. These methods are discussed below.

After you have assigned your data to a model, you really don’t need it anymore, so you could just get rid of it:

<pre class="prettyprint linenums">var data = [1,2,3,4,5]; var MyDataModel = $.Model(data, 'my-data-handle'); data = undefined; </pre>

Model Types

Models can hold two types of data: a single object of key value pairs, or an array of data, usually objects, such a merchandise, employees, etc. Models have some methods that work for objects and others that work for collections. Object methods only work when the data is an object, same for collection methods. But some methods work for both. When accessing and manipulating your data you do need to be aware of what kind of data you are dealing with. If you’re not sure, you can query a model to discover its type:

var obj = {name: 'Joe', age: 32}; var MyObjModel = $.Model(obj, 'my-obj-model'); MyObjModel.getType(); // returns "object" var people = [ {name: 'Joe', age: 32}, {name: 'Sam', age: 26}, {name: 'Mary', age: 25} ]; var PeopleModel = $.Model(people, 'people-handle'); PeopleModel.getType(); // returns "array"

Data Binding

Truck’s views can be bound to a model. When you bind a view to a model, Truck creates a mediator to listen to the model. By default, when you modify the data of a model, the model dispatches and event with its handle to notify the system of the change. If a view is bound to that model, the mediator will intercept that handle message and update the view with the new version of the model’s data.

However, you can control whether a model announces its changes or not. When performing any modification of a model, you can provide an optional last parameter of “true”. This tells the model not to publish its changes. This is useful where you need to make a number of changes to a model that a view is bound to and don’t want all the intermediate changes being propagated to the view. When you’re done you can simple re-render the view and it will get the latest state of the model.

Accessing an Object

If you put an object in your model, you can access and modify its data with the following properties:

setProp

getProp

setObject

mergeObject

setProp(property, doNotPropogate)

This method takes two arguments: a property name and a value. If the property does not exist on the object, it will be added. If the property exists, its value will be changed to the provided value.

MyObjModel.setProp('firstName', 'John'); MyObjModel.setProp('lastName', 'Doe');

If we pass an optional, third parameter of “true”, the model will not propagate its changes:

// Do not propagate the modification: MyObjModel.setProp('firstName', 'John', true);

getProp(property)

This method lets you get a property from a model. If the property doesn’t exist you get undefined.

var firstName = MyObjModel.getProp('firstName');

setObject(object, doNotPropogate)

This method sets the content of the model to the provided object. This is useful where you have an empty object model and want to add a number of properties quickly. If the model already has content, this will replace that content with the provided object.

var MyObjModel = $.Model({}, 'my-obj-handle'); MyObjModel.setObject({ firstName: 'John', lastName: 'Doe', age: 23 });

If we pass an optional, second parameter of “true”, the model will not propagate its changes:

// Do not propagate the modification: MyObjModel.setObject(obj, true);

mergeObject(object, doNotPropogate)

This method lets you merge an object into a model’s object. This is useful where you want to update a number of properties with new values quickly, or add new properties.

var MyObjModel = $.Model({firstName: 'John'}, 'my-obj-handle'); MyObjModel.mergeObj({ lastName: 'Doe', age: 32 });

If we pass an optional, second parameter of “true”, the model will not propagate its changes:

// Do not propagate the modification: MyObjModel.setObject(obj, true);

Collections

Collections of objects are the most likely candidate for consumption in a mobile web app. We’re talking lists, long lists. Having a model that handles collections enables easy data binding. With a model, you would have to duplicate the collection and run a poll to check for changes. The more collections and the bigger the collections, the longer it takes for the dirty checking to discover changes. In contrast, Truck’s model handles notifying the system when a model’s collection changes.

As we saw above, you can initialize a collection model by assigning it an array, or you could make an empty array. Collection models have a wide number of methods for manipulating them. These mirror many common array methods, while some are unique to models:

size

push

pop

unshift

shift

concat

insert

unique

forEach

filter

map

pluck

eq

index

sort

reverse

sortBy

delete

run

poke

setItemProp

getItemProp

deleteItemProp

size()

The size method lets you get the number of items in a model’s collection. This is equivalent to [].length.

if (myModel.size()) { console.log('We got items!'); }

push(obj, doNotPropogate)

This method allows you to push data onto the end of a model’s collection. If you pass a second optional true value, the model will not publish it changes to the system.

// Propagate the changes: myModel.push({name: 'Joe', age: 32}); // Don't propagate the changes: myMode.push({name: 'John', age: 25}, true);

pop()

This method lets you pop off the last item in a model’s collection.

var lastValue = myMode.pop();

unshift(obj, doNotPropogate)

This method lets you push data onto the begining of a model’s collection. If you pass an optional second true value, the model will not propagate its changes.

// Add data to the start of the colleciton. // Propagate the changes: myModel.unshift({name: 'Joe', age: 32}); // Don't propagate the changes: myMode.unshift({name: 'John', age: 25}, true);

shift(doNotPropogate)

This method will remove the first item from the beginning of a model’s collection. If you pass a true value, the model will not propagate its changes to the system.

concat(array, doNotPropogate)

This method lets you concatenate an array of data to your model. This allows you to add a large set of items to a model. By passing an optional second true value you can tell the model not to propagate its changes.

// Add more items to the model, // and propagate the change: PeopleModel.concat([ {name: 'Joe', age: 28}, {name: 'Suzie', age 26}, {name: 'Sam', age 31} ]); // Add more items to the model, // but do not propagate the changes: PeopleModel.concat([ {name: 'Joe', age: 28}, {name: 'Suzie', age 26}, {name: 'Sam', age 31} ], true);

insert(position, data, doNotPropogate)

This method allows you to insert an object into your model at the provided position. You can also provide an optional third parameter to tell the model not to propagate its changes. The position value is a zero-based number.

// Insert object at the fifth position: PeopleModel.insert(4, {name: 'Joe', age: 18}); // Don't propagate the change: PeopleModel.insert(4, {name: 'Joe', age: 18}, true);

unique()

Running this method on a collection eliminates any duplicates. This is really useful in cases where the user might have submited the same value multiple times without realizing.

// Eliminate duplicates in the model: PeopleModel.unique();

forEach(callback)

This method allows you to loop over the items in the collection while executing a callback. The callback gets two parameter values - the context and the index. This works exactly like the Array.forEach method.

PeopleModel.forEach(function(person) { console.log(person.name); if (person.age < 21) { console.log('Not old enough!'); });

filter(callback)

This method allows you to filter the contents of a collection. This works the same as Array.filter.

// Function to filter model objects by id: var filterModel = function(id) { var whichPerson = MyModel.filter(function(person) { return person.guid === id; }); console.log(whichPerson.name); }; // Get object with this id: filterModel('asd234asd241');

map(callback)

This method allows you to map a function to each item in the collection. This works the same as Array.map.

MyModel.map(function(person) { console.log(person.name); });

pluck(property)

This method allows you to pluck all the values of a property from a collection. For example, if you wanted to get the age of all people in PeopleModel, you would do the following:

var ages = PeopleModel.pluck('age');

eq(number)

This method lets you get an item from a collection based on its numerical position. The numbers are zero-based.

index(prop, value)

This method lets you find the index value of a collection item based on its property value. It takes two arguments, a property and a value.

var position = PeopleModel.index('name', 'Joe');

sort()

This method performs a normal array sort on the model’s collection.

// Sort the model in ascending order: PeopleModel.sort();

reverse()

This model allows you to reverse the order of a model’s collection.

// Reverse the order of the model: PeopleModel.reverse();

sortBy(properties)

This model allows you to sort a model by a property or multiple properties. By default the sort is in ascending order. You can tell Truck to sort a property set in descending order by prefixing the property with a hyphen.

// Sort by name and age: PeopleModel.sortBy('name', 'age'); // Sort in descending order by age: PeopleModel(-age);

You can sort a collection by as many properties as makes sense for what you are doing.

run(callback)

This method allows you to run an arbitary callback on the method.

MyModel.run(function(model, data) { var names = model.pluck('name'); names.forEach(function(name) { console.log(name); }); data.forEach(function(job) { console.log(job); }); }); </pre>

setItemProp(index, prop, value, doNotPropogate)

This method allows you to set a property and value on an object at a particular index in a collection. By providing an optional forth parameter of true, you can tell the model not to propagate its change.

MyModel.setItemProp(23, 'price', '300.00'); // Tell the model not to dispatch the changes: MyModel.setItemProp(23, 'price', '300.00', true);

getItemProp(index, prop)

This method lets you get the value of a property on an object at a particular index in the collection.

// Get the name property from // object at position 15: MyModel.getItemProp(14, 'name');

deleteItemProp(index, prop, doNotPropogate)

This method lets you delete a property from an object at a particular index in a collection. An optional third true parameter tells the model not to propagate its change.

// Delete name off of object at position: 27: MyModel.deleteItemProp(26, 'name');

Shared Methods

The following methods are shared by models of objects and collections.

delete(data, doNotPropogate)

This method allows you to delete a collection item from the model. You can tell the model to delete and item based on its index value. Index values are zero-based numbers.

// Delete property from model's object: MyModel.delete('firstName'); // Delete 10th object from model's collection: MyModel.delete(9); // Don't propagate the change: MyModel.delete(9, true);

poke()

If you were making a lot of changes to a model and had told it not to propagate its changes, when you are done you can tell the model to publish its current state by poking it. This takes no arguments.

// Modify a model and do not propagate its changes: PeopleModel.pop(true); PeopleModel.unshift({name: 'Dan', age: 42}, true); // Let publish the model's current state: PeopleModel.poke();

getHandle()

Find out what handle a model is using.

var handle = PeopleModel.getHandle();

setHandle()

Like most things in Truck, you can change the handle a model is using. When would you want to do this? If you want the models changes to be captured by a mediator listening to a different handle. <pre class="prettyprint linenums">`// Switch the people handel to the employee handle: PeopleModel.setHandle('employee-handle');

purge();

This method allows you to empty a model. This sets an object or array to empty. The object will have no properties and the array will have no length.

// Purge a model's object: ObjectModel.purge() // object is now {} // Purge a model's collection: ArrayModel.purge() // array is now []

hasData()

This method lets you find out whether you model has any data. If the data has an empty object or array, this will return false.

isIterable()

You can find out if a model is iterable or not using this method. This is similar to using getType() to find out if the model is a collection. An object model will always return false. In contrast, even an empty model collection will return true because even an empty array supports forEach, etc.

getData()

This method returns whatever the current data of a model is.

var people = PeopleModel.getData();

getLastModTime()

This method lets you find out the last time the model was changed.

Conclusion

Visual Studio Code is a new text editor from Microsoft. It’s cross-platform, with versions for Windows, Mac and Linux. And, best of all, it’s free. The main purpose of this editor is for code Web-based applications. You can also work with some other languages, like C#, etc. If you write JavaScript on the client side and also on the server side, this could be your dream editor. It supports basic Git tasks without having to leave. It also shows you the diffs between your checked in code and the current changes. It supports gulp tasks: it parses your gulp file, identifies any tasks you defined and makes them available through it task menu. Using NPM, you can create a gulp task to do almost anything you need. With Visual Studio Code, you can debug Node on the server side and step through the call stack. Easy-peasy.

Visual Studio Code really shines when you use it to write TypeScript. But whether you’re writing TypeScript that will get converted to JavaScript, or you’re just writing straight JavaScript, you’ll want to take advantage of TypeScript to make your JavaScript better.

TypeScript Declaration Files

TypeScript is a superset of JavaScript that offers optional typing. It uses interfaces to define the types of objects, functions and arrays. When writing TypeScript, you may find you need to create a declaration file, myCode.d.ts, to describe the types for your TypeScript. The TypeScript declaration files enable Visual Studio Code to parse your JavaScript and provide real time analysis, including code completion, error checking, refactoring, etc.

The JavaScript that it produces is really close to what I would have written. Only one thing bugs me about it: the formatting. The defualt JavaScript gets output like C#/Java. There is no way to make it format like normal JavaScript. Regardless whether you or your team is using TypeScript on a project, normal human beings, especially users, will have to look at that JavaScript at some point. Any serious company has a style guide for the JavaScript they deploy.

Unfortunately the Visual Studio Code and TypeScript team both think we should only care about minified JavaScript. Nobody in their right mind tries to read minified JavaScript. Well, actually I have. It’s not fun. Companies need a way for the hundreds of thousands of people who know standard JavaScript to look at and comprehend their code.

So… To make a long story short, I came up with the following workaround to change the default formating of TypeScript’s JavaScript output. You just need to pipe your stream to jsbeautifier. First you need to import both TypeScript and JSBeautifier into your Gulpfile:

Recently I took the plunge and converted ChocolateChipJS into TypeScript. ChocolateChipJS started off in 2006 as a collection of utility functions to do basic DOM traversal and manipulation. I was not allowed to use jQuery by my employer because it was open source. Whatever we used had to be created by us. Rather than constantly recreating the wheel, I started putting together a utility library. 

The biggest impetus came with the launch of the iPhone in 2007. There was no native sdk. If you wanted to make an “app”, you had to use HTML, CSS and JavaScript. It was not long before various libraries and frameworks began to appear for creating mobile Web apps for the iPhone. I tried out a lot of them. They all shared one problem – poor performance. After a lot of frustration, I though I would try to do something about it. I dug up my utility functions and started refactoring, and refactoring, and refactoring. The result was ChocolateChipJS, a JavaScript DOM library created especially for mobile browers. Its small but also fast at everything it does.

So, time went by and a went through many revisions, writing it from scratch several times for better performance, etc. Eventually I wound up breaking it into small pieces. I used “gulp” to parse the files, replace variales for some global values and a number of gulp modules to replace, refine, and stitch everything together into the final file, run it through a linter, minifier and output unit tests. 

After spending some time toying around with TypeScript, I decided I’d convert the source code into TypeScript. For end users, they’d still get the JavaScript functionality they were expecting. It would just be one more step add to my already complex build process.

Well, it actually took me three attempts before I wound up with what I wanted. This was partly due to my unfamiliarity with TypeScript best practices, as well as what I wanted to achieve with the conversion. I was working with a DOM utility library, so it wasn’t the best candidate for classes and other advanced features in TypeScript. After three failures, I decided to scale back what I was trying to do. Fortunately, everything came together and I was very happy with the results.

Previously I had made a TypeScript declaration file for my library. In my previous attempts I did not use the declaration file because I though it would be too restricting. This time I made it the basis for the code I was writing. Granted, I had to make some structural changes to how some of the static methods were defined. And with that, everything actually went fairly smoothly. I did have to do some type casting to coerce a type from specific to general. But that was no big deal. Oh, and the declaration file provided excellent Intellisense as I was writing the code. Surprisingly, I was able to reuse a lot of JavaScript once the method signatures were properly defined and the static properties had there types properly defined in the declaration file. 

My main take away from this is that if I start a new TypeScript project, espeically if it’s from scratch, I would first define all my TypeScript interfaces. Then I’d write the actual TypeScript.

ChocolateChip-UI’s Big Brother

I’m the author of ChocolateChip-UI. It started with the launch of the iPhone. Steve Jobs had proclaimed that the only way to make apps for the iPhone was Web apps. There were about a dozen different libraries to approximate the native look of iOS for web apps. Except that none of them were very good. Some of them were quite aweful. They were all underpowered. I, like many, was very disappointed. I wanted better tools.

I began thinking that I would try making my own framework. I started off simple, trying to figure out how to make a basic window full of content act like what was typically in an iPhone app. Then came lists of various layout types. And, one by one, a menagery of widgets. In the end I had a decent library for iOS. But then the Android crowd started asking me for an Android theme. I got myself an Android phone for testing. This was Gingerbread times. And the performance in the Android browser was so bad and the CSS so buggy. It reminded me of all the things I hated about IE6. Except that in a mobile browser in those days you had no way to troubleshoot anything short of alerts. So debugging was abysmal, worse than IE6.

Year by year, things improved, bugs got fixed, users asked for new features, mobile operating systems got fresher themes. I tinkered away, improving on old code bases. Every other year I would rewrite the JavaScript and CSS from scratch.

Recently, I was getting ready for a big upgrade, but I wasn’t sure what I was going to do. I had all the layouts and widgets I wanted. There didn’t seem to be anything I lacking. Most bugs were pretty minor. So I thought long and hard about the very nature of the framework. I had originally designed it as a front end for other frameworks, whether Backbone, Angular or whatever. I didn’t want to take a stand on MV*. I’d leave that up to the developer. I was just providing a UI, a colorful veneer, over whatever the developer was using to build their app.

Let There Be Models

I decided the framework could use a true model. I took a hard look at Backbone. Noted what I liked and what I didn’t like. Then I started playing around with data abstractions in JavaScript. I wound up with a nifty object factory that would take data - whether and object or an array of objects - and conceal it in a object instance. The only way to access the data was through the model’s interface. The concept seemed to be working really well, so I thought I should take a crack at making a similar module for controllers. But I wanted the controllers to do things others didn’t. You could designate how many times a controller could run, or when. And then with a model and a controller, I tought about views. ChocolateChip-UI is basically just a view. But it isn’t organized as a module - things are all over the place. So I started build a view module. And I made it so you could bind the view to an element, or bind events to it, or bind it to a model for data binding, etc. When I was done, I had a Model-View-Controller framework.

Now, after creating my model, view and controller modules, I decided to throw out ChocolateChipJS and instead create a new DOM library that had the same API as jQuery. This would mean no learning curve for developers. Plus, if you wanted to add jQuery, it wouldn't require any changes to the framework. In the end I had a DOM library that replicated jQuery but was less than half the size. Instead of jQuery’s Ajax, it had the new, modern Fetch API. Instead of jQuery’s stale Deferred object, it uses ES6 promises with a polyfill for older browsers.

A New Framework Deserves A New Name

While sitting at my desk and going over all the notes and comments I had made while I was working, I realized the framework needed a new name. The descriptions were vivid: mechanics, like a tank, the engine, serves as wheels, a chassis. I realized I was building this thinking not of chocolate but of vehicles. So I chose the name TruckJS. Trucks are serious vehicles. They haul heavy loads. A quick search and I had the domain and NPM projects. And so, I present you TruckJS, a complete, standalone MVC framework for building mobile web apps. It has models, views, mediators, data binding, routers, local data persistence, touch gestures, etc.

At the World Wide Developer Conference last week, Apple introduced Safari 9. Every version comes with flashy new CSS features and JavaScript improvements, this year no different. We got prefix-less CSS properties galore, and snap-points for CSS-based carousels. These allow you to define how the carousel scrolls through your content, snapping to the elements as you wish. This is a feature that was first introduced by Microsoft on IE. Later they proposed it as a standard. The current form of the stardard is slightly different from the original version introduced by Microsoft. It is currently supported by Safari and Firefox, with IE supporting the Microsoft version. Apple also announced support for new ECMAScript 6 features: classes, weak sets, template literals, tagged templates, computed properties, symbol object and object.asign. Somehow the fat arrow function for lexical "this" didn't make it into this version. Yeah, I'm disappointed on that one.

The browser itself also got updated with new features. In particular, they announced pinned sites. But more importantly, they introduced a completely revamped Web inspector. Watching the presentation, I knew this was going to be huge for developers. Then I sat down and started using it on real stuff. Oh my God! My mind was blown. I felt like a kid on Christmas morning.

The Web inspector is useful for look at the DOM tree your browser has assembled from your code. This is especially useful when your site is put together from disparate parts or by consuming dynamic data.

It's All About Types

JavaScript is an amazing language, flexible, forgiving and dynamic. No need to build and run, no compile. It runs when the browser loads. JavaScript is a weak typed language, whereas languages like Java, C# and others are strongly typed. Ok, this means that in JavaScript you can do the following:

var value = null; value = "This is a string value." value = 12345; varlue = ['1','2','3','4']; value = {one: 1, two: 2, three: 3};

As you can see, we have assigned many different types to the same variable without a problem. JavaScript will not care. Other languages would have a heart attack. JavaScript's trick of coercing types can also have unexpected results. Back in 1995 when Brendan Eich created JavaScript for Netscape Navigator, it's purpose was for enabling simple interactions between the user and the Web page. There was no though of single page apps or apps at all. It was intended as a simple scripting language. JavaScript was give type coercion to make it easier for developers to do certain types of concatenation. But if you are not aware of this, you might get some unexpected results:

var sum = function(num1, num2) { // Return the sum of two numbers: return num1 + num2; }

Now let's use this function in some unexpected ways:

sum(1, 2); // returns 3 sum(1, "whater"); // returns 1whatever sum("1", 2); // returns "12" // JavaScript does type coercion when we compare values: (1 == 1 ); // returns true (1 == '1'); // returns true

In the first example, our function returned the sum of 1 and 2, as expected. But in the other examples we got some unexpected string concatenation because JavaScript looks at the string arguments provided and figured you really wanted to do string concatenation, so it converted the numbers into strings and returned the concatenated result. Similarly, when we compare to identical numbers, we get true, and when we compare a number with a string representing that number, JavaScript performs type coercion and considers them equal, although technically they are not.

If you're a seasoned JavaScript developer, you know you need to check your parameters with typeof and instanceof to be sure your dealing with the types you are expecting. And you could use functions such as parseInt, parseFloat, Number and String to convert one type to another. After typos, I'd bet the biggest cause of bugs is caused by a function getting an unexpected type as an argument. This is really hard to avoid when you have a large project with a lot of thrid party dependencies. Or even when your own code base grows to several thousand lines across many files. You just can't see the whole picture to catch these types of bugs.

To see what's going on we usually depend on console.log or console.dir so we can see the values of variables and arguments. If I had a dollar for every one of these I've written in the past 10 years I'd be a billionaire.

Web Inspector to the Rescue

This brings me to Safari 9. Remember that 80's song "Last Night a D.J. Saved My Life"? That's how I feel about the Web inspector in Safari 9. Last night I loaded some code in Safari 9 and used the new Web inspector to see what was going on. Using the debugging tools was like having an enlightenment.

OK, so what's there and why was I so excited? Well, it was the special things that the Safari team must have created exclusively for me: type anotations. Statically typed languages, such as Java, C# and Swift, use type annotations to show what type is expected. TypeScript, also offers optional type annotations, and like Swift, can infer types. The new Web inspector in Safari 9 does the same thing, it shows you all the types that the JavaScirpt engine is expecting based on the current state of the code. Like TypeScript, it infers types based on your usage, and shows you the return types for functions and methods. I can't tell you how useful this is when you're trying to figure out why something isn't working. But its the difference between banging your head against the wall in frustration to finding a bug quickly, fixing it and moving on. I can't tell you how many times I've spent hours monitoring thousands of lines of code trying to find why it wasn't working when the culprit was a wrong type being passed somewhere unexpected and the code not handling it. Being able to see types in the debugger will give you a better understanding of what your code is doing and help you spot those errant types.

So, let's take a look at that Web inspector. When you open it, you want to head right over to the debugger tab. Where going to set a breakpoint on our css method to see what happens as our code tries to apply CSS to some list items:

    Now, all we have to do is reload the page and let our code in the page try to use the css method. The code we're using is this:

$('li').css({color: "red", padding: "20px"});

And here's what happens:

    In the above image you can see that because we've passed an object as the argument for css, that it shows the name property as type "Object" and the optional second parameter, value, is undefined. You'll notice that in the right column the Web inspector uses little colored symbols to indicate types:

    O is for Object, f for function, N for Number, S for string and ? for undefined. Also I was pleasantly surprised to see the the Web inspector shows you when a number is an integer or a float.

If we hover over the property argument in css, we'll get a popover showing us what the object's value is at the moment:

    At this point we can use the down arrow in the top left panel to step through our code. If you do this in Chrome or Firefox, this walks you through all of your code. In Safari 9 this steps you through only the code immediately involved in our breakpoint, which is css. So, here what our first step looks like:

    Here you can see all the different types being revealed as we step through our code. Notice the column on the right shows all the current values according to what line of code you're on. You can see that we're setting the color and padding of the list items.

If we step further, we'll wind up on another method, camelize, which the method css uses to turn hyphenated properties into camel case:

    If we hover over the camelize variable "string", we'll get a popup with its value, in this case, "padding":

    console.log is dead! Long live the console!

So, I said you didn't need to use console.log any more to inspector your code. I was telling a half lie. With Safari 9, you don't need console.log to find out what your code is doing, but you can still use the console in other ways. You can set a break point in your code via the debugger panel, then invoke that method or any method that will use it in the console.This will cause the debugger to kick in and enable you to walk the object graph. This is absolutely brilliant. This didn't seem to work in the Chrome developer tools or in the Firefox Web tools either. I think this is going to prove to be a very handy feature to use for troubleshooting.

Below we've set a breakpoint at "addClass" and in the console we've entered the code: $('li').addClass(1234). Of course, 1234 is not a valid value for a class. That's the point.

    When we hit return, we get the following. Notice how it shows us that we're pass a number as an argument (type Integer in the code and className is 1234 in the right column):

JavaScript is a dynamically typed language. For developers coming from languages with static typing, this will be the aspect of the language that they dislike the most. Languages with strict typing require you to define the types of all values before compilation. Because it runs in the browser, JavaScript uses dynamic typing. This means that a variable that initially held a number might later have a string reasigned to it. If you have written your code to expect that variable to be a number and somehow it gets a string asigned to it, your code will break. For statically typed languages, the types of all values are checked during compilation and errors are thrown if they do not match. Since JavaScript runs in the browser, there is no initial checking of types. This means that the onus of type checking is on the developer. If you need a variable to be a number before you use it, you need to check that it is a number.

To complicate matters, JavaScript has a feature that can be both useful and a pain: type coercion. JavaScript looks at operations you are trying to perform and if the types don't match, it will try to convert one of them for what it thinks you are trying to accomplish. For example:

"2" * 2; // returns 4 '4' / 2; // returns 2 '4' - 1; // returns 3

However, if we use the addition operator with mixed types we will not get addition, but string concatenation:

'1' + 1; // returns '11'

This happens because the addition operator is also used to do string contatenation. Therefor it coerces the number to strings if any portion of the operation contains a string. To get around that problem, you could always perform another operation first:

'2' + 2; // returns '22', not what we wanted. '2' * 1 + 2 // returns 3. The multiplication coerced the string into a number.

It is not safe to expect coercion to work always. You should instead check the type of the value before using it.

Types

JavaScript has the following types:

Undefined

Null

Boolean

String

Number

Object

Symbol

If you're used to other languages, you might find it strange to see Undefined and Null as object. JavaScript is an object-oriented language and so it designates even Undefined and Null as objects. Symbol is a type new to ECMAScript 6. We won't cover the Symbol type here because it is not widely supported yet.

You might notice that the above list is missing the following: Array, Function, RegExp, Date, Math, Error, arguments, etc. That's because these objects are derived from Object. In ECMAScript 6 we also get new collections: Maps, Sets, WeakMaps and WeakSets. For a thorough list and explanation of JavaScript objects, consult Mozilla's documentation.

Undefined

For developers coming from other languages, Undefined can have them scratching their heads. Undefined is a property in the global scope. Also, it is not a reserved word, so, for instance, you could nave a variable in a non-global scope undefined without issue. However, you would not be able to do that if your were in the global scope. Undefined is returned whenever something doesn't have a value. For example, a variable declaration without a value assignment:

var something; // undefined

Similarly, with arrays, because you can have an empty index, those would be undefined as well:

var arr = [1,,3]; // [1, undefined, 3] arr[0] // 1 arr[1] // undefined arr[2] // 3

In the case of functions, if they do not return a value, then they automatically return undefined:

var func = function() {}; func(); // returns undefined

If you define a function that performs an operation that does not return a value, the function will automatically return undefined. This is because JavaScript functions must always return something. So, if you see your functions returning undefined when you are not explicitly returning anything, this is expected behavior.

undefined is not a object but a literal. You can assign it to variable or object property to set that to undefined:

var foo = "abc"; foo = undefined; // Test if foo is undefined now: foo === undefined; // returns true typeof foo; // returns "undefined".

Null

Unlike undefined, null is an empty value. And it is not global. Null cannot be overridden to have some other value. A variable or an object can have a null value. Giving a variable or object a null value is a common way of disposing of it. This does not actually delete the item, but just removes whatever value or properties it had. Because of coercion it is possible that null and undefined appear to be the same thing, although they are not:

var foo; var bar = null; foo === bar; // false foo == bar; // with coercion, true

Why this coercion occurs is because fundamentally foo and bar both have no practical value. Although a type, null is not an object but a literal.

Boolean

Boolean can be objects or literals. A boolean has two possible values: true or false. The new keyword is required when using the object version of boolean:

var foo = new Boolean(false); var bar = new Boolean(true); if (!foo) return false; // Will return false if (bar) return true; // Will return true

The boolean object cannot be coerced. So the following will fail:

var foo = new Boolean(false); var bar = new Boolean(true); foo === false; // returns false, not true bar === true; // returns false, not true

Object booleans work with normal conditional construction with if as shown in the first example.

One thing to keep in mind when using the object boolean is that if you use any value other than false as the value, it will generate a true boolean. This includes using a false boolean to create a new boolean:

var bool_1 = new Boolean(false); bool_1.valueOf(); // returns false; var bool_2 = new Boolean(bool_1); bool_2.valueOf(); // returns true var bool_3 = new Boolean('Whatever'); bool_3.valueOf(); // returns true var bool_4 = new Boolean(123); bool_4.valueOf(); // returns true var bool_5 = new Boolean(-1); bool_5.valueOf(); // returns true

Using the boolean literal avoids this problem, and there really is no reason to use the Boolean object to create booleans. Boolean literals are created with the boolean values true or false. When using the boolean literal, JavaScript will borrow the Boolean object's methods, allowing you to use them on the literal:

var bool_1 = false; bool_1.valueOf(); // returns false; var bool_2 = true; bool_2.valueOf(); // returns true;

Boolean Coercion

Because of coercion, JavaScript can treat non-boolean values as booleans. The example that might bite the most is 0:

0 === false; // returns false 0 == false; // returns true var foo = 0; if (!foo) { // do something } else { // do something else }

In the above example with the if keyword, because foo is 0, it will be treated as false. Now image if you were looping over an array of numbers and one had a value of 0, if you where doing a value check, you would not be able to get it because it would always test false:

var numbers = [0, 1, 2]; numbers.forEach(function(ctx, idx) { if (ctx) { console.log(ctx); } }); // This will output: 1, 2 // Not 0, 1, 2

To avoid this type of boolean coercion, you need to use the identity operator:

var numbers = [0, 1, 2]; numbers.forEach(function(ctx, idx) { if (ctx === 0 || ctx) { console.log(ctx); } }); // This will output: 0, 1, 2

String

Like the boolean type, string also has two forms: object and literal. The string object:

var str = new String("This is the text."); console.log(str); // returns "This is the text."

Creating a literal string is more straightforward:

var str = "This is the text."; console.log(str); // returns "This is the text."

When using a string literal, JavaScript borrows the methods of the string object. As such there really isn't any reason to use the string object to create and manipulate strings. In JavaScript, string are immutable:

// Create a string and perform string concatenation: var fruits = "Apples and orange"; fruits + "s."; // outputs "Apples and orangess" console.log(fruits); // returns "Apples and orange"

To get the result of string mutation, you need to assign the result to a variable. Usually this is done by assign the new value back to the original variable, replacing its value:

var fruits = "Apples and orange"; var fruits = fruits + "s."; // or: var fruits += "s."; console.log(fruits); // returns "Apples and oranges."

The above string operation worked as we would expect because we replaced the value of the unmutated string with the value of the mutated version.

Math operations

To implement string concatenation, JavaScript uses the addition operator. Using other math operators will not work but return a special number value, NaN, meaning "not a number". This is returned when trying to perform math operations on a non-number.

var foo = "This is Foo!"; foo * 2; // returns NaN

Number

Like booleans and strings, the JavaScript number type has two forms: object and literal. We use the new keyword to create a new number object:

var one = new Number(1); console.log(one); // returns 1 // Use a quoted number: var two = new Number("2"); console.log(two); // returns 2

Like string objects, there really is no reason to use number objects. Number literals are more straightforward:

var one = 1; console.log(one); // returns 1 var two = 2; console.log(two); // returns 2

Like strings, numbers in JavaScript are immutable. So to perform math operations you need to assign the result to the original variable or a new one:

var num = 1; num + 1 // returns 2 console.log(num); // returns 1 // Reassign the new number to num: num += 1; // returns 2 console.log(num); // returns 2

Object

Like string and number, object has both and object constructor version and a literal version. You can create an object with the constructor like this:

var obj = new Object(); typeof obj; // returns "object"

Although this is a simple way to create a new object, it is not very useful. In practice most developers use a function as an object constructor. This is possible because functions are derived from Object.

var Person = function(name) { this.name = name; this.revealName = function() { return this.name; } } var joe = new Person("Joe"); joe.revealName(); // returns "Joe" typeof joe; // returns "object"

We can also create an object literal. This does not have a constructor, but it does allow quickly defining an object:

var person = { name : "Joe", revealName : function() { return this.name; } }; person.revealName(); // returns "Joe" typeof joe; // returns "object"

From the base Object a number of other object types are derived: Array, Function, RegExp, Date, Math, Error and arguments.

var arr = [1,2,3]; typeof arr; // returns "object" var func = function() {}; typeof func;// returns "function" // But: func instanceof Object; // returns true var date = new Date(); typeof date; // returns "object"

Although these are all considered objects by the JavaScript engine, they have their own individual methods that give them their particular functionalities. For example, functions can be called or applied in the code.

After writing the repeater for ChocolateChip-UI’s $.template method, we though it would be nice to have a way of do a declarative repeater, like Angularjs and other frameworks offer. You would use the attribute data-repeat and give it the value of the repetive data you want it to render. A template might look like this:

<ul data-repeater="luminaries" class='cloak'> <li>[[= data.firstName ]], [[= data.lastName]]</li> </ul>

Our data for this might look like this:

var renaissanceLuminaries = { persons: [ {firstName: "Albert", lastName: "Einstein", letter: "a"}, {firstName: "Steven", lastName: "Hawking", letter: "b"}, {firstName: "Neil", lastName: "deGrasse Tyson", letter: "c"}, {firstName: "Leonardo", lastName: "Da Vinci", letter: "d"}, {firstName: "Nicholas", lastName: "Copernicus", letter: "e"} ] };

We'll only be interested in get the persons property because it holds the array of data we want to output in our repeater.

Our $.template.repeater method already exists, although it expects three parameters: the target container, a template to repeat, the data to iterate over. We can change this method to work a little different. We want it to check for declarative repeaters when no parameters are parsed. We'll check for any elements with the attribute data-repeat, and then we'll grab its value. This will be the name of the data array we want to iterate. The problem is, when we extract this from the DOM node, we get a string value. In most cases the data you have that you will want to use with a repeater is inside a jQuery DOM ready event. This means the data scope is limited to that. Meanwhile, ChocolateChip-UI's code is getting parsed a load time, before this happens, so it has a different scope. As such the template method doesn't have access to the scope where your data is defined. Now if your data was exposed to the global scope, we could access it with our string value by doing something like:

var data = window['myDataRepeatValue']

But this is really, really bad. Never do this. You do not want to polute the global space unnecessarily. Thinking about this, We decided to use a new object on the $.template object:

$.template.data

You can assign data to it like this:

$.template.data['people'] = ["Joe", "Sally", "Tom", "Jane", "Bill"];

If you think about what this is doing with your data, you might realize that in essence you are duplicating it. This might be fine for small amounts of data, but as the amount of data being used in repeaters increases, this is a waste of your memory. So we decided that after render the repeater, we will delete its data from $.template.data automatically, allow it to be garbage collected.

So, let's make this happen. Our original repeater code looked like this:

$.template.repeater = function( element, tmpl, data) { var template = $.template(tmpl); if (!$.isArray(data)) { console.error('$.template.repeater() requires data of type Array.'); return '$.template.repeater() requires data of type Array.'; } if ($.isArray(data)) { data.forEach(function(item) { $(element).append(template(item)); }); } };

We need to add out new data holder to this, and we want to expose an index value that we can output in our template:

$.template.data = {}; $.template.index = 0; $.template.repeater = function( element, tmpl, data) { //... };

As we mentioned, we want the $.template.repeater to look for declarative templates when no parameters are passed, so we need to do a check for no parameters. The easiest way is to check for the first one, element. If it is undefined, then there are no parameters:

$.template.data = {}; $.template.repeater = function( element, tmpl, data) { if (!element) { // When no parameters, look for declarative repeaters! } }

If there are parameters, we want to continue with the usual repeater processing:

$.template.data = {}; $.template.repeater = function( element, tmpl, data) { if (!element) { // When no parameters, look for declarative repeaters! } else { // Exit if data is not repeatable: if (!$.isArray(data)) { console.error('$.template.repeater() requires data of type Array.'); return '$.template.repeater() requires data of type Array.'; } else { var template = $.template(tmpl); if ($.isArray(data)) { data.forEach(function(item) { $(element).append(template(item)); }); } } } }

Next, we need to find all the repeaters on the page:

var repeaters = $('[data-repeater]');

We need to loop the returned value so that we can address all declarative repeater templates:

var repeaters = $('[data-repeater]'); // Set the index value to 0 before looping; $.template.index = 0; repeaters.forEach(function(repeater) { // Get the template from inside the repeater: var template = repeater.innerHTML; // Get a reference to the physical repeater for use later: repeater = $(repeater); });

Next we want to examine the repeater to see what data was designated for its repetition:

var repeaters = $('[data-repeater]'); // Set the index value to 0 before looping; $.template.index = 0; repeaters.forEach(function(repeater) { // Get the template from inside the repeater: var template = repeater.innerHTML; // Get a reference to the physical repeater for use later: repeater = $(repeater); // Get the value of "data-repeat". // This will be the data we use // to loop while rendering the template: var d = repeater.attr('data-repeater'); });

After getting the data-repeat value, we need to check if it is underfined, or if it matches a value stored on the $.template.data object. If there is a problem, we want to stop and return a console error so that the developer knows to check what caused this:

var repeaters = $('[data-repeater]'); // Set the index value to 0 before looping; $.template.index = 0; repeaters.forEach(function(repeater) { // Get the template from inside the repeater: var template = repeater.innerHTML; // Get a reference to the physical repeater for use later: repeater = $(repeater); // Get the value of "data-repeat". // This will be the data we use // to loop while rendering the template: var d = repeater.attr('data-repeater'); // If the "data-repeater" value is undefined, // or it does not match a value stored in // $.template.data, log and error: if (!d || !$.template.data[d]) { console.error("No matching data for template. Check your data assignment on $.template.data or the template's data-repeater value."); return; } });

With error checking out of the way, we can deal with rendering the repeater template. First we need to empty the current container, effectively removing its current template. We also want to remove the class "cloak" so that the content being inserted gets display to the screen:

repeater.empty(); repeater.removeClass('cloak');

Next we need to parse the template that we extracted from the repeater:

repeater.empty(); repeater.removeClass('cloak'); var t = $.template(template);

We can now iterate over the data stored in $.template.data:

repeater.empty(); repeater.removeClass('cloak'); var t = $.template(template); $.template.data[d].forEach(function(item) { repeater.append(t(item)); // Increase the value of index: $.template.index += 1; });

Lastly, we want to delete the data stored on $.template.data to free up the memory:

repeater.empty(); repeater.removeClass('cloak'); var t = $.template(template); $.template.data[d].forEach(function(item) { repeater.append(t(item)); // Increase the value of index: $.template.index += 1; }); delete $.template.data[d];

So, here's the complete version of the template repeater:

$.template.data = {}; $.template.repeater = function( element, tmpl, data) { if (!element) { var repeaters = $('[data-repeater]'); $.template.index = 0; repeaters.forEach(function(repeater) { var template = repeater.innerHTML; repeater = $(repeater); var d = repeater.attr('data-repeater'); if (!d || !$.template.data[d]) { console.error("No matching data for template. Check your data assignment on $.template.data or the template's data-repeater value."); return; } repeater.empty(); repeater.removeClass('cloak'); var t = $.template(template); $.template.data[d].forEach(function(item) { repeater.append(t(item)); $.template.index += 1; }); delete $.template.data[d]; }); } else { // Exit if data is not repeatable: if (!$.isArray(data)) { console.error('$.template.repeater() requires data of type Array.'); return '$.template.repeater() requires data of type Array.'; } else { var template = $.template(tmpl); if ($.isArray(data)) { data.forEach(function(item) { $(element).append(template(item)); }); } } } };

With this we can now do the following:

<ul data-repeater="luminaries" class='cloak'> <li>[[= $.template.index + 1 ]]: [[= data.firstName ]], [[= data.lastName]]</li> </ul> <script> // Define an object with an iterable property (persons): var renaissanceLuminaries = { persons: [ {firstName: "Albert", lastName: "Einstein", letter: "a"}, {firstName: "Steven", lastName: "Hawking", letter: "b"}, {firstName: "Neil", lastName: "deGrasse Tyson", letter: "c"}, {firstName: "Leonardo", lastName: "Da Vinci", letter: "d"}, {firstName: "Nicholas", lastName: "Copernicus", letter: "e"} ] }; // Assign the iterable portion of the object to $.template.data: $.template.data['luminaries'] = renaissanceLuminaries.persons; // Parse declarative repeater: $.template.repeater(); </script>

Because ChocolateChip-UI's templates use JavaScript for the variable parsing, you can use normal JavaScript with your template variables. Notice how we added 1 to the value of $.template.index before it gets rendered. Or we could run a string fuction, such as String.toUpperCase() to capitalize the last name:

<ul data-repeater="luminaries" class='cloak'> <li>[[= $.template.index + 1 ]]: [[= data.firstName ]], [[= data.lastName.toUpperCase() ]]</li> </ul>

ChocolateChipJS and ChocolateChip-UI have had a template module for a long time. Templates allow you to extract portions of your app whose content will change depending on the data available. Using $.template(), you can create templates to do the following:

(function(){ "use strict"; $.extend($, { templates : {}, template : function ( tmpl, variable ) { var regex, delimiterOpen, delimiterClosed; variable = variable ? variable : 'data'; regex = /\[\[=([\s\S]+?)\]\]/g; delimiterOpen = '[['; delimiterClosed = ']]'; var template = new Function(variable, "var p=[];" + "p.push('" + tmpl .replace(/[\r\t\n]/g, " ") .split("'").join("\\'") .replace(regex,"',$1,'") .split(delimiterOpen).join("');") .split(delimiterClosed).join("p.push('") + "');" + "return p.join('');"); return template; } }); })();

$.templates is just a convenient storage place for templates so you can access them repeatedly.

To start of, you have two ways to define a template, as a string or in a script tag. If your template is very simple, a string might make for sense. If it's at all complex, you'll want to use a script tag. Below are two different template approaches:

var simpleTemplate = '<li>[[= data.firstname ]] [[= data.lastname ]]</li>';

We could use the above template to output one list item to a list:

<ul id='listOfPeople'></ul> <script> $(function() { var data = {firstname: "John", lastname: "Doe"}; var listTemplate = '<li>[[= data.firstname ]] [[= data.lastname ]]</li>'; var parsedTemplate = $.template(listTemplate); // Render the template to the page: $('#listOfPeople').html(parsedTemplate(data)); }); </script>

Notice the use of the keyword data to indicate the values the template will display. This is required.

Now, as I mentioned earlier, this is fine for one person. But if you have multiple items to render, you'd have to write a loop:

<ul id='listOfPeople'></ul> <script> $(function() { var data = {firstName: "Albert", lastName: "Einstein"}, {firstName: "Steven", lastName: "Hawking"}, {firstName: "Neil", lastName: "deGrasse Tyson"} ]; var listTemplate = '<li>[[= data.firstname ]] [[= data.lastname ]]</li>'; var parsedTemplate = $.template(listTemplate); // First empty the list: $('#listOfPeople').empty(); // Render the template to the page: data.forEach(function(person) { $('#listOfPeople').append(parsedTemplate(person)); }); }); </script>

This isn't that hard, but it would be nice to have an easier way of outputting arrays of data. That's where repeaters come in to help. A repeater is a template feature that consumes and iterable data type and outputs it as a list. Since we don't have one, we're going to make one for ChocolateChip-UI. Let's consider what we need to make this happen. We already have a template engine. So, when need a reference to the element that will receive the repeated template, we need the template to repeat, and we need the data it will use. With this we can set up the following:

$.template.repeater = function( element, tmpl, data) { // code here };

We're defining a method directly on the $.template method for the purpose of orthogonality. Our repeat just expects a referce to a defined template, as yet unparsed. Therefore, we will need to parse the template before we can do anything with it:

$.template.repeater = function( element, tmpl, data) { var template = $.template(tmpl); };

Next we want to make sure the data is iterable and is an array. We'll use ChocolateChip-UI's $.isArray() method to check for that. If it is not an array, we want to notify the developer by logging and error to the console. We also return the string. This is so, if you check the return, you can test to see if the repeater received and iterable array or not. That's because you can check the console output from within your code, so this provides an opportunity to verify the data:

$.template.repeater = function( element, tmpl, data) { var template = $.template(tmpl); if (!$.isArray(data)) { console.error('$.template.repeater() requires data of type Array.'); return '$.template.repeater() requires data of type Array.'; } };

And now finally, we need to do the loppy-loop thingie:

$.template.repeater = function( element, tmpl, data) { var template = $.template(tmpl); if (!$.isArray(data)) { console.error('$.template.repeater() requires data of type Array.'); return '$.template.repeater() requires data of type Array.'; } if ($.isArray(data)) { data.forEach(function(item) { $(element).append(template(item)); }); } };

With the above template repeater, we can now do the following:

<ul id='listOfPeople'></ul> <script> $(function() { // Our data as an array of objects: var luminaries = { persons: [ {firstName: "Albert", lastName: "Einstein"}, {firstName: "Steven", lastName: "Hawking"}, {firstName: "Neil", lastName: "deGrasse Tyson"} ] }; // Define our template: var listTemplate = '<li>[[= data.firstname ]] [[= data.lastname ]]</li>'; // First empty the list: $('#listOfPeople').empty(); // Render the template to the page using the repeater. // We pass it only the "persons" array from our object, // since that's the repeatable part: $.template.repeater($('#listOfPeople'), listTemplate, luminaries.persons); }); </script>

This is much simpler, easier to implement and maintain. And it gives us the following output:

<ul id="listOfPeople"> <li>Albert, Einstein</li> <li>Steven, Hawking</li> <li>Neil, deGrasse Tyson</li> </ul>