JavaScript – 9bit Studios

Native JavaScript Promises

Ian — Tue, 21 Feb 2017 18:39:41 +0000

Promises are awesome and the new native promise JavaScript implementation is great and pretty much entirely supported across all modern browsers. In the past developers used various different libraries like jQuery.Deferred() or Q to handle their promise implementations. However, with the native Promise object now in JavaScript in most if not all environments, these are no longer really needed. They’ll still work fine, but it would be advisable to start moving towards the native implementations of promises.

Below are 2 different examples of how you could use the native Promise object in JavaScript…

//2 different examples of promise usage.  
jQuery(document).ready(function() {  
    
    var test = [];

    function getPost(id){
        var def = new Promise(function(resolve, reject){
            jQuery.ajax({ 
                url: "https://jsonplaceholder.typicode.com/posts/" + id,
                type: "GET",
                dataType: "json",
                success: function(data){
                    test.push(data);
                    resolve(data)
                },
                error: function(){
                    reject();
                }
            }); 

        });

        return def;
    }

    // Implementation #1
    getPost(1).then(function(data){
        console.log(data);
        return getPost(2); 

    }).then(function(data){
        console.log(data);
        return getPost(3); 

    }).then(function(data){
        console.log(data);

    }).catch(function(error){
        console.log('Sorry an error ocurred!');
        def.reject();
    });   

});

Note that here I am only using jQuery’s AJAX method to do the asynchronous call to the demo API I am using that will give you back some sample JSON. You could just as easily do the above with the native XHR or even newer approaches such as fetch. As you probably already know, jQuery is an abstraction of native methods, so it makes sense that it ultimately does not matter what you use in our simple demonstration.

In the preceding example we looked at how you could implement the native Promise object if you needed a specific sequential order of the promises being returned. If you did not care at all about the order in which they came back and just needed to know when they *all* were finished you could do something like the below…

jQuery(document).ready(function() {  
    
    var test = [];

    function getPost(id){
        var def = new Promise(function(resolve, reject){
            jQuery.ajax({ 
                url: "https://jsonplaceholder.typicode.com/posts/" + id,
                type: "GET",
                dataType: "json",
                success: function(data){
                    test.push(data);
                    resolve(data)
                },
                error: function(){
                    reject();
                }
            }); 

        });

        return def;
    }

    // Implementation #2
    var arr = [getPost(1), getPost(2), getPost(3)]
    Promise.all(arr).then(function(values){
        console.log(values);
    });

});

Good stuff!

To Do: Create Your First React Application – Part II

Ian — Tue, 15 Nov 2016 01:07:17 +0000

Previously, we looked at getting set up creating a React “to do” application by installing our Node.js driven build tools and laying out some introductory components of code. In what follows we will continue on where we left off.

Adding “To Do” Items & Handling User Input

So far we have just looked how to display our components. Rendering data out to our page is all well and good, but to make our application truly dynamic we are going to need to implement a way to add and remove items to and from our list as well as edit them should we need to make any changes to any of the properties. So let’s update the code in TodoList.js to the following…

import {react} from 'react';
import {Todo} from './Todo';

export class TodoList extends React.Component {
    
    constructor(){
        super(...arguments);
        this.state = {
            todos: this.props.data,
            addTodoTitle: '',
            addTodoSummary: ''
        }
    }
    
    addTodoTitleChange(e){
        this.setState({
            addTodoTitle: e.target.value
        });        
    }
    
    addTodoSummaryChange(e){
        this.setState({
            addTodoSummary: e.target.value
        });           
    }    
        
    addTodo(){
        this.state.todos.push({
            id: this.state.todos[this.state.todos.length - 1].id + 1,
            title: this.state.addTodoTitle,
            summary: this.state.addTodoSummary,
            done: false
        });

        this.setState({
            todos: this.state.todos,
            addTodoTitle: '',
            addTodoSummary: ''
        });        
    }
    
    render() {
        
        var items = this.props.data.map((item, index) => {
            return (
                
            );        
        });
        
        return(
            
                {items}
                
                Add New Item:
                Title  this.addTodoTitleChange()} />
                Description  this.addTodoSummaryChange()}>
                
            
        )
    }
};

So let’s discuss what is going on here. We have added 2 new values to our initial state object and we have created a form that will allow us to add a new “to do” item to our list. When we enter text into these fields the functions to update the state will run and we will update these values with setState by getting the current value of the form element we are editing off of the event that is passed into the function (e.target.value). Once we have filled out the form with the title and summary of the new item that we want, we can click the “Add New Item” button which, as we can see from our “onClick” handler, will run the “addTodo” function. If we look at this function we can see the code that we will need to add a new item to our list. Recall that we have to give each individual item an id and no two items can have the same id. So to generate a new id we will look at what the id value of the last item in our array is and just add 1 to that. That is an easy way to ensure that the new items that we add are always unique. We get the title and the summary from this.state which we have been setting in our text input handler functions. Lastly, we just set the initial value of the “done” flag to false since adding a new to do to the list is presumably not done yet. All of this data is passed into the common JavaScript Array object’s “push” method. We then update the state of our “todos” and then clear out the input text box and textarea in our form to get them ready to receive another value.

So build your code with $ webpack (or whatever task runner you are using) and try it out. You can see how we can now add new items to our list! Pretty slick!

Improving Our Code

Our example above works but you may have noticed something problematic with our implementation. We have individual handler functions for the two text elements in our “Add New Item” form. We also have separate properties that we use for setState. This is fine for this simple example, but what if we had a component with many different properties and values with many different fields that needed to be filled out? If we were to take the same approach as our example above, we would have to create an individual function for each and every property. Not too efficient!

So what can we do to mitigate this potential scenario of our React application scaling to incorporate more complex objects? We should abstract this functionality into one handler function and also pass in the property that we need to update depending on the form element we are currently changing. So let’s change the code in our TodoList.js file to the following…

import {react} from 'react';
import {Todo} from './Todo';

export class TodoList extends React.Component {
    
    constructor(){
        super(...arguments);
        this.state = {
            todos: this.props.data,
            newItem: {
                title: '',
                summary: ''
            }
        }
    }
    
    handleChange(key, event){
        var change = {
            title: this.state.newItem.title,
            summary: this.state.newItem.summary
        };
        change[key] = event.target.value;
        
        this.setState({           
            newItem: change        
        });               
    }
    
    addTodo(){
        this.state.todos.push({
            id: this.state.todos[this.state.todos.length - 1].id + 1,
            title: this.state.newItem.title,
            summary: this.state.newItem.summary,
            done: false
        });

        this.setState({
            todos: this.state.todos,
            newItem: {
                title: '',
                summary: ''
            }
        });        
    }
    
    render() {
        
        var items = this.props.data.map((item, index) => {
            return (
                );        
        });
        
        return(
            
                {items}
                
                Add New Item:
                Title  this.handleChange('title', e)} />
                Description  this.handleChange('summary', e)}>
                
            
        )
    }
};

So what have we done here? For starters, instead of creating individual properties for each value our component will hold we will hold we put these into one object called “newItem.” That way if our component were ever to change we could just add to this single object rather than creating separate properties directly on the state object. Note too that we have also created a single handler function called “handleChange” to handle the change to any of our form elements. We have updated the format of our “onChange” events. Now we are passing a second parameter in to the handler function. This serves to tell React which field is currently being updated. In the handler function, we then construct the object to get the current state of all the values in our component and then we use the key that we passed in to change the relevant property.

Now if we build and run again, we can see that we have the same functionality, but we have refactored our code in such a way that we can scale our components to add new properties in the future. This is much better for us in the long run.

Validation

Validation of data is an important aspect of any application. In React we are mostly dealing with client-side validation. It is common knowledge within software development that you can never trust client-side validation alone because anyone on the client side can use developer tools and change the code that runs on the client to circumvent any validation that happens on the client. So any data that we send up to a server from a React application should also always always always be validated on the server as well. But chances are most of the users of your app will not be malicious individuals cracking open their developer tools and trying to hack their way into your system, so we will want to make sure that the good/normal users of your application have a good user experience. Part of this involves making sure that any input(s) that the users of your app make is checked and validated on the client side so that the app does not have to wait to make an entire round trip up to the server before informing the user that they have done something they were not supposed to… forgot to fill out a required form field, entered incorrect data in a form field such as an improperly formatted e-mail address or phone number, or any number of other common errors that can happen when handling user input. Again, this does not substitute for always validating your data on the server side as well, but it is a useful first line of defense and an important element to an enjoyable experience for your users. It also can reduce the traffic load on your server(s). If you can prevent sending a request until all the data that you’re getting from the client is good and valid, you should only need to make the particular request that you need to make to the server one time!

So all that being said, client-side validation definitely has its uses and it is worth making the effort to put it in for the aforementioned reasons. Fortunately, React has built in structure to validate props that we pass into our components and make sure that required data is present and that the data is of the correct type. We can do a quick test to demonstrate that validation aspects of React are present.

To start out, in our Todo.js file place the following at the bottom of the file (outside of the class declaration)…

...
} // end of Todo class

Todo.propTypes = {
    title: React.PropTypes.string.isRequired
}

What we have declared here is that the title property is required and must be present on the component. To test out that this is working, edit the “Todolist.js” file by removing the “title” property in the render method…

...
    render() {
        
        var items = this.props.data.map((item, index) => {
            return (
                 this.removeTodo(index)} />);        
        });
        
        return(
             
...

If we build and run our application we see the following warning message logged to our developers…

Warning: Failed propType: Required prop `title` was not specified in `Todo`. Check the render method of `TodoList`.

Because we have specified that we are expecting this property called “title” React issues this warning ahead of time. Now that we know that React is picking up on validation, we can go ahead and put the “title” property that we just deleted back in again. Now if we build and run the file again we see that the warning message goes away!

Let’s build upon this and explore some additional aspects of component validation. In addition to specifying which properties are required, we can also specify which data types we are expecting as well. We know that in rendering our list of “to do” components we are expecting an array of objects with different properties that we use to render out in the list. In our “TodoList.js” file, let’s add the following at the bottom (again, after the closing “}” for the class definition).

...
}
TodoList.propTypes = {
    data: React.PropTypes.arrayOf(React.PropTypes.object)
}

Here we have specified that the property that we pass into data in our “App.js” file needs to be an array of objects. Then in the Todo.js file we can build on what we did earlier with the “title” prop and add a few more rules around the expected values.

Todo.propTypes = {
    title: React.PropTypes.string,
    summary: React.PropTypes.string,
    completed: React.PropTypes.bool
}

There are many other aspects of validation that you can incorporate into your application and how you incorporate things really depends on how your application is structured. We will not cover every single validation case in detail here, but the preceding sections should give you a good place to start when you want to implement validation into your components. For more detail on this you can consult the React documentation.

Removing “To Do” Items & Passing Click Events From Child Component to a Parent Component

So now that we have the ability to add “to do” items, let’s take a look at how we can implement the functionality to remove items. Change the code in TodoList.js to the following…

import {react} from 'react';
import {Todo} from './Todo';

export class TodoList extends React.Component {
    
    constructor(){
        super(...arguments);
        this.state = {
            todos: this.props.data,
            newItem: {
                title: '',
                summary: ''
            }
        }
    }
    
    handleChange(key, event){
        var change = {
            title: this.state.newItem.title,
            summary: this.state.newItem.summary
        };
        change[key] = event.target.value;
        
        this.setState({           
            newItem: change        
        });               
    }
    
    addTodo(){
        this.state.todos.push({
            id: this.state.todos[this.state.todos.length - 1].id + 1,
            title: this.state.newItem.title,
            summary: this.state.newItem.summary,
            done: false
        });

        this.setState({
            todos: this.state.todos,
            newItem: {
                title: '',
                summary: ''
            }
        });        
    }
    
    removeTodo(index) {
        this.state.todos.splice(index, 1);

        this.setState({
            todos: this.state.todos
        });  
    }
    
    render() {
        
        var items = this.props.data.map((item, index) => {
            return (
                 this.removeTodo(index)} />);        
        });
        
        return(
            
                {items}
                
                Add New Item:
                Title  this.handleChange('title', e)} />
                Description  this.handleChange('summary', e)}>
                
            
        )
    }
};

As we can see we have added a “removeTodo” method that will remove the item in our “todos” array at a certain index. But there is an additional layer to this functionality that we need to explore. Each individual “to do” item needs to have its own remove button. Otherwise, how will the user know which item he/she is removing? So we are actually going to have to update Todo.js as well (where the definitions of individual “to do” components are located). Before we do that make special note of the “remove” property for the Todo component in the render method above. We are essentially passing our “removeTodo” method down into each component. This is how we get cross-component communication and it will become increasingly more important later on.

On that note, change the code in Todo.js to the following…

import {react} from 'react';

export class Todo extends React.Component {
    
    constructor(){
        super(...arguments);
        this.state = {
            completed: this.props.completed,
        }
    } 
    toggleCompleted(){
        this.setState({completed: !this.state.completed})
    }
    render() {
        
        return(
            
                {this.state.title}
{this.state.summary}
  this.toggleCompleted()} />
                
            
        )  
    }
};

As we can see here we have added a “Remove” button and wired the “onClick” event to this.props.remove. Recall from above that the “remove” property was a function on the “TodoList” component. So when we are clicking that button we are essentially calling up into that function. This code works and our click event travels up into the parent component and runs the “removeTodo” function there and it knows which item the event came from and its index in the list. Pretty neat, eh? This is a basic example of how we can pass events from child components to parent components.

As we have seen that using props, state, and event handlers properly is an essential part of developing React applications. There are many different places we can put our props and our event handlers and how you go about structuring things is entirely up to you. It can seem a bit complicated or overwhelming at first but after working with React for awhile you will begin to see some of the wisdom behind it. If you ever find yourself in a place where you are not sure what to do, you should always keep in mind this simple ancient React proverb…

Pass properties down, pass events up.

We saw this with our functionality to remove items from our list. We passed our function that we wanted to run down as a property into the Todo component, and linked the two when we passed the button click for the “Remove” button up to this function on the parent component. That is the general pattern to follow when working with React and communication between components. If you heed this wisdom, you will be very wise and build React applications that will be maintainable enough to endure for all eternity, young grasshopper.

Editing “To Do” Items

There is one final piece of functionality that we need to implement to have a useful React application and that is the ability to edit items in place. As it turns out all of the pieces that we need to implement this can be done in the Todo component. We do not need to keep track of anything at the TodoList level because all of the data we want to change resides within each item. So change the code of Todo.js to the following…

import {react} from 'react';

export class Todo extends React.Component {
    
    constructor(){
        super(...arguments);
        this.state = {
            title: this.props.title,
            summary: this.props.summary,
            completed: this.props.completed,
        }
    } 
    toggleCompleted(){
        this.setState({completed: !this.state.completed})
    }
    editTodo(key, event) {
        
        var change = {
            title: this.state.title,
            summary: this.state.summary
        };
        change[key] = event.target.value;
        this.setState(change);       
    }       
    render() {
        
        return(
            
                {this.state.title}
                {this.state.summary} 
                 this.toggleCompleted()} />
                
                 this.editTodo('title', e)} />  this.editTodo('summary', e)}>                 
                
                
            
        )  
    }
};

As we can see we have added a textbox and a textarea where we can edit the title and the summary. Similar to what we did earlier with our code to add an item, we create a common handler function (editTodo) for all of the fields that are editable and pass in a string with the name of the property we want to update. Notice that when we edit each individual item, the display text of each individual title and summary also change because they are data bound to this value.

Conditionally Displaying Elements Within Components

This editing functionality works fine from a functional standpoint, but as far as UX (user experience) goes it is not very good. It is ugly having a big form in the middle of each item as part of the display and one can only imagine how big and bloated things would get if we have more properties and or more items. We need to have a way to only show these when that particular item is being edited. For this we can again turn back to state and see if we can add an “edit mode” flag to our component so that we will only display the editing form elements when this “edit mode” flag is set to true. So let’s update the code in our Todo.js file to the following…

import {react} from 'react';

export class Todo extends React.Component {
    
    constructor(){
        super(...arguments);
        this.state = {
            title: this.props.title,
            summary: this.props.summary,
            completed: this.props.completed,
            inEditMode: false
        }
    } 
    toggleCompleted(){
        this.setState({completed: !this.state.completed})
    }
    toggleEditMode(){
        this.setState({ inEditMode: !this.state.inEditMode });
    }
    editTodo(key, event) {
        
        var change = {
            title: this.state.title,
            summary: this.state.summary
        };
        change[key] = event.target.value;
        this.setState(change);       
    }       
    render() {
        
        return(
            
                {this.state.inEditMode ?  this.editTodo('title', e)} />  this.editTodo('summary', e)}>
 : {this.state.title}
{this.state.summary}
  this.toggleCompleted()} />}
                
                
            
        )  
    }
};

As we can see we have added the flag “inEditMode” to our state that we toggle when we click our newly added “Edit” button which runs the “toggleEditMode” function. What does this do? In our component display we are using a ternary operator to display the form elements if the item is in “edit mode.” If the particular item is not in “edit mode” we just display the title and summary as we had been doing before. This implementation is one of the ways that is suggested to conditionally display parts of a React component in the React documentation. As this piece grows with more complex templates doing things this way could get a little bit bloated. So an alternative to this, as is suggested in the React documentation, is to do the conditional check for “inEditMode” just outside of the render function’s return method like so…

import {react} from 'react';

export class Todo extends React.Component {
    
    constructor(){
        super(...arguments);
        this.state = {
            title: this.props.title,
            summary: this.props.summary,
            completed: this.props.completed,
            inEditMode: false
        }
    } 
    toggleCompleted(){
        this.setState({completed: !this.state.completed})
    }
    toggleEditMode(){
        this.setState({ inEditMode: !this.state.inEditMode });
    }
    editTodo(key, event) {
        
        var change = {
            title: this.state.title,
            summary: this.state.summary
        };
        change[key] = event.target.value;
        this.setState(change);       
    }       
    render() {
        var display;
        if(this.state.inEditMode) {
            display =  this.editTodo('title', e)} />  this.editTodo('summary', e)}>;
        } else {
            display = {this.state.title}
{this.state.summary}
  this.toggleCompleted()} />
        }
        
        return(
            
                {display}
                
                
            
        )  
    }
};

This approach is a bit cleaner for more complex displays with more data values to keep track of.

Updating the Parent Component after State Changes on the Child

As we have seen the state in our individual to do items (title, summary, etc.) is stored on each individual “to do” item and the list of them is stored on the parent “TodoList” component. However, let’s take a brief look at something involved with this interaction that will be very important to remember when developing React applications. It is something that might seem a little unexpected at first but not all state changes in a child necessarily trigger state changes in the parent. This is especially noticeable when storing lists of child components in a property on the state object that is an array. In our case, our “TodoList” component has the “todos” property that stores the array of “Todo” components.

As it turns out we will actually have to specifically declare what we want to do on the parent when the child updates because there are certain instances when the parent state array is not aware of what has changed on the child component. Let’s take a look at when and why this might occur and what we can do about it.

In our “addTodo” method of our “TodoList” component, add the following at the bottom of this method such that our method looks like the following…

addTodo(){
    this.state.todos.push({
        id: this.state.todos[this.state.todos.length - 1].id + 1,
        title: this.state.newItem.title,
        summary: this.state.newItem.summary,
        done: false
    });

    this.setState({
        todos: this.state.todos,
        newItem: {
            title: '',
            summary: ''
        }
    });

    console.log(this.state.todos)        
}

Here we are logging just the current array of “to do” items whenever we add a new item. Now, after webpack recompiles this code let’s refresh our browser. As expected, we will see our original list of “to do” items. Edit the first existing item in our list by changing the title from “Eat Breakfast” to “Eat Brunch” or something like that. You can change the summary as well if you like, but any change will suffice here for purposes of demonstration. When you are done click the “Stop Editing” button.

As we can see the array of objects is logged to the console and there will be 4 items as we would expect [Object, Object, Object, Object]. However, look and see what happens if we expand and examine the first object (the one we originally edited). Surprisingly, the title still says “Eat Breakfast,” even though in the UI it says “Eat Brunch” because we changed it earlier. What is going on there?

This is one of those cases where parent component does not pick up changes in the child. As far as the parent component sees, there is still an object at index 0 of the “todos” property on the state object. Even though we changed the properties of that object, there was no change in the array from the parent’s point of view. When a new object to the array, that change *is* actually picked up because the array is now 1 item longer so the new item appears in the array. Long story short, there are steps we need to take to make sure that the parent state that stores the list of child components gets updated when we edit individual items. If we were to go to save our list to a database or something like that, we would want to be sure that we have all the up to date information of all the items in our list.

The way that we will handle the updating of items is to create a method on the parent. We will then pass that method down into the child component via props and then call that method inside of the method that handles child updates. Let’s take a look at what this looks like when implemented…

Add the following method to the “TodoList” component…

updateTodo(obj, index){
    this.state.todos[index] = {
        id: this.state.todos[index].id,
        title: obj.title,
        summary: obj.summary
    };
}

Then in the render() method, when we are looping through each “to do” item via the Array.map method, attach an update prop to each “Todo” component.

render() {
    
    var items = this.props.data.map((item, index) => {
        return (
             this.updateTodo(obj, index)}
                remove={() => this.removeTodo(index)} />);        
});
...

There is nothing special about the name “update.” We could name this prop whatever we want. Notice that this prop points to the method we had just created earlier. It will receive 2 parameters. The first will be passed up from the child “Todo” component, and the second is the index so we have a way of knowing which item in the array to update. All we end up doing is replacing the old object at this spot with the new object with updated data. We keep the id key exactly the same.

Finally, in the “Todo” component, in the place where we update individual state for the item (out editing function), we can call the update method via this.props. So add the call to our update method on the parent to youe “Todo” component…

editTodo(key, event) {
    
    var change = {
        title: this.state.title,
        summary: this.state.summary
    };
    change[key] = event.target.value;
    this.setState(change);    
    this.props.update(change);   
}

Notice our call to the “update” method which comes in as a prop. Basically all we are doing here is passing the data object that we have just changed up into our update property. This data comes in and gets passed to the parent method along with the index location where this data lives in the array.

Now if we rebuild and rerun our code we can see that when we update our individual items and then add a new item (assuming we still have the console.log in our code) we can see that whenever we edit “Todo” items, they are getting updated in the array and our data is consistent between parent and child. If we were to go save this data, we could be confident knowing it is up to date and consistent with what the user is seeing in the UI.

So that is something to be cognizant of when working with React. It is always a good thing to confirm that your state of anything on parent components match the individual child state properties.

CSS Styling & Polish in React

We will cover how to handle the visual styling (CSS) in React more in depth in future discussions, but for now it is worth doing a little bit of styling to add a bit of polish to our application here just to get our feet wet. Let’s add a stylesheet reference to our index.html file…




    React

And then we can add a few additional items to each of our list items that make up each individual “to do” component. Update the code in Todo.js to the following…

import {react} from 'react';

export class Todo extends React.Component {
    
    constructor(){
        super(...arguments);
        this.state = {
            title: this.props.title,
            summary: this.props.summary,
            completed: this.props.completed,
            inEditMode: false
        }
    } 
    toggleCompleted(){
        this.setState({completed: !this.state.completed})
    }
    toggleEditMode(){
        this.setState({ inEditMode: !this.state.inEditMode });
    }
    editTodo(key, event) {
        
        var change = {
            title: this.state.title,
            summary: this.state.summary
        };
        change[key] = event.target.value;
        this.setState(change);       
    }       
    render() {
        var isComplete = this.state.completed ? 'complete' : '';
        var display;
        
        if(this.state.inEditMode) {
            display =  this.editTodo('title', e)} />  this.editTodo('summary', e)}>;
        } else {
            display = {this.state.title}
{this.state.summary}
  this.toggleCompleted()} />
        }
        
        return(
            
                {display}
                
                
            
        )  
    }
};

All of the changes that we have made are in the “render” function. We are using the React “className” hook to add a class to the item if the state of the current item is “completed.” If it is not in a “completed” state, this class is not added. Note that we are only doing this for the elements in “display mode.” We do not need to show this distinction when we are in “edit mode”

And then of course let’s create a “style.css” file in a “css” directory and then add some CSS to a style.css file in a “css” directory…

.complete {
    text-decoration: line-through;
}

When our “completed” class is added to the item, the “to do” item will have a “crossed-out” look to it signaling that we are done with the task. Now if we build and run this code we can see that clicking on the text box will toggle the state of whether a “to do” is completed. When a “to do” is marked as complete, the item gets crossed out by using the line-through text decoration.

We can expand on this and add a bit more CSS to enhance the display of our application. Place the following styling in the style.css file…

.complete {
    text-decoration: line-through;
}

#content label {
    display: block;
    margin-bottom: 10px;
}

#content input[type="text"] {
    margin-bottom: 10px;
    display: block;
}

#content textarea {
    margin-bottom: 10px;
    display: block;
}

#content ul {
    list-style-type: none;
    padding-left: 0;
            
}

#content li {
    margin: 5px 0;
    background: #fcfcfc;
    border: 1px solid #eee;
    padding: 10px;
}

#content li input[type="text"] {
    display: block;
    width: 100%;
    margin-bottom: 10px;
}

#content li textarea {
    display: block;
    width: 100%;
    margin-bottom: 10px;
}

#content li h2 {
    margin-top: 0;
}

Nothing too fancy, but it cleans things up a little bit.

Summary

Whew! We have come a long way and made great progress in writing our “To Do” application but we have covered a lot of the basic components of application functionality: displaying, adding, editing, and removing items. In the preceding sections we took a look at how we could do some more complex implementations in our React applications. We looked at how we could nest components within one another and we also looked at how we could handle user input — including text input and clicks — and how to send it to the UI and let React handle our UI updates. By now we are seeing how React handles a lot of this stuff for us and how its simple understandable syntax makes writing a client-side UI in JavaScript a lot cleaner with a lot less code. These will provide some valuable aspects as our applications grow and get more complex.

To Do: Create Your First React Application – Part I

Ian — Thu, 06 Oct 2016 20:09:02 +0000

React is a JavaScript library that is primarily responsible for handling the “view” component of a JavaScript single-page application. As it describes itself of the React homepage…

Lots of people use React as the V in MVC. Since React makes no assumptions about the rest of your technology stack, it’s easy to try it out on a small feature in an existing project.

React’s focus, first and foremost, has to do with rendering dynamic UIs in a manner that is visually appealing to the user. It is flexible enough that it can be used in a diversity of capacities and contexts. We have looked at React in previous entries. In what follows we will look at creating an introductory application using React and React related tools and libraries. One of the more ubiquitous tutorial applications that developers build when learning a new language or framework is the TO DO (To do) app. In terms of prevalence, it is probably second only to the “Hello, World” app which has been around since the dawn of programming. But the “To Do” application is popular because it covers a lot of the basics of how a language or framework handles a number of things. There must be a way to add a new “to do” so handling user input is involved. The same is true for displaying data, editing and saving data, and changing display state when data updates. All of these things are going to be important implementations in any application.

In what follows we will create the iconic “To Do” application in React and discuss some of the inner workings as we go along. We will take a deeper look into React components and how we can add some dynamic interactivity to our React applications in response to user actions — things like clicks and entering text in a text box — and updating our views accordingly.

JSX Compilation with Babel & Browserify

As we will see, React has its own programming language called JSX. It has been described as sort of like a mixture of JavaScript and XML and it is React’s own special easy-to-read abstracted syntax. JSX is not required to create React applications and you can write your React components in native JavaScript if you prefer. Because browsers do not natively understand JSX in order for your react application to run JSX needs get converted to native JavaScript.

The React website suggests that you utilize tools like Babel and/or Browserify (both of which run on Node.js). Babel is what is known as a transpiler. It mostly functions as a tool that takes code written in ECMAScript 6 (ES6) and converts it to ES5. As of 2015 this is still necessary because support for ES6 across all browsers is not widespread yet. Until support for ES6 is implemented across all browsers, tools like Babel will still be needed. Although many people think of Babel primarily as an ES6 to ES5 transpiler, Babel also comes with JSX support as well. You can merely run the Babel transpiler on your JSX files and they will be converted to native JavaScript that will be recognized by any browser circa 2015.

Browserify allows for Node.js style module loading in your client-side JavaScript. Like with Node, it allows you to import code in certain JavaScript files into other JavaScript files for better organization of your code.

Task Runners / Module Bundlers

For our sample code, we will be using task runners to handle our JSX conversion to native JavaScript. You may have heard of task runners like Grunt or Gulp, or module bundlers like webpack. We will be using webpack because it has, at least for the time being, become the utility of choice among the React community. If you are not entirely familiar with JavaScript task runners it would definitely be worthwhile to read the webpack documentation (or watch a few videos) on what it is and why you would want to use it. The more recent versions of React essentially require you to set up your tools before you work with JSX in React. In previous versions of React there was an easy extra

As we can see, we are going to include App.js, which will be a file that we generate in our task runner. Note too we are creating a

with the id of “content.”

Next, create a folder called “src” and create a file called App.js in this folder. For this tutorial we are going to be breaking our components up into different modules so in our App.js file all we need to add for now is the following.

import {react} from 'react';

In the same directory as your App.js file, next create a file called “Todo.js”. In this file, we are going to need to create a React component/class that will represent each individual “to do.” Add the following code to this file…

import {react} from 'react';

class Todo extends React.Component {
    
    render() {
        return(I am a to do)  
    }
};

Pretty straightforward. This should look familiar as it is similar to our other earlier examples.

Now what we’re going to do is import this module into our App.js file. How do we do this? In our App.js file we just need to add the following…

import {react} from 'react';
import {Todo} from './Todo';

This will tell our code to import the “Todo” module from the “Todo” file relative to where “App.js” is located. With module loading in ES6 you can omit the “.js” from the file when you are importing modules.

So we are definitely well on our way but if we were to run this code as it is right now we would get an error. Why is this? Well, because we are importing a module from our “Todo.js” file we need to specify what this file exports. To do this we need to add the “export” keyword in front of what we want to make available from the “Todo.js” file. Thus, we need to change our code in our “Todo.js” file to the following…

import {react} from 'react';

export class Todo extends React.Component {
    
    render() {
        return(I am a to do) 
    }
};

Notice how we have added the “export” keyword in front of our class. Now there is something that can be imported from the “Todo.js” file. We will get into more complex combinations of what various files can export and import later on, but for now this simple example shows the basic setup of how it is done.

Now in our App.js file add the “render” method so we can confirm that everything is working…

 import {react} from 'react';
import {Todo} from './Todo';

ReactDOM.render(, document.getElementById('content'));

Let’s build our App.js file by running “webpack” by opening up a terminal window typing the following…

$ webpack

Doing the above will build the App.js file and place it in our “dist” folder. Now if we open up another terminal window and run our server with…

$ npm start

and we go to https://localhost:8080 in our browser, if all has gone well we should be able to see the text “I am a to do.”

Component Composition

For our application we will be rendering a list of “to do” items inside of our “to do” list. Thus, we will also need to create a component that represents our “to do” list. So create a “TodoList.js” file in the same directory as the others and add the following code…

import {react} from 'react';
import {Todo} from './Todo';

export class TodoList extends React.Component {
    
    render() {
        return(To do list here...)  
    }
};

“TodoList” is the component that will serve as our “root” container component for our React application. It is just returning some placeholder text for now, but we will be adding more complexity to it very soon. Because the “TodoList” top-level component for this particular application, it is this one that will be the one that we want to render in our App.js file (not the individual “Todo” components). So change the code in our App.js file to the following…

import {react} from 'react';
import {TodoList} from './TodoList';

ReactDOM.render(, document.getElementById('content'));

Notice now how we are now rendering the “TodoList” component now and not the “Todo” components.

Now let’s take a look at how we could add some “depth” to our components (i.e. nesting components within components). In this case we will be nesting individual “Todo” components inside of our “TodoList” component. So in our “TodoList.js” file we can update our code to the following…

import {react} from 'react';
import {Todo} from './Todo';

export class TodoList extends React.Component {
    
    render() {
        return ();
    }
};

It is as simple as that! You can include other components in what you return in your render method. This can include multiple components if you so desire…

 import {react} from 'react';
import {Todo} from './Todo';

export class TodoList extends React.Component {
    
    render() {
        return (
            
                
                
                
            
        );
    }
};

This example will render the text in our “Todo” component 3 times.

In a real-world application, what you render in any given React component will often include multiple components of many different types. This is what we refer to when we explain React components as being composable. They can be composed of multiple components of different types.

Our example is very plain right now. Let’s take a look and see if we can make things more dynamic by rendering out some variable data and adding some interactivity by wiring up some events (clicks, hovers, etc.)

Properties With this.props

We discussed the importance of this.props and this.state a bit earlier and we will expand upon this in the upcoming sections. To start let’s use some sample data. This data will again be an array of objects and will be somewhat similar to what we used earlier in our introduction to React. So update the App.js file to look like the following…

import {react} from 'react';
import {TodoList} from './TodoList';

let todos = [
    {
        id: 1,
        title: "Eat Breakfast",
        summary: "Toast and scrambled eggs would be nice.",
        done: true
    },
    {
         id: 2,
         title: "Walk Dog",
         summary: "Dress for wet weather.",
         done: false
    },
    {
         id: 3,
         title: "Learn React",
         summary: "I am making great progress!",
         done: false
         
     }
];

ReactDOM.render(, document.getElementById('content'));

Here we have an array of objects that we are going to pass in to our “TodoList” component. Inside of our component the data will be accessible by using this.props.data. The name “data” is just the name that I picked. You can choose any name that you want for your property attributes.

Continuing on, update the code in our TodoList.js file to the following…

import {react} from 'react';
import {Todo} from './Todo';

export class TodoList extends React.Component {
    
    render() {
        
        let items = this.props.data.map(function(item){
            return ();        
        });
        
        return({items})
    }
};

As we can see, we are accessing the data that is passed into our component with this.props.data. We iterate through the array and for each item, we pass the data in the item one level deeper into a “Todo” component. We create a collection of these components and return each one.

And then finally, let’s update our Todo.js file to the following…

 import {react} from 'react';

export class Todo extends React.Component {
    
    render() {
        return(
            
                {this.props.title}
                {this.props.summary}
                
            
        )  
    }
};

So as we can see here, the title, the summary, and the flag on whether or not the item is marked as completed that we are passing into the component will be available with this.props.completed because we passed the done property in the object on each item into this slot.

Now if we build our files with $ webpack we can see the listing of our “to do” items. The ones that have the “done” property set to true have the checkbox checked.

Handling Events & State

One of the important parts that React applications handle for you is management of “state.” What is state? State is basically the current values that any given component holds that is often reflected in the way that the UI displays and represents its values. In our example above some of the items in our “to do” list hold a current state of being “completed” and some hold a current state of being “not completed.” State is the current collection of properties holding a set of values within a component. When the state updates, that is, when the value of one of these properties in a component changes, the component re-renders itself. We hinted at this piece of React briefly before and this one of React’s awesome features. Components re-render themselves when there is any change. We do not have to try to update things manually ourselves within the UI!

There are a number of different ways that a component’s state can change, but one of the more common ways is via events. Events are things such as mouse clicks and hovers that are usually instigated by a user but they can also be triggered in code as well. Wiring up events in React is similar to how it is done inline with JavaScript in HTML. You may have seen code like this before in vanilla JavaScript…

In the “onclick” attribute, we run the showMessage() function which will alert a message “Hello world!”. React takes a similar approach to this when it comes to hooking up events. Let’s see what this looks like. Update the code in “Todo.js” to the following…

import {react} from 'react';

export class Todo extends React.Component {
    
    constructor(){
        super(...arguments);
        this.state = {
            completed: this.props.completed
        }
    }
    
    toggleCompleted(){
        this.setState({completed: !this.state.completed})
    }
    
    render() {
        return(
            
                {this.props.title}
                {this.props.summary}
                 this.toggleCompleted()} />
            
        )  
    }
};

You may have noticed the “…arguments” in the constructor. This is the spread operator that is a new feature in ES6 and in JSX. You also might notice our use of an arrow function that we discussed earlier in the “onChange” attribute. This is actually a necessity with regard to the scope of the component. If we did not use an arrow function here, the function in the attribute would create its own scope. Therefore we would have had to use “bind” and write something like onChange={this.toggleCompleted.bind(this)}. However, because arrow functions operate in the context of the parent scope, “bind” becomes unnecessary and the scope of the attribute operates under the scope of the component.

For the checkbox, we could attach and “onClick” event here if we wanted to and it would work fine, but instead of using the “onClick” event, we will use the “onChange” event because it is a bit more all-encompassing. In the future we will work with input textboxes, select boxes, and a number of other form elements. The “onChange” event will cover that a bit more comprehensively and we will be using it more regularly as we go along. There will be a time and a place for “onClick” specifically as well but in this case, onChange is a better fit.

If we build our code and ran this code as it is, we would get a warning message in the console saying…

Warning: Each child in an array or iterator should have a unique "key" prop. Check the render method of `TodoList`. See https://fb.me/react-warning-keys for more information.

What is going on here? As we can see from the suggested page in the React docs there is a description of why this warning is appearing…

The situation gets more complicated when the children are shuffled around (as in search results) or if new components are added onto the front of the list (as in streams). In these cases where the identity and state of each child must be maintained across render passes, you can uniquely identify each child by assigning it a key… When React reconciles the keyed children, it will ensure that any child with key will be reordered (instead of clobbered) or destroyed (instead of reused).

So when dealing with events and state React requires a unique ID “key” to be attached for child components within a set. React uses this internally to allow for efficient reordering and identifying a specific item within the set. This is especially important when items are added to or removed from the set. So let’s update the code in our TodoList.js file…

import {react} from 'react';
import {Todo} from './Todo';

export class TodoList extends React.Component {
    
    render() {
        
        var items = this.props.data.map(function(item){
            return ();        
        });
        
        return({items})
    }
};

As we can see, we have passed in the item ID as the key property. That’s all we have to do! Once we do this and then rebuild our JavaScript this error message will go away. React is very helpful in giving us information with regard to how we need to change our code to set things up properly.

Now if we open our browser and go to our https://localhost:8080 site (run $npm start) we can see the items in our list rendered. The ones that have the “done” property set to true will have the checkbox checked. If we check/uncheck the checkboxes, the underlying data for the component underneath will be toggled as the “toggleCompleted” method will be running each time we do this. This brings us to the concept of state, something that is inexorably linked with events.

As we have mentioned earlier, state is the current collection of properties holding a set of values within a component. Collectively it is the status of the component at any given time and is subject to change at any time. This change will trigger React to do a “rerender” of the UI. In our example we are displaying the title and the summary with this.props.title and this.props.summary. In React, this.props is read-only and cannot be changed. Trying to set this.props.title = ‘Something Else’ will result in an error. Contrary to this.props, this.state is mutable. Because the “completed” property will change we will set an initial value for it in the constructor. Note that even though we cannot change anything on this.props we can still read the values in this.props to set an initial state. When certain events happen or certain functions execute, we can update the state of the component with this.setState and pass in an object containing all the properties we want to update. We will also do this for the title and summary properties later on when we get into writing our functions to edit our “to do” components. But for now we are just doing this with our “completed” flag.

That about does it for part 1. In part 2 we will work on filling out the application a bit more and adding in some validation. Until next time…

ECMAScript 6 Arrow Functions

Ian — Thu, 18 Aug 2016 19:52:46 +0000

Arrow functions, also sometimes called “fat arrow” functions, are a new ES6 syntax for writing anonymous function expressions. We have looked at working with ES6 in previous entries about classes and module loading. (a.k.a the “next version of JavaScript”). A function expression in JavaScript refers to the notation where a developer sets a variable equal to a function like so…

var sum = function (a, b) { return a + b; }

Note that a function expression is different from a function declaration which would look like the following…

function sum(a, b) { return a + b }

So arrow functions are primarily centered around function expressions. They have 2 main purposes. For one, they provide a more concise syntax which is a nice thing to have and can make code more readable. If were to take our function expression above and rewrite it as an arrow function, it would look like the following…

var sum = (a, b) => a + b;

As can be seen here, this syntax looks a bit different from our original function expression. We have the arrow pointer pointing a statement that has omitted the { } from encapsulating the function body and we have omitted the “return” statement. In the above arrow function these things are implied. If we wanted to we could include these things and the meaning of the function would be the same.

var sum = (a, b) => { return a + b };

There are few rules around the syntax of arrow functions to watch out for. If there is only one argument in an arrow function the parenthesis do not need to be included. So an arrow function that simply returns “a” could be written like so…

var getVal = a => a;

However if the arrow function takes no arguments, parentheses must be used…

var getVal = () => "Hello world!";

Another interesting case of arrow function syntax is returning an empty object. The following results in an error…

var getVal = () => { };

The compiler sees this as having nothing in the function body and does not know what to return. As a result when returning an empty object you have to do the following…

var getVal = () => ({ });

So as we can see, arrow functions give us a much more terse way of writing code, allowing for a more readable concise syntax. This becomes useful in cases when using functions that have callbacks involved as arguments. Many functions that that perform asynchronous operations with data have this format. The following asynchronous promise style function…

getData().then(function (data) {
    return data;
});

Could be rewritten as the following using arrow functions…

getData().then(data => data);

It is pretty apparent that the second example is a lot more compact. As the number of functions like these get chained together, it can make the code a lot easier to read once you get used to the syntax.

Another and perhaps a more important aspect arrow functions is that they handle the scope of the “this” pointer within the function in a different manner. In other words, in arrow functions “this” points to the scope of the parent environment that the arrow function is contained within. This is a very important distinction. Arrow functions do not create their own “this” as normal functions do. A side-effect of this is that you cannot instantiate an arrow function with the “new” keyword as you can with normal functions because arrow functions have no internal prototype property.

Why were things done this way in ES6 and why is this useful? This can be very useful because you now no longer have to use apply, call, or bind to bind to the parent scope. One of the more common uses of the bind method within JavaScript applications is to pass the parent scope downward as you go multiple levels deep within methods within in object literal. For example, let’s say we had the following very general “actionClass” object literal. A lot of JavaScript applications use this pattern as an implementation…

Click me!

As we can see we are calling the actionClass.init() method which will set up some event handlers. So let’s add an event (using jQuery) where when we click an element we call another one of the methods within our actionClass object.

Click me!

This code does not work. When we try to click the div we get an error in our console…

Uncaught TypeError: this.doSomething is not a function

Why is that? Well it is because the callback function for the click event has its own scope. “this” is now pointing at the function it is being called from. One way that developers solve this is by setting a variable to the parent scope. The following code works…

Click me!

This is certainly a viable option and works fine for our simple example. However, as we go deeper and get more complex into multiple levels of nested functions with events or getting data asynchronously via AJAX requests or any number of other possibilities the process of constantly assigning variables to the scope that you want can get kind of messy. So what other approach can we take? This is where bind comes into the picture. We could also do something like the following…

Click me!

Simply by attaching .bind(this) after our function closing bracket } we are changing the scope of the function. We longer need to say var self = this;

But with arrow functions we can accomplish the same thing without having to resort to using “bind.” We can rewrite the above in the following manner (assuming we had ES6 compatibility in the browser or we transpiled the code)…

Click me!

Now because we have used an arrow function, the “this” pointer is set to the parent scope because of how arrow functions bind the lexical “this” to the parent. It may take a bit of getting used to but overall the differing scope of the “this” pointer combined with the concise syntax can make code that makes use of arrow functions a lot more readable and maintainable. We will be making use of them to some degree in upcoming examples, so it was necessary to at least introduce what arrow functions are and what they do.

This is just a brief look at a couple of the newer features found in ES6. Hopefully you found it helpful.

ECMAScript 6 Module Loading

Ian — Sat, 23 Jul 2016 19:47:02 +0000

In the past we had looked at working with classes in ECMAScript 6, the “next version of JavaScript.” Another component of ES6 that you will find prevalent is module loading. These are basically the same conceptual implementation of modules that you will find in Node.js. Modules in ES6 solve the problem of scope and dependency management. In the past with ES5 a variable or function just declared in the open — whether in a script block in an HTML file or in an external .js file — like so….

function sayHi(name) {
    return "Hi, " + name;
}

would be considered to be bad practice because you were polluting the global object (which is often the window object in the context of the web). As the size and complexity of your application grew the maintainability of it would become a lot more difficult because you would have to worry about potentially overwriting other variables and functions later on in your application if you happened to name them the same or accidentally assign them a value that you did not intend to. Because of this, you often saw applications “namespace” the various methods and variables of an application to objects like so…

var app = app || {};
app.greeting = {
    sayHi: function (name) {
        return "Hi, " + name;
    }
};

to avoid polluting the global object.

With ES6 modules, however, all of this becomes unnecessary. You can declare functions and variables freely and the scope is always local to that file unless explicitly specified as a global object. This makes managing scope and maintaining your application a lot easier.

If you have ever done any development with Node.js, you should be somewhat familiar with modules as it follows a particular form and structure known as the CommonJS module loading syntax. Basically the idea is that you can import various functions and methods from other JavaScript files into your own JavaScript file by using the “import” keyword. You reference the path to the file you are loading as a module from the location of the file you are importing your module(s) into. So let’s say in your project you had a file called “greeting.js” that lived in a folder named “lib” with the following code in it

export function sayHi(name) {
    return "Hi, " + name;
}
export function sayHello(name) {
    return "Hello, " + name;
}
export function sayHey(name) {
    return "Hey, " + name;
}

The “exports” keyword means that these functions are exported and can be imported into other JavaScript files. For example, in the root of your project (one level up from the “lib” directory) let’s say you had a file called main.js. In that file you could do the following…

import * as greet from 'lib/greeting';

console.log(greet.sayHi('Joe')); // "Hi, Joe"
console.log(greet.sayHello('Sally')); // "Hello, Sally"

Here we are importing all of the exported functions in the greeting.js file into a variable called “greet” using the * wildcard locally to our main.js file. If there were any other exported functions or properties in our greeting.js file, this would be available in main.js as well.

There are other syntaxes that can be utilized in module importing. For example, if we only wanted the sayHi and sayHello methods imported from our greeting.js file (and we did not want or need the sayHey method for some reason) we could do the following in main.js…

import { sayHi, sayHello } from 'lib/greeting';

console.log(sayHi('Joe')); // "Hi, Joe"
console.log(sayHello('Sally')); // "Hello, Sally"

There are other variations on the importing syntax and implementation as well that we might see as we go along. The main point is that this gives you a lot of flexibility in how you structure your application. Doing all of this is not too dissimilar from the importing that you would so in Java…

import com.domain.package;

or C#

using System.Net;

The difference being that in JavaScript you import from the path to the file and in Java and C# the packages are compiled into memory and imported from there. But in all cases the approach serves the same purpose.

You could also use the require syntax (again familiar from Node.js) to import a module…

var greet = require('lib/greeting.js')

console.log(greet.sayHi('Joe')); // "Hi, Joe"
console.log(greet.sayHello('Sally')); // "Hello, Sally"

The choice is yours depending on which you prefer.

How to Take Retina Display Screenshots on PC using Firefox

Ian — Tue, 28 Jun 2016 15:37:44 +0000

In previous posts we looked at how to create mobile application projects using Apache Crodova and we saw how we could use HTML5, CSS, and JavaScript to develop mobile applications on this platform. And we also walked through the submission process of your app to various app stores (Apple’s App Store and Google Play).

One component of the submission process that we didn’t really cover is the process of taking screenshots of your application. These are required to create the “preview” aspects of your app that the app store will present before a user purchases/downloads your app. Obviously there are any number of ways you can take screenshots… everything from browser extensions, to online services, to pushing the “PrtSc” button on your keyboard. But one of the things that inevitably comes up is the need to take high resolution screenshots, particularly those of the retina displays of iPhones and iPads (displays with 2x and 3x pixel densities). Taking screenshots at these resolutions will lead to some pretty large screenshots. You can see the full list here in Apple’s developer documentation. As you can see, some of the screenshots require some fairly large dimensions. At the time of this writing, the 5.5 inch iPhones require dimensions of 1242 x 2208 pixels for hi-res portrait and 2208 x 1242 pixels for hi-res landscape. The iPad pro screenshots have to be 2048 x 2732 pixels for hi-res portrait and 2732 x 2048 pixels for hi-res landscape. Those are pretty big and you may not have a way of capturing a display this large.

So what to do? Fortunately there is a way to take high pixel density screenshots using the Firefox web browser. You don’t even need an extension and you don’t need a monitor with a high DPI (dots per inch) display. Here is how you can do this…

To start it is assumed that you have your app viewable as a demo in the
Open Firefox and from the menu select Tools > Web Developer > Responsive Design View.
Set the resolution according to what you need. e.g. for 4.7-inch Retina displays (iPhone 6) set 750×1334, and for 5.5-inch Retina displays (iPhone 6 Plus) set 1242×2208
Open the hamburger menu in Firefox and set the zoom level e.g. for 4.7-inch Retina displays (iPhone 6) you can set the zoom to 200% and for 5.5-inch Retina displays (iPhone 6 Plus) you can set the zoom to 300%. Firefox will change the pixel ratio according to the zoom level and will respond to resolution media queries. This will give you the correct responsive layout and high DPI rendering.
Press Shift + F2 to open the console and type in “screenshot” (and maybe hit space bar) then . This part is important. You must use the console instead of the screenshot button to get a high DPI screenshot. Using the little screencap button in the developer tools is no good. If all goes well, you should see some kind of indication on the screen that the screenshot has been saved/created

Now you will have a high resolution screencap with the correct dimensions that you can upload into iTunes connect! Thanks Mozilla!

Asynchronous Processes Inside of a Loop in JavaScript

Ian — Sun, 31 Jan 2016 01:15:40 +0000

As the web development world becomes more and more asynchronous with the emergence of technology stacks like Node.js, REST APIs, and some of the features we see in ECMAScript 6 (the latest version of JavaScript), there are whole new dimensions involved with how we exchange data over the web and how we code for this. One of the challenges with asynchronous programming is that there might be some additional considerations regarding the specific time that certain parts of your code executes and/or the order in which data is coming in to your callback functions that you set up to execute when your processes are complete. If things happen when you don’t expect them or in a different order than you expect them if you’re not ready to handle this, you’re going to get some undesirable results.

What is an example of this? What if, say, I had to do something this?

for(var i=1; i < 6; i++) {
    asyncFunction(function(data){
        console.log('The index is ' + i);
        console.log('The data is ' + data);
    });
}

Here I have set up a callback that will execute when our hypothetical asynchronous process is complete, but I also want to have access to the value of the index in the callback. If I had a list of items and I wanted to do an async process on each of the items in my list, this is some information that I would want.

If were to run this we might see something like the following in our console…

The index is 5
{ data: "item2" }
The index is 5
{ data: "item1" }
The index is 5
{ data: "item3" }
The index is 5
{ data: "item5" }
The index is 5
{ data: "item4" }

Hmm, that doesn’t look right. Why is this happening? Well, it’s because as far has JavaScript is concerned the asynchronous process that we run is done executing and JavaScript moves back up to the top of the loop and continues on. Thus, the value of the index in our loop rockets to 5 before any data comes back. What’s more, the data that we are getting back is coming in at different times in no particular order.

If we wanted to do things in a particular order, this state of things might be difficult. We might end up having to do some sorting after we get our data back for each item and we really do not have any idea when we are actually done (apart from maybe keeping a count of the response we get from our async process). This is a cumbersome and non-performant way of doing things. What we need is a way to maintain the context of the index of our loop in our callback function(s) so that we are able to keep some semblance of order as we do these async processes. How can we accomplish this?

The answer to this is fairly straightforward: function factories. That is, a function that returns another function. You might be familiar with the concept of a function factory if you have ever looked at the factory pattern in your study of software development. These functions that we return will be created on the fly and as a result of this they will have their own context when they are created. In essence, our function that creates these functions becomes our “callback factory” … a function that makes callbacks to run when we get our data back.

Let’s take a look at a practical example of this. In this example I am going to use a demo API that returns some sample data in JSON format. I am going to use jQuery to fetch this data via the ajax method (AJAX being an acronym for Asynchronous JavaScript and XML). Getting this data is, of course, going to be an asynchronous process. In the success method we will make a call to our function factory which will create a new function for us. This function will maintain its context at the time that it is created (and thus will have the correct index value of our loop at the time it is created). This will look like something like the following…

function callbackFactory(i){
    return function(data, textStatus, jqXHR){
        console.log('We are calling with index ' + i + ' and the data is...')
        console.log(data);
    }
}

for(var i=1; i < 6; i++) {

    jQuery.ajax({
        type: "GET",
        url: "https://jsonplaceholder.typicode.com/posts/" + i,
        contentType: "application/json; charset=utf-8",
        async: true,
        dataType: "json",
        success: callbackFactory(i),
        error: function (jqXHR, textStatus, errorThrown) {
            console.log(errorThrown);
        }
    });
}

So if we run this code, we can see that the index value is preserved. And we get the values logged to the console like so…

We are calling with index 5 and the data is...
{userId: 1, id: 5, title: "nesciunt quas odio", body: "repudiandae veniam quaerat sunt sed↵alias aut fugi...sse voluptatibus quis↵est aut tenetur dolor neque"}
We are calling with index 2 and the data is...
{userId: 1, id: 2, title: "qui est esse", body: "est rerum tempore vitae↵sequi sint nihil reprehend...aperiam non debitis possimus qui neque nisi nulla"}
We are calling with index 1 and the data is...
{userId: 1, id: 1, title: "sunt aut facere repellat provident occaecati excepturi optio reprehenderit", body: "quia et suscipit↵suscipit recusandae consequuntur ...strum rerum est autem sunt rem eveniet architecto"}
We are calling with index 4 and the data is...
{userId: 1, id: 4, title: "eum et est occaecati", body: "ullam et saepe reiciendis voluptatem adipisci↵sit ... ipsam iure↵quis sunt voluptatem rerum illo velit"}
We are calling with index 3 and the data is...
{userId: 1, id: 3, title: "ea molestias quasi exercitationem repellat qui ipsa sit aut", body: "et iusto sed quo iure↵voluptatem occaecati omnis e...↵molestiae porro eius odio et labore et velit aut"}

Although we do not have control over when our async processes are complete (our data still comes back at different times in no particular order),we at least still have a reference as to what item in our loop corresponds to which set of data we get back from our AJAX calls (which is far better than what we had previously).

What we looked at above is just a simple example of how to conceptualize some of the considerations involved with asynchronous programming in JavaScript. Beyond this, there are certainly more structured implementations like using promises. A promise object is used for deferred and asynchronous computations and it represents an operation that hasn’t completed yet, but is expected in the future. An example of a promise implementation using jQuery and our API would look something like the following…

jQuery(document).ready(function() {  
    
    function getPost(id){
        var def = jQuery.Deferred();

        jQuery.ajax({ 
            url: "https://jsonplaceholder.typicode.com/posts/" + id,
            type: "GET",
            dataType: "json",
            success: function(data){
                def.resolve(data)
            },
            error: function(){
                def.reject();
            }
        }); 

        return def.promise();
    }

   
    getPost(1).then(function(data){
        console.log(data);
        return getPost(2); 

    }).then(function(data){
        console.log(data);
        return getPost(3); 

    }).then(function(data){
        console.log(data);

    }).fail(function(error){
        console.log('Sorry an error ocurred!')
        def.reject();
    });   
    
});

See here we have a function called “getPost” that will return a promise for us that the jQuery library provides. We can then use that function to essentially queue up the requests we need to make so that we can get the data back in the order that we need it. If you are not familiar with promises it is very worthwhile to learn about them because they are fairly prevalent in modern JavaScript (at least as of circa midway through the 2010s decade). There are lots of promise libraries and popular libraries and frameworks like jQuery and Angular have some sort of promise pattern built into them.

Apart from promises there are also other methods of handling asynchronousity and what you decide to implement really depends on the problem(s) you are trying to solve, how and when you need to get your data back and all of that. Like with many things, there is no magic bullet solution that will work in all instances across all codebases. It really comes down to what is going to work best for your particular implementation. Hopefully, however, this introduction has been a good introduction into *how* you think about asynchronous operations. If you can conceptualize how things are occurring, you can determine the best approach to structuring your code.

Submit Apache Cordova Applications for iOS and Android to the Apple App Store & Google Play

Ian — Tue, 12 Jan 2016 00:08:00 +0000

In the past, we have looked at setting up Apache Cordova mobile applications for iOS and Android with HTML5, JavaScript and how to develop for this versatile platform. In what follows we will look at how to submit your application to the app stores of the respective platforms once you have finished developing your application.

As we looked at before, you will need a computer with the SDKs of the platform(s) you want to release on. If you want to release for Android devices, you will need to grab the Android SDK. I actually recommend you install Android Studio as this will download everything you need for this and future releases. If you want to release for iOS devices, you will of course need a Mac computer with Xcode installed. Unfortunately, you cannot develop iOS applications without a Mac. So if you want to build and release for iOS you will have to find some way to get access to one.

You will also need to sign up for developer accounts for the platforms you want to release on. These developer accounts do cost money. For Google Play (Android) there is a one time developer fee of $25. For an iOS developer account the fee is $99/per year.

Once you have signed up for your developer accounts, we can build our applications for release on the iOS and Android platforms.

Submitting to Your Cordova App for iOS to the Apple App Store

Once you are satisfied with how your app functions on all of the devices that you want your application to run on, you can start the process of preparing your project for submitting your app to the Apple App Store.

To submit your Apache Cordova application for sale (or free download) on the App Store you will need to go through the normal process that all apps must go through before they are submitted to the store. Building an app for release on iOS is a fairly straightforward process. You need to compile the release file by running the following command in the root of your Cordova project…

$ cordova build --release ios

This will build your application for release. There will be a generated Xcode project in the platforms/ios directory

Next, you’ll need go to https://developer.apple.com and click on “member center.” Sign in with your developer account if you have not already.

Creating an iOS Distribution Certificate

Click on “Certificates Identifiers and Profiles” and then on the next screen click on “Certificates.”

Click on the “+” button on the certificates page and scroll down in the production section and choose the “App Store and Ad Hoc” option and click “Continue”

We will want to create a new certificate so we will need to open up Keychain Access. The easiest way to do this is in your Mac click on the search bar in the top right and search for “Keychain Access” and open this application, Click on Keychain Access in the menu in the top left, and in the dropdown hover over “Certificate Assistant” and choose “Request a Certificate From a Certificate Authority”

This will open up a modal which you can then fill out the e-mail address with your developer account e-mail and then a common name which can usually just be the same of your organization. After you have filled these out choose the “Save to disk” option and save the certificate to wherever you want on your computer.

After we do this back in our developer account we will click “Continue” again and on the next page we will upload the CSR file we just created and saved to our computer. Attach the file via the “Choose file…” button, attach the file and click the “Generate” button.

In the next screen you will be able to download the generated file (which is an iOS distribution .cer file) by clicking on the “Download” button.

Download this file and save it somewhere on your computer (probably the “Downloads” folder).

After this, we need to again open up the “Keychain Access” application and we need to drag and drop this certificate into the section in the top left of the “Keychain Access” window called “logins.” Note that this information is also present on the download screen we were just at in the Developer Center.

That is all that we need to do for creating an iOS Distribution Certificate

Creating an App ID in Developer Center

Now that we have created our distribution certificate. we need to create an App ID. The App ID is a unique identifier key that the App Store will use to differentiate it from other apps.

Back in our developer account at https://developer.apple.com, click on the on the “Certificates Identifiers and Profiles” link. On the next screen click on the “App IDs” link under the “Identifiers” section. Click on the “+” button at the top to create a new App ID.

On the next screen, you fill in the name with whatever you want, but it is probably best to just put the name of your app in there. You need to be able to tell which App ID belongs to which app and the name is probably the easiest. So however you want to do that, it is totally up to you.

You will also need to enter your bundle ID in the “App ID Suffix” section. To find your bundle ID you will need to open up Xcode and open your project. In Xcode you will need to highlight your project file and then select your project in the dropdown in the upper-left corner of the window you need to select your application name under “Targets.” You need to navigate over to the “Info” tab and look at the Bundle Identifier value on this screen. You can change this to whatever you like. I like the reverse domain notation. If it were me doing this I would put com.ninebitstudios.name where “name” is the name of my application. So it would be something like com.ninebitstudios.fishblaster or something like that. But you can put whatever you want in here. Once you have this set, you need to also enter this in the “App ID Suffix” section in the App IDs section in your developer account. After you do this scroll down to the bottom of the page and click “Continue.”

There will be a confirmation screen on the next screen where you can click “Submit” and then on the next screen click “Done.” You should now see your App ID in the table view of iOS app IDs.

Creating an iOS Provisioning Profile in Developer Center

Back in the developer center, Under the “Provisioning Profiles” section in the “Certificates, Identifiers & Profiles” screen click on “Distribution.” Click on the “+” button to create a new provisioning profile. In the next section scroll down and choose “App Store” to create a distribution provisioning profile to submit your app to the App Store and click on “Continue”.

In the next section from the you can choose your app ID in the dropdown and click “Continue”.

Next you can create a name for the profile. You can put whatever you want in here, the name of your organization or the name of your application.

After you have chosen something click on the “Generate” button. This will take you to a screen where you can download your iOS Provisioning Profile. Download this .mobileprovision file and save it somewhere on your computer.

Now go to the location where you downloaded this provisioning profile. Double click on it and choose the “Add to Library” option to add this profile to the iPhone configuration utility.

Creating an App in iTunes Connect

Now you need to go to back to your developer center at developer.apple.com. From here you will need to select “iTunes Connect” and once you are in iTunes Connect you need to select the “My Apps” option. You will need to click on the “+” button to add a new app.

From here there is a lot of information that you will need to fill out for your application. This is basically a way of creating a new application portal where everything that will be used by Apple to publish your app will go. You will need to add some screenshots of the proper dimensions that will be used for the App Store previews. The tools and notifications provided there should give you indicators as to what items or information you need to provide. You can do this now or you can wait until after your application file has been uploaded and you are ready to finalize your submission to Apple for review.

Configuring & Packaging Project in Xcode

After you have done the above steps you will need to open Xcode if it is not already open. For an Apache Cordova project you can open the project by going to /platforms/ios and double clicking on the “.xcodeproj” file. You will then need to highlight your project in the left pane in Xcode and select your project under “Projects” in the upper left (i.e. do not select your project under “Targets”)

Click on the “Info” tab and in the “Configurations” section click on the “+” button and choose the “Duplicate Release Configuration” option. Double-click the newly created/duplicated configuration and rename it to “Distribution.” You should only have “Debug”, “Release”, and “Distribution.”

Next select your project under “Targets” in the upper left (i.e. do not select your project under “Project”). Next highlight the “Build Settings” tab. In the “Code Signing” section change all of the options under “Code Signing Identity” to the name of your certificate that you created earlier. Next change all of the options under “Provisioning Profile” to the value of the provisioning profile that you created earlier.

You will then need to do the exact same steps only this time you need to highlight your project in the left pane in Xcode and select your project under “Projects” in the upper left (i.e. do not select your project under “Targets”). After you do this highlight the “Build Settings” tab. In the “Code Signing” section change all of the options under “Code Signing Identity” to the name of your certificate that you created earlier. Next change all of the options under “Provisioning Profile” to the value of the provisioning profile that you created earlier. So it is a repeat of the same process that you just did for when you had your project selected under “Targets”

Next highlight your simulator at the top of your screen and choose the “iOS Device” option.

Then select “Product” in the top menu and choose “Archive.”

If all goes well, you should get a “Build Succeeded” notification.

Submitting to App Store Option #1 – Submit to App Store Button

You now have your finished product that you will submit to the App Store. You should see something like the following screen…

To submit your app to Apple’s App Store all that you have to do is click the “Submit to App Store…” button. If you want you can use some of the tools to validate your project if you like to make sure that there are no errors.

If all goes well you should see the following…

If you run into any issues doing things by this process, you can try the approach below.

Submitting to App Store Option #2 – Uploading your Archive (.ipa file)

If you run into an issue that says “Unable to validate your application. The application you have selected does not exist” or recieve other error messages of any sort, you might have to try to use an alternate method of submitting your app. Apparently this is an issue that occurs for some developers in some environments. If you run into this issue you can still submit your application manually. You can use the “Application Loader” utility to upload your app to the App Store. Select this utility by choosing Xcode > Open Developer Tool > Application Loader from the top menu

With the Application Loader utility open, click the “Export” button on this screen. In the prompt, select the “Save for iOS App Store Deployment” option.

Click on the “Next” button. You will be prompted choose your developer account. Then click “OK.” This will create a .ipa file for you on your computer. You can then go add this file in iTunes Connect by signing in to your account and uploading it there.

Finalizing your Submission in iTunes Connect

Once you have uploaded your application, you need to go back to iTunes Connect and finalize your submission to Apple. You can finish uploading the required icons and screenshots at this time if you have not done so already. Once you have everything set, click on the “Submit for Review” button and follow the prompts. There is a review process that every app submitted to Apple undergoes to ensure quality assurance and that the app follows all of Apple’s requirements and guidelines for selling apps. It will take about 10 days for Apple to get around to reviewing your app and they will notify you on whether it is approved for sale or rejected.

If your app is rejected, do not be discouraged. Nearly every app developer has had an app rejected at some point or another. You just need to fix the issues that are outlined by the review team and resubmit. Fortunately the resubmission process goes pretty quickly because you already have all of the bits in your project set up. You’ll just need to fix what needs to be fixed in your Cordova project and rebuild and follow all of the same steps as outlined above. Fortunately, most of the hard work of filling out all the forms and creating the provisioning and distribution files is already done.

Sometimes it takes one or two tries to get your app approved, but if you keep at it, you’ll get there!

Submitting to Your Cordova App for Android to Google Play

To submit your Apache Cordova application for sale (or free download) on Google Play you will need to go through the normal process that all Android apps must go through before they are submitted to Google Play. In many ways the process of distributing applications on Android via Google Play is a lot more streamlined, quicker, and developer-friendly (i.e. easier) when compared to submitting apps to Apple’s App Store.

Creating an Application in the Google Play Developer Console

The first thing that we will need to do in order to prepare for distributing our application on Android is to create a new application within this Google Play Developer console. You will need to sign into you Google Play Developer Console and then you’ll need to click on the “Add New Application” button and fill out the details for your app. You will need to upload some screenshots, icons and also answer some questions to get your app a rating to indicate the “age appropriateness” of you app and the degree to which it contains mature/adult content. You will also see that that there is a button to upload an “APK” file. This is your app file for Android which we will create next.

Creating an APK File

In the following sections we will build an APK file (which is shorthand for Android application package) that we submit to Google Play. You need to compile the release file by running the following command in the root of your Cordova project…

$ cordova build android --release

This will create a file in the /platforms/android/build/outputs/apk directory called android-release-unsigned.apk (or something like that). Hang on to this file (or make a copy of it) because we will need it later.

The “unsigned” designation just means that it has not been signed with a certificate of authenticity. Later on we will be adding the credentials from our developer account for security purposes. We will need to do that by using a number of the tools provided by Java to “sign” our application. The first utility we will utilize is the “keytool.” The keytool utility is part of what ships with the Java Development Kit (JDK). So on my windows machine it was located at C:\Program Files\Java\jdk1.7.0_51\bin\keytool.exe. The location might be different for different operating systems. It’s basically wherever your JDK is installed in the “bin” directory. Wherever it is on you computer, run the keytool utility with the following command (or its equivalent)…

$ keytool -genkey -v -keystore ninebitapp.keystore -alias ninebitapp -keyalg RSA -keysize 2048 -validity 10000

You can change the name of your keystore file in the -keystore flag to whatever you want. All that specifies is the name of the file that gets output after running this command.

Next we will take the .keystore file that was created with the keytool utility and sign it using another utility that ships with the JDK called “jarsigner.exe.” Get the android-release-unsigned.apk file that we grabbed from our Cordova project. Using this file and the generated .keystore file we created from the previous command and run the following…

"C:\Program Files\Java\jdk1.7.0_51\bin\jarsigner.exe" -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ninebitapp.keystore app.apk ninebitapp

NOTE: I actually renamed the .apk file to “app.apk.” Reason being, I encountered an error when trying to use jarsigner tool when the filename was left as “android-release-unsigned.apk” I guess the tool doesn’t like hyphens?

When you run this command you will have to enter some credentials to password protect this file for your Google Play developer account with this certificate of authenticity.

Now that we have signed the .apk file we will use the “zipalign” tool to prepare our application for release. The “ZipAlaign” tool can be found in the Android SDK directory. We can utilize it by running the following command on our signed .apk file.

"C:\Users\IanC\AppData\Local\Android\sdk\build-tools\22.0.1\zipalign" -v 4 app.apk ninebit_out.apk

This will create a zip aligned .apk file. It is this file we will submit to the Google Play store via the Google developer console. Just follow the prompts there and submit. Google Play apparently does have a brief review process, but really it’s probably just to confirm that the app launches and does not contain any malware. Unlike with the App Store, your app will almost certainly be approved if it passes these 2 smoke tests. Also, you expect your app to be available for download on Google Play within a few hours. This is a much shorter duration than the 10 days it takes for the iOS review process.

Summary

In the preceeding discussions we went through and looked at the process for building your apps for release on iOS and Android and submitting your applications to the Apple App Store and Google Play. Hopefully, in reading this you have found this at least somewhat helpful. Until next time, happy developing! Go create great apps!

Develop Apache Cordova Applications with HTML5 & JavaScript

Ian — Sat, 19 Dec 2015 22:59:14 +0000

In a prior discussion we looked at how to set up a project so that we could develop an Apache Cordova application using HTML5 and JavaScript. In that section we mostly covered how to set up, build, and run the project — which consisted of the same application in the www folder that Apache Crodova bootstraps when you create a new project. In what follows we will look at the approach for actually writing own code for our app and will look at how an app in Apache Cordova gets initialized. We will also look at how we can extend the Apache Cordova platform by using plugins to give ourselves additional features and functionality that will make for an all around better user-experience (UX) for the users of our app.

Now that we have our project set up and all our platforms added all that we have left to do now is create our application by creating what basically amounts to a website that runs HTML and JavaScript in the “www” folder. How should one develop for Apache Cordova? Personally, I would delete all of the boilerplate files and folders and start from scratch. That is what we will do here. Just take a quick note of how things are referenced in the index.html file and do the same for your own files.

In doing this, I have modified the index.html file in the “www” folder to the following…



    
        
        
        
        
        
        Cordova Application
    
    
        
        Initializing...

Note: Do not worry about that “cordova.js” reference or the fact that this file is nowhere to be found in our “www” folder. Apache Cordova will utilize this in the proper context when the app runs (so leave it in there).

So as far as the index.html goes, there is nothing too fancy. I have a css file (index.css) and a js file (index.js). That is all you need to get started.

Next, let’s look at our JavaScript in the index.js file. There is really only one thing you need to make note of when you develop Apache Cordova applications in JavaScript. There is a special event that Apache Cordova uses to tell the platform that the everything is loaded and the device you are using is ready to start running JavaScript in your Cordova application. This is what is known as the “deviceready” event. It only fires when you are running an app within a Cordova context (i.e. on a device or an emulator of a device). In a lean version of JavaScript for a cordova application would look like the following (in index.js)…

var app = {
    init: function() {
        document.addEventListener('deviceready', this.main, false);
    },
    main: function() {
        document.getElementById('main').innerText = 'App is ready...'
    }
};

app.init();

Here we are calling the “init” function which will add a listener for the “deviceready” event. When this event fires the “main” function will run, which in this case just changes the inner text of a div element So if we run this using

$ cordova emulate android

$ cordova emulate ios

from the root of our project we will see our device boot up, our app launch, and if all goes well we will see the text “App is ready…” so we know that our event is firing.

But it gets kind of annoying to have to fire up the emulator every time we want to test something out or make small changes in doing development. So it would be easier to be able to open the index.html file in the browser. But the problem with this is that the browser does not natively support the “deviceready” event. If you try to open index.html in a browser you see that the text remains as “Initializing…” The “deviceready” event does not get fired by the browser. So to get around this we have to set a flag so that we conditionally check if we are trying to run our app in a browser. So update the code in index.js to the following…

var config = {
    DEV: true    
};

var app = {
    init: function() {
        if(config.DEV) {
            this.main();
        } else {
            document.addEventListener('deviceready', this.main, false);
        }
    },
    main: function() {
        document.getElementById('main').innerText = 'App is ready...'
    }
};

app.init();

Now that we have set a flag in config to check whether we are just intending to run in “dev mode” in the browser, we will just call the main function directly and that will be the place that we kick off our application. We essentially bypass the “deviceready” step.

Now if you run this in the browser, we see that the “App is ready…” text is rendered to the page. If we change the config.DEV flag to “false” and run

$ cordova emulate android

$ cordova emulate ios

we can see that our main function is still running to kick off our app.

Even though the “deviceready” event is kind of the official Apache Cordova way of making sure that everything is initialized, if you forget to change the “DEV” flag to “false” and directly call the “main” function while running on a device, things will probably still work.

Splash Screens, Icons, & Using Plugins

Apache Cordova gives you a great framework out of the box to create a mobile app that can run on different platforms (as we have seen). But as great as it is, often there are things that you run into that may not be as easy to implement as they would be if you were creating an app using the native tools and languages. Fortunately, if you run into something that is not natively supported in Apache Cordova, there is a vibrant plugin ecosystem (and community behind it) that has worked to extend the support and functionality of the framework. You may have noted that there was a “plugins” folder in our Apache Cordova project. This is where installed plugins go.

Let’s take a look at a plugin that allows us to display a “splash screen” while our app launches. This is a common feature that you may have seen in many apps. We will use the cordova-plugin-splashscreen plugin. This plugin will allow us to specify paths to images that we will use as our splash screens. Because there are so many different resolutions across iOS and Android phones and tablets, we are going to have to specify a number of different resolutions of images that we will use for our splash screens. It will also allow you to show the Rather than list out what each of these resolutions need to be I have included a sample Apache Cordova project here as a download with some blank images of the sizes that they need to be to support this feature on most (nearly all) modern devices (iPhones, iPads, Android phones, and Android tablets). You can find these in the “res” folder in the “www” directory.

This cordova-plugin-splashscreen plugin will also allow us to specify the images that will be used for the icon of our app that shows up on the user’s home screen when the app gets installed. Up until now, Apache Cordova has just been using its own default image (that little robot looking thingy). But with this plugin we can change the icon, to what we want it to be! Awesome!

To install our plugin we just need to run the following from the root of our Apache Cordova project…

$ cordova plugin add cordova-plugin-splashscreen

If for some reason that does not work for you, you can try running the following

$ cordova plugin add https://github.com/apache/cordova-plugin-splashscreen.git

Once the plugin is installed we can now specify the paths to our splash screens and icons. We will do this in the config.xml that resides in the root of our project. As mentioned prior I have posted a sample Apache Cordova project that is available for download. In that project we can see the config.xml file that looks like the following…



    SampleApp
    
        A sample Apache Cordova application...
    
    
        Apache Cordova Team

As we can see, we have specified paths to a number of different images of different resolutions. with these settings the cordova-plugin-splashscreen Apache Cordova plugin will automatically figure out which is the best resolution to use depending on the

We can also see that in the elements down at the bottom we have specified “SplashScreenDelay” preference down at the bottom of the config.xml file. This specifies to show the splash screen for 4 seconds (4000 milliseconds). You can change this value to the one that you prefer.

Now if you run your application with

$ cordova emulate android

$ cordova emulate ios

You will see a splash screen displayed before the app launches. It’s blank for now until you bust out your graphic designer skills and create a nice looking one. If you click on the “home” button on the emulator device you can see on the home screen that the icon we have in our project is now used as the app icon. Like with the splash screen, obviously for a production app we would want to make nice looking icons consistent with the theme of our app. But the functionality is there and all you have to do is replace the icons and splash screens in the sample project with your own app branding.

So sample project and try it out. Note: After downloading the project you will need to 1) add the platform(s) that you want to work with with $ cordova platform add and 2) install the splash screen plugin with $ cordova plugin add cordova-plugin-splashscreen.

Summary

Now that we have walked through how to set up some app initialization code from here, everything that you want to do is entirely up to you. There are really no limitations on what you can do here. Apart from the unique “deviceready” event there is nothing special that you need to do to code for Apache Cordova (and even hooking into the “deviceready” event probably isn’t even absolutely essential). You can just create things in the same way that you would if you were going to put this web application on the web and have users run it in their browsers. There is no special magic needed. You can add more CSS files, images, other JavaScript files, or whatever else you want to and start building. You can use popular front-end frameworks like Bootstrap or Foundation. Or, if you prefer, you can import a framework specifically designed for mobile such as jQuery Mobile. You can use popular JavaScript development frameworks like Backbone.js, Ember.js, AngularJS, or React. Ultimately the choice is entirely up to you. I cannot choose for you.

From there, the sky’s the limit. You can do whatever you like to create whatever kind of app you want. But since there are so many different types of applications for so many different purposes, it is ultimately up to you to decide on what technologies you want to use and what is the best way to implement your app. So get out there and develop it up. Until next time, cheers and happy developing!

Create Mobile Applications for iOS and Android with HTML5, JavaScript, and Apache Cordova

Ian — Sat, 12 Dec 2015 22:49:53 +0000

Obviously at the time of this writing in the 2nd decade of the 21st century, you are no doubt well acquainted with the immense proliferation and impact that mobile apps have had in and on our world. It was not long ago that we were all sitting at our computers at our desks for the large majority of the time we spent in our various avenues of technological communications over the Internet — complete with our with our giant monitors, whirring computer fans, buzzing drives, and the garbled noise of dial-up modems. Now, mobile phones and tablets probably make up as much, if not more, of our time spent working, playing, and communicating online. Everyone has a ~$100 to $600 smartphone (i.e. computer) in their pocket. And with this rise of mobile, apps found on the popular stores — like Apple’s iOS App Store, Google Play (Android), Amazon and a host of others — have completely transformed the way that we do anything and everything because well, there is an app for anything and everything. Every single facet of life probably has an app to manage some aspect of it. Need to remember to breathe? There is an app for that! Yeah, that is a joke (probably)… but there are plenty of “real” apps out there (e.g. iBeer) that are just as pointless. Fun and goofy, yes, but pointless. And they all post their pointlessness to Facebook and/or Twitter.

Whether you want to develop an app to manage some minute aspect of life or just create a fun game, or whatever else, you can download the SDK for the platform(s) that you want to release your app on, do some tutorials, and start building. That’s all well and good, but if you want to port your application to another platform (e.g. release an iOS app also for Android), you will essentially have to try rebuild the same app using the languages in tools of a different platform. For example, iOS apps for iPhone and iPad have traditionally been developed on a Mac in the Xcode IDE using the Objective-C programming language (though Apple has recently released a new language called Swift that can also be used to build iOS apps). Android apps, by contrast are built using Java and Eclipse or the more recently released Android Studio. Native Windows Phone apps are built using C# and XAML in Visual Studio. Other platforms have their own setups. If you want to take this approach you definitely can, but it should be fairly apparent that developing and maintaining a number of different codebases for multiple platforms quickly adds up to a lot of time, effort, and often money as the sizes and complexity of your apps increase.

At the same time as the rise of mobile in the past decade, something else has occurred: the rise of HTML5 and JavaScript web applications. Beginning at around 2009 – 2010 one of the more noticeable developments was the rise of websites and web applications making use of more open technologies such as HTML5 and JavaScript to bring interactivity and 2-way communication between clients (usually browsers) and servers. With Flash on the way out due its proprietary nature, resource hogging, security issues, poor SEO — along with its being snubbed by Apple for support on iPhones and iPads for basically all these reasons — meant that something had to fill the void. HTML5 and JavaScript moved into this space and developers started turning to it for creating interactive “app-like” experiences.

Wouldn’t it be awesome if there were a way to write a single application in HTML and JavaScript with a single codebase and have a way to port this application to all of the different mobile platforms? I am so glad you asked.

Apache Cordova — also commonly known as “PhoneGap” (the only difference between the two is propriety) — allows us combine combine these open technologies together with the SDKs of the various mobile application platforms to make native mobile applications using technologies such as HTML and JavaScript. You can basically create a small static HTML and JavaScript website or web application and this code will be imported into native iOS, Android, Windows Phone projects and configured specifically for the respective platforms. Thus, you *do* still have to have the SDK of the platform installed to build, run, and release the apps. So to create an iOS app you will still need a Mac and Xcode. To create Android apps you will need to install the Android SDK (which comes with the Android Studio IDE). But the important aspect of using Cordova is that the HTML and JavaScript that each project will pull in and build will be the same across all platforms. Want to release an update with some slick new features or fix some bugs that have been reported by your users? You need only change your code in your HTML and JavaScript. You don’t have to try and rewrite the same code and/or functionality in a different language on each platform. From there all you need to do is run a few simple commands from the command lines and your HTML and JavaScript will get built and converted into an application that can run on the platform(s) you are targeting.

In what follows we will explore what it looks like to use Cordova to create a mobile application in HTML and JavaScript that can run on a number of different platform. For our examples, we will build our app for iOS and Android, but the process is essentially the same for building for other platforms (e.g. Microsoft Windows Phone, Amazon Kindle Fire). You would just need to download the SDKs for those platforms if you wanted to run your app on those types of devices as well.

So let’s get to it…

Installing Node.js

The first thing that we will need to do before we do anything else is install Node.js. Apache Cordova runs on Node.js so it is a prerequisite. If you’re not entirely familiar with Node.js there is a primer on Node.js here. It has become a huge part of JavaScript development in the last half-decade and is only becoming more and more prominent.

To install Node.js all you have to do is head on over to their website and follow the directions for your operating system (Windows, Mac, or Linux).

Installing Apache Cordova

Once we have Node.js installed, next we will need to install Apache Cordova. We just do this over npm. npm comes with the Node.js installation, so you already have it on your machine from installing Node.

To install Cordova open up a command window or terminal and run the following…

$ npm install -g cordova

In case you are not familiar with it, the “-g” flag means “global.” You will want to do this so that you can run Cordova commands from any directory on your system.

Creating an Apache Cordova Project

Now you can go to a directory where you want to create your Cordova project and open a command window/terminal. We will be initializing a new Cordova application here with the Cordova “create” command. For more information on the configuration options you can choose when installing and setting up your project, please see the Apache Cordova documentation here. Run the following command from your command line…

$ cordova create ninebit com.ninebitstudios.ninebitapp NinebitApp

The command above will create a vanilla Cordova project called “NinebitApp” and ocnfiguring it with a unique ID that uses reverse domain name notation in a directory named “ninebit.” What you will want to do is change these values to what you want for your own application.

$ cordova create

For example…

$ cordova create yourdirectory com.yourdomain.yourapp YourAppName

but just plug your own values that you want in there.

You should see the directory with the name you specified created with with a number of files and directories in there like “platforms,” “plugins,” “www”, and a “config.xml” file. The config.xml file will have some of the values that you specified in your mobile. The actual location where you will write your HTML and JavaScript is in the “www” directory. If you explore that directory and open the index.html file you will see a boilerplate web application which basically just displays an image on the page. Even though it does not do much, this is an app that can run on any of the platforms we want to specify. We will add these platforms next.

Adding Support for Android Devices to the Project

Now that we have our project created we need to “add” the platforms that we want to release on to our project. Open a command window in the root directory of the project (the one with the config.xml file).

To add Android to our project run the following…

$ cordova platform add android

You should see a directory called “android” in the platforms folder. This folder contains a native Android project that is preconfigured to take the HTML and JavaScript in the “www” folder and run it in an Android device. If you opened Android Studio and clicked on “Create New Android Project” you would see almost the same files and folders in the project that gets created when creating a native Android application. There will be few extra files and folders in the Cordova Android project specific to Apache Cordova.

Because we now have a native Android project, we can run it on the Android emulator. In the root directory we can now run following…

$ cordova emulate android

This should launch the Android emulator and automatically run your application after it boots up. Note that you might need to set up a device for Android project to use before you try to run the command above. To do this, you will need to launch the Android Virtual Device Manager (AVD Manager.exe). This application resides in the root folder of where you installed your Android Studio SDK. You can also launch AVD Manager in Android Studio under the “Tools” menu under “Android.” However you open this application, once you are in there just click “Create New” and pick whatever device you want. Once you get the device set up you can try to run the command above again.

Adding Support for iOS Devices to the Project

Similarly, if you want to add support for iOS

$ cordova platform add ios

As was the case with Android above, you should see an “ios” directory. This folder contains a native Xcode project that is preconfigured to take the HTML and JavaScript in the “www” folder and run it in an iOS device.

Remember that you *must* have the SDK of the platform you are trying to add installed on your system. If you do not the Cordova console should inform you of this error.

For iOS you will want to make sure that you have the proper folder permissions in all of the directories and folders you will be working in. I had some issues trying to emulate when running all the cordova commands with sudo. So make sure on your Cordova project directory you do something like the following…

$ sudo chmod -R 777 foldername

so that you can run all the commands without using sudo

The first thing that you’ll want to do is add the iOS platform to your project.

$ cordova platform add ios

You can then build for iOS by running the following command. If you are able to do so without errors, you’ll know that everything is all good.

$ cordova build ios

Note in /platforms/ios/cordova/lib there is a list-emulator-images tool that you can run to list out all of the emulator images that you have installed. These are the different devices that you can emulate your apps…

$ ./platforms/ios/cordova/lib/list-emulator-images

You will see a list like the following…

iPhone-4s
iPhone-5
iPhone-5s
iPhone-6-Plus
iPhone-6
iPad-2
iPad-Retina
iPad-Air
Resizable-iPhone
Resizable-iPad

If you want to specify a target, you can run the simulator on a specific device by targeting a specific device. For example…

cordova emulate ios --target="iPhone-4s"
cordova emulate ios --target="iPad-Air"
cordova emulate ios --target="iPhone-6"
cordova emulate ios --target="iPhone-6-Plus"

Otherwise, the iOS development tools will just use what is set as the default device (usually the latest version of the iPhone that is currently in production).

And of course, if you want to emulate on an iOS device in Xcode you can run the following command in your project root…

$ cordova emulate iOS

This should launch the iOS simulator and run your application.

Summary

In the above discussion we looked at all of the steps, tools, and environments necessary to create an Apache Cordova project and get things set up such that you can begin developing cross-platform mobile applications. In a future discussions we will take a deeper look at how write the code for out apps as well as how to package everything in your application up once you are finished developing and submit it to the respective stores for iOS (App Store) and Android (Google Play). But those are other discussions for some other days. So until next time, happy mobile developing!