CSE330 Wiki - User contributions [en]

Web Application Security, Part 1

2015-08-02T18:55:23Z

Shane: /* Git Exposed */

Application-level web security is of increasing concern among web developers. This article outlines some types of security threats to your web application and how to solve those threats.

This is Part 1 of the Web Application Security article, geared toward the material covered in [[Module 2]]. For material covered in [[Module 3]] (MySQL), see [[Web Application Security, Part 2]]. For material covered in [[Module 6]] (JavaScript), see [[Web Application Security, Part 3]].

== Introduction to Application-Level Web Security ==

Every day, computer hackers around the world penetrate web applications, often for personal profits. You may find it hard to believe, but '''even high-profile web sites (banks, social media, even computer security companies) are vulnerable to application-level attacks!'''

Not only is it embarrassing to be the programmer who wrote the vulnerable code, but it could also cost you your job. As a prudent web developer, it is ''imperative'' that you take precautionary measures to make your application difficult to penetrate. Indeed, most of the time, if your site is well-written, hackers will just move on.

Here's the golden rule: Anything in your site that accepts user input, whether via a form, an AJAX request, a file upload, or even malformed links, can be used as an attack vector. '''NEVER TRUST USER INPUT!!!''' This can be summarized in the acronym FIEO, or ''Filter Input, Escape Output''.

=== FIEO in PHP ===

==== Filtering Input ====

"Filter Input" means that you should check that input data is of the format that you are expecting. For example, if you are expecting a number, you should cast it to a float or an int. If you are expecting a phone number, you should run it through a regular expression (you will learn regular expressions in module 4). For example:

<source lang="PHP">
<?php
// Cast a number to a float or an int:
$amount = (float) $_POST['amount'];

// Pass a phone number through a regular expression:
$phone = preg_match('/\d{3}-\d{3}-\d{4}/', $_POST['phone']) ? $_POST['phone'] : "";
?>
</source>

==== Escaping Output ====

"Escape Output" means that you need to nullify, or ''escape'', characters that have special meaning in the markup language of interest. For example, consider the following string:

<source lang="html4strict">
If a<b and b<c then a<c.
</source>

Since a less-than sign means the start of a tag in HTML, and '''b''' is a valid tag name, the above string will ''not'' render as you might expect in HTML. Therefore, we need to ''escape'' our less-than signs by using HTML entities:

<source lang="html4strict">
If a<b and b<c then a<c.
</source>

The "<" is an '''HTML entity''' that will render as a less-than sign. (For more information on HTML entities, [http://docs.webplatform.org/wiki/html/entities read this article on the WebPlatform wiki].)

PHP provides a function that, given a string, will convert special characters to their HTML entity equivalents.

<source lang="PHP">
<?php
$str = "If a<b and b<c then a<c.";

// Convert special characters to HTML entities before outputting:
echo htmlentities($str);
?>
</source>

'''Note:''' ''htmlentities'' escapes a string for use in HTML, but it does ''not'' escape a string for use in other markup languages. You need to use different methods when escaping strings for other languages.

=== Why Not to Escape Input ===

Filtering your input is important, as shown above. However, it is bad practice to ''escape'' your input. For example, don't do this:

<source lang="PHP">
<?php
$message = htmlentites($_POST['amount']); // bad practice
// then store $message in a database, etc.
?>
</source>

The reason this is bad practice is that it permanently ties that string to its final output format. For example, what if some time down the road you want to support display of that message in a PDF? You'd need to go back and remove all the HTML entities again.

This is why you should ''filter'' strings at the input stage but not ''escape'' them until the final output stage.

== Format String Injection ==

If you like using functions like '''printf''' and '''sprintf''', you may find yourself writing

<source lang="php">
printf( "%s", htmlentities($_GET['username']) ); // good example
</source>

It is tempting to reduce this to

<source lang="php">
printf( htmlentities($_GET['username']) ); // BAD example
</source>

Although the second implementation will work for most usernames, it is '''''not''''' correct! You are essentially making the client-provided username the ''format string'' for printf. If the username contains any percentage sign (%), it will be interpreted as the start of a parameter in the format string, causing your script to return errors. Worse yet, it is known that certain combinations of format parameters will actually reveal system information in the error log.

=== Solution ===

The solution is simple: never put dynamic input as the format string. It should always be static, either hard-coded or from a stable source like a YAML file. User-supplied input should ''always'' be fed into the string as arguments to sprintf and printf.

If you are outputting only one little string like in the example above, it suffices to use a PHP function like '''print''' or '''echo''':

<source lang="php">
print htmlentities($_GET['username']); // good example
echo htmlentities($_GET['username']); // good example
</source>

== Server Configurations ==

Sometimes hackers attempt to penetrate your application from the server side rather than the application side. Server-side security is beyond the realm of this course, but here are some things you should keep in mind.

* Use a highly secure root password, and it should be one that you don't use anywhere else. Seriously.
* Use a firewall system to block unnecessary ports from public access. SSH and Web Server should really be the only ports you need. You should keep the web serve on port 80, but you have the option of moving SSH to a port other than 22 to make it slightly more secure.

=== Git Exposed ===

Another thing to keep in mind is that by default, Apache serves up ''everything'' in your file tree, only except for Apache-specific configuration files like .htaccess. This means that if you're not careful, your .git directory can be served, exposing attackers to your raw source code, including things like database passwords! A recent study found that [http://www.jamiembrown.com/blog/one-in-every-600-websites-has-git-exposed/ one in every 600 web sites is making this mistake]. Don't be one of them!

[[Category:Module 2]]
[[Category:Web Application Security]]

Web Application Security, Part 1

2015-08-02T18:54:08Z

Shane: /* Server Configurations */ Don't expose .git

JavaScript

2015-07-24T19:35:16Z

Shane: /* Prototypal Inheritance */ Adding note about extending built-in prototypes

JavaScript is the most widely used scripting language for implementing client-side functionality in Web applications. Unlike PHP, JavaScript code is interpreted and executed in a client's web browser (not on the web server).

== JavaScript? Did you mean Java? ==

'''JavaScript''' is a prototype-based programming language focussed on web interactivity. It was first introduced in Netscape Navigator, and it in turn gave rise to what is now '''[http://www.ecmascript.org/ ECMAScript]'''. Originally, JavaScript was called "LiveScript". Sun, the developer of Java at the time, wanted a language that would complement its compiled Java language, and so LiveScript was renamed JavaScript.

Beyond that, '''Java and JavaScript are as similar as Ham and Hamster.'''

Java and JavaScript have similar syntax, but the under workings are quite different. For example, Java requires strict typing, but JavaScript allows for dynamic typing. Java is object-oriented, but JavaScript is prototype-oriented. Java is compiled, but JavaScript is interpreted. Java supports event listeners, but JavaScript makes them a fundamental part of the language. Java variables are scoped to the innermost method or loop, but JavaScript variables are scoped only to the innermost function.

== JavaScript Language Components ==

This section highlights some features of the JavaScript language that differentiate it from other languages. For a more comprehensive JavaScript tutorial, the following tutorials are both quality:

* [http://docs.webplatform.org/wiki/javascript WebPlatform]: Great for learning JavaScript for the first time. Advocates best practices for modern JavaScript development.
* [http://www.quirksmode.org/js/contents.html QuirksMode]: More advanced than the WebPlatform tutorial, but it thoroughly covers the most powerful aspects of pure JavaScript and gives unparalleled advice on browser compatibility.

Advice: Do '''NOT''' Google for "JavaScript Tutorial". The first few hits advocate bad or outdated practices. Stick with the ones listed here.

=== Variables and Scope ===

To define a variable in JavaScript, use the '''var''' keyword.

<source lang="javascript">
var foo = "bar";
</source>

All variables are objects. In the case above, the variable '''foo''' is an object of the class '''String'''.

Notice that like PHP, you do not have to explicitly define a type for a variable like '''int''' or '''String'''; this is because JavaScript and PHP are ''dynamically typed languages''.

JavaScript code can access any variable higher in the “function tree”, but not vice-versa. This is called '''scope'''. ''All functions create their own scope.''

When you reference a variable, JavaScript will look up through the "function tree" until it finds the variable you asked for. This means that you could define variables of the same name as global variables inside of functions. For demonstration of concept:

<source lang="javascript">
var a = "hello";
var b = "world";

function sayGoodByeWorld(){
var a = "goodbye";

alert(a); // goodbye
alert(b); // world
}

sayGoodByeWorld();

alert(a); // hello
</source>

=== Object Literals ===

A very common way of storing and transporting data in JavaScript is by using objects. You can define an object with certain properties using an '''object literal''':

<source lang="javascript">
var apple = {
color: "red",
flavor: "sweet",
season: "autumn"
}

alert(apple.color); // red
</source>

=== Functions ===

To define a function in JavaScript, use the '''function''' keyword.

<source lang="javascript">
function sayHello(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Pass an argument to a function like this:

<source lang="javascript">
function sayHello(name){
alert("Hello, "+name);
}

sayHello("Todd"); // call the function and pass an argument
</source>

==== Functions are Objects ====

In JavaScript, functions are objects. This means that they can be assigned to variables, manipulated on the fly, and even passed as arguments to other functions! '''''This is an extremely important feature of JavaScript''''' that makes it such a robust language for web development.

You create a function variable like this:

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Observe that you can make [[#Variables and Scope|scope-dependent]] functions in this way.

=== Closures ===

{{DoctypeTV
|youtube_id=HaPlj796ngQ
|time=5m45s
|desc=JavaScript Closures
}}

A '''closure''' is a way to separate a certain snippet of JavaScript code from the global scope. This is useful if you do not want to "muck up" global variables. Closures are nothing more than anonymous functions that are called as soon as they are created:

<source lang="javascript">
var a = "hello";

(function(){
var b = "world";

alert(a); // hello
alert(b); // world
})();

alert(a); // hello
alert(b); // ReferenceError: b is not defined
</source>

{{JSFiddleExample
|title=Passing Variables to a Closure
|desc=This example demonstrates how you can "save" previous versions of a variable using closures. This is possible because of scoping and the fact that function variables can be returned as objects.
|fiddle_id=YURqa
}}

Most JavaScript libraries (like jQuery) write all of their code in a closure. What this means is that except for one or two variable names (jQuery or $), everything associated with the library is completely self-contained.

=== Prototypal Inheritance ===

JavaScript implements '''prototypal inheritance''', as opposed to a language like Java or C++, which implements '''classical inheritance'''. JavaScript is one of only a handful of languages implementing prototype-based inheritance.

Here's how it works. Every callable object (function) has a '''prototype'''. When instances of that object are created, their properties and methods are copied (inherited) from the prototype. Additionally, changes made to the prototype later in the program are "copied" to every instance.

For example, if you wanted to make a method on all strings that added a “!”, you could modify String’s prototype:

<source lang="javascript">
String.prototype.bang = function(){
return this+"!"; // Notice: the context is the instance itself
}

alert("Hello".bang()); // alerts Hello!
</source>

To "extend" an object, just copy its prototype to a new object. However, since classical inheritance and prototypal inheritance are different concepts, copying prototypes may have results that you don't expect. [http://beej.us/blog/data/javascript-prototypes-inheritance/ This article] seems to have a pretty good explanation of how to "inherit" prototypes with example implementations.

==== Extending Built-In Prototypes ====

You should be aware that there is an active debate in the web development community about whether it is good programming style to extend the prototypes of built-in objects like String and Array, such as in the ''String.prototype.bang'' example above. There are legitimate arguments on both sides. [http://stackoverflow.com/questions/8859828/javascript-what-dangers-are-in-extending-array-prototype This Stack Overflow post] has good links to some articles discussing this issue.

=== Context ===

{{DoctypeTV
|youtube_id=0a4r4bm1nQA
|time=4m32s
|desc=The ''this'' Variable in JavaScript
}}

Every function is called on a certain object, which is not necessarily the same object in which it was defined. This is called '''context'''.

To call a function on an arbitrary context, use either '''call''' or '''apply'''. ''call'' takes a list of arguments, while ''apply'' takes them all in an array.

To access the current context, use the '''this''' keyword. Demonstration of concept:

<source lang="javascript">
var sayThisColor = function(){
alert(this.color);
}

var apple = { color: "red" }

sayThisColor(); // undefined
sayThisColor.call(apple); // red
</source>

== Events ==

Events are really what make JavaScript such a powerful language for web development.

Rather than being thread based, JavaScript is event based. Since all JavaScript code runs in a single thread, '''there are no concurrency issues'''. When an event occurs, JavaScript automatically calls the ''event callback'' as soon as all previous events' callbacks have finished executing.

Code in the form of a '''callback function''' is associated with events via a '''listener'''. For example, the following JavaScript causes ''sayHello()'' (the callback function) to be run whenever the button with ID "hello" is clicked (the event):

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

document.getElementById("hello").addEventListener("click", sayHello, false);
</source>

{{JSFiddleExample
|title=Binding Callbacks to a Button Click
|fiddle_id=L8c4Z
|cse330=true
|desc=In this example, notice how we bind the callback function when the ''DOMContentLoaded'' event fires. This is because JavaScript requires that the button has been parsed by the browser before it can add event listeners to it.
}}

The '''addEventListener''' method takes three parameters:
* The event type
* The callback function
*: The callback function is passed one parameter: the event object.
* A boolean representing bubble (false) or capture (true) phase
*: You usually want Bubble phase. For more information on event phase, see [[#Event Phase]]

Note that versions of Internet Explorer prior to version 9 required that you use a different, albeit similar, function for assigning event listeners called '''attachEvent'''. attachEvent takes the same arguments as addEventListener, except you need to put '''on''' before the event type (e.g. "onclick"), and the third argument (phase) is not necessary.

It is perfectly valid to use an '''anonymous function''' as your callback function:

<source lang="javascript">
document.getElementById("hello").addEventListener("click", function(event){
alert("Hello, World! Event Type: "+event.type);
}, false);
</source>

QuirksMode has perhaps the best series of articles about the ins and outs of JavaScript events on the internet: http://www.quirksmode.org/js/contents.html#events

=== The Event Object ===

Callback functions are passed one argument: an ''event object''. You see above that one property of the event object is ''event.type''. To see the full list of properties of the event object, you could run the code:

<source lang="javascript">
document.getElementById("my_btn").addEventListener("click", function(event){
var strout = "";
for(var i in event){
strout += i + ": " + event[i] + "\n";
}
console.log(strout);
}, false);
</source>

Some of the most useful properties and methods include:
* '''event.target''' references the object on which the event occurred.
* '''event.currentTarget''' references the object whose listener is currently being processed.
*: ''Note:'' event.target and event.currentTarget might be the same or might be different, depending on whether you are listening for bubbled events.
* '''event.preventDefault()''' stops the normal result of the event from being executed. For example, if you listen for a form's ''submit'' event, you can call event.preventDefault() to stop the form from being submitted.
* '''event.stopPropagation()''' prevents any other event listeners from being executed. For more detail, read the section on Event Phase below.

For more detail on the event object, see [http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#interface-Event the W3C specification].

'''Note:''' If your callback function does not take any parameters, it will still run; you just won't have as easy of access to the event object.

=== Event Handlers and Memory Management ===

JavaScript is an automatically garbage-collected language, meaning that memory management is mostly taken care of for you. However, there are some instances when you need to be careful about creating "zombie" objects. In JavaScript, this mostly revolves around the idea of event listeners.

I could give an explanatory example, but instead I'll tell you straightaway that '''the moral of the story is that for every "addEventListener", there should probably be a "removeEventListener".''' Here are some good articles to satisfy your hunger for more details on event listeners and JavaScript memory management:

* http://www.vladalexandruionescu.com/2012/08/javascript-memory-leaks.html
* http://lostechies.com/derickbailey/2012/03/19/backbone-js-and-javascript-garbage-collection/
* http://stackoverflow.com/questions/5326300/garbage-collection-with-node-js

When you start working with Node.JS in the next module, it's more important than ever to keep good accounting of your event listeners.

=== Event Phase ===

In JavaScript, events occur in two phases: '''Capture Phase''' and '''Bubble Phase'''. Consider the following HTML document:

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head><title>Event Test</title></head>
<body>
<div id="box">
<button id="btn">
Hello
</button>
</div>
</body>
</html>
</source>

Suppose the user clicks on the "Hello" button. Events will be fired in the following order:

# Capture Phase CLICK on the Document
# Capture Phase CLICK on the Body
# Capture Phase CLICK on the Div#box
# Target Phase CLICK on the Button#btn
# Bubble Phase CLICK on the Div#box
# Bubble Phase CLICK on the Body
# Bubble Phase CLICK on the Document

{{JSFiddleExample
|title=Using Capture Phase to Enable or Disable a Toolbar
|fiddle_id=r32Dz
|desc=We bind an event in the capture phase to the div with ID ''toolbar''. When ''e.stopPropagation()'' is called, the event does not reach the buttons in the toolbar.
}}

Graphically, here is the order in which an event occurs in three generic nested elements:

[[File:EventPhase.gif]]

Why is this useful? Suppose you have a control panel (toolbar, etc) that you want to temporarily deactivate. (For example, Bold/Italic/Underline buttons on a graphic text editor that currently has no content.) You could keep bubble phase event listeners on your buttons, but prevent those events from occurring by stopping the event in the capture phase on the parent element before the event reaches your buttons! Example:

<source lang="javascript">
var disableToolbarFunc = function(e){
e.stopPropogation();
}

// To disable toolbar:
document.getElementById("box").addEventListener("click", disableToolbarFunc, true);

// To re-enable toolbar:
document.getElementById("box").removeEventListener("click", disableToolbarFunc, true);
</source>

'''Word of caution:''' Like many great things in web development, capture phase does not work in versions of Internet Explorer prior to version 9. There is no elegant substitution for older versions of Internet Explorer.

'''Note:''' When the event reaches the innermost element, there is no distinction between capture phase and bubble phase. The order in which event handlers were added to the element determines the order in which those callbacks are evaluated.

== Document Object Model ==

The '''Document Object Model (DOM)''' is what enables JavaScript to manipulate the content of your web page.

=== Nodes and Traversing the DOM ===

Each element on your page, whether it is a <nowiki><p>, <img/></nowiki>, a string of text, or even an attribute, is called a '''node'''.

Every node, except for the document itself, has exactly one parent. A single node may have multiple children.

Consider the following HTML code:

<source lang="html4strict">
<ul id="my-list">
<li class="fruits">Apples</li>
<li class="citrus">Oranges and <strong>Lemons</strong></li>
<li class="berries">Cherries</li>
</ul>
</source>

Here, the ul with ID "my-list" has three child '''element nodes''' (the three li's) as well as four child '''text nodes''' (the whitespace counts as a text node) and a child '''attribute node'''. The second LI has one child '''text node''' as well as one child '''element node''' and one child '''attribute node'''.

The DOM can be traversed in JavaScript. First, let's look at an example.

<source lang="javascript">
e = document.getElementById("my-list").getElementsByClassName("citrus")[0].lastChild.nodeName;
alert(e);
</source>

{{JSFiddleExample
|title=Currently Selected Radio Button
|fiddle_id=SHcng
|desc=In pure JavaScript, in order to determine the currently selected radio button, it is necessary to iterate over an array of pointers to all possible radio buttons, and stop when you find one that is "checked".
}}

The above snippet gets the element with class name '''citrus''' that is a child of the element with ID '''my-list''' (the second LI in the example above), and alerts the type of its second child node (which in this case is '''STRONG''').

Some common methods for traversing the DOM include:

* Node.parentNode
* Node.childNodes - returns an array of nodes
* Node.firstChild - same as Node.childNodes[0]
* Node.lastChild - same as Node.childNodes[Node.childNodes.length-1]
* Node.previousSibling
* Node.nextSibling

You can also search for child (including all descendants) using one of the following methods:

* Node.getElementsByTagName("tag-name") - returns an array of element nodes having the tag name '''tag-name''' that are descendants of Node
* Node.getElementById("id") - returns a single node having the ID '''id''' that is a descendant of Node
* Node.getElementsByName("what-name") - returns an array of element nodes having their '''name''' attribute set to '''what-name'''. Useful for radio buttons and other form elements.
* Node.getElementsByClassName("class") - returns an array of nodes having the class '''class'''
*: '''Note:''' As of October 2012, 82% of the browser market supports Node.getElementsByClassName ([http://caniuse.com/getelementsbyclassname more info]). In order to support the other 18%, you need to either add your own getElementsByClassName to Node's prototype or use a JavaScript library like jQuery or MooTools.

It is common in JavaScript to have long statements like the one in the example above, where you call methods on several objects in sequence.

=== Creating, Moving, and Removing Nodes ===

You will frequently find yourself wanting to modify the DOM. JavaScript provides methods that help you do this.

Consider the same HTML as above. If you wanted to add another element to the list, you could use this code:

<source lang="javascript">
var newLi = document.createElement("li"); // creates a node with the tag name li
newLi.appendChild(document.createTextNode("Broccoli"));
newLi.setAttribute("class", "veggies");
document.getElementById("my-list").appendChild(newLi);
</source>

If you wanted to remove the apples from the list, you could do:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").removeChild(apple);
</source>

If you wanted to move the apples to the end of the list, you could do this:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").appendChild(apple);
</source>

Notice that '''Node.append()''' both removes a node from its previous location ''and'' appends it to its new location, which is always going to be as the last child of the parent node.

In summary, here are the methods to know from this section:

* Node.append(otherNode) - removes otherNode from its current location in the DOM (if applicable) and then adds it as the last child of Node
* Node.removeChild(otherNode) - removes otherNode, a child of Node, from the DOM
* document.createElement("tag-name") - create a new node with the tag name "tag-name"
* document.createTextNode("text") - create a node containing only the string '''text'''
* Node.setAttribute("attribute", "value") - sets the attribute node of name "attribute" to "value"

=== DOM Shortcuts ===

In the above sections, we have been creating, reading, modifying, and deleting Nodes. This is the most "correct" way to change the content of a web page from inside JavaScript.

This section documents a few shortcuts that are not as "pure" as using Nodes but can be less confusing and cumbersome.

{{JSFiddleExample
|title=Displaying Information
|fiddle_id=Q3BPZ
|desc=This example shows how to use some of the shortcut methods for using JavaScript to display information on the page.
}}

==== textContent ====

Using textContent to display information is probably the easiest method out there. For example, the following code overwrites whatever is in the element with ID "holder" with the string "Hello World":

<source lang="javascript">
document.getElementById("holder").textContent = "Hello World";
</source>

If you wanted to instead append the text, simply use '''+=''' instead of '''=''':

<source lang="javascript">
document.getElementById("holder").textContent += " - Later, he said Hello World - ";
</source>

Note that textContent displays strings literally; that is, it does not allow for HTML. Setting the textContent property also removes any HTML that may have already been in that element.

==== innerHTML ====

If you need to use HTML in your output but don't want to use the method described earlier in this section, a straightforward strategy is to use the innerHTML property of an element. For example, the following code would add a paragraph saying "Hello World" to the element with ID "holder":

<source lang="javascript">
document.getElementById("holder").innerHTML += "<p>Hello World</p>";
</source>

'''Important:''' You need to be careful to prevent XSS-type attacks if you display information using innerHTML. For example, be sure to escape a user-supplied string before appending it to innerHTML.

=== JavaScript Inspectors ===

{{DoctypeTV
|youtube_id=PKzrmbN-pMg
|time=4m13s
|desc=Using Firebug, WebKit Inspector, and IE Developer Tools
}}

Various browsers and browser plugins give you, the developer, tools to debug your code, inspect the DOM, and much more. Using these tools is essential for an efficient workflow.

* '''Firebug'''. Firebug is a plugin for Firefox that is a toolkit full of web developer tools, one of which is a DOM inspector. To inspect the DOM of a web page, simply open the Firebug window while viewing the web page.
* '''WebKit Inspector'''. The WebKit Inspector, which is available in both Chrome and Safari, enables you to see the DOM tree and relationships between elements. However, its DOM inspection tools are not as robust as those of Firebug.
* '''Opera Dragonfly'''. The web browser Opera comes with a web developer toolkit similar to the WebKit Inspector called Dragonfly. It is important that you test your sites in Opera, because although Opera has only a small fraction of the desktop browser market, it is second only to WebKit on the mobile market. Opera also has extremely strong CSS support, so it is good for testing for bugs in your CSS.

All of the above-mentioned tools enable you to look at the DOM of your web page and find what properties and methods are associated with each node. This is helpful because if you have JavaScript that manipulates HTML elements, you cannot tell which properties are associated with which elements by looking at the source code alone.

[[Category:Module 6]]

Node.JS

2015-07-10T08:11:17Z

Shane: /* Node.JS Security */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The unofficial instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably ''use-nave-no-shell.sh''.

The instructions at the above link have a couple bugs. If you run this sequence of commands, Node and NPM will install correctly:

<source lang="bash">
$ mkdir ~/.nave
$ cd ~/.nave
$ wget http://github.com/isaacs/nave/raw/master/nave.sh
$ sudo ln -s $PWD/nave.sh /usr/local/bin/nave
$ chmod a+x nave.sh
$ sudo chown -R $USER:$USER /usr/local
$ nave usemain stable
$ curl -L https://www.npmjs.org/install.sh | sh
</source>

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

''npm'' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

'''Note:''' When using npm to install local dependencies, '''''do not use sudo'''''. It will screw up your file permissions.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

The two links below have good information about security vulnerabilities specific to Node.JS that you should think about when crafting your application.

# Book from PragProg ($24, 2015): https://pragprog.com/book/kdnodesec/secure-your-node-js-web-application
# Slideshow from a Switzerland Conference on Application Security (2012): http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

'''Tip:''' Once you set up your ''package.json'' file, you can automatically add a dependency to it by using the ''--save'' argument on ''npm install'': <code>npm install --save socket.io</code>

[[Category:Module 7]]

Node.JS

2015-07-10T08:10:58Z

Shane: /* Node.JS Security */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The unofficial instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably ''use-nave-no-shell.sh''.

The instructions at the above link have a couple bugs. If you run this sequence of commands, Node and NPM will install correctly:

<source lang="bash">
$ mkdir ~/.nave
$ cd ~/.nave
$ wget http://github.com/isaacs/nave/raw/master/nave.sh
$ sudo ln -s $PWD/nave.sh /usr/local/bin/nave
$ chmod a+x nave.sh
$ sudo chown -R $USER:$USER /usr/local
$ nave usemain stable
$ curl -L https://www.npmjs.org/install.sh | sh
</source>

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

''npm'' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

'''Note:''' When using npm to install local dependencies, '''''do not use sudo'''''. It will screw up your file permissions.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

The two links below have good information about security vulnerabilities specific to Node.JS that you should think about when crafting your application.

1. Book from PragProg ($24, 2015): https://pragprog.com/book/kdnodesec/secure-your-node-js-web-application
2. Slideshow from a Switzerland Conference on Application Security (2012): http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

'''Tip:''' Once you set up your ''package.json'' file, you can automatically add a dependency to it by using the ''--save'' argument on ''npm install'': <code>npm install --save socket.io</code>

[[Category:Module 7]]

Pong Game

2015-02-20T04:10:57Z

Shane:

This article documents ''pong-game.js'', a pre-built JavaScript file that helps you implement your pong game.

== Setup ==

First thing first: set up a static file server running Node.JS. We will need it in order to serve up our HTML and JavaScript content.

=== File 1: pong-game.js ===

The first file you can save in your ''static'' directory will be ''pong-game.js'', which you can download from here: http://classes.engineering.wustl.edu/cse330/content/pong-game.js

We created the ''pong-game.js'' file for you to save you time and so that you can focus on the Node.JS and Socket.IO aspects of this module. This file contains the core Pong engine, but it does ''not'' establish communication between users of any kind.

=== File 2: client.js ===

You should create an additional file, ''client.js'', which you include into ''client.html'' and which contains the client-side logic for your Pong game. It should load after ''pong-game.js''. You will be saving all of you client-side code in this file.

=== File 3: client.html ===

The third file you can save in your ''static'' directory should be an HTML file created from your favorite [[HTML and CSS#Quick and Easy Page Layout|Quick and Easy Page Layout]]. You need to add the following CSS rules:

<source lang="css">
#gameContainer{
margin: 0 auto;
width: 960px;
height: 500px;
}
#controls{
height: 20px;
text-align: center;
}
#game{
width: 960px;
height: 480px;
border: 1px solid black;
}
</source>

Add the following HTML inside your ''main'' div; this is what will contain the Pong game canvas:

<source lang="html4strict">
<div id="gameContainer" style="display:none;">
<div id="game"></div>
</div>
</source>

You also need to require ''pong-game.js'' and ''client.js''.

<source lang="html4strict">
<script src="pong-game.js"></script>
<script src="client.js"></script>
</source>

=== Connecting to Socket.IO ===

Now that you have your static fileserver running that serves up your three files (''pong-game.js'', ''client.html'', and ''client.js''), we need to connect everything with Socket.IO.

Set up a static fileserver by following the instructions in [[Node.JS|the Node.JS guide]]. When finished, add the following lines:

<source lang="javascript">
var io = socketio.listen(app);
io.sockets.on("connection", function(socket){
// This closure runs when a new Socket.IO connection is established.

// Listen for client messaging server:
socket.on("message", function(content){
// do stuff
});

// Send a message from the server to the client:
socket.emit("message", {some:"data"});
});
</source>

Don't forget to require socket.io at the top of your file!

<source lang="javascript">
socketio = require("socket.io")
</source>

You also need to make sure to install ''socket.io'' from npm.

Inside of the ''io.listen'' callback function is where most of your server-side code will go.

On the client side, you need to include the Socket.IO library (put this above ''pong-game.js'' and ''client.js''):

<source lang="html4strict"><script src="/socket.io/socket.io.js"></script></source>

And finally, you need to connect your client to the Socket.IO server (put this in ''client.js''):

<source lang="javascript">var socket = io.connect(window.location.origin);</source>

But enough of us giving you all the code! It's time for you to start being creative.

== The API ==

For the remainder of this module, your work will be in three files:

* app.js (or whatever you called your Node.JS file)
* client.html
* client.js

What you need to do is to build a system that enables two players who are both viewing ''client.html'' to choose each other (e.g., from a lobby) and play a game of Pong.

You should be wondering, "how do I interact with the Pong game?" The public interface is as follows.

=== Methods ===

* '''pong.init()'''
*: Initialize the game client.
* '''pong.resetBall([x, y])'''
*: Arbitrarily set the position of the ball. Defaults to the center if no arguments are given. Cancels all animations currently acting on the ball.
* '''pong.launch(angle, direction)'''
*: Launch the ball ''from its current position'' in the specified ''angle'' (-89 to +89) and direction (-1 for left or 1 for right).
* '''pong.updateOpponentPaddle(position)'''
*: Set the position of the opponent paddle to ''position''. (Hint: the ''position'' value should have been generated by the opponent's '''paddlemove''' event)
* '''pong.pauseOrResumeGame()'''
*: Set the game in a paused state, or remove the game from a paused state.
* '''pong.ready()'''
*: Returns true if the game is not in a "paused" state.
* '''pong.setScore(score)'''
*: Display score on the game canvas. ''score'' is an object literal containing two fields: left and right.

=== Events ===

All events for the pong game are fired on the window.

* '''paddlemove'''
*: The player's paddle has moved.
*: This event will fire only after the paddle has moved 15 pixels or more.
** '''event.detail.position'''
**: The new y coordinate of the paddle.
* '''paddlehit-left'''
*: The ball has hit the left side of the screen.
** '''event.detail.hit'''
**: True if the ball hit the player's paddle; false otherwise.
** '''event.detail.angle'''
**: If the ball was reflected, the new angle of the ball's rightward movement.
** '''event.detail.position'''
**: The position at which the ball hit the left side.

=== Problems with Our Interface ===

There are at least two major problematic issues with our API:

* We are firing events on the window. We should have taken the time to make our Pong class implement the EventTarget interface directly.
* We are putting more trust in the client than we should, because the client can fake any angle and position upon the '''paddlehit-left''' event and manipulate the game in his or her favor. The trajectory should be computed on the Node.JS side.

Just be aware of the above issues as you complete this lab. You won't be required to fix them, although if you do (and if you recompile your modified code with Lime) you may be a candidate for extra credit.

=== Enabling a Player to Pause ===

''You do not need to implement pausing for the purposes of Module 7. If you do, you can earn 5 points of creative portion.''

Implementing a game pause is more difficult for a network game than it is for a game that runs on just one computer: you need to make sure that the game is in a state such that you won't run into any race conditions, etc.

One situation during a Pong game when it makes sense to enable a user to pause the game is after a user has lost a round. Since the game at that point in time is waiting for the player to launch the next ball, we shouldn't have any race conditions.

If you implement pausing, the '''pong.pauseOrResumeGame()''' and '''pong.ready()''' functions will come in handy.

== Examples ==

=== Starting a Pong Game ===

Once two players have formed a pair, one of them needs to initialize the game with a certain angle and direction for the ball. Here is how you might go about doing this:

<source lang="javascript">
// generate an initial angle between -60 degrees and +60 degrees:
var initAngle = -60 + 120*Math.random();

// randomly choose the initial direction of the ball:
var initDirection = Math.random() < 0.5 ? -1 : 1;

// show the game canvas:
document.getElementById("gameContainer").style.display = "block";

// initialize the game canvas:
pong.init();

// move the ball to the center:
pong.resetBall();

// set the ball into motion:
pong.launch(initAngle, initDirection);

// tell the server about the ball's initial angle and direction. For example:
socket.emit("launch", {
angle: initAngle,
direction: initDirection
});
</source>

=== When a Player Reflects the Ball ===

When the ball hits a player's side, the '''paddlehit-left''' event fires on the window. Here is how you might listen for this event in your ''client.js'' and transmit this information over your socket:

<source lang="javascript">
window.addEventListener("paddlehit-left", function(e){
// e.detail.hit will be true if the client hit the ball with his/her paddle.
if (e.detail.hit) {
console.log("HIT PADDLE. New angle: %f", e.detail.angle); // log a message to the console

// Tell our opponent via Socket.IO about the ball's new angle and position:
socket.emit("reflect", {
angle: e.detail.angle,
position: e.detail.position
});

// Note: The game automatically launches the ball and determines the angle based on the ball's position relative to the paddle position. We therefore do not need to call pong.launch() in here (but our opponent will, as shown below).
}else{
console.log("MISSED PADDLE");

// in here, we will update the score, check for victory condition, launch a new ball (perhaps after a timeout), etc.
}
});
</source>

Here is what you might have in ''app.js'' inside of your Socket.IO callback function:

<source lang="javascript">
// Listen for the "reflect" message from the client
socket.on("reflect", function(data){
// Tell our opponent about the reflection.
// Note: In this sample implementation, we store the opponent in `socket.opponent`.
// You might use a different mechanism for storing the opponent's socket.
socket.opponent.emit("reflect", data);
});
</source>

Finally, here is what you might have on the opponent's end (hint: this is also in ''client.js''):

<source lang="javascript">
// Listen for the "reflect" message from the server
socket.on("reflect", function(data){
// In order to make up for any network lag, immediately move the ball to its correct position:
pong.resetBall(960, data.position);

// Finally, launch the ball on our local game client:
pong.launch(data.angle, -1);
});
</source>

== Flow Chart ==

If you are a visual learner, this flow chart of the logic you need to build for the pong game might be useful.

[[File:Module 7 Flow Chart.png]]

== How We Built pong-game.js ==

If you are curious, we used the [http://www.limejs.com/ LimeJS] framework as the backbone of ''pong-game.js''. You can find the pre-compiled source code for the Pong game here:

* http://classes.engineering.wustl.edu/cse330/content/pong.js
* http://classes.engineering.wustl.edu/cse330/content/ball.js

We then used the [https://developers.google.com/closure/compiler/ Google Closure Compiler] to compile all of the libraries you need into the one modular JavaScript file.

Just to be clear, ''for the purposes of Module 7, you do not need to bother with either LimeJS or Google Closure.''

[[Category:Module 7]]
[[Category:Former Content]]

Web Application Security, Part 2

2015-02-14T03:27:21Z

Shane: /* Abuse of Functionality */

This is Part 2 of the Web Application Security article, geared toward the material covered in [[Module 3]]. For material covered in [[Module 2]] (HTML, CSS, and PHP), see [[Web Application Security, Part 1]]. For material covered in [[Module 6]] (JavaScript), see [[Web Application Security, Part 3]].

== Password Security ==

Let's assume for a moment that despite all of your efforts in the other fronts of web security, an attacker was still able to extract information from your database. If you store your passwords as plain text, not only will the attacker be able to log in as whomever he chooses, but the attacker will ''also'' likely be able to log in as the users of your site on different sites (since many users employ the same password on several different web sites).

=== Encryption ===

The types of encryption and encryption algorithms is a whole class to itself.

In CSE330 and future web application development, you should always use '''one-way encryption''' to encrypt your passwords. What this means is that you feed a string of text (a password) to an encryption function, and that encryption function returns another string of text that is a ''digest'' of the password. It is impossible to mathematically convert a digest back to its associated password, but encrypting the same password will always yield the same digest.

One-way encryption algorithms can also be ''salted''. What this means is that the string to be encrypted is modified by a ''salt'' before the encryption occurs. The same salt and the same password will always yield the same digest. Using a salted hashing algorithm is preferable to a non-salted hashing algorithm for passwords because although digests cannot be reversed, non-salted digests can be looked up in a rainbow table.

=== Solution ===

So, the solution is to store salted, one-way-encrypted passwords in your database. PHP provides the [http://php.net/crypt crypt()] function to do this for you.

How does it work? ''crypt()'' is an automagical function that both generates a random salt and tests for password integrity. Let's look at a few examples.

<source lang="php">
<?php

echo crypt("Hello World");
/*
* The above line prints, for example: $1$WQvMDFgI$5.mVOS7V2Q/aB78Mxl13Q1
* This line is of the format: $1$random-salt$crypted-password
*/

echo crypt("Hello World", '$1$WQvMDFgI$5.mVOS7V2Q/aB78Mxl13Q1');
/*
* The above line prints: $1$WQvMDFgI$5.mVOS7V2Q/aB78Mxl13Q1
* This is the same as the salt-hash string we passed as the second argument.
*/

echo crypt("Goodbye World", '$1$WQvMDFgI$5.mVOS7V2Q/aB78Mxl13Q1');
/*
* The above line prints: $1$WQvMDFgI$1REUkR026Ttck17Sfzp.V/
* Note that this is NOT the same as when we pass the real password to crypt.
*/
?>
</source>

As you can see form the above example, '''crypt() generates a string that contains ''both'' a random salt ''and'' the hashed password.''' You can store the constant-length value in a CHAR field in your database, and then have just one field for both the password and the salt.

=== Example ===

Here is an example of what you might do on your login page. '''''Note:'' This example assumes that you salted the user's password already and stored it in the database.'''

<source lang="php">
<?php
// This is a *good* example of how you can implement password-based user authentication in your web application.

require 'database.php';

// Use a prepared statement
$stmt = $mysqli->prepare("SELECT COUNT(*), id, crypted_password FROM users WHERE username=?");

// Bind the parameter
$stmt->bind_param('s', $user);
$user = $_POST['username'];
$stmt->execute();

// Bind the results
$stmt->bind_result($cnt, $user_id, $pwd_hash);
$stmt->fetch();

$pwd_guess = $_POST['password'];
// Compare the submitted password to the actual password hash
if( $cnt == 1 && crypt($pwd_guess, $pwd_hash)==$pwd_hash){
// Login succeeded!
$_SESSION['user_id'] = $user_id;
// Redirect to your target page
}else{
// Login failed; redirect back to the login screen
}
?>
</source>

'''Note:''' You may sometimes see functions like vanilla [http://php.net/md5 md5()] used to encrypt passwords. md5() does indeed perform one-way encryption, but it does so without a salt. '''THIS IS BAD PRACTICE''', because unsalted md5 hashes can be trivially reversed using a rainbow table. (Just Google for "md5 decrypter".) Using a salt prevents the effective use of a rainbow table.

=== OpenID ===

One other solution that will solve ''all'' issues related to password security is to not have passwords at all. This can be achieved using [[wikipedia:OpenID|OpenID]], which allows end users to use their accounts from other sites (e.g. Google, Yahoo, and Twitter) to authenticate on your site. Not only does this make your life easier in the security realm, but it also eliminates the need for password recovery, etc.

There are many PHP libraries available for OpenID authentication; one such library is the creatively named [http://pear.php.net/package/OpenID OpenID], which you can install using [[PHP#PEAR|PEAR]]. You will need to install some other packages first, some from yum (if using RHEL) and some from pear. (If you don't install them, PEAR will yell at you.) These are the commands you need to run in order to install the correct packages (make sure you understand what they do before running them):

<source lang="bash">
$ sudo yum install php-mbstring php-bcmath # not necessary on Debian
$ sudo apachectl graceful # restart Apache
$ sudo pear install Crypt_DiffieHellman-0.2.6 Validate-0.8.5 Services_Yadis-0.5.1 OpenID-0.3.3
</source>

Here's an example implementation that uses the PEAR package.

'''Login Page:'''
<source lang="html4strict">
<form action="process_openid.php" method="post">
<input id="start" name="start" type="hidden" value="true" />
<fieldset>
<legend>Sign in using OpenID</legend>
<div id="openid_choice">
<p>Please select your account provider:</p>
<select name="identifier">
<option value="https://www.google.com/accounts/o8/id">Google</option>
<option value="http://yahoo.com/">Yahoo</option>
</select>
</div>
<p>
<input type="submit" value="Sign In"/>
</p>
</fieldset>
</form>
</source>

'''process_openid.php:'''
<source lang="php">
<?php
require_once 'OpenID/RelyingParty.php';
require_once 'OpenID/Message.php';
require_once 'Net/URL2.php';

session_start();

$realm = "http://www.yoursite.com/";
$returnTo = $realm . "path/to/process_openid.php";

$identifier = @$_POST['identifier'] ?: @$_SESSION['identifier'] ?: null; // note: the @ signs suppress "undefined" notices

$o = new OpenID_RelyingParty($returnTo, $realm, $identifier);

// Part 1: We are processing a login request before visiting the OpenID provider
if(@$_POST['start']) {
$authRequest = $o->prepare();
$url = $authRequest->getAuthorizeURL();

header("Location: ".$url);
exit;
}

// Part 2: The user is returning to our site after visiting the OpenID provider's site
else {
$usid = @$_SESSION['identifier'] ?: null;
unset($_SESSION['identifier']);

$queryString = count($_POST) ? file_get_contents('php://input') : $_SERVER['QUERY_STRING'];

$message = new OpenID_Message($queryString, OpenID_Message::FORMAT_HTTP);

$result = $o->verify(new Net_URL2($returnTo . '?' . $queryString), $message);

if($result->success()){
// Login Success!

// Get the OpenID identifier, which is unique to every OpenID user (i.e. you can use it in your database to
// keep track of people between logins), and save it in the session:
$_SESSION["openid.identity"] = $message->get("openid.identity");

// Now redirect to the target page for logged-in users
}else{
// Login Failed. You can redirect back to the login page or whatever
}
}
?>
</source>

'''Note:''' OpenID is by nature a secure form of authentication for a web application; the fact that government agencies like the GSA use OpenID helps attest to this. However, OpenID remains vulnerable to man-in-the-middle, content-spoofing attacks. If you are writing a high-profile application using OpenID, it is therefore recommended that you establish an SSL (https) connection to your OpenID providers to help prevent phishing.

'''Note:''' You may use OpenID for modules 4 and higher, but you must implement your own authentication system for module 3.

=== Real-Life Examples ===

Here is a constantly-updated list of sites that do not use proper password security: http://plaintextoffenders.com/

== Cross-Site Request Forgery ==

{{DoctypeTV
|youtube_id=3IOKaIRg8V4
|time=3m45s
|desc=Cross Site Request Forgeries
}}

A cross-site request forgery (CSRF, pronounced ''sea-surf'') involves a victim, who is logged in to the targeted site, visiting an attacker’s site. The attacker has code on his site that forces the victim to unwittingly perform actions on the targeted site.

For example, suppose Mother Goose visited Dr. Evil's blog. Dr. Evil had the following tag embedded in his bloc:

<nowiki><img src="http://www.bank.com/transfer.php?dest=dr-evil&amount=5000" /></nowiki>

This would cause Mother Goose to authorize a $5000 transfer to Dr. Evil, completely without Mother Goose's knowledge!

Worse yet, Dr. Evil could just send an e-mail to Mother Goose with this image tag. All Mother Goose would need to do to be attacked is open the e-mail! (Now you know why sometimes your e-mail client turns off images from suspicious sources.)

=== Solution ===

The first precautionary measure is to always use POST requests (as opposed to GET requests) for actions that change something on your server. This will fend off all except the most hard-core CSRF attacks.

However, fully preventing CSRF attacks is not difficult. To do this, you can use a '''CSRF token'''. A CSRF token is a known string of text that is submitted in all of the forms on your site. If the string is not what you expect, then you can assume that the request was forged.

For example, consider this form:

<source lang="html4strict">
<form action="transfer.php">
<input type="text" name="dest" />
<input type="number" name="amount" />
<input type="submit" value="Transfer" />
</form>
</source>

We can easily add a hidden CSRF token field like so (as well as making the form POST rather than GET):

<source lang="html4strict">
<form action="transfer.php" method="post">
<input type="text" name="dest" />
<input type="number" name="amount" />
<input type="hidden" name="token" value="<?php echo $_SESSION['token'];?>" />
<input type="submit" value="Transfer" />
</form>
</source>

'''This assumes that <code>$_SESSION['token']</code> contains an alphanumeric string that was randomly generated upon session creation.''' For example, you could add this line ''beneath beneath where the user successfully authenticates'':

<source lang="php">
$_SESSION['token'] = substr(md5(rand()), 0, 10); // generate a 10-character random string
</source>

We can now test for validity of the CSRF token on the server side (in transfer.php):

<source lang="php">
<?php
$destination_username = $_POST['dest'];
$amount = $_POST['amount'];
if($_SESSION['token'] !== $_POST['token']){
die("Request forgery detected");
}
$mysqli->query(/* perform transfer */);
?>
</source>

Now, if Mother Goose were to view a page containing the malicious <img/> tag, the transfer would not take place.

=== Real-Life Examples ===

* [http://www.zdnet.com/no-data-breach-in-first-weibo-attack-2062301014/ Weibo, June 2011]
* [http://www.huffingtonpost.com/huff-wires/20110601/us-tec-google-hacking-attack/ Gmail, June 2011]
* [http://www.pcworld.com/businesscenter/article/228609/hackers_steal_hotmail_messages_thanks_to_web_flaw.html Hotmail, May 2011]
* [http://www.theregister.co.uk/2010/05/19/facebook_private_data_leak/ Facebook, May 2010]

== SQL Injection ==

[[File:Exploits of a mom.png]]

SQL injection occurs when an attacker submits specially-crafted input into your server, which is then included in an SQL query. The input modifies the query to perform additional actions on the database or to access unwanted information.

For instance, suppose you had the following code:

<source lang="php">
<?php
require 'database.php';

/* DISCLAIMER: THIS CODE IS BAD IN MANY MORE WAYS THAN JUST
BEING VULNERABLE TO SQL INJECTION! IT IS FOR DEMONSTRATION OF
CONCEPT ONLY. DO NOT USE THIS CODE IN YOUR OWN PROJECTS! */

$res = $mysqli->query("SELECT id FROM users WHERE username='".$_POST['username']."' AND password='".$_POST['password']."'");

if( $res->num_rows==1 ){
    $row = $res->fetch_assoc();
    $_SESSION['user_id'] = $row["id"];
}else{
    echo "Login failed.";
    exit;
}
?>
</source>

This code is vulnerable to SQL injection. For example, suppose the attacker used the following string of text for his username:

mother-goose' --

Here's what the resulting query would look like:

<source lang="mysql">
SELECT id FROM users WHERE username='mother-goose' --' AND password=''
</source>

Since <code>--</code> is the start of a comment in SQL, when MySQL interprets this query, it will ''completely ignore'' the password-checking part of the query! Dr. Evil can log in using anyone's username and steal all of their money!

=== Solution ===

If you write your queries manually (as in the example above), you need to use <code>$mysqli->real_escape_string()</code> to sanitize your input:

<source lang="php">
<?php
$safe_username = $mysqli->real_escape_string($_POST['username']);
// ...
?>
</source>

However, the better solution is to use prepared queries. For more information on prepared queries, see [[PHP and MySQL]].

'''IMPORTANT:''' If you correctly use the sample code in the PHP and MySQL guide above, you are already safe from SQL injection attacks.

=== Real-Life Examples ===

* [http://www.zdnet.com/unknowns-hack-european-space-agency-4010026071/ European Space Agency, May 2012]
* [http://www.dutchnews.nl/news/archives/2012/04/new_online_medical_records_sca.php Dutch Department Stores, April 2012]
* [http://www.msnbc.msn.com/id/46735808/ns/technology_and_science-security/ Ancestry.com, March 2012]
* [http://www.scmagazine.com.au/News/292592,allphones-hacked-staff-passwords-exposed.aspx Allphones (Australian Telecommunications Retailer), March 2012]
* [http://www.abc4.com/content/news/slc/story/More-fallout-Salt-Lake-City-police-website-hacked/PiSspE768UiioitJ3K4gyQ.cspx Salt Lake City Police Department, February 2012]

== Abuse of Functionality ==

''Abuse of Functionality'' is a general term that refers to when an attacker exploits vulnerabilities in the logic of your application.

For example, suppose you were a banking site, and you had the following code to perform a transaction:

<source lang="php">
<?php
require 'database.php';

$amount = (double) $_POST['amount'];
$destination_username = $mysqli->real_escape_string($_POST['destination']);

$mysqli->autocommit(false); // start transaction
$mysqli->query("UPDATE users SET balance=balance-".$amount."
WHERE id=".$_SESSION['user_id']);
$mysqli->query("UPDATE users SET balance=balance+".$amount."
WHERE username='".$destination_username."'");
$mysqli->commit(); // commit transaction
?>
</source>

It may not be obvious, but if you don't filter your input, it is trivial for an attacker to ''insert a negative number'' into the "amount" field and transfer money from anyone's account to his account! The solution here is to simply filter amount for what you expect (in this case, a positive number that is not greater than the user's current balance).

=== Filtering on the Client Side is Never Enough ===

Suppose you have an e-mail field in a form in HTML, and you use some JavaScript function (or HTML5) to check it for form as an e-mail address:

<source lang="html4strict">
<input type="text" name="email" onchange="checkEmail(this);" /> 

<input type="email" name="email" /> 
</source>

With this filter in place, any layperson using your form is now required to submit an e-mail address in that field. ''However'', it is trivial for an attacker to bypass this client-side filtering (e.g., by using web developer tools like Firebug) and still submit non-email text to your server. This is why '''IT IS ESSENTIAL THAT YOU FILTER INPUT ON THE SERVER SIDE! Any sort of filtering on the client side are just bells and whistles for the end user.'''

=== Information Leakage ===

''Information Leakage'' is a noteworthy type of ''Abuse of Functionality'' attack that involves unprivileged users accessing privileged information. In fact, Information Leakage accounts for a significant percentage of all recorded web application vulnerabilities (second only to Cross-Site Scripting).

The concept is relatively simple. Suppose you have an administration page that loads an image containing a graph of all activity on your site:

'''admin.php'''
<source lang="php">
<?php
if($_SESSION['admin']) echo '<img src="stats.php?day=2012-08-19" alt="Stats for 2012-08-19" />';
?>
</source>

'''stats.php'''
<source lang="php">
<?php
// query the database, and save the results in $result

$im = new PNGraph();
$im->takeData($result);

header("Content-Type: image/png");
print $im->toString();
?>
</source>

Notice how you check for admin credentials in ''admin.php''. However, you forgot to do this in ''stats.php'' itself. An attacker could simply load ''stats.php'' directly to see all of the sensitive admin-only information!

==== Solution ====

Information Leakage is an attack that requires the developer to see the big picture and really keep track of what's going on in his or her application. As a rule of thumb, ''whenever'' you query the database to access sensitive information, check the permissions of the user first.

=== A Note about Frameworks ===

Web frameworks are designed to make web development more agile, but they in turn have security weaknesses of their own. For instance, the infamous ''mass-assignment vulnerability'' in Ruby on Rails-type MVC frameworks is an abuse of functionality vulnerability that enables attackers to save arbitrary information in your database (!).

The important thing to know is that '''if you use a web framework, be familiar with the security considerations with that framework'''. Most of the time, frameworks will have articles on their web sites that discuss these concerns. (If your framework doesn't have a guide like this, you should probably be using a different framework!)

=== Real-Life Examples ===

* [http://gizmodo.com/some-guy-figured-out-how-to-delete-every-photo-on-faceb-1685491356 Facebook, February 2015 (bypassing authorization on REST API calls)]
* [http://www.whitec0de.com/new-hotmail-exploit-can-get-any-hotmail-email-account-hacked-for-just-20/ Hotmail, April 2012 (parameter manipulation)]
* [http://www.theregister.co.uk/2012/04/18/toshiba_slapped_by_ico/ Toshiba, April 2012 (parameter manipulation / information leakage)]
* [http://www.zdnet.com/blog/security/3-million-bank-accounts-hacked-in-iran/11577 Iranian Banks, April 2012 (information leakage)]
* [http://www.zdnet.com/blog/security/hacker-steals-chinese-government-defense-contracts/11386 Chinese Department of Defense, April 2012 (information leakage)]
* [http://articles.chicagotribune.com/2012-04-04/news/sns-rt-us-usa-hackers-utahbre83404g-20120404_1_data-security-breach-cyber-attack-hackers Utah Medicaid, April 2012]

== CAPTCHA Abuse ==

CAPTCHAs are a great way to stop robots from submitting forms in your web application. However, depending on how you implement CAPTCHAs, it might be possible for a hacker to bypass the CAPTCHA on your site.

For example, suppose you are making a home-grown CAPTCHA system for your application. You have a table '''CaptchaTable''' with the following fields: '''id''' and '''value'''. Your form looks like this:

<source lang="html4strict">
<form action="signup.php" method="post">
<strong>Subscribe to our newsletter</strong>
<input type="email" name="email" placeholder="Enter Your Email Here" />
<input type="text" name="captcha_value" placeholder="Type what you see in the CAPTCHA below." />
<img src="captcha.php?id=12345" />
<input type="hidden" name="captcha_id" value="12345" />
<input type="submit" value="Sign Up" />
</form>
</source>

Here's what the code on ''signup.php'' might look like:

<source lang="php">
<?php
$email = $_POST["email"];
$captcha_id = (int) $_POST["captcha_id"];
$captcha_value = $_POST["captcha_value"];

// check CAPTCHA

$captcha_stmt = $mysqli->prepare("select count(*) as match from CaptchaTable where id=? and value=?");
$captcha_stmt->bind_param("is", $captcha_id, $captcha_value);
$captcha_stmt->execute();
$captcha_row = (int) $captcha_stmt->fetch_assoc();
$captcha_stmt->close();

if ($captcha_row["match"] == 0){
http_response_code(403);
echo "Invalid CAPTCHA";
exit;
}

// continue with signup procedure down here
?>
</source>

The issue here is that a hacker can simply solve one CAPTCHA and then send that CAPTCHA ID and Value over and over again!

=== Solution ===

If you already have a home-grown CAPTCHA system, the best solution here would be to simply issue another query to the database that deletes a CAPTCHA id-value pair as soon as it is submitted in a form.

If you haven't yet implemented your CAPTCHA system, you might want to consider a third-party solution like [http://www.google.com/recaptcha reCAPTCHA].

[[Category:Module 3]]
[[Category:Web Application Security]]

JavaScript

2015-01-09T10:24:56Z

Shane:

JavaScript is the most widely used scripting language for implementing client-side functionality in Web applications. Unlike PHP, JavaScript code is interpreted and executed in a client's web browser (not on the web server).

== JavaScript? Did you mean Java? ==

'''JavaScript''' is a prototype-based programming language focussed on web interactivity. It was first introduced in Netscape Navigator, and it in turn gave rise to what is now '''[http://www.ecmascript.org/ ECMAScript]'''. Originally, JavaScript was called "LiveScript". Sun, the developer of Java at the time, wanted a language that would complement its compiled Java language, and so LiveScript was renamed JavaScript.

Beyond that, '''Java and JavaScript are as similar as Ham and Hamster.'''

Java and JavaScript have similar syntax, but the under workings are quite different. For example, Java requires strict typing, but JavaScript allows for dynamic typing. Java is object-oriented, but JavaScript is prototype-oriented. Java is compiled, but JavaScript is interpreted. Java supports event listeners, but JavaScript makes them a fundamental part of the language. Java variables are scoped to the innermost method or loop, but JavaScript variables are scoped only to the innermost function.

== JavaScript Language Components ==

This section highlights some features of the JavaScript language that differentiate it from other languages. For a more comprehensive JavaScript tutorial, the following tutorials are both quality:

* [http://docs.webplatform.org/wiki/javascript WebPlatform]: Great for learning JavaScript for the first time. Advocates best practices for modern JavaScript development.
* [http://www.quirksmode.org/js/contents.html QuirksMode]: More advanced than the WebPlatform tutorial, but it thoroughly covers the most powerful aspects of pure JavaScript and gives unparalleled advice on browser compatibility.

Advice: Do '''NOT''' Google for "JavaScript Tutorial". The first few hits advocate bad or outdated practices. Stick with the ones listed here.

=== Variables and Scope ===

To define a variable in JavaScript, use the '''var''' keyword.

<source lang="javascript">
var foo = "bar";
</source>

All variables are objects. In the case above, the variable '''foo''' is an object of the class '''String'''.

Notice that like PHP, you do not have to explicitly define a type for a variable like '''int''' or '''String'''; this is because JavaScript and PHP are ''dynamically typed languages''.

JavaScript code can access any variable higher in the “function tree”, but not vice-versa. This is called '''scope'''. ''All functions create their own scope.''

When you reference a variable, JavaScript will look up through the "function tree" until it finds the variable you asked for. This means that you could define variables of the same name as global variables inside of functions. For demonstration of concept:

<source lang="javascript">
var a = "hello";
var b = "world";

function sayGoodByeWorld(){
var a = "goodbye";

alert(a); // goodbye
alert(b); // world
}

sayGoodByeWorld();

alert(a); // hello
</source>

=== Object Literals ===

A very common way of storing and transporting data in JavaScript is by using objects. You can define an object with certain properties using an '''object literal''':

<source lang="javascript">
var apple = {
color: "red",
flavor: "sweet",
season: "autumn"
}

alert(apple.color); // red
</source>

=== Functions ===

To define a function in JavaScript, use the '''function''' keyword.

<source lang="javascript">
function sayHello(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Pass an argument to a function like this:

<source lang="javascript">
function sayHello(name){
alert("Hello, "+name);
}

sayHello("Todd"); // call the function and pass an argument
</source>

==== Functions are Objects ====

In JavaScript, functions are objects. This means that they can be assigned to variables, manipulated on the fly, and even passed as arguments to other functions! '''''This is an extremely important feature of JavaScript''''' that makes it such a robust language for web development.

You create a function variable like this:

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Observe that you can make [[#Variables and Scope|scope-dependent]] functions in this way.

=== Closures ===

{{DoctypeTV
|youtube_id=HaPlj796ngQ
|time=5m45s
|desc=JavaScript Closures
}}

A '''closure''' is a way to separate a certain snippet of JavaScript code from the global scope. This is useful if you do not want to "muck up" global variables. Closures are nothing more than anonymous functions that are called as soon as they are created:

<source lang="javascript">
var a = "hello";

(function(){
var b = "world";

alert(a); // hello
alert(b); // world
})();

alert(a); // hello
alert(b); // ReferenceError: b is not defined
</source>

{{JSFiddleExample
|title=Passing Variables to a Closure
|desc=This example demonstrates how you can "save" previous versions of a variable using closures. This is possible because of scoping and the fact that function variables can be returned as objects.
|fiddle_id=YURqa
}}

Most JavaScript libraries (like jQuery) write all of their code in a closure. What this means is that except for one or two variable names (jQuery or $), everything associated with the library is completely self-contained.

=== Prototypal Inheritance ===

JavaScript implements '''prototypal inheritance''', as opposed to a language like Java or C++, which implements '''classical inheritance'''. JavaScript is one of only a handful of languages implementing prototype-based inheritance.

Here's how it works. Every callable object (function) has a '''prototype'''. When instances of that object are created, their properties and methods are copied (inherited) from the prototype. Additionally, changes made to the prototype later in the program are "copied" to every instance.

For example, if you wanted to make a method on all strings that added a “!”, you could modify String’s prototype:

<source lang="javascript">
String.prototype.bang = function(){
return this+"!"; // Notice: the context is the instance itself
}

alert("Hello".bang()); // alerts Hello!
</source>

To "extend" an object, just copy its prototype to a new object. However, since classical inheritance and prototypal inheritance are different concepts, copying prototypes may have results that you don't expect. [http://beej.us/blog/data/javascript-prototypes-inheritance/ This article] seems to have a pretty good explanation with example implementations.

=== Context ===

{{DoctypeTV
|youtube_id=0a4r4bm1nQA
|time=4m32s
|desc=The ''this'' Variable in JavaScript
}}

Every function is called on a certain object, which is not necessarily the same object in which it was defined. This is called '''context'''.

To call a function on an arbitrary context, use either '''call''' or '''apply'''. ''call'' takes a list of arguments, while ''apply'' takes them all in an array.

To access the current context, use the '''this''' keyword. Demonstration of concept:

<source lang="javascript">
var sayThisColor = function(){
alert(this.color);
}

var apple = { color: "red" }

sayThisColor(); // undefined
sayThisColor.call(apple); // red
</source>

== Events ==

Events are really what make JavaScript such a powerful language for web development.

Rather than being thread based, JavaScript is event based. Since all JavaScript code runs in a single thread, '''there are no concurrency issues'''. When an event occurs, JavaScript automatically calls the ''event callback'' as soon as all previous events' callbacks have finished executing.

Code in the form of a '''callback function''' is associated with events via a '''listener'''. For example, the following JavaScript causes ''sayHello()'' (the callback function) to be run whenever the button with ID "hello" is clicked (the event):

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

document.getElementById("hello").addEventListener("click", sayHello, false);
</source>

{{JSFiddleExample
|title=Binding Callbacks to a Button Click
|fiddle_id=L8c4Z
|cse330=true
|desc=In this example, notice how we bind the callback function when the ''DOMContentLoaded'' event fires. This is because JavaScript requires that the button has been parsed by the browser before it can add event listeners to it.
}}

The '''addEventListener''' method takes three parameters:
* The event type
* The callback function
*: The callback function is passed one parameter: the event object.
* A boolean representing bubble (false) or capture (true) phase
*: You usually want Bubble phase. For more information on event phase, see [[#Event Phase]]

Note that versions of Internet Explorer prior to version 9 required that you use a different, albeit similar, function for assigning event listeners called '''attachEvent'''. attachEvent takes the same arguments as addEventListener, except you need to put '''on''' before the event type (e.g. "onclick"), and the third argument (phase) is not necessary.

It is perfectly valid to use an '''anonymous function''' as your callback function:

<source lang="javascript">
document.getElementById("hello").addEventListener("click", function(event){
alert("Hello, World! Event Type: "+event.type);
}, false);
</source>

QuirksMode has perhaps the best series of articles about the ins and outs of JavaScript events on the internet: http://www.quirksmode.org/js/contents.html#events

=== The Event Object ===

Callback functions are passed one argument: an ''event object''. You see above that one property of the event object is ''event.type''. To see the full list of properties of the event object, you could run the code:

<source lang="javascript">
document.getElementById("my_btn").addEventListener("click", function(event){
var strout = "";
for(var i in event){
strout += i + ": " + event[i] + "\n";
}
console.log(strout);
}, false);
</source>

Some of the most useful properties and methods include:
* '''event.target''' references the object on which the event occurred.
* '''event.currentTarget''' references the object whose listener is currently being processed.
*: ''Note:'' event.target and event.currentTarget might be the same or might be different, depending on whether you are listening for bubbled events.
* '''event.preventDefault()''' stops the normal result of the event from being executed. For example, if you listen for a form's ''submit'' event, you can call event.preventDefault() to stop the form from being submitted.
* '''event.stopPropagation()''' prevents any other event listeners from being executed. For more detail, read the section on Event Phase below.

For more detail on the event object, see [http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#interface-Event the W3C specification].

'''Note:''' If your callback function does not take any parameters, it will still run; you just won't have as easy of access to the event object.

=== Event Handlers and Memory Management ===

JavaScript is an automatically garbage-collected language, meaning that memory management is mostly taken care of for you. However, there are some instances when you need to be careful about creating "zombie" objects. In JavaScript, this mostly revolves around the idea of event listeners.

I could give an explanatory example, but instead I'll tell you straightaway that '''the moral of the story is that for every "addEventListener", there should probably be a "removeEventListener".''' Here are some good articles to satisfy your hunger for more details on event listeners and JavaScript memory management:

* http://www.vladalexandruionescu.com/2012/08/javascript-memory-leaks.html
* http://lostechies.com/derickbailey/2012/03/19/backbone-js-and-javascript-garbage-collection/
* http://stackoverflow.com/questions/5326300/garbage-collection-with-node-js

When you start working with Node.JS in the next module, it's more important than ever to keep good accounting of your event listeners.

=== Event Phase ===

In JavaScript, events occur in two phases: '''Capture Phase''' and '''Bubble Phase'''. Consider the following HTML document:

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head><title>Event Test</title></head>
<body>
<div id="box">
<button id="btn">
Hello
</button>
</div>
</body>
</html>
</source>

Suppose the user clicks on the "Hello" button. Events will be fired in the following order:

# Capture Phase CLICK on the Document
# Capture Phase CLICK on the Body
# Capture Phase CLICK on the Div#box
# Target Phase CLICK on the Button#btn
# Bubble Phase CLICK on the Div#box
# Bubble Phase CLICK on the Body
# Bubble Phase CLICK on the Document

{{JSFiddleExample
|title=Using Capture Phase to Enable or Disable a Toolbar
|fiddle_id=r32Dz
|desc=We bind an event in the capture phase to the div with ID ''toolbar''. When ''e.stopPropagation()'' is called, the event does not reach the buttons in the toolbar.
}}

Graphically, here is the order in which an event occurs in three generic nested elements:

[[File:EventPhase.gif]]

Why is this useful? Suppose you have a control panel (toolbar, etc) that you want to temporarily deactivate. (For example, Bold/Italic/Underline buttons on a graphic text editor that currently has no content.) You could keep bubble phase event listeners on your buttons, but prevent those events from occurring by stopping the event in the capture phase on the parent element before the event reaches your buttons! Example:

<source lang="javascript">
var disableToolbarFunc = function(e){
e.stopPropogation();
}

// To disable toolbar:
document.getElementById("box").addEventListener("click", disableToolbarFunc, true);

// To re-enable toolbar:
document.getElementById("box").removeEventListener("click", disableToolbarFunc, true);
</source>

'''Word of caution:''' Like many great things in web development, capture phase does not work in versions of Internet Explorer prior to version 9. There is no elegant substitution for older versions of Internet Explorer.

'''Note:''' When the event reaches the innermost element, there is no distinction between capture phase and bubble phase. The order in which event handlers were added to the element determines the order in which those callbacks are evaluated.

== Document Object Model ==

The '''Document Object Model (DOM)''' is what enables JavaScript to manipulate the content of your web page.

=== Nodes and Traversing the DOM ===

Each element on your page, whether it is a <nowiki><p>, <img/></nowiki>, a string of text, or even an attribute, is called a '''node'''.

Every node, except for the document itself, has exactly one parent. A single node may have multiple children.

Consider the following HTML code:

<source lang="html4strict">
<ul id="my-list">
<li class="fruits">Apples</li>
<li class="citrus">Oranges and <strong>Lemons</strong></li>
<li class="berries">Cherries</li>
</ul>
</source>

Here, the ul with ID "my-list" has three child '''element nodes''' (the three li's) as well as four child '''text nodes''' (the whitespace counts as a text node) and a child '''attribute node'''. The second LI has one child '''text node''' as well as one child '''element node''' and one child '''attribute node'''.

The DOM can be traversed in JavaScript. First, let's look at an example.

<source lang="javascript">
e = document.getElementById("my-list").getElementsByClassName("citrus")[0].lastChild.nodeName;
alert(e);
</source>

{{JSFiddleExample
|title=Currently Selected Radio Button
|fiddle_id=SHcng
|desc=In pure JavaScript, in order to determine the currently selected radio button, it is necessary to iterate over an array of pointers to all possible radio buttons, and stop when you find one that is "checked".
}}

The above snippet gets the element with class name '''citrus''' that is a child of the element with ID '''my-list''' (the second LI in the example above), and alerts the type of its second child node (which in this case is '''STRONG''').

Some common methods for traversing the DOM include:

* Node.parentNode
* Node.childNodes - returns an array of nodes
* Node.firstChild - same as Node.childNodes[0]
* Node.lastChild - same as Node.childNodes[Node.childNodes.length-1]
* Node.previousSibling
* Node.nextSibling

You can also search for child (including all descendants) using one of the following methods:

* Node.getElementsByTagName("tag-name") - returns an array of element nodes having the tag name '''tag-name''' that are descendants of Node
* Node.getElementById("id") - returns a single node having the ID '''id''' that is a descendant of Node
* Node.getElementsByName("what-name") - returns an array of element nodes having their '''name''' attribute set to '''what-name'''. Useful for radio buttons and other form elements.
* Node.getElementsByClassName("class") - returns an array of nodes having the class '''class'''
*: '''Note:''' As of October 2012, 82% of the browser market supports Node.getElementsByClassName ([http://caniuse.com/getelementsbyclassname more info]). In order to support the other 18%, you need to either add your own getElementsByClassName to Node's prototype or use a JavaScript library like jQuery or MooTools.

It is common in JavaScript to have long statements like the one in the example above, where you call methods on several objects in sequence.

=== Creating, Moving, and Removing Nodes ===

You will frequently find yourself wanting to modify the DOM. JavaScript provides methods that help you do this.

Consider the same HTML as above. If you wanted to add another element to the list, you could use this code:

<source lang="javascript">
var newLi = document.createElement("li"); // creates a node with the tag name li
newLi.appendChild(document.createTextNode("Broccoli"));
newLi.setAttribute("class", "veggies");
document.getElementById("my-list").appendChild(newLi);
</source>

If you wanted to remove the apples from the list, you could do:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").removeChild(apple);
</source>

If you wanted to move the apples to the end of the list, you could do this:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").appendChild(apple);
</source>

Notice that '''Node.append()''' both removes a node from its previous location ''and'' appends it to its new location, which is always going to be as the last child of the parent node.

In summary, here are the methods to know from this section:

* Node.append(otherNode) - removes otherNode from its current location in the DOM (if applicable) and then adds it as the last child of Node
* Node.removeChild(otherNode) - removes otherNode, a child of Node, from the DOM
* document.createElement("tag-name") - create a new node with the tag name "tag-name"
* document.createTextNode("text") - create a node containing only the string '''text'''
* Node.setAttribute("attribute", "value") - sets the attribute node of name "attribute" to "value"

=== DOM Shortcuts ===

In the above sections, we have been creating, reading, modifying, and deleting Nodes. This is the most "correct" way to change the content of a web page from inside JavaScript.

This section documents a few shortcuts that are not as "pure" as using Nodes but can be less confusing and cumbersome.

{{JSFiddleExample
|title=Displaying Information
|fiddle_id=Q3BPZ
|desc=This example shows how to use some of the shortcut methods for using JavaScript to display information on the page.
}}

==== textContent ====

Using textContent to display information is probably the easiest method out there. For example, the following code overwrites whatever is in the element with ID "holder" with the string "Hello World":

<source lang="javascript">
document.getElementById("holder").textContent = "Hello World";
</source>

If you wanted to instead append the text, simply use '''+=''' instead of '''=''':

<source lang="javascript">
document.getElementById("holder").textContent += " - Later, he said Hello World - ";
</source>

Note that textContent displays strings literally; that is, it does not allow for HTML. Setting the textContent property also removes any HTML that may have already been in that element.

==== innerHTML ====

If you need to use HTML in your output but don't want to use the method described earlier in this section, a straightforward strategy is to use the innerHTML property of an element. For example, the following code would add a paragraph saying "Hello World" to the element with ID "holder":

<source lang="javascript">
document.getElementById("holder").innerHTML += "<p>Hello World</p>";
</source>

'''Important:''' You need to be careful to prevent XSS-type attacks if you display information using innerHTML. For example, be sure to escape a user-supplied string before appending it to innerHTML.

=== JavaScript Inspectors ===

{{DoctypeTV
|youtube_id=PKzrmbN-pMg
|time=4m13s
|desc=Using Firebug, WebKit Inspector, and IE Developer Tools
}}

Various browsers and browser plugins give you, the developer, tools to debug your code, inspect the DOM, and much more. Using these tools is essential for an efficient workflow.

* '''Firebug'''. Firebug is a plugin for Firefox that is a toolkit full of web developer tools, one of which is a DOM inspector. To inspect the DOM of a web page, simply open the Firebug window while viewing the web page.
* '''WebKit Inspector'''. The WebKit Inspector, which is available in both Chrome and Safari, enables you to see the DOM tree and relationships between elements. However, its DOM inspection tools are not as robust as those of Firebug.
* '''Opera Dragonfly'''. The web browser Opera comes with a web developer toolkit similar to the WebKit Inspector called Dragonfly. It is important that you test your sites in Opera, because although Opera has only a small fraction of the desktop browser market, it is second only to WebKit on the mobile market. Opera also has extremely strong CSS support, so it is good for testing for bugs in your CSS.

All of the above-mentioned tools enable you to look at the DOM of your web page and find what properties and methods are associated with each node. This is helpful because if you have JavaScript that manipulates HTML elements, you cannot tell which properties are associated with which elements by looking at the source code alone.

[[Category:Module 6]]

JavaScript

2015-01-09T09:34:45Z

Shane: /* Event Handlers and Memory Management */

JavaScript is the most widely used scripting language for implementing client-side functionality in Web applications. Unlike PHP, JavaScript code is interpreted and executed in a client's web browser (not on the web server).

== JavaScript? Did you mean Java? ==

'''JavaScript''' is a prototype-based programming language focussed on web interactivity. It was first introduced in Netscape Navigator, and it in turn gave rise to what is now '''[http://www.ecmascript.org/ ECMAScript]'''. Originally, JavaScript was called "LiveScript". Sun, the developer of Java at the time, wanted a language that would complement its compiled Java language, and so LiveScript was renamed JavaScript.

Beyond that, '''Java and JavaScript are as similar as Ham and Hamster.'''

Java and JavaScript have similar syntax, but the under workings are quite different. For example, Java requires strict typing, but JavaScript allows for dynamic typing. Java is object-oriented, but JavaScript is prototype-oriented. Java is compiled, but JavaScript is interpreted. Java supports event listeners, but JavaScript makes them a fundamental part of the language. Java variables are scoped to the innermost method or loop, but JavaScript variables are scoped only to the innermost function.

== JavaScript Language Components ==

This section highlights some features of the JavaScript language that differentiate it from other languages. For a more comprehensive JavaScript tutorial, the following tutorials are both quality:

* [http://docs.webplatform.org/wiki/javascript WebPlatform]: Great for learning JavaScript for the first time. Advocates best practices for modern JavaScript development.
* [http://www.quirksmode.org/js/contents.html QuirksMode]: More advanced than the WebPlatform tutorial, but it thoroughly covers the most powerful aspects of pure JavaScript and gives unparalleled advice on browser compatibility.

Advice: Do '''NOT''' Google for "JavaScript Tutorial". The first few hits advocate bad or outdated practices. Stick with the ones listed here.

=== Variables and Scope ===

To define a variable in JavaScript, use the '''var''' keyword.

<source lang="javascript">
var foo = "bar";
</source>

All variables are objects. In the case above, the variable '''foo''' is an object of the class '''String'''.

Notice that like PHP, you do not have to explicitly define a type for a variable like '''int''' or '''String'''; this is because JavaScript and PHP are ''dynamically typed languages''.

JavaScript code can access any variable higher in the “function tree”, but not vice-versa. This is called '''scope'''. ''All functions create their own scope.''

When you reference a variable, JavaScript will look up through the "function tree" until it finds the variable you asked for. This means that you could define variables of the same name as global variables inside of functions. For demonstration of concept:

<source lang="javascript">
var a = "hello";
var b = "world";

function sayGoodByeWorld(){
var a = "goodbye";

alert(a); // goodbye
alert(b); // world
}

sayGoodByeWorld();

alert(a); // hello
</source>

=== Object Literals ===

A very common way of storing and transporting data in JavaScript is by using objects. You can define an object with certain properties using an '''object literal''':

<source lang="javascript">
var apple = {
color: "red",
flavor: "sweet",
season: "autumn"
}

alert(apple.color); // red
</source>

=== Functions ===

To define a function in JavaScript, use the '''function''' keyword.

<source lang="javascript">
function sayHello(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Pass an argument to a function like this:

<source lang="javascript">
function sayHello(name){
alert("Hello, "+name);
}

sayHello("Todd"); // call the function and pass an argument
</source>

==== Functions are Objects ====

In JavaScript, functions are objects. This means that they can be assigned to variables, manipulated on the fly, and even passed as arguments to other functions! '''''This is an extremely important feature of JavaScript''''' that makes it such a robust language for web development.

You create a function variable like this:

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Observe that you can make [[#Variables and Scope|scope-dependent]] functions in this way.

=== Closures ===

{{DoctypeTV
|youtube_id=HaPlj796ngQ
|time=5m45s
|desc=JavaScript Closures
}}

A '''closure''' is a way to separate a certain snippet of JavaScript code from the global scope. This is useful if you do not want to "muck up" global variables. Closures are nothing more than anonymous functions that are called as soon as they are created:

<source lang="javascript">
var a = "hello";

(function(){
var b = "world";

alert(a); // hello
alert(b); // world
})();

alert(a); // hello
alert(b); // ReferenceError: b is not defined
</source>

{{JSFiddleExample
|title=Passing Variables to a Closure
|desc=This example demonstrates how you can "save" previous versions of a variable using closures. This is possible because of scoping and the fact that function variables can be returned as objects.
|fiddle_id=YURqa
}}

Most JavaScript libraries (like jQuery) write all of their code in a closure. What this means is that except for one or two variable names (jQuery or $), everything associated with the library is completely self-contained.

=== Prototypal Inheritance ===

JavaScript implements '''prototypal inheritance''', as opposed to a language like Java or C++, which implements '''classical inheritance'''. JavaScript is one of only a handful of languages implementing prototype-based inheritance.

Here's how it works. Every callable object (function) has a '''prototype'''. When instances of that object are created, their properties and methods are copied (inherited) from the prototype. Additionally, changes made to the prototype later in the program are "copied" to every instance.

For example, if you wanted to make a method on all strings that added a “!”, you could modify String’s prototype:

<source lang="javascript">
String.prototype.bang = function(){
return this+"!"; // Notice: the context is the instance itself
}

alert("Hello".bang()); // alerts Hello!
</source>

To "extend" an object, just copy its prototype to a new object. However, since classical inheritance and prototypal inheritance are different concepts, copying prototypes may have results that you don't expect. [http://beej.us/blog/data/javascript-prototypes-inheritance/ This article] seems to have a pretty good explanation with example implementations.

=== Context ===

{{DoctypeTV
|youtube_id=0a4r4bm1nQA
|time=4m32s
|desc=The ''this'' Variable in JavaScript
}}

Every function is called on a certain object, which is not necessarily the same object in which it was defined. This is called '''context'''.

To call a function on an arbitrary context, use either '''call''' or '''apply'''. ''call'' takes a list of arguments, while ''apply'' takes them all in an array.

To access the current context, use the '''this''' keyword. Demonstration of concept:

<source lang="javascript">
var sayThisColor = function(){
alert(this.color);
}

var apple = { color: "red" }

sayThisColor(); // undefined
sayThisColor.call(apple); // red
</source>

== Events ==

Events are really what make JavaScript such a powerful language for web development.

Rather than being thread based, JavaScript is event based. Since all JavaScript code runs in a single thread, '''there are no concurrency issues'''. When an event occurs, JavaScript automatically calls the ''event callback'' as soon as all previous events' callbacks have finished executing.

Code in the form of a '''callback function''' is associated with events via a '''listener'''. For example, the following JavaScript causes ''sayHello()'' (the callback function) to be run whenever the button with ID "hello" is clicked (the event):

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

document.getElementById("hello").addEventListener("click", sayHello, false);
</source>

{{JSFiddleExample
|title=Binding Callbacks to a Button Click
|fiddle_id=L8c4Z
|cse330=true
|desc=In this example, notice how we bind the callback function when the ''DOMContentLoaded'' event fires. This is because JavaScript requires that the button has been parsed by the browser before it can add event listeners to it.
}}

The '''addEventListener''' method takes three parameters:
* The event type
* The callback function
*: The callback function is passed one parameter: the event object.
* A boolean representing bubble (false) or capture (true) phase
*: You usually want Bubble phase. For more information on event phase, see [[#Event Phase]]

Note that versions of Internet Explorer prior to version 9 required that you use a different, albeit similar, function for assigning event listeners called '''attachEvent'''. attachEvent takes the same arguments as addEventListener, except you need to put '''on''' before the event type (e.g. "onclick"), and the third argument (phase) is not necessary.

It is perfectly valid to use an '''anonymous function''' as your callback function:

<source lang="javascript">
document.getElementById("hello").addEventListener("click", function(event){
alert("Hello, World! Event Type: "+event.type);
}, false);
</source>

QuirksMode has perhaps the best series of articles about the ins and outs of JavaScript events on the internet: http://www.quirksmode.org/js/contents.html#events

=== The Event Object ===

Callback functions are passed one argument: an ''event object''. You see above that one property of the event object is ''event.type''. To see the full list of properties of the event object, you could run the code:

<source lang="javascript">
document.getElementById("my_btn").addEventListener("click", function(event){
var strout = "";
for(var i in event){
strout += i + ": " + event[i] + "\n";
}
console.log(strout);
}, false);
</source>

Some of the most useful properties and methods include:
* '''event.target''' references the object on which the event occurred.
* '''event.currentTarget''' references the object whose listener is currently being processed.
*: ''Note:'' event.target and event.currentTarget might be the same or might be different, depending on whether you are listening for bubbled events.
* '''event.preventDefault()''' stops the normal result of the event from being executed. For example, if you listen for a form's ''submit'' event, you can call event.preventDefault() to stop the form from being submitted.
* '''event.stopPropagation()''' prevents any other event listeners from being executed. For more detail, read the section on Event Phase below.

For more detail on the event object, see [http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#interface-Event the W3C specification].

'''Note:''' If your callback function does not take any parameters, it will still run; you just won't have as easy of access to the event object.

=== Event Handlers and Memory Management ===

JavaScript is an automatically garbage-collected language, meaning that memory management is mostly taken care of for you. However, there are some instances when you need to be careful about creating "zombie" objects. In JavaScript, this mostly revolves around the idea of event listeners.

I could give an explanatory example, but instead I'll tell you straightaway that '''the moral of the story is that for every "addEventListener", there should probably be a "removeEventListener".''' Here are some good articles to satisfy your hunger for more details on event listeners and JavaScript memory management:

* http://www.vladalexandruionescu.com/2012/08/javascript-memory-leaks.html
* http://lostechies.com/derickbailey/2012/03/19/backbone-js-and-javascript-garbage-collection/

When you start working with Node.JS in the next module, it's more important than ever to keep good accounting of your event listeners.

=== Event Phase ===

In JavaScript, events occur in two phases: '''Capture Phase''' and '''Bubble Phase'''. Consider the following HTML document:

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head><title>Event Test</title></head>
<body>
<div id="box">
<button id="btn">
Hello
</button>
</div>
</body>
</html>
</source>

Suppose the user clicks on the "Hello" button. Events will be fired in the following order:

# Capture Phase CLICK on the Document
# Capture Phase CLICK on the Body
# Capture Phase CLICK on the Div#box
# Target Phase CLICK on the Button#btn
# Bubble Phase CLICK on the Div#box
# Bubble Phase CLICK on the Body
# Bubble Phase CLICK on the Document

{{JSFiddleExample
|title=Using Capture Phase to Enable or Disable a Toolbar
|fiddle_id=r32Dz
|desc=We bind an event in the capture phase to the div with ID ''toolbar''. When ''e.stopPropagation()'' is called, the event does not reach the buttons in the toolbar.
}}

Graphically, here is the order in which an event occurs in three generic nested elements:

[[File:EventPhase.gif]]

Why is this useful? Suppose you have a control panel (toolbar, etc) that you want to temporarily deactivate. (For example, Bold/Italic/Underline buttons on a graphic text editor that currently has no content.) You could keep bubble phase event listeners on your buttons, but prevent those events from occurring by stopping the event in the capture phase on the parent element before the event reaches your buttons! Example:

<source lang="javascript">
var disableToolbarFunc = function(e){
e.stopPropogation();
}

// To disable toolbar:
document.getElementById("box").addEventListener("click", disableToolbarFunc, true);

// To re-enable toolbar:
document.getElementById("box").removeEventListener("click", disableToolbarFunc, true);
</source>

'''Word of caution:''' Like many great things in web development, capture phase does not work in versions of Internet Explorer prior to version 9. There is no elegant substitution for older versions of Internet Explorer.

'''Note:''' When the event reaches the innermost element, there is no distinction between capture phase and bubble phase. The order in which event handlers were added to the element determines the order in which those callbacks are evaluated.

== Document Object Model ==

The '''Document Object Model (DOM)''' is what enables JavaScript to manipulate the content of your web page.

=== Nodes and Traversing the DOM ===

Each element on your page, whether it is a <nowiki><p>, <img/></nowiki>, a string of text, or even an attribute, is called a '''node'''.

Every node, except for the document itself, has exactly one parent. A single node may have multiple children.

Consider the following HTML code:

<source lang="html4strict">
<ul id="my-list">
<li class="fruits">Apples</li>
<li class="citrus">Oranges and <strong>Lemons</strong></li>
<li class="berries">Cherries</li>
</ul>
</source>

Here, the ul with ID "my-list" has three child '''element nodes''' (the three li's) as well as four child '''text nodes''' (the whitespace counts as a text node) and a child '''attribute node'''. The second LI has one child '''text node''' as well as one child '''element node''' and one child '''attribute node'''.

The DOM can be traversed in JavaScript. First, let's look at an example.

<source lang="javascript">
e = document.getElementById("my-list").getElementsByClassName("citrus")[0].lastChild.nodeName;
alert(e);
</source>

{{JSFiddleExample
|title=Currently Selected Radio Button
|fiddle_id=SHcng
|desc=In pure JavaScript, in order to determine the currently selected radio button, it is necessary to iterate over an array of pointers to all possible radio buttons, and stop when you find one that is "checked".
}}

The above snippet gets the element with class name '''citrus''' that is a child of the element with ID '''my-list''' (the second LI in the example above), and alerts the type of its second child node (which in this case is '''STRONG''').

Some common methods for traversing the DOM include:

* Node.parentNode
* Node.childNodes - returns an array of nodes
* Node.firstChild - same as Node.childNodes[0]
* Node.lastChild - same as Node.childNodes[Node.childNodes.length-1]
* Node.previousSibling
* Node.nextSibling

You can also search for child (including all descendants) using one of the following methods:

* Node.getElementsByTagName("tag-name") - returns an array of element nodes having the tag name '''tag-name''' that are descendants of Node
* Node.getElementById("id") - returns a single node having the ID '''id''' that is a descendant of Node
* Node.getElementsByName("what-name") - returns an array of element nodes having their '''name''' attribute set to '''what-name'''. Useful for radio buttons and other form elements.
* Node.getElementsByClassName("class") - returns an array of nodes having the class '''class'''
*: '''Note:''' As of October 2012, 82% of the browser market supports Node.getElementsByClassName ([http://caniuse.com/getelementsbyclassname more info]). In order to support the other 18%, you need to either add your own getElementsByClassName to Node's prototype or use a JavaScript library like jQuery or MooTools.

It is common in JavaScript to have long statements like the one in the example above, where you call methods on several objects in sequence.

=== Creating, Moving, and Removing Nodes ===

You will frequently find yourself wanting to modify the DOM. JavaScript provides methods that help you do this.

Consider the same HTML as above. If you wanted to add another element to the list, you could use this code:

<source lang="javascript">
var newLi = document.createElement("li"); // creates a node with the tag name li
newLi.appendChild(document.createTextNode("Broccoli"));
newLi.setAttribute("class", "veggies");
document.getElementById("my-list").appendChild(newLi);
</source>

If you wanted to remove the apples from the list, you could do:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").removeChild(apple);
</source>

If you wanted to move the apples to the end of the list, you could do this:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").appendChild(apple);
</source>

Notice that '''Node.append()''' both removes a node from its previous location ''and'' appends it to its new location, which is always going to be as the last child of the parent node.

In summary, here are the methods to know from this section:

* Node.append(otherNode) - removes otherNode from its current location in the DOM (if applicable) and then adds it as the last child of Node
* Node.removeChild(otherNode) - removes otherNode, a child of Node, from the DOM
* document.createElement("tag-name") - create a new node with the tag name "tag-name"
* document.createTextNode("text") - create a node containing only the string '''text'''
* Node.setAttribute("attribute", "value") - sets the attribute node of name "attribute" to "value"

=== DOM Shortcuts ===

In the above sections, we have been creating, reading, modifying, and deleting Nodes. This is the most "correct" way to change the content of a web page from inside JavaScript.

This section documents a few shortcuts that are not as "pure" as using Nodes but can be less confusing and cumbersome.

{{JSFiddleExample
|title=Displaying Information
|fiddle_id=Q3BPZ
|desc=This example shows how to use some of the shortcut methods for using JavaScript to display information on the page.
}}

==== textContent ====

Using textContent to display information is probably the easiest method out there. For example, the following code overwrites whatever is in the element with ID "holder" with the string "Hello World":

<source lang="javascript">
document.getElementById("holder").textContent = "Hello World";
</source>

If you wanted to instead append the text, simply use '''+=''' instead of '''=''':

<source lang="javascript">
document.getElementById("holder").textContent += " - Later, he said Hello World - ";
</source>

Note that textContent displays strings literally; that is, it does not allow for HTML. Setting the textContent property also removes any HTML that may have already been in that element.

==== innerHTML ====

If you need to use HTML in your output but don't want to use the method described earlier in this section, a straightforward strategy is to use the innerHTML property of an element. For example, the following code would add a paragraph saying "Hello World" to the element with ID "holder":

<source lang="javascript">
document.getElementById("holder").innerHTML += "<p>Hello World</p>";
</source>

'''Important:''' You need to be careful to prevent XSS-type attacks if you display information using innerHTML. For example, be sure to escape a user-supplied string before appending it to innerHTML.

=== JavaScript Inspectors ===

{{DoctypeTV
|youtube_id=PKzrmbN-pMg
|time=4m13s
|desc=Using Firebug, WebKit Inspector, and IE Developer Tools
}}

Various browsers and browser plugins give you, the developer, tools to debug your code, inspect the DOM, and much more. Using these tools is essential for an efficient workflow.

* '''Firebug'''. Firebug is a plugin for Firefox that is a toolkit full of web developer tools, one of which is a DOM inspector. To inspect the DOM of a web page, simply open the Firebug window while viewing the web page.
* '''WebKit Inspector'''. The WebKit Inspector, which is available in both Chrome and Safari, enables you to see the DOM tree and relationships between elements. However, its DOM inspection tools are not as robust as those of Firebug.
* '''Opera Dragonfly'''. The web browser Opera comes with a web developer toolkit similar to the WebKit Inspector called Dragonfly. It is important that you test your sites in Opera, because although Opera has only a small fraction of the desktop browser market, it is second only to WebKit on the mobile market. Opera also has extremely strong CSS support, so it is good for testing for bugs in your CSS.

All of the above-mentioned tools enable you to look at the DOM of your web page and find what properties and methods are associated with each node. This is helpful because if you have JavaScript that manipulates HTML elements, you cannot tell which properties are associated with which elements by looking at the source code alone.

[[Category:Module 6]]

JavaScript

2015-01-09T09:32:10Z

Shane: /* Event Handlers and Memory Management */

JavaScript is the most widely used scripting language for implementing client-side functionality in Web applications. Unlike PHP, JavaScript code is interpreted and executed in a client's web browser (not on the web server).

== JavaScript? Did you mean Java? ==

'''JavaScript''' is a prototype-based programming language focussed on web interactivity. It was first introduced in Netscape Navigator, and it in turn gave rise to what is now '''[http://www.ecmascript.org/ ECMAScript]'''. Originally, JavaScript was called "LiveScript". Sun, the developer of Java at the time, wanted a language that would complement its compiled Java language, and so LiveScript was renamed JavaScript.

Beyond that, '''Java and JavaScript are as similar as Ham and Hamster.'''

Java and JavaScript have similar syntax, but the under workings are quite different. For example, Java requires strict typing, but JavaScript allows for dynamic typing. Java is object-oriented, but JavaScript is prototype-oriented. Java is compiled, but JavaScript is interpreted. Java supports event listeners, but JavaScript makes them a fundamental part of the language. Java variables are scoped to the innermost method or loop, but JavaScript variables are scoped only to the innermost function.

== JavaScript Language Components ==

This section highlights some features of the JavaScript language that differentiate it from other languages. For a more comprehensive JavaScript tutorial, the following tutorials are both quality:

* [http://docs.webplatform.org/wiki/javascript WebPlatform]: Great for learning JavaScript for the first time. Advocates best practices for modern JavaScript development.
* [http://www.quirksmode.org/js/contents.html QuirksMode]: More advanced than the WebPlatform tutorial, but it thoroughly covers the most powerful aspects of pure JavaScript and gives unparalleled advice on browser compatibility.

Advice: Do '''NOT''' Google for "JavaScript Tutorial". The first few hits advocate bad or outdated practices. Stick with the ones listed here.

=== Variables and Scope ===

To define a variable in JavaScript, use the '''var''' keyword.

<source lang="javascript">
var foo = "bar";
</source>

All variables are objects. In the case above, the variable '''foo''' is an object of the class '''String'''.

Notice that like PHP, you do not have to explicitly define a type for a variable like '''int''' or '''String'''; this is because JavaScript and PHP are ''dynamically typed languages''.

JavaScript code can access any variable higher in the “function tree”, but not vice-versa. This is called '''scope'''. ''All functions create their own scope.''

When you reference a variable, JavaScript will look up through the "function tree" until it finds the variable you asked for. This means that you could define variables of the same name as global variables inside of functions. For demonstration of concept:

<source lang="javascript">
var a = "hello";
var b = "world";

function sayGoodByeWorld(){
var a = "goodbye";

alert(a); // goodbye
alert(b); // world
}

sayGoodByeWorld();

alert(a); // hello
</source>

=== Object Literals ===

A very common way of storing and transporting data in JavaScript is by using objects. You can define an object with certain properties using an '''object literal''':

<source lang="javascript">
var apple = {
color: "red",
flavor: "sweet",
season: "autumn"
}

alert(apple.color); // red
</source>

=== Functions ===

To define a function in JavaScript, use the '''function''' keyword.

<source lang="javascript">
function sayHello(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Pass an argument to a function like this:

<source lang="javascript">
function sayHello(name){
alert("Hello, "+name);
}

sayHello("Todd"); // call the function and pass an argument
</source>

==== Functions are Objects ====

In JavaScript, functions are objects. This means that they can be assigned to variables, manipulated on the fly, and even passed as arguments to other functions! '''''This is an extremely important feature of JavaScript''''' that makes it such a robust language for web development.

You create a function variable like this:

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Observe that you can make [[#Variables and Scope|scope-dependent]] functions in this way.

=== Closures ===

{{DoctypeTV
|youtube_id=HaPlj796ngQ
|time=5m45s
|desc=JavaScript Closures
}}

A '''closure''' is a way to separate a certain snippet of JavaScript code from the global scope. This is useful if you do not want to "muck up" global variables. Closures are nothing more than anonymous functions that are called as soon as they are created:

<source lang="javascript">
var a = "hello";

(function(){
var b = "world";

alert(a); // hello
alert(b); // world
})();

alert(a); // hello
alert(b); // ReferenceError: b is not defined
</source>

{{JSFiddleExample
|title=Passing Variables to a Closure
|desc=This example demonstrates how you can "save" previous versions of a variable using closures. This is possible because of scoping and the fact that function variables can be returned as objects.
|fiddle_id=YURqa
}}

Most JavaScript libraries (like jQuery) write all of their code in a closure. What this means is that except for one or two variable names (jQuery or $), everything associated with the library is completely self-contained.

=== Prototypal Inheritance ===

JavaScript implements '''prototypal inheritance''', as opposed to a language like Java or C++, which implements '''classical inheritance'''. JavaScript is one of only a handful of languages implementing prototype-based inheritance.

Here's how it works. Every callable object (function) has a '''prototype'''. When instances of that object are created, their properties and methods are copied (inherited) from the prototype. Additionally, changes made to the prototype later in the program are "copied" to every instance.

For example, if you wanted to make a method on all strings that added a “!”, you could modify String’s prototype:

<source lang="javascript">
String.prototype.bang = function(){
return this+"!"; // Notice: the context is the instance itself
}

alert("Hello".bang()); // alerts Hello!
</source>

To "extend" an object, just copy its prototype to a new object. However, since classical inheritance and prototypal inheritance are different concepts, copying prototypes may have results that you don't expect. [http://beej.us/blog/data/javascript-prototypes-inheritance/ This article] seems to have a pretty good explanation with example implementations.

=== Context ===

{{DoctypeTV
|youtube_id=0a4r4bm1nQA
|time=4m32s
|desc=The ''this'' Variable in JavaScript
}}

Every function is called on a certain object, which is not necessarily the same object in which it was defined. This is called '''context'''.

To call a function on an arbitrary context, use either '''call''' or '''apply'''. ''call'' takes a list of arguments, while ''apply'' takes them all in an array.

To access the current context, use the '''this''' keyword. Demonstration of concept:

<source lang="javascript">
var sayThisColor = function(){
alert(this.color);
}

var apple = { color: "red" }

sayThisColor(); // undefined
sayThisColor.call(apple); // red
</source>

== Events ==

Events are really what make JavaScript such a powerful language for web development.

Rather than being thread based, JavaScript is event based. Since all JavaScript code runs in a single thread, '''there are no concurrency issues'''. When an event occurs, JavaScript automatically calls the ''event callback'' as soon as all previous events' callbacks have finished executing.

Code in the form of a '''callback function''' is associated with events via a '''listener'''. For example, the following JavaScript causes ''sayHello()'' (the callback function) to be run whenever the button with ID "hello" is clicked (the event):

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

document.getElementById("hello").addEventListener("click", sayHello, false);
</source>

{{JSFiddleExample
|title=Binding Callbacks to a Button Click
|fiddle_id=L8c4Z
|cse330=true
|desc=In this example, notice how we bind the callback function when the ''DOMContentLoaded'' event fires. This is because JavaScript requires that the button has been parsed by the browser before it can add event listeners to it.
}}

The '''addEventListener''' method takes three parameters:
* The event type
* The callback function
*: The callback function is passed one parameter: the event object.
* A boolean representing bubble (false) or capture (true) phase
*: You usually want Bubble phase. For more information on event phase, see [[#Event Phase]]

Note that versions of Internet Explorer prior to version 9 required that you use a different, albeit similar, function for assigning event listeners called '''attachEvent'''. attachEvent takes the same arguments as addEventListener, except you need to put '''on''' before the event type (e.g. "onclick"), and the third argument (phase) is not necessary.

It is perfectly valid to use an '''anonymous function''' as your callback function:

<source lang="javascript">
document.getElementById("hello").addEventListener("click", function(event){
alert("Hello, World! Event Type: "+event.type);
}, false);
</source>

QuirksMode has perhaps the best series of articles about the ins and outs of JavaScript events on the internet: http://www.quirksmode.org/js/contents.html#events

=== The Event Object ===

Callback functions are passed one argument: an ''event object''. You see above that one property of the event object is ''event.type''. To see the full list of properties of the event object, you could run the code:

<source lang="javascript">
document.getElementById("my_btn").addEventListener("click", function(event){
var strout = "";
for(var i in event){
strout += i + ": " + event[i] + "\n";
}
console.log(strout);
}, false);
</source>

Some of the most useful properties and methods include:
* '''event.target''' references the object on which the event occurred.
* '''event.currentTarget''' references the object whose listener is currently being processed.
*: ''Note:'' event.target and event.currentTarget might be the same or might be different, depending on whether you are listening for bubbled events.
* '''event.preventDefault()''' stops the normal result of the event from being executed. For example, if you listen for a form's ''submit'' event, you can call event.preventDefault() to stop the form from being submitted.
* '''event.stopPropagation()''' prevents any other event listeners from being executed. For more detail, read the section on Event Phase below.

For more detail on the event object, see [http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#interface-Event the W3C specification].

'''Note:''' If your callback function does not take any parameters, it will still run; you just won't have as easy of access to the event object.

=== Event Handlers and Memory Management ===

JavaScript is an automatically garbage-collected language, meaning that memory management is mostly taken care of for you. However, there are some instances when you need to be careful about creating "zombie" objects. In JavaScript, this mostly revolves around the idea of event listeners.

I could give an explanatory example, but instead I'll tell you straightaway that '''the moral of the story is that for every "addEventListener", there should probably be a "removeEventListener".''' For more details on memory leaks in JavaScript, read this article: http://www.vladalexandruionescu.com/2012/08/javascript-memory-leaks.html

When you start working with Node.JS in the next module, it's more important than ever to keep good accounting of your event listeners.

=== Event Phase ===

In JavaScript, events occur in two phases: '''Capture Phase''' and '''Bubble Phase'''. Consider the following HTML document:

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head><title>Event Test</title></head>
<body>
<div id="box">
<button id="btn">
Hello
</button>
</div>
</body>
</html>
</source>

Suppose the user clicks on the "Hello" button. Events will be fired in the following order:

# Capture Phase CLICK on the Document
# Capture Phase CLICK on the Body
# Capture Phase CLICK on the Div#box
# Target Phase CLICK on the Button#btn
# Bubble Phase CLICK on the Div#box
# Bubble Phase CLICK on the Body
# Bubble Phase CLICK on the Document

{{JSFiddleExample
|title=Using Capture Phase to Enable or Disable a Toolbar
|fiddle_id=r32Dz
|desc=We bind an event in the capture phase to the div with ID ''toolbar''. When ''e.stopPropagation()'' is called, the event does not reach the buttons in the toolbar.
}}

Graphically, here is the order in which an event occurs in three generic nested elements:

[[File:EventPhase.gif]]

Why is this useful? Suppose you have a control panel (toolbar, etc) that you want to temporarily deactivate. (For example, Bold/Italic/Underline buttons on a graphic text editor that currently has no content.) You could keep bubble phase event listeners on your buttons, but prevent those events from occurring by stopping the event in the capture phase on the parent element before the event reaches your buttons! Example:

<source lang="javascript">
var disableToolbarFunc = function(e){
e.stopPropogation();
}

// To disable toolbar:
document.getElementById("box").addEventListener("click", disableToolbarFunc, true);

// To re-enable toolbar:
document.getElementById("box").removeEventListener("click", disableToolbarFunc, true);
</source>

'''Word of caution:''' Like many great things in web development, capture phase does not work in versions of Internet Explorer prior to version 9. There is no elegant substitution for older versions of Internet Explorer.

'''Note:''' When the event reaches the innermost element, there is no distinction between capture phase and bubble phase. The order in which event handlers were added to the element determines the order in which those callbacks are evaluated.

== Document Object Model ==

The '''Document Object Model (DOM)''' is what enables JavaScript to manipulate the content of your web page.

=== Nodes and Traversing the DOM ===

Each element on your page, whether it is a <nowiki><p>, <img/></nowiki>, a string of text, or even an attribute, is called a '''node'''.

Every node, except for the document itself, has exactly one parent. A single node may have multiple children.

Consider the following HTML code:

<source lang="html4strict">
<ul id="my-list">
<li class="fruits">Apples</li>
<li class="citrus">Oranges and <strong>Lemons</strong></li>
<li class="berries">Cherries</li>
</ul>
</source>

Here, the ul with ID "my-list" has three child '''element nodes''' (the three li's) as well as four child '''text nodes''' (the whitespace counts as a text node) and a child '''attribute node'''. The second LI has one child '''text node''' as well as one child '''element node''' and one child '''attribute node'''.

The DOM can be traversed in JavaScript. First, let's look at an example.

<source lang="javascript">
e = document.getElementById("my-list").getElementsByClassName("citrus")[0].lastChild.nodeName;
alert(e);
</source>

{{JSFiddleExample
|title=Currently Selected Radio Button
|fiddle_id=SHcng
|desc=In pure JavaScript, in order to determine the currently selected radio button, it is necessary to iterate over an array of pointers to all possible radio buttons, and stop when you find one that is "checked".
}}

The above snippet gets the element with class name '''citrus''' that is a child of the element with ID '''my-list''' (the second LI in the example above), and alerts the type of its second child node (which in this case is '''STRONG''').

Some common methods for traversing the DOM include:

* Node.parentNode
* Node.childNodes - returns an array of nodes
* Node.firstChild - same as Node.childNodes[0]
* Node.lastChild - same as Node.childNodes[Node.childNodes.length-1]
* Node.previousSibling
* Node.nextSibling

You can also search for child (including all descendants) using one of the following methods:

* Node.getElementsByTagName("tag-name") - returns an array of element nodes having the tag name '''tag-name''' that are descendants of Node
* Node.getElementById("id") - returns a single node having the ID '''id''' that is a descendant of Node
* Node.getElementsByName("what-name") - returns an array of element nodes having their '''name''' attribute set to '''what-name'''. Useful for radio buttons and other form elements.
* Node.getElementsByClassName("class") - returns an array of nodes having the class '''class'''
*: '''Note:''' As of October 2012, 82% of the browser market supports Node.getElementsByClassName ([http://caniuse.com/getelementsbyclassname more info]). In order to support the other 18%, you need to either add your own getElementsByClassName to Node's prototype or use a JavaScript library like jQuery or MooTools.

It is common in JavaScript to have long statements like the one in the example above, where you call methods on several objects in sequence.

=== Creating, Moving, and Removing Nodes ===

You will frequently find yourself wanting to modify the DOM. JavaScript provides methods that help you do this.

Consider the same HTML as above. If you wanted to add another element to the list, you could use this code:

<source lang="javascript">
var newLi = document.createElement("li"); // creates a node with the tag name li
newLi.appendChild(document.createTextNode("Broccoli"));
newLi.setAttribute("class", "veggies");
document.getElementById("my-list").appendChild(newLi);
</source>

If you wanted to remove the apples from the list, you could do:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").removeChild(apple);
</source>

If you wanted to move the apples to the end of the list, you could do this:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").appendChild(apple);
</source>

Notice that '''Node.append()''' both removes a node from its previous location ''and'' appends it to its new location, which is always going to be as the last child of the parent node.

In summary, here are the methods to know from this section:

* Node.append(otherNode) - removes otherNode from its current location in the DOM (if applicable) and then adds it as the last child of Node
* Node.removeChild(otherNode) - removes otherNode, a child of Node, from the DOM
* document.createElement("tag-name") - create a new node with the tag name "tag-name"
* document.createTextNode("text") - create a node containing only the string '''text'''
* Node.setAttribute("attribute", "value") - sets the attribute node of name "attribute" to "value"

=== DOM Shortcuts ===

In the above sections, we have been creating, reading, modifying, and deleting Nodes. This is the most "correct" way to change the content of a web page from inside JavaScript.

This section documents a few shortcuts that are not as "pure" as using Nodes but can be less confusing and cumbersome.

{{JSFiddleExample
|title=Displaying Information
|fiddle_id=Q3BPZ
|desc=This example shows how to use some of the shortcut methods for using JavaScript to display information on the page.
}}

==== textContent ====

Using textContent to display information is probably the easiest method out there. For example, the following code overwrites whatever is in the element with ID "holder" with the string "Hello World":

<source lang="javascript">
document.getElementById("holder").textContent = "Hello World";
</source>

If you wanted to instead append the text, simply use '''+=''' instead of '''=''':

<source lang="javascript">
document.getElementById("holder").textContent += " - Later, he said Hello World - ";
</source>

Note that textContent displays strings literally; that is, it does not allow for HTML. Setting the textContent property also removes any HTML that may have already been in that element.

==== innerHTML ====

If you need to use HTML in your output but don't want to use the method described earlier in this section, a straightforward strategy is to use the innerHTML property of an element. For example, the following code would add a paragraph saying "Hello World" to the element with ID "holder":

<source lang="javascript">
document.getElementById("holder").innerHTML += "<p>Hello World</p>";
</source>

'''Important:''' You need to be careful to prevent XSS-type attacks if you display information using innerHTML. For example, be sure to escape a user-supplied string before appending it to innerHTML.

=== JavaScript Inspectors ===

{{DoctypeTV
|youtube_id=PKzrmbN-pMg
|time=4m13s
|desc=Using Firebug, WebKit Inspector, and IE Developer Tools
}}

Various browsers and browser plugins give you, the developer, tools to debug your code, inspect the DOM, and much more. Using these tools is essential for an efficient workflow.

* '''Firebug'''. Firebug is a plugin for Firefox that is a toolkit full of web developer tools, one of which is a DOM inspector. To inspect the DOM of a web page, simply open the Firebug window while viewing the web page.
* '''WebKit Inspector'''. The WebKit Inspector, which is available in both Chrome and Safari, enables you to see the DOM tree and relationships between elements. However, its DOM inspection tools are not as robust as those of Firebug.
* '''Opera Dragonfly'''. The web browser Opera comes with a web developer toolkit similar to the WebKit Inspector called Dragonfly. It is important that you test your sites in Opera, because although Opera has only a small fraction of the desktop browser market, it is second only to WebKit on the mobile market. Opera also has extremely strong CSS support, so it is good for testing for bugs in your CSS.

All of the above-mentioned tools enable you to look at the DOM of your web page and find what properties and methods are associated with each node. This is helpful because if you have JavaScript that manipulates HTML elements, you cannot tell which properties are associated with which elements by looking at the source code alone.

[[Category:Module 6]]

JavaScript

2015-01-09T09:21:23Z

Shane: /* Event Handlers and Memory Management */

JavaScript is the most widely used scripting language for implementing client-side functionality in Web applications. Unlike PHP, JavaScript code is interpreted and executed in a client's web browser (not on the web server).

== JavaScript? Did you mean Java? ==

'''JavaScript''' is a prototype-based programming language focussed on web interactivity. It was first introduced in Netscape Navigator, and it in turn gave rise to what is now '''[http://www.ecmascript.org/ ECMAScript]'''. Originally, JavaScript was called "LiveScript". Sun, the developer of Java at the time, wanted a language that would complement its compiled Java language, and so LiveScript was renamed JavaScript.

Beyond that, '''Java and JavaScript are as similar as Ham and Hamster.'''

Java and JavaScript have similar syntax, but the under workings are quite different. For example, Java requires strict typing, but JavaScript allows for dynamic typing. Java is object-oriented, but JavaScript is prototype-oriented. Java is compiled, but JavaScript is interpreted. Java supports event listeners, but JavaScript makes them a fundamental part of the language. Java variables are scoped to the innermost method or loop, but JavaScript variables are scoped only to the innermost function.

== JavaScript Language Components ==

This section highlights some features of the JavaScript language that differentiate it from other languages. For a more comprehensive JavaScript tutorial, the following tutorials are both quality:

* [http://docs.webplatform.org/wiki/javascript WebPlatform]: Great for learning JavaScript for the first time. Advocates best practices for modern JavaScript development.
* [http://www.quirksmode.org/js/contents.html QuirksMode]: More advanced than the WebPlatform tutorial, but it thoroughly covers the most powerful aspects of pure JavaScript and gives unparalleled advice on browser compatibility.

Advice: Do '''NOT''' Google for "JavaScript Tutorial". The first few hits advocate bad or outdated practices. Stick with the ones listed here.

=== Variables and Scope ===

To define a variable in JavaScript, use the '''var''' keyword.

<source lang="javascript">
var foo = "bar";
</source>

All variables are objects. In the case above, the variable '''foo''' is an object of the class '''String'''.

Notice that like PHP, you do not have to explicitly define a type for a variable like '''int''' or '''String'''; this is because JavaScript and PHP are ''dynamically typed languages''.

JavaScript code can access any variable higher in the “function tree”, but not vice-versa. This is called '''scope'''. ''All functions create their own scope.''

When you reference a variable, JavaScript will look up through the "function tree" until it finds the variable you asked for. This means that you could define variables of the same name as global variables inside of functions. For demonstration of concept:

<source lang="javascript">
var a = "hello";
var b = "world";

function sayGoodByeWorld(){
var a = "goodbye";

alert(a); // goodbye
alert(b); // world
}

sayGoodByeWorld();

alert(a); // hello
</source>

=== Object Literals ===

A very common way of storing and transporting data in JavaScript is by using objects. You can define an object with certain properties using an '''object literal''':

<source lang="javascript">
var apple = {
color: "red",
flavor: "sweet",
season: "autumn"
}

alert(apple.color); // red
</source>

=== Functions ===

To define a function in JavaScript, use the '''function''' keyword.

<source lang="javascript">
function sayHello(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Pass an argument to a function like this:

<source lang="javascript">
function sayHello(name){
alert("Hello, "+name);
}

sayHello("Todd"); // call the function and pass an argument
</source>

==== Functions are Objects ====

In JavaScript, functions are objects. This means that they can be assigned to variables, manipulated on the fly, and even passed as arguments to other functions! '''''This is an extremely important feature of JavaScript''''' that makes it such a robust language for web development.

You create a function variable like this:

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Observe that you can make [[#Variables and Scope|scope-dependent]] functions in this way.

=== Closures ===

{{DoctypeTV
|youtube_id=HaPlj796ngQ
|time=5m45s
|desc=JavaScript Closures
}}

A '''closure''' is a way to separate a certain snippet of JavaScript code from the global scope. This is useful if you do not want to "muck up" global variables. Closures are nothing more than anonymous functions that are called as soon as they are created:

<source lang="javascript">
var a = "hello";

(function(){
var b = "world";

alert(a); // hello
alert(b); // world
})();

alert(a); // hello
alert(b); // ReferenceError: b is not defined
</source>

{{JSFiddleExample
|title=Passing Variables to a Closure
|desc=This example demonstrates how you can "save" previous versions of a variable using closures. This is possible because of scoping and the fact that function variables can be returned as objects.
|fiddle_id=YURqa
}}

Most JavaScript libraries (like jQuery) write all of their code in a closure. What this means is that except for one or two variable names (jQuery or $), everything associated with the library is completely self-contained.

=== Prototypal Inheritance ===

JavaScript implements '''prototypal inheritance''', as opposed to a language like Java or C++, which implements '''classical inheritance'''. JavaScript is one of only a handful of languages implementing prototype-based inheritance.

Here's how it works. Every callable object (function) has a '''prototype'''. When instances of that object are created, their properties and methods are copied (inherited) from the prototype. Additionally, changes made to the prototype later in the program are "copied" to every instance.

For example, if you wanted to make a method on all strings that added a “!”, you could modify String’s prototype:

<source lang="javascript">
String.prototype.bang = function(){
return this+"!"; // Notice: the context is the instance itself
}

alert("Hello".bang()); // alerts Hello!
</source>

To "extend" an object, just copy its prototype to a new object. However, since classical inheritance and prototypal inheritance are different concepts, copying prototypes may have results that you don't expect. [http://beej.us/blog/data/javascript-prototypes-inheritance/ This article] seems to have a pretty good explanation with example implementations.

=== Context ===

{{DoctypeTV
|youtube_id=0a4r4bm1nQA
|time=4m32s
|desc=The ''this'' Variable in JavaScript
}}

Every function is called on a certain object, which is not necessarily the same object in which it was defined. This is called '''context'''.

To call a function on an arbitrary context, use either '''call''' or '''apply'''. ''call'' takes a list of arguments, while ''apply'' takes them all in an array.

To access the current context, use the '''this''' keyword. Demonstration of concept:

<source lang="javascript">
var sayThisColor = function(){
alert(this.color);
}

var apple = { color: "red" }

sayThisColor(); // undefined
sayThisColor.call(apple); // red
</source>

== Events ==

Events are really what make JavaScript such a powerful language for web development.

Rather than being thread based, JavaScript is event based. Since all JavaScript code runs in a single thread, '''there are no concurrency issues'''. When an event occurs, JavaScript automatically calls the ''event callback'' as soon as all previous events' callbacks have finished executing.

Code in the form of a '''callback function''' is associated with events via a '''listener'''. For example, the following JavaScript causes ''sayHello()'' (the callback function) to be run whenever the button with ID "hello" is clicked (the event):

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

document.getElementById("hello").addEventListener("click", sayHello, false);
</source>

{{JSFiddleExample
|title=Binding Callbacks to a Button Click
|fiddle_id=L8c4Z
|cse330=true
|desc=In this example, notice how we bind the callback function when the ''DOMContentLoaded'' event fires. This is because JavaScript requires that the button has been parsed by the browser before it can add event listeners to it.
}}

The '''addEventListener''' method takes three parameters:
* The event type
* The callback function
*: The callback function is passed one parameter: the event object.
* A boolean representing bubble (false) or capture (true) phase
*: You usually want Bubble phase. For more information on event phase, see [[#Event Phase]]

Note that versions of Internet Explorer prior to version 9 required that you use a different, albeit similar, function for assigning event listeners called '''attachEvent'''. attachEvent takes the same arguments as addEventListener, except you need to put '''on''' before the event type (e.g. "onclick"), and the third argument (phase) is not necessary.

It is perfectly valid to use an '''anonymous function''' as your callback function:

<source lang="javascript">
document.getElementById("hello").addEventListener("click", function(event){
alert("Hello, World! Event Type: "+event.type);
}, false);
</source>

QuirksMode has perhaps the best series of articles about the ins and outs of JavaScript events on the internet: http://www.quirksmode.org/js/contents.html#events

=== The Event Object ===

Callback functions are passed one argument: an ''event object''. You see above that one property of the event object is ''event.type''. To see the full list of properties of the event object, you could run the code:

<source lang="javascript">
document.getElementById("my_btn").addEventListener("click", function(event){
var strout = "";
for(var i in event){
strout += i + ": " + event[i] + "\n";
}
console.log(strout);
}, false);
</source>

Some of the most useful properties and methods include:
* '''event.target''' references the object on which the event occurred.
* '''event.currentTarget''' references the object whose listener is currently being processed.
*: ''Note:'' event.target and event.currentTarget might be the same or might be different, depending on whether you are listening for bubbled events.
* '''event.preventDefault()''' stops the normal result of the event from being executed. For example, if you listen for a form's ''submit'' event, you can call event.preventDefault() to stop the form from being submitted.
* '''event.stopPropagation()''' prevents any other event listeners from being executed. For more detail, read the section on Event Phase below.

For more detail on the event object, see [http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#interface-Event the W3C specification].

'''Note:''' If your callback function does not take any parameters, it will still run; you just won't have as easy of access to the event object.

=== Event Handlers and Memory Management ===

JavaScript is an automatically garbage-collected language, meaning that memory management is mostly taken care of for you. However, there are some instances when you need to be careful about creating "zombie" objects. One common "gotcha" instance of this is in event listeners.

For example, consider the code:

<source lang="javascript">
// Declare an object
var myObject = {
fn: function(event) {
alert("Hello World");
}
};

// Make a property of that object listen for some event
document.getElementById("my-div").addEventListener("click", myObject.fn, false);
</source>

In the above example, myObject will ''not'' be garbage collected, even if it goes out of scope, so long as its property ''fn'' is a listener for an event on the div. In order to release myObject from memory, you need o do the following:

<source lang="javascript">
// If we want myObject to be garbage collected when it leaves scope, we need to remove the event listener.
document.getElementById("my-div").removeEventListener("click", myObject.fn, false);
</source>

The moral of the story is that for every "addEventListener", there should probably be a "removeEventListener".

For more information on memory leaks in JavaScript, read this article: http://www.vladalexandruionescu.com/2012/08/javascript-memory-leaks.html

=== Event Phase ===

In JavaScript, events occur in two phases: '''Capture Phase''' and '''Bubble Phase'''. Consider the following HTML document:

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head><title>Event Test</title></head>
<body>
<div id="box">
<button id="btn">
Hello
</button>
</div>
</body>
</html>
</source>

Suppose the user clicks on the "Hello" button. Events will be fired in the following order:

# Capture Phase CLICK on the Document
# Capture Phase CLICK on the Body
# Capture Phase CLICK on the Div#box
# Target Phase CLICK on the Button#btn
# Bubble Phase CLICK on the Div#box
# Bubble Phase CLICK on the Body
# Bubble Phase CLICK on the Document

{{JSFiddleExample
|title=Using Capture Phase to Enable or Disable a Toolbar
|fiddle_id=r32Dz
|desc=We bind an event in the capture phase to the div with ID ''toolbar''. When ''e.stopPropagation()'' is called, the event does not reach the buttons in the toolbar.
}}

Graphically, here is the order in which an event occurs in three generic nested elements:

[[File:EventPhase.gif]]

Why is this useful? Suppose you have a control panel (toolbar, etc) that you want to temporarily deactivate. (For example, Bold/Italic/Underline buttons on a graphic text editor that currently has no content.) You could keep bubble phase event listeners on your buttons, but prevent those events from occurring by stopping the event in the capture phase on the parent element before the event reaches your buttons! Example:

<source lang="javascript">
var disableToolbarFunc = function(e){
e.stopPropogation();
}

// To disable toolbar:
document.getElementById("box").addEventListener("click", disableToolbarFunc, true);

// To re-enable toolbar:
document.getElementById("box").removeEventListener("click", disableToolbarFunc, true);
</source>

'''Word of caution:''' Like many great things in web development, capture phase does not work in versions of Internet Explorer prior to version 9. There is no elegant substitution for older versions of Internet Explorer.

'''Note:''' When the event reaches the innermost element, there is no distinction between capture phase and bubble phase. The order in which event handlers were added to the element determines the order in which those callbacks are evaluated.

== Document Object Model ==

The '''Document Object Model (DOM)''' is what enables JavaScript to manipulate the content of your web page.

=== Nodes and Traversing the DOM ===

Each element on your page, whether it is a <nowiki><p>, <img/></nowiki>, a string of text, or even an attribute, is called a '''node'''.

Every node, except for the document itself, has exactly one parent. A single node may have multiple children.

Consider the following HTML code:

<source lang="html4strict">
<ul id="my-list">
<li class="fruits">Apples</li>
<li class="citrus">Oranges and <strong>Lemons</strong></li>
<li class="berries">Cherries</li>
</ul>
</source>

Here, the ul with ID "my-list" has three child '''element nodes''' (the three li's) as well as four child '''text nodes''' (the whitespace counts as a text node) and a child '''attribute node'''. The second LI has one child '''text node''' as well as one child '''element node''' and one child '''attribute node'''.

The DOM can be traversed in JavaScript. First, let's look at an example.

<source lang="javascript">
e = document.getElementById("my-list").getElementsByClassName("citrus")[0].lastChild.nodeName;
alert(e);
</source>

{{JSFiddleExample
|title=Currently Selected Radio Button
|fiddle_id=SHcng
|desc=In pure JavaScript, in order to determine the currently selected radio button, it is necessary to iterate over an array of pointers to all possible radio buttons, and stop when you find one that is "checked".
}}

The above snippet gets the element with class name '''citrus''' that is a child of the element with ID '''my-list''' (the second LI in the example above), and alerts the type of its second child node (which in this case is '''STRONG''').

Some common methods for traversing the DOM include:

* Node.parentNode
* Node.childNodes - returns an array of nodes
* Node.firstChild - same as Node.childNodes[0]
* Node.lastChild - same as Node.childNodes[Node.childNodes.length-1]
* Node.previousSibling
* Node.nextSibling

You can also search for child (including all descendants) using one of the following methods:

* Node.getElementsByTagName("tag-name") - returns an array of element nodes having the tag name '''tag-name''' that are descendants of Node
* Node.getElementById("id") - returns a single node having the ID '''id''' that is a descendant of Node
* Node.getElementsByName("what-name") - returns an array of element nodes having their '''name''' attribute set to '''what-name'''. Useful for radio buttons and other form elements.
* Node.getElementsByClassName("class") - returns an array of nodes having the class '''class'''
*: '''Note:''' As of October 2012, 82% of the browser market supports Node.getElementsByClassName ([http://caniuse.com/getelementsbyclassname more info]). In order to support the other 18%, you need to either add your own getElementsByClassName to Node's prototype or use a JavaScript library like jQuery or MooTools.

It is common in JavaScript to have long statements like the one in the example above, where you call methods on several objects in sequence.

=== Creating, Moving, and Removing Nodes ===

You will frequently find yourself wanting to modify the DOM. JavaScript provides methods that help you do this.

Consider the same HTML as above. If you wanted to add another element to the list, you could use this code:

<source lang="javascript">
var newLi = document.createElement("li"); // creates a node with the tag name li
newLi.appendChild(document.createTextNode("Broccoli"));
newLi.setAttribute("class", "veggies");
document.getElementById("my-list").appendChild(newLi);
</source>

If you wanted to remove the apples from the list, you could do:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").removeChild(apple);
</source>

If you wanted to move the apples to the end of the list, you could do this:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").appendChild(apple);
</source>

Notice that '''Node.append()''' both removes a node from its previous location ''and'' appends it to its new location, which is always going to be as the last child of the parent node.

In summary, here are the methods to know from this section:

* Node.append(otherNode) - removes otherNode from its current location in the DOM (if applicable) and then adds it as the last child of Node
* Node.removeChild(otherNode) - removes otherNode, a child of Node, from the DOM
* document.createElement("tag-name") - create a new node with the tag name "tag-name"
* document.createTextNode("text") - create a node containing only the string '''text'''
* Node.setAttribute("attribute", "value") - sets the attribute node of name "attribute" to "value"

=== DOM Shortcuts ===

In the above sections, we have been creating, reading, modifying, and deleting Nodes. This is the most "correct" way to change the content of a web page from inside JavaScript.

This section documents a few shortcuts that are not as "pure" as using Nodes but can be less confusing and cumbersome.

{{JSFiddleExample
|title=Displaying Information
|fiddle_id=Q3BPZ
|desc=This example shows how to use some of the shortcut methods for using JavaScript to display information on the page.
}}

==== textContent ====

Using textContent to display information is probably the easiest method out there. For example, the following code overwrites whatever is in the element with ID "holder" with the string "Hello World":

<source lang="javascript">
document.getElementById("holder").textContent = "Hello World";
</source>

If you wanted to instead append the text, simply use '''+=''' instead of '''=''':

<source lang="javascript">
document.getElementById("holder").textContent += " - Later, he said Hello World - ";
</source>

Note that textContent displays strings literally; that is, it does not allow for HTML. Setting the textContent property also removes any HTML that may have already been in that element.

==== innerHTML ====

If you need to use HTML in your output but don't want to use the method described earlier in this section, a straightforward strategy is to use the innerHTML property of an element. For example, the following code would add a paragraph saying "Hello World" to the element with ID "holder":

<source lang="javascript">
document.getElementById("holder").innerHTML += "<p>Hello World</p>";
</source>

'''Important:''' You need to be careful to prevent XSS-type attacks if you display information using innerHTML. For example, be sure to escape a user-supplied string before appending it to innerHTML.

=== JavaScript Inspectors ===

{{DoctypeTV
|youtube_id=PKzrmbN-pMg
|time=4m13s
|desc=Using Firebug, WebKit Inspector, and IE Developer Tools
}}

Various browsers and browser plugins give you, the developer, tools to debug your code, inspect the DOM, and much more. Using these tools is essential for an efficient workflow.

* '''Firebug'''. Firebug is a plugin for Firefox that is a toolkit full of web developer tools, one of which is a DOM inspector. To inspect the DOM of a web page, simply open the Firebug window while viewing the web page.
* '''WebKit Inspector'''. The WebKit Inspector, which is available in both Chrome and Safari, enables you to see the DOM tree and relationships between elements. However, its DOM inspection tools are not as robust as those of Firebug.
* '''Opera Dragonfly'''. The web browser Opera comes with a web developer toolkit similar to the WebKit Inspector called Dragonfly. It is important that you test your sites in Opera, because although Opera has only a small fraction of the desktop browser market, it is second only to WebKit on the mobile market. Opera also has extremely strong CSS support, so it is good for testing for bugs in your CSS.

All of the above-mentioned tools enable you to look at the DOM of your web page and find what properties and methods are associated with each node. This is helpful because if you have JavaScript that manipulates HTML elements, you cannot tell which properties are associated with which elements by looking at the source code alone.

[[Category:Module 6]]

Getting MEAN

2015-01-07T12:28:34Z

Shane: /* What did all that mean? */

=Installation=
To install MEAN, make sure you already have all of the following components installed and configured correctly.
<br/>
'''1. Node.js''' (should come with npm) <br/>
To find out if you have node and npm, try checking their versions (may not be the same):
<source lang="bash">
node --version
v0.10.25
npm --version
1.3.24
</source>

IF you don't have node.js, install it [http://nodejs.org/ here].

'''2. Bower'''

Bower is a web application manager used by MEAN. To install bower, type the following command in your terminal:
<source lang="bash">npm install -g bower</source>

'''3. MongoDB'''
To install MongoDB, follow the instructions for your OS [http://docs.mongodb.org/manual/installation/ here].

'''4. Grunt'''
To install Grunt type the following command:
<source lang="bash">npm install -g grunt-cli</source>

'''5. and finally, MEAN'''
In your terminal, type:
<source lang="bash"> > sudo npm install -g mean-cli </source>

* MEAN stack documentations are available [http://mean.io/#!/docs here]. They'll help you to get familiar with the file structure and idioms.

== What did all that mean? ==

You just installed four different command line tools. Here's what they all do.

* '''npm''' is the package manager for Node.JS. It installs libraries for use by your Node.JS applications. The configuration file for ''npm'' (the list of packages for ''npm'' to install) is ''package.json''.
* '''bower''' is a package manager for front-end libraries. Rather than manually downloading your jQuery, Bootstrap, Angular, and other front-end JavaScript and CSS (and remembering to update them when a new version of one of those libraries comes out), ''bower'' installs them for you. The configuration file for ''bower'' (the list of packages for ''bower'' to install) is ''bower.json''.
* '''grunt''' is a build tool designed for JavaScript. It's like ''make'' or ''ant'', but for JavaScript. The configuration file for ''grunt'' (the list of commands to run when building your project) is ''Gruntfile.js'' (a name inspired by the ''Makefile'' for ''make'', the dominant C and C++ build tool).
* '''mean''' is a utility designed to help you carry out routine tasks associated with developing for the MEAN stack.

Don't be confused by the fact that you use ''npm'' to install ''bower'', ''grunt'', and ''mean''. The people who made ''bower'', ''grunt'', and ''mean'' just all decided to use ''npm'' as the place to publish their projects, probably because the executables themselves are written in Node.JS. They could just as well have chosen ''apt-get'' or ''yum'' or any of the other package managers you've been using in this class.

=Running the Default App =
* Init and run an app.
<source lang="bash">
> mean init myApp // create your first app
> cd myApp
> npm install // Install dependencies
> grunt // Launch mean
</source>
Make sure MongoDB is connected and running (if you run into problems, refer to the section on MongoDB)

* Go ahead and explore features of the default Article app (such as logging in, adding/deleting articles).

=Generating a Package =
* By now you should know what a package is in MEAN. If you don't, read [http://learn.mean.io/#mean-io-packages this].

* Try creating a package named myPackage by typing:
<source lang="bash">
> mean package myPackage
</source>
Locate it inside the packages folder:
* Compare the structure of myPackage folder to that of the default app. Make sure you see both '''public''' and '''server''' folders and their subfolders.
* Restart your app, make sure you can see a link to the newly created package.

=A Closer Look at the App =
Take a look at the directory where you app resides, you will see two folders '''public''' and '''server''', which contain code for the client side and server side respectively.

== Models ==

Open up article.js in /server/models

MEAN is MVC on the client side and the server side. Since the model is tied to the backend to MongoDB, you will only see the models folder on the server side, which is normal.
The models are mongoose models that's why we need to require mongoose (what the following line does):

<source lang="javascript">
var mongoose = require('mongoose'), Schema = mongoose.Schema;
</source>
The following part then defines the schema:
<source lang="javascript">
var ArticleSchema = new Schema({
created: {
type: Date,
default: Date.now
},
title: {
type: String,
default: '',
trim: true
},
content: {
type: String,
default: '',
trim: true
},
user: {
type: Schema.ObjectId,
ref: 'User'
}
});
</source>
The next part is validations, or criteria an object needs to pass before it can be saved to the DB.
The following code is to make sure that an article has a title:
<source lang="javascript">
ArticleSchema.path('title').validate(function(title) {
return title.length;
}, 'Title cannot be blank');
</source>

Finally, Mongoose allows us to define methods to our data objects as well.
These are called statics. From the Mongoose doc: Schemas not only define the structure of your document and casting of properties, they also define document instance methods, static Model methods, compound indexes and document lifecycle hooks called middleware.
The following code defines a method called load for the article schema:
<source lang="javascript">
ArticleSchema.statics.load = function(id, cb) {
this.findOne({
_id: id
}).populate('user', 'name username').exec(cb);
};
</source>

If you have trouble understanding what the code does, review the Mongoose [http://mongoosejs.com/docs/index.html quick start] guide.

=== Models Practice ===
Define a schema for a model named '''Phone''', name it phone.js and save it in the corresponding folder in 'myPackage' (hint: /packages/myPackage/server/models/)
A product needs to have the following fields with specific types. Here is an example of a Phone object can be stored in the MongoDB:
<source lang="javascript">
{
"age": 0,
"id": "motorola-xoom-with-wi-fi",
"imageUrl": "img/phones/motorola-xoom-with-wi-fi.0.jpg",
"name": "Motorola XOOM\u2122 with Wi-Fi",
"snippet": "The Next, Next Generation\r\n\r\nExperience the future with Motorola XOOM wi.. d by Android 3.0 (Honeycomb)."
}
</source>

This is taken from phones.json used by the AngularJS tutorial. If you have gone through the tutorial, you should have realized that instead of using a DB, json files were used to simplify the tutorial.
Find phones.json in /app/phones in the angular tutorial folder and try importing its content to MongoDB so you can use them in your current MEAN package.
<br/> Here is how (assuming mongod is running):

<source lang="bash">
> mongo --shell // connect to mongo shell
> use mean-dev // switches to database used by mean.
> mongoimport --db mean-dev --collection phones --type json --file ''<path to phones.json>'' --jsonArray // imports json file to the DB
> show collections // check to see if phones are added to your database
> coll = db.phones // to see the content of the file
</source>

== Controllers ==

You'll find a controllers folder on both the server side and the client (public) side.
* The client side controllers are part of the Angular MVC scheme that contains client side logic and may issue requests to the server.
* The server side controllers deal with the models and requests from the client side.

'''Server side:'''

* Find articles.js in the controllers folder. Try to understand what each part does.

'''Client side:''' open up articles.js in /articles/public/controllers
Compare the functions defined in ArticlesController, can you find the server side implementation of corresponding functions?

Here is a diagram to help you understand how this works:

[[File:Mean.png]]

== Views & Routing ==
Even though typically views are implemented and used for the client end, routing happens on both ends.

* Find articles.js in /server/routes
You'll see that it requires the articles controller and its methods for querying the database.

The first section requires the articles controller, which defines different methods

For example, code below tells the server to use a method named "all" in the articles controller when the url is pointed to /articles:

<source lang="javascript">
app.route('/articles')
.get(articles.all)
</source>

*Go to http://localhost:3000/articles, what do you see? Does it make sense?

Let's switch to the public folder where the views reside. Go to articles/public/views, open up list.html: <br/>
The first line tells the framework that ArticlesController is responsible for this particular view and when this view is loaded, use find() to initiate data binding.
<source lang="html4strict">
<section data-ng-controller="ArticlesController" data-ng-init="find()">
</source>

Feel free to take a look at what find() does. Make sure you understand that what find() does is actually done by the backend, where a corresponding find() is written (as mentioned above).
Hopefully you have a better understanding of how these technologies all work together now.

Review the AngularJS section if you have any questions regarding the view data binding.

The view files in articles/views only defines the code for displaying the articles, where does the navigation bar gets defined.
The answer is in /public/system.
*The .html files in public/system/views provide a container/layout for the application.
For example, header.html includes the menu bar (displayed on the top of the page):

<source lang="html4strict">
<div class="left pull-left">
<ul class="navbar-nav nav">
<li data-ng-repeat="item in menus.main" ui-route="/{{item.link}}" ng-class="{active: $uiRoute}">
<a mean-token="item.link" ui-sref='{{item.link}}'>{{item.title}}</a>
</li>
</ul>
</div>
</source>

* Try changing <nowiki>{{item.title}} </nowiki> inside the <a> </a>tags to "my articles" see what happens to the page.
* The ui-sref is "href" in ui-route, an AngularJS plugin, try changing <nowiki>{{item.link}}</nowiki> to #!/myarticles,
* What happens to the application now? When you click on "my articles"?

The page to articles is no longer served!

But how does the framework know which page to serve given a certain url? The file responsible for this (called routing in web development) is in public/articles/routes

open up articles.js in this folder and find the line that specifies the routing scheme for /articles:
<source lang="javascript">

.state('all articles', {
url: '/articles',
templateUrl: 'public/articles/views/list.html',
resolve: {
loggedin: checkLoggedin
}
}
</source>

This is ui-route's way of telling the server what to serve the page specified by the templateUrl when it sees "localhost:3000/#!/phones".
The #! is a hash prefix used for MEAN to make ajax calls so make sure to include it when coding your views.
Now try changing the url to "/myarticles", save and go back to your app, click on "my articles" now, what happens?

*This is important if you want to customize your navigation bar and links. Just remember that each url needs an entry in the route file, in the format of the example above.

= Practice =

Can you implement a view in your myPackage to display all phones injected in the DB?
Hint: myPackage has the same file structure as the default app.

Getting MEAN

2015-01-07T12:26:41Z

Shane: /* What did all that mean? */

=Installation=
To install MEAN, make sure you already have all of the following components installed and configured correctly.
<br/>
'''1. Node.js''' (should come with npm) <br/>
To find out if you have node and npm, try checking their versions (may not be the same):
<source lang="bash">
node --version
v0.10.25
npm --version
1.3.24
</source>

IF you don't have node.js, install it [http://nodejs.org/ here].

'''2. Bower'''

Bower is a web application manager used by MEAN. To install bower, type the following command in your terminal:
<source lang="bash">npm install -g bower</source>

'''3. MongoDB'''
To install MongoDB, follow the instructions for your OS [http://docs.mongodb.org/manual/installation/ here].

'''4. Grunt'''
To install Grunt type the following command:
<source lang="bash">npm install -g grunt-cli</source>

'''5. and finally, MEAN'''
In your terminal, type:
<source lang="bash"> > sudo npm install -g mean-cli </source>

* MEAN stack documentations are available [http://mean.io/#!/docs here]. They'll help you to get familiar with the file structure and idioms.

== What did all that mean? ==

You just installed four different command line tools. Here's what they all do.

* '''npm''' is the package manager for Node.JS. It installs libraries for use by your Node.JS applications. The configuration file for ''npm'' (the list of packages for ''npm'' to install) is ''package.json''.
* '''bower''' is a package manager for front-end libraries. Rather than manually downloading your jQuery, Bootstrap, Angular, and other front-end JavaScript and CSS (and remembering to update them when a new version of one of those libraries comes out), ''bower'' installs them for you. The configuration file for ''bower'' (the list of packages for ''bower'' to install) is ''bower.json''.
* '''grunt''' is a build tool designed for JavaScript. It's like ''make'' or ''ant'', but for JavaScript. The configuration file for ''grunt'' (the list of commands to run when building your project) is ''Gruntfile.js''.
* '''mean''' is a utility designed to help you carry out routine tasks associated with developing for the MEAN stack.

Don't be confused by the fact that you use ''npm'' to install ''bower'', ''grunt'', and ''mean''. The people who made ''bower'', ''grunt'', and ''mean'' just all decided to use ''npm'' as the place to publish their projects, probably because the executables themselves are written in Node.JS. They could just as well have chosen ''apt-get'' or ''yum'' or any of the other package managers you've been using in this class.

=Running the Default App =
* Init and run an app.
<source lang="bash">
> mean init myApp // create your first app
> cd myApp
> npm install // Install dependencies
> grunt // Launch mean
</source>
Make sure MongoDB is connected and running (if you run into problems, refer to the section on MongoDB)

* Go ahead and explore features of the default Article app (such as logging in, adding/deleting articles).

=Generating a Package =
* By now you should know what a package is in MEAN. If you don't, read [http://learn.mean.io/#mean-io-packages this].

* Try creating a package named myPackage by typing:
<source lang="bash">
> mean package myPackage
</source>
Locate it inside the packages folder:
* Compare the structure of myPackage folder to that of the default app. Make sure you see both '''public''' and '''server''' folders and their subfolders.
* Restart your app, make sure you can see a link to the newly created package.

=A Closer Look at the App =
Take a look at the directory where you app resides, you will see two folders '''public''' and '''server''', which contain code for the client side and server side respectively.

== Models ==

Open up article.js in /server/models

MEAN is MVC on the client side and the server side. Since the model is tied to the backend to MongoDB, you will only see the models folder on the server side, which is normal.
The models are mongoose models that's why we need to require mongoose (what the following line does):

<source lang="javascript">
var mongoose = require('mongoose'), Schema = mongoose.Schema;
</source>
The following part then defines the schema:
<source lang="javascript">
var ArticleSchema = new Schema({
created: {
type: Date,
default: Date.now
},
title: {
type: String,
default: '',
trim: true
},
content: {
type: String,
default: '',
trim: true
},
user: {
type: Schema.ObjectId,
ref: 'User'
}
});
</source>
The next part is validations, or criteria an object needs to pass before it can be saved to the DB.
The following code is to make sure that an article has a title:
<source lang="javascript">
ArticleSchema.path('title').validate(function(title) {
return title.length;
}, 'Title cannot be blank');
</source>

Finally, Mongoose allows us to define methods to our data objects as well.
These are called statics. From the Mongoose doc: Schemas not only define the structure of your document and casting of properties, they also define document instance methods, static Model methods, compound indexes and document lifecycle hooks called middleware.
The following code defines a method called load for the article schema:
<source lang="javascript">
ArticleSchema.statics.load = function(id, cb) {
this.findOne({
_id: id
}).populate('user', 'name username').exec(cb);
};
</source>

If you have trouble understanding what the code does, review the Mongoose [http://mongoosejs.com/docs/index.html quick start] guide.

=== Models Practice ===
Define a schema for a model named '''Phone''', name it phone.js and save it in the corresponding folder in 'myPackage' (hint: /packages/myPackage/server/models/)
A product needs to have the following fields with specific types. Here is an example of a Phone object can be stored in the MongoDB:
<source lang="javascript">
{
"age": 0,
"id": "motorola-xoom-with-wi-fi",
"imageUrl": "img/phones/motorola-xoom-with-wi-fi.0.jpg",
"name": "Motorola XOOM\u2122 with Wi-Fi",
"snippet": "The Next, Next Generation\r\n\r\nExperience the future with Motorola XOOM wi.. d by Android 3.0 (Honeycomb)."
}
</source>

This is taken from phones.json used by the AngularJS tutorial. If you have gone through the tutorial, you should have realized that instead of using a DB, json files were used to simplify the tutorial.
Find phones.json in /app/phones in the angular tutorial folder and try importing its content to MongoDB so you can use them in your current MEAN package.
<br/> Here is how (assuming mongod is running):

<source lang="bash">
> mongo --shell // connect to mongo shell
> use mean-dev // switches to database used by mean.
> mongoimport --db mean-dev --collection phones --type json --file ''<path to phones.json>'' --jsonArray // imports json file to the DB
> show collections // check to see if phones are added to your database
> coll = db.phones // to see the content of the file
</source>

== Controllers ==

You'll find a controllers folder on both the server side and the client (public) side.
* The client side controllers are part of the Angular MVC scheme that contains client side logic and may issue requests to the server.
* The server side controllers deal with the models and requests from the client side.

'''Server side:'''

* Find articles.js in the controllers folder. Try to understand what each part does.

'''Client side:''' open up articles.js in /articles/public/controllers
Compare the functions defined in ArticlesController, can you find the server side implementation of corresponding functions?

Here is a diagram to help you understand how this works:

[[File:Mean.png]]

== Views & Routing ==
Even though typically views are implemented and used for the client end, routing happens on both ends.

* Find articles.js in /server/routes
You'll see that it requires the articles controller and its methods for querying the database.

The first section requires the articles controller, which defines different methods

For example, code below tells the server to use a method named "all" in the articles controller when the url is pointed to /articles:

<source lang="javascript">
app.route('/articles')
.get(articles.all)
</source>

*Go to http://localhost:3000/articles, what do you see? Does it make sense?

Let's switch to the public folder where the views reside. Go to articles/public/views, open up list.html: <br/>
The first line tells the framework that ArticlesController is responsible for this particular view and when this view is loaded, use find() to initiate data binding.
<source lang="html4strict">
<section data-ng-controller="ArticlesController" data-ng-init="find()">
</source>

Feel free to take a look at what find() does. Make sure you understand that what find() does is actually done by the backend, where a corresponding find() is written (as mentioned above).
Hopefully you have a better understanding of how these technologies all work together now.

Review the AngularJS section if you have any questions regarding the view data binding.

The view files in articles/views only defines the code for displaying the articles, where does the navigation bar gets defined.
The answer is in /public/system.
*The .html files in public/system/views provide a container/layout for the application.
For example, header.html includes the menu bar (displayed on the top of the page):

<source lang="html4strict">
<div class="left pull-left">
<ul class="navbar-nav nav">
<li data-ng-repeat="item in menus.main" ui-route="/{{item.link}}" ng-class="{active: $uiRoute}">
<a mean-token="item.link" ui-sref='{{item.link}}'>{{item.title}}</a>
</li>
</ul>
</div>
</source>

* Try changing <nowiki>{{item.title}} </nowiki> inside the <a> </a>tags to "my articles" see what happens to the page.
* The ui-sref is "href" in ui-route, an AngularJS plugin, try changing <nowiki>{{item.link}}</nowiki> to #!/myarticles,
* What happens to the application now? When you click on "my articles"?

The page to articles is no longer served!

But how does the framework know which page to serve given a certain url? The file responsible for this (called routing in web development) is in public/articles/routes

open up articles.js in this folder and find the line that specifies the routing scheme for /articles:
<source lang="javascript">

.state('all articles', {
url: '/articles',
templateUrl: 'public/articles/views/list.html',
resolve: {
loggedin: checkLoggedin
}
}
</source>

This is ui-route's way of telling the server what to serve the page specified by the templateUrl when it sees "localhost:3000/#!/phones".
The #! is a hash prefix used for MEAN to make ajax calls so make sure to include it when coding your views.
Now try changing the url to "/myarticles", save and go back to your app, click on "my articles" now, what happens?

*This is important if you want to customize your navigation bar and links. Just remember that each url needs an entry in the route file, in the format of the example above.

= Practice =

Can you implement a view in your myPackage to display all phones injected in the DB?
Hint: myPackage has the same file structure as the default app.

Getting MEAN

2015-01-07T12:21:55Z

Shane: /* What did all that mean? */

=Installation=
To install MEAN, make sure you already have all of the following components installed and configured correctly.
<br/>
'''1. Node.js''' (should come with npm) <br/>
To find out if you have node and npm, try checking their versions (may not be the same):
<source lang="bash">
node --version
v0.10.25
npm --version
1.3.24
</source>

IF you don't have node.js, install it [http://nodejs.org/ here].

'''2. Bower'''

Bower is a web application manager used by MEAN. To install bower, type the following command in your terminal:
<source lang="bash">npm install -g bower</source>

'''3. MongoDB'''
To install MongoDB, follow the instructions for your OS [http://docs.mongodb.org/manual/installation/ here].

'''4. Grunt'''
To install Grunt type the following command:
<source lang="bash">npm install -g grunt-cli</source>

'''5. and finally, MEAN'''
In your terminal, type:
<source lang="bash"> > sudo npm install -g mean-cli </source>

* MEAN stack documentations are available [http://mean.io/#!/docs here]. They'll help you to get familiar with the file structure and idioms.

== What did all that mean? ==

You just used three different command line tools. Here's what they all do.

* '''npm''' is the package manager for Node.JS. It installs libraries for use by your Node.JS applications. The configuration file for ''npm'' (the list of packages for ''npm'' to install) is ''package.json''.
* '''bower''' is a package manager for front-end libraries. Rather than manually downloading your jQuery, Bootstrap, Angular, and other front-end JavaScript and CSS (and remembering to update them when a new version of one of those libraries comes out), ''bower'' installs them for you. The configuration file for ''bower'' (the list of packages for ''bower'' to install) is ''bower.json''.
* '''grunt''' is a build tool designed for JavaScript. It's like ''make'' or ''ant'', but for JavaScript. The configuration file for ''grunt'' (the list of commands to run when building your project) is ''Gruntfile.js''.

Don't be confused by the fact that you use ''npm'' to install ''bower'' and ''grunt''. The people who made ''bower'' and ''grunt'' just both decided to use ''npm'' as the place to publish their projects, probably because the executables themselves are written in Node.JS. They could just as well have chosen ''apt-get'' or ''yum'' or any of the other package managers you've been using in this class.

=Running the Default App =
* Init and run an app.
<source lang="bash">
> mean init myApp // create your first app
> cd myApp
> npm install // Install dependencies
> grunt // Launch mean
</source>
Make sure MongoDB is connected and running (if you run into problems, refer to the section on MongoDB)

* Go ahead and explore features of the default Article app (such as logging in, adding/deleting articles).

=Generating a Package =
* By now you should know what a package is in MEAN. If you don't, read [http://learn.mean.io/#mean-io-packages this].

* Try creating a package named myPackage by typing:
<source lang="bash">
> mean package myPackage
</source>
Locate it inside the packages folder:
* Compare the structure of myPackage folder to that of the default app. Make sure you see both '''public''' and '''server''' folders and their subfolders.
* Restart your app, make sure you can see a link to the newly created package.

=A Closer Look at the App =
Take a look at the directory where you app resides, you will see two folders '''public''' and '''server''', which contain code for the client side and server side respectively.

== Models ==

Open up article.js in /server/models

MEAN is MVC on the client side and the server side. Since the model is tied to the backend to MongoDB, you will only see the models folder on the server side, which is normal.
The models are mongoose models that's why we need to require mongoose (what the following line does):

<source lang="javascript">
var mongoose = require('mongoose'), Schema = mongoose.Schema;
</source>
The following part then defines the schema:
<source lang="javascript">
var ArticleSchema = new Schema({
created: {
type: Date,
default: Date.now
},
title: {
type: String,
default: '',
trim: true
},
content: {
type: String,
default: '',
trim: true
},
user: {
type: Schema.ObjectId,
ref: 'User'
}
});
</source>
The next part is validations, or criteria an object needs to pass before it can be saved to the DB.
The following code is to make sure that an article has a title:
<source lang="javascript">
ArticleSchema.path('title').validate(function(title) {
return title.length;
}, 'Title cannot be blank');
</source>

Finally, Mongoose allows us to define methods to our data objects as well.
These are called statics. From the Mongoose doc: Schemas not only define the structure of your document and casting of properties, they also define document instance methods, static Model methods, compound indexes and document lifecycle hooks called middleware.
The following code defines a method called load for the article schema:
<source lang="javascript">
ArticleSchema.statics.load = function(id, cb) {
this.findOne({
_id: id
}).populate('user', 'name username').exec(cb);
};
</source>

If you have trouble understanding what the code does, review the Mongoose [http://mongoosejs.com/docs/index.html quick start] guide.

=== Models Practice ===
Define a schema for a model named '''Phone''', name it phone.js and save it in the corresponding folder in 'myPackage' (hint: /packages/myPackage/server/models/)
A product needs to have the following fields with specific types. Here is an example of a Phone object can be stored in the MongoDB:
<source lang="javascript">
{
"age": 0,
"id": "motorola-xoom-with-wi-fi",
"imageUrl": "img/phones/motorola-xoom-with-wi-fi.0.jpg",
"name": "Motorola XOOM\u2122 with Wi-Fi",
"snippet": "The Next, Next Generation\r\n\r\nExperience the future with Motorola XOOM wi.. d by Android 3.0 (Honeycomb)."
}
</source>

This is taken from phones.json used by the AngularJS tutorial. If you have gone through the tutorial, you should have realized that instead of using a DB, json files were used to simplify the tutorial.
Find phones.json in /app/phones in the angular tutorial folder and try importing its content to MongoDB so you can use them in your current MEAN package.
<br/> Here is how (assuming mongod is running):

<source lang="bash">
> mongo --shell // connect to mongo shell
> use mean-dev // switches to database used by mean.
> mongoimport --db mean-dev --collection phones --type json --file ''<path to phones.json>'' --jsonArray // imports json file to the DB
> show collections // check to see if phones are added to your database
> coll = db.phones // to see the content of the file
</source>

== Controllers ==

You'll find a controllers folder on both the server side and the client (public) side.
* The client side controllers are part of the Angular MVC scheme that contains client side logic and may issue requests to the server.
* The server side controllers deal with the models and requests from the client side.

'''Server side:'''

* Find articles.js in the controllers folder. Try to understand what each part does.

'''Client side:''' open up articles.js in /articles/public/controllers
Compare the functions defined in ArticlesController, can you find the server side implementation of corresponding functions?

Here is a diagram to help you understand how this works:

[[File:Mean.png]]

== Views & Routing ==
Even though typically views are implemented and used for the client end, routing happens on both ends.

* Find articles.js in /server/routes
You'll see that it requires the articles controller and its methods for querying the database.

The first section requires the articles controller, which defines different methods

For example, code below tells the server to use a method named "all" in the articles controller when the url is pointed to /articles:

<source lang="javascript">
app.route('/articles')
.get(articles.all)
</source>

*Go to http://localhost:3000/articles, what do you see? Does it make sense?

Let's switch to the public folder where the views reside. Go to articles/public/views, open up list.html: <br/>
The first line tells the framework that ArticlesController is responsible for this particular view and when this view is loaded, use find() to initiate data binding.
<source lang="html4strict">
<section data-ng-controller="ArticlesController" data-ng-init="find()">
</source>

Feel free to take a look at what find() does. Make sure you understand that what find() does is actually done by the backend, where a corresponding find() is written (as mentioned above).
Hopefully you have a better understanding of how these technologies all work together now.

Review the AngularJS section if you have any questions regarding the view data binding.

The view files in articles/views only defines the code for displaying the articles, where does the navigation bar gets defined.
The answer is in /public/system.
*The .html files in public/system/views provide a container/layout for the application.
For example, header.html includes the menu bar (displayed on the top of the page):

<source lang="html4strict">
<div class="left pull-left">
<ul class="navbar-nav nav">
<li data-ng-repeat="item in menus.main" ui-route="/{{item.link}}" ng-class="{active: $uiRoute}">
<a mean-token="item.link" ui-sref='{{item.link}}'>{{item.title}}</a>
</li>
</ul>
</div>
</source>

* Try changing <nowiki>{{item.title}} </nowiki> inside the <a> </a>tags to "my articles" see what happens to the page.
* The ui-sref is "href" in ui-route, an AngularJS plugin, try changing <nowiki>{{item.link}}</nowiki> to #!/myarticles,
* What happens to the application now? When you click on "my articles"?

The page to articles is no longer served!

But how does the framework know which page to serve given a certain url? The file responsible for this (called routing in web development) is in public/articles/routes

open up articles.js in this folder and find the line that specifies the routing scheme for /articles:
<source lang="javascript">

.state('all articles', {
url: '/articles',
templateUrl: 'public/articles/views/list.html',
resolve: {
loggedin: checkLoggedin
}
}
</source>

This is ui-route's way of telling the server what to serve the page specified by the templateUrl when it sees "localhost:3000/#!/phones".
The #! is a hash prefix used for MEAN to make ajax calls so make sure to include it when coding your views.
Now try changing the url to "/myarticles", save and go back to your app, click on "my articles" now, what happens?

*This is important if you want to customize your navigation bar and links. Just remember that each url needs an entry in the route file, in the format of the example above.

= Practice =

Can you implement a view in your myPackage to display all phones injected in the DB?
Hint: myPackage has the same file structure as the default app.

Getting MEAN

2015-01-07T12:18:44Z

Shane: Adding explanation of npm, bower, and grunt.

=Installation=
To install MEAN, make sure you already have all of the following components installed and configured correctly.
<br/>
'''1. Node.js''' (should come with npm) <br/>
To find out if you have node and npm, try checking their versions (may not be the same):
<source lang="bash">
node --version
v0.10.25
npm --version
1.3.24
</source>

IF you don't have node.js, install it [http://nodejs.org/ here].

'''2. Bower'''

Bower is a web application manager used by MEAN. To install bower, type the following command in your terminal:
<source lang="bash">npm install -g bower</source>

'''3. MongoDB'''
To install MongoDB, follow the instructions for your OS [http://docs.mongodb.org/manual/installation/ here].

'''4. Grunt'''
To install Grunt type the following command:
<source lang="bash">npm install -g grunt-cli</source>

'''5. and finally, MEAN'''
In your terminal, type:
<source lang="bash"> > sudo npm install -g mean-cli </source>

* MEAN stack documentations are available [http://mean.io/#!/docs here]. They'll help you to get familiar with the file structure and idioms.

== What did all that mean? ==

You just used three different command line tools. Here's what they all do.

* '''npm''' is the package manager for Node.JS. It installs libraries for use by your Node.JS applications. The configuration file for ''npm'' (the list of packages for ''npm'' to install) is ''package.json''.
* '''bower''' is a package manager for front-end libraries. Rather than manually downloading your jQuery, Bootstrap, Angular, and other front-end JavaScript and CSS (and remembering to update them when a new version of one of those libraries comes out), ''bower'' installs them for you. The configuration file for ''bower'' (the list of packages for ''bower'' to install) is ''bower.json''.
* '''grunt''' is a build tool designed for JavaScript. It's like ''make'' or ''ant'', but for JavaScript. The configuration file for ''grunt'' (the list of commands to run when building your project) is ''Gruntfile.js''.

=Running the Default App =
* Init and run an app.
<source lang="bash">
> mean init myApp // create your first app
> cd myApp
> npm install // Install dependencies
> grunt // Launch mean
</source>
Make sure MongoDB is connected and running (if you run into problems, refer to the section on MongoDB)

* Go ahead and explore features of the default Article app (such as logging in, adding/deleting articles).

=Generating a Package =
* By now you should know what a package is in MEAN. If you don't, read [http://learn.mean.io/#mean-io-packages this].

* Try creating a package named myPackage by typing:
<source lang="bash">
> mean package myPackage
</source>
Locate it inside the packages folder:
* Compare the structure of myPackage folder to that of the default app. Make sure you see both '''public''' and '''server''' folders and their subfolders.
* Restart your app, make sure you can see a link to the newly created package.

=A Closer Look at the App =
Take a look at the directory where you app resides, you will see two folders '''public''' and '''server''', which contain code for the client side and server side respectively.

== Models ==

Open up article.js in /server/models

MEAN is MVC on the client side and the server side. Since the model is tied to the backend to MongoDB, you will only see the models folder on the server side, which is normal.
The models are mongoose models that's why we need to require mongoose (what the following line does):

<source lang="javascript">
var mongoose = require('mongoose'), Schema = mongoose.Schema;
</source>
The following part then defines the schema:
<source lang="javascript">
var ArticleSchema = new Schema({
created: {
type: Date,
default: Date.now
},
title: {
type: String,
default: '',
trim: true
},
content: {
type: String,
default: '',
trim: true
},
user: {
type: Schema.ObjectId,
ref: 'User'
}
});
</source>
The next part is validations, or criteria an object needs to pass before it can be saved to the DB.
The following code is to make sure that an article has a title:
<source lang="javascript">
ArticleSchema.path('title').validate(function(title) {
return title.length;
}, 'Title cannot be blank');
</source>

Finally, Mongoose allows us to define methods to our data objects as well.
These are called statics. From the Mongoose doc: Schemas not only define the structure of your document and casting of properties, they also define document instance methods, static Model methods, compound indexes and document lifecycle hooks called middleware.
The following code defines a method called load for the article schema:
<source lang="javascript">
ArticleSchema.statics.load = function(id, cb) {
this.findOne({
_id: id
}).populate('user', 'name username').exec(cb);
};
</source>

If you have trouble understanding what the code does, review the Mongoose [http://mongoosejs.com/docs/index.html quick start] guide.

=== Models Practice ===
Define a schema for a model named '''Phone''', name it phone.js and save it in the corresponding folder in 'myPackage' (hint: /packages/myPackage/server/models/)
A product needs to have the following fields with specific types. Here is an example of a Phone object can be stored in the MongoDB:
<source lang="javascript">
{
"age": 0,
"id": "motorola-xoom-with-wi-fi",
"imageUrl": "img/phones/motorola-xoom-with-wi-fi.0.jpg",
"name": "Motorola XOOM\u2122 with Wi-Fi",
"snippet": "The Next, Next Generation\r\n\r\nExperience the future with Motorola XOOM wi.. d by Android 3.0 (Honeycomb)."
}
</source>

This is taken from phones.json used by the AngularJS tutorial. If you have gone through the tutorial, you should have realized that instead of using a DB, json files were used to simplify the tutorial.
Find phones.json in /app/phones in the angular tutorial folder and try importing its content to MongoDB so you can use them in your current MEAN package.
<br/> Here is how (assuming mongod is running):

<source lang="bash">
> mongo --shell // connect to mongo shell
> use mean-dev // switches to database used by mean.
> mongoimport --db mean-dev --collection phones --type json --file ''<path to phones.json>'' --jsonArray // imports json file to the DB
> show collections // check to see if phones are added to your database
> coll = db.phones // to see the content of the file
</source>

== Controllers ==

You'll find a controllers folder on both the server side and the client (public) side.
* The client side controllers are part of the Angular MVC scheme that contains client side logic and may issue requests to the server.
* The server side controllers deal with the models and requests from the client side.

'''Server side:'''

* Find articles.js in the controllers folder. Try to understand what each part does.

'''Client side:''' open up articles.js in /articles/public/controllers
Compare the functions defined in ArticlesController, can you find the server side implementation of corresponding functions?

Here is a diagram to help you understand how this works:

[[File:Mean.png]]

== Views & Routing ==
Even though typically views are implemented and used for the client end, routing happens on both ends.

* Find articles.js in /server/routes
You'll see that it requires the articles controller and its methods for querying the database.

The first section requires the articles controller, which defines different methods

For example, code below tells the server to use a method named "all" in the articles controller when the url is pointed to /articles:

<source lang="javascript">
app.route('/articles')
.get(articles.all)
</source>

*Go to http://localhost:3000/articles, what do you see? Does it make sense?

Let's switch to the public folder where the views reside. Go to articles/public/views, open up list.html: <br/>
The first line tells the framework that ArticlesController is responsible for this particular view and when this view is loaded, use find() to initiate data binding.
<source lang="html4strict">
<section data-ng-controller="ArticlesController" data-ng-init="find()">
</source>

Feel free to take a look at what find() does. Make sure you understand that what find() does is actually done by the backend, where a corresponding find() is written (as mentioned above).
Hopefully you have a better understanding of how these technologies all work together now.

Review the AngularJS section if you have any questions regarding the view data binding.

The view files in articles/views only defines the code for displaying the articles, where does the navigation bar gets defined.
The answer is in /public/system.
*The .html files in public/system/views provide a container/layout for the application.
For example, header.html includes the menu bar (displayed on the top of the page):

<source lang="html4strict">
<div class="left pull-left">
<ul class="navbar-nav nav">
<li data-ng-repeat="item in menus.main" ui-route="/{{item.link}}" ng-class="{active: $uiRoute}">
<a mean-token="item.link" ui-sref='{{item.link}}'>{{item.title}}</a>
</li>
</ul>
</div>
</source>

* Try changing <nowiki>{{item.title}} </nowiki> inside the <a> </a>tags to "my articles" see what happens to the page.
* The ui-sref is "href" in ui-route, an AngularJS plugin, try changing <nowiki>{{item.link}}</nowiki> to #!/myarticles,
* What happens to the application now? When you click on "my articles"?

The page to articles is no longer served!

But how does the framework know which page to serve given a certain url? The file responsible for this (called routing in web development) is in public/articles/routes

open up articles.js in this folder and find the line that specifies the routing scheme for /articles:
<source lang="javascript">

.state('all articles', {
url: '/articles',
templateUrl: 'public/articles/views/list.html',
resolve: {
loggedin: checkLoggedin
}
}
</source>

This is ui-route's way of telling the server what to serve the page specified by the templateUrl when it sees "localhost:3000/#!/phones".
The #! is a hash prefix used for MEAN to make ajax calls so make sure to include it when coding your views.
Now try changing the url to "/myarticles", save and go back to your app, click on "my articles" now, what happens?

*This is important if you want to customize your navigation bar and links. Just remember that each url needs an entry in the route file, in the format of the example above.

= Practice =

Can you implement a view in your myPackage to display all phones injected in the DB?
Hint: myPackage has the same file structure as the default app.

Node.JS

2014-11-03T18:29:49Z

Shane: /* Installing Node.JS */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The unofficial instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably ''use-nave-no-shell.sh''.

The instructions at the above link have a couple bugs. If you run this sequence of commands, Node and NPM will install correctly:

<source lang="bash">
$ mkdir ~/.nave
$ cd ~/.nave
$ wget http://github.com/isaacs/nave/raw/master/nave.sh
$ sudo ln -s $PWD/nave.sh /usr/local/bin/nave
$ chmod a+x nave.sh
$ sudo chown -R $USER:$USER /usr/local
$ nave usemain stable
$ curl https://www.npmjs.org/install.sh | sh
</source>

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

''npm'' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

'''Note:''' When using npm to install local dependencies, '''''do not use sudo'''''. It will screw up your file permissions.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O. There may be quiz questions about this code.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

Here is a good slideshow introducing Node.JS as well as some security vulnerabilities to look out for: http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

'''Tip:''' Once you set up your ''package.json'' file, you can automatically add a dependency to it by using the ''--save'' argument on ''npm install'': <code>npm install --save socket.io</code>

[[Category:Module 7]]

Socket.IO

2014-11-03T17:55:53Z

Shane:

AJAX is useful when one-way communication is satisfactory for your web application. However, what happens when you need two-way communication, like a chat client or multiplayer game? AJAX isn't the tool for the job. This is where '''Socket.IO''' comes in.

Built to work natively with Node.JS, Socket.IO enables asynchronous, two-way communication between the server and the client. This means that the server can send messages to the client without the client having to ask first, as is the case with AJAX. As you learn Socket.IO, Non-Blocking I/O will become your best friend!

== Installing Socket.IO ==

Before you install Socket.IO, you need to install [[Node.JS]] and NPM, which is often installed automatically when you install Node.JS.

The NPM package manager is different from many of the package managers we've used in that you need to install remote packages for every project in which you use them. This means that you need to '''cd''' to the working directory in which you want to keep your Node.JS JavaScript file, ''and then'' run the following command:

<source lang="bash">
$ npm install socket.io
</source>

'''Note:''' If you pass the ''-g'' to ''npm install'', then the package will be installed "globally" on your instance, so all Node.JS projects will be able to use it. However, this is not recommended for all projects. [http://blog.nodejs.org/2011/04/06/npm-1-0-link/ Read Node.JS's justification here.]

== Messaging ==

Socket.IO works by having clients send messages to the server and the server send messages to clients. For example, consider the code:

<source lang="javascript">
// Computer A:
socket.emit("info", {
"hello": "world"
});

// Computer B:
socket.on("info", function (data) {
console.log(data.hello);
});
</source>

Computer A could be ''either the client or the server'', and Computer B would be the other. When '''socket.emit(name, data)''' is called on either end, the callback function in '''socket.on''' that listens for the message named ''name'' is called with the ''data'' from '''socket.emit'''.

== A First Socket.IO Application: Chat Server and Client ==

Building a chat client is surprising simple using Socket.IO and Node.JS, and it gives great insight into the workings of Socket.IO. Take the time to understand how this example works, and ask questions; if you understand this, the group portion will be easy!

=== The Chat Server ===

You can make a file called ''chat-server.js'' with the following code:

<source lang="javascript">
// Require the packages we will use:
var http = require("http"),
socketio = require("socket.io"),
fs = require("fs");

// Listen for HTTP connections. This is essentially a miniature static file server that only serves our one file, client.html:
var app = http.createServer(function(req, resp){
// This callback runs when a new connection is made to our HTTP server.

fs.readFile("client.html", function(err, data){
// This callback runs when the client.html file has been read from the filesystem.

if(err) return resp.writeHead(500);
resp.writeHead(200);
resp.end(data);
});
});
app.listen(3456);

// Do the Socket.IO magic:
var io = socketio.listen(app);
io.sockets.on("connection", function(socket){
// This callback runs when a new Socket.IO connection is established.

socket.on('message_to_server', function(data) {
// This callback runs when the server receives a new message from the client.

console.log("message: "+data["message"]); // log it to the Node.JS output
io.sockets.emit("message_to_client",{message:data["message"] }) // broadcast the message to other users
});
});

</source>

The above code makes a simple HTTP server that responds to all connections with the contents of the file "client.html", which we will make in the next step. We tell Socket.IO to listen for "message" events, and when it hears one, it should emit a new event called "someone said" back to the connected clients.

=== The Chat Client ===

Here is a front-end client that could work with our server, in ''client.html'':

<source lang="html4strict">

<!DOCTYPE html>
<html>
<head>
<script src="/socket.io/socket.io.js"></script>
<script type ="text/javascript">

var socketio = io.connect();
socketio.on("message_to_client",function(data) {
//Append an HR thematic break and the escaped HTML of the new message
document.getElementById("chatlog").appendChild(document.createElement("hr"));
document.getElementById("chatlog").appendChild(document.createTextNode(data['message']));
});

function sendMessage(){
var msg = document.getElementById("message_input").value;
socketio.emit("message_to_server", {message:msg});
}

</script>
</head>
<body>
<input type=text" id="message_input"/>
<button onclick="sendMessage()">send</button>
<div id="chatlog"></div>
</body>
</html>

</source>

'''Note:''' This example passes strings as the event data, but you can pass any JavaScript datatype, including object literals.

To see this in action, save these two files in the same directory, cd over to the directory, and start the server:

<source lang="bash">$ node chat-server.js</source>

Fire up your favorite browser and navigate to http://localhost:3456/. Open the page in two windows. Violà: you have your (very basic) chat client!

== Resources ==

The [http://socket.io/ Socket.IO web site] has concise examples that tell you pretty much all you need to know in order to build a functional Socket.IO web application.

[[Category:Module 7]]

Socket.IO

2014-10-31T04:47:17Z

Shane: Indentation

AJAX is useful when one-way communication is satisfactory for your web application. However, what happens when you need two-way communication, like a chat client or multiplayer game? AJAX isn't the tool for the job. This is where '''Socket.IO''' comes in.

Built to work natively with Node.JS, Socket.IO enables asynchronous, two-way communication between the server and the client. This means that the server can send messages to the client without the client having to ask first, as is the case with AJAX. As you learn Socket.IO, Non-Blocking I/O will become your best friend!

== Installing Socket.IO ==

Before you install Socket.IO, you need to install [[Node.JS]] and NPM, which is often installed automatically when you install Node.JS.

The NPM package manager is different from many of the package managers we've used in that you need to install remote packages for every project in which you use them. This means that you need to '''cd''' to the working directory in which you want to keep your Node.JS JavaScript file, ''and then'' run the following command:

<source lang="bash">
$ npm install socket.io
</source>

'''Note:''' If you pass the ''-g'' to ''npm install'', then the package will be installed "globally" on your instance, so all Node.JS projects will be able to use it. However, this is not recommended for all projects. [http://blog.nodejs.org/2011/04/06/npm-1-0-link/ Read Node.JS's justification here.]

== Messaging ==

Socket.IO works by having clients send messages to the server and the server send messages to clients. For example, consider the code:

<source lang="javascript">
// Computer A:
socket.emit("info", {
"hello": "world"
});

// Computer B:
socket.on("info", function (data) {
console.log(data.hello);
});
</source>

Computer A could be ''either the client or the server'', and Computer B would be the other. When '''socket.emit(name, data)''' is called on either end, the callback function in '''socket.on''' that listens for the message named ''name'' is called with the ''data'' from '''socket.emit'''.

== A First Socket.IO Application: Chat Server and Client ==

Building a chat client is surprising simple using Socket.IO and Node.JS, and it gives great insight into the workings of Socket.IO. Take the time to understand how this example works, and ask questions; if you understand this, the group portion will be easy!

=== The Chat Server ===

You can make a file called ''chat-server.js'' with the following code:

<source lang="javascript">
// Require the packages we will use:
var http = require("http"),
socketio = require("socket.io"),
fs = require("fs");

// Listen for HTTP connections. This is essentially a miniature static file server that only serves our one file, client.html:
var app = http.createServer(function(req, resp){
// This callback runs when a new connection is made to our HTTP server.

fs.readFile("client.html", function(err, data){
// This callback runs when the client.html file has been read from the filesystem.

if(err) return resp.writeHead(500);
resp.writeHead(200);
resp.end(data);
});
});
app.listen(3456);

// Do the Socket.IO magic:
var io = socketio.listen(app);
io.sockets.on("connection", function(socket){
// This callback runs when a new Socket.IO connection is established.

socket.on('message_to_server', function(data) {
// This callback runs when the server receives a new message from the client.

console.log("message: "+data["message"]); // log it to the Node.JS output
io.sockets.emit("message_to_client",{message:data["message"] }) // broadcast the message to other users
});
});

</source>

The above code makes a simple HTTP server that responds to all connections with the contents of the file "client.html", which we will make in the next step. We tell Socket.IO to listen for "message" events, and when it hears one, it should emit a new event called "someone said" back to the connected clients.

=== The Chat Client ===

Here is a front-end client that could work with our server, in ''client.html'':

<source lang="html4strict">

<!DOCTYPE html>
<html>
<head>
<script src="/socket.io/socket.io.js"></script>
<script type ="text/javascript">

var socketio = io.connect("127.0.0.1:3456");
socketio.on("message_to_client",function(data) {
//Append an HR thematic break and the escaped HTML of the new message
document.getElementById("chatlog").appendChild(document.createElement("hr"));
document.getElementById("chatlog").appendChild(document.createTextNode(data['message']));
});

function sendMessage(){
var msg = document.getElementById("message_input").value;
socketio.emit("message_to_server", {message:msg});
}

</script>
</head>
<body>
<input type=text" id="message_input"/>
<button onclick="sendMessage()">send</button>
<div id="chatlog"></div>
</body>
</html>

</source>

'''Note:''' This example passes strings as the event data, but you can pass any JavaScript datatype, including object literals.

To see this in action, save these two files in the same directory, cd over to the directory, and start the server:

<source lang="bash">$ node chat-server.js</source>

Fire up your favorite browser and navigate to http://localhost:3456/. Open the page in two windows. Violà: you have your (very basic) chat client!

== Resources ==

The [http://socket.io/ Socket.IO web site] has concise examples that tell you pretty much all you need to know in order to build a functional Socket.IO web application.

[[Category:Module 7]]

HTML and CSS

2014-10-28T20:01:53Z

Shane:

You have probably used so-called "What-You-See-Is-What-You-Get" (WYSIWYG) web page editor before. You select text, press the bold button, and voilà! Your text is bold. But what's really happening behing the scenes is that your editor is generating HTML and CSS code. Indeed, every page you view on the internet is built using HTML and CSS. In this guide, you will learn the principles of HTML and CSS and learn how they fit together to make a web page.

== Basic Structure of a Web Page ==

The most basic web page is shown below.

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head>
<title>My First Web Page</title>
</head>
<body>
<p>Hello World!</p>
</body>
</html>
</source>

If you were to open this page in Firefox, you would see the following:

[[File:BasicHTML.png‎]]

This is the skeleton of every web page on the internet. Things to notice:

* The page begins with a DOCTYPE declaration. This is a mandatory part of a web page, and it tells the browser what version of HTML to use when rendering your page. In this case, the browser should use HTML 5.
* The rest of the page consists of ''tags'', in a hierarchy as follows:
** html
*** head
**** title
*** body
**** p

You can view a web page's source code in your browser; in Firefox, the keyboard shortcut is Ctrl-U (or Command-U), and in Chrome, it is Alt-Ctrl-U (or Option-Command-U).

== Introduction to HTML ==

HTML stands for ''HyperText Markup Language''. Notice that HTML is ''not'' a programming language, so it doesn't have classes, methods, variables, or anything else you may be used to seeing. Instead, HTML defines the ''content'' of a web page, and it uses ''tags'' to do that for you.

=== Tags ===

Tags define the content of your page. Each tag represents an ''element''. There are two main types of elements: content elements and empty elements.

==== Content Elements ====

A '''content element''' is a container for other elements on your page, and it participates in the nesting hierarchy of a web page. The general format looks like this:

<source lang="html4strict">
<tagname> Contents </tagname>
</source>

If you've used BBCode before in online forums, HTML should look familiar, except that it uses angle brackets (less-than and greater-than signs) instead of square brackets.

'''Note:''' There are actually several different types of content elements, including phrasing content, sectioning content, and flow content. More details can be found [http://www.w3.org/html/wg/drafts/html/master/dom.html#content-models in the HTML5 spec].

==== Void Elements ====

A '''void element''' or '''empty element''' represents an element on your page that does not participate in the nesting hierarchy. An empty element looks like this:

<source lang="html4strict">
<tagname />
</source>

Although the trailing slash is optional on void/empty elements, it is considered best practice to include it, and it also makes it more clear what's a content element and what's a void element when reviewing your code.

==== Content Tags with Optional Closing Tag ====

HTML has a quirk in that a few content tags, such as <nowiki><p></nowiki>, <nowiki><tbody></nowiki>, and <nowiki><li></nowiki>, do not require that the end tag be present. In addition, both the opening and the closing tags <nowiki><html></nowiki>, <nowiki><head></nowiki>, and <nowiki><body></nowiki> may ''sometimes'' be omitted. For example, the following code will pass the validator as a valid HTML5 document:

<source lang="html4strict">
<!DOCTYPE html>


<title>My Miniature Document</title>


<div>
<p>
Hello

<p>
World

</div>


</source>

More information is in [http://www.w3.org/TR/html5/syntax.html#optional-tags the HTML5 spec].

===== Why to Always Include Closing Tags =====

It will make your life easier if you always include closing tags, even if they are technically optional, for the following reasons:

* It is best practice to '''be explicit''' in your code.
* You can see in the spec how there are strict conditions for when the closing tags are implied and when they are not. Changing something at the end of your document could have '''adverse consequences''' to something earlier if you are using implicit end tags.
* Popular browsers such as Internet Explorer 9 will create the incorrect DOM structure when closing tags are omitted, leading to '''hard-to-detect bugs'''

It might be advantageous to take advantage of this HTML quirk is if you are hard-core trying to optimize the load speed of your pages, but in most other cases, omitting closing tags will only cause frustration.

=== Attributes ===

Both content elements and void elements can have attributes that further define their functionality. You define an attribute like this:

<source lang="html4strict">
<contenttag attribute="value"> Content </contenttag>
<emptytag attribute="value" />
</source>

=== Commonly Used Tags ===

For reference, below is a list of commonly used tags in HTML. For a complete list, see [http://www.w3.org/TR/html5/#contents section 4 of the HTML 5 Specification].

Void elements are distinguished from content elements by the presence of a trailing slash.

==== Semantic Elements ====

{{DoctypeTV
|youtube_id=53bFhkqThCQ
|time=5m18s
|desc=Semantic Elements in HTML5
}}

Use these tags for defining broad sections of your page with a specific purpose.

* '''<nowiki><header></nowiki>''' Defines the header section of a web page
* '''<nowiki><footer></nowiki>''' Defines the footer section of a web page
* '''<nowiki><nav></nowiki>''' Defines the section of your page that contains navigation links
* '''<nowiki><article></nowiki>''' Defines an article on your page (useful for screen readers)
* '''<nowiki><section></nowiki>''' Defines a real section of your page; for example, one with unique headings distinct from the rest of the document
* '''<nowiki><figure></nowiki>''' Defines a figure
** '''<nowiki><figcaption></nowiki>''' Defines a caption for that figure (<figcaption> should be nested inside of <figure>)
* '''<nowiki><form></nowiki>''' Defines a form into which the user should input data
** '''<nowiki><input type="text/number/date/radio/etcetera" name="name" /></nowiki>''' Defines an input field of a certain type
** '''<nowiki><label for="input-id"></nowiki>''' Defines a label for an input field with the ID ''input-id''
** '''<nowiki><select name="name"></nowiki>''' Defines an input field where the user can select one or more choices (like a drop-down box)
*** '''<nowiki><option value="value"></nowiki>''' Defines an option for the select box
** '''<nowiki><textarea name=""></nowiki>''' Defines a text box (which is larger than a text field)

For more information on HTML forms, read the article [[HTML Forms]].

==== External Media ====

Use these tags to include external media onto your page.

* '''<nowiki><iframe src="source"></nowiki>''' Represents a little window on your page into which ''source'' is loaded; ''source'' could be a PDF document, for example, or an entire other web page
* '''<nowiki><link rel="what" type="mime" href="source" /></nowiki>''' Defines an external document ''what'' located at ''source'' with the mime type ''mime'' that should be loaded into your HTML page. '''Note: <link /> does NOT define a hyperlink! <a> is for that.''' Used most commonly for including CSS stylesheets.
* '''<nowiki><img src="source" alt="text" /></nowiki>''' Defines an image located at ''source'' that has a textual representation of ''text''
* '''<nowiki><audio></nowiki>''' Represents an audio clip on your page
* '''<nowiki><video></nowiki>''' Represents a video clip on your web page
* '''<nowiki><canvas></nowiki>''' Defines a canvas for advanced drawing (we will learn more about this in future modules)

==== Outlining Elements ====

Use these elements to define an outline for your page, including definitions and citations.

* '''<nowiki><h1> to <h6></nowiki>''' Defines the outline for your page
* '''<nowiki><p></nowiki>''' Defines a paragraph of text
* '''<nowiki><dl></nowiki>''' Defines a Dictionary List
** '''<nowiki><dt></nowiki>''' Defines a Dictionary Term
** '''<nowiki><dd></nowiki>''' Defines a Dictionary Definition
* '''<nowiki><table></nowiki>''' Defines a table for displaying data
** '''<nowiki><thead>, <tbody>, <tfoot></nowiki>''' Defines the heading, body content, and footing of a table
*** '''<nowiki><tr></nowiki>''' Defines a table row
**** '''<nowiki><th></nowiki>''' Defines a table cell that contains a heading
**** '''<nowiki><td></nowiki>''' Defines a table cell that contains data
* '''<nowiki><ol> and <ul></nowiki>''' Define ordered and unordered lists, respectively (meaning numbered lists and bulleted lists)
** '''<nowiki><li></nowiki>''' Defines a list item for either <nowiki><ol> or <ul></nowiki>
* '''<nowiki><q></nowiki>''' Represents a short, inline quotation quoted from another source
* '''<nowiki><blockquote></nowiki>''' Represents a longer block of text quoted from another source

==== Miscellaneous Elements ====

This section lists useful elements that don't fit into one of the other categories.

* '''<nowiki><a href="destination"></nowiki>''' Make a hyperlink to destination
* '''<nowiki><br /></nowiki>''' Denotes where a line break should appear (note that white space is ignored when rendering, so a line break in the source code is ''not'' reflected in the output)
* '''<nowiki><button></nowiki>''' Defines a clickable button
* '''<nowiki><code></nowiki>''' Defines a piece of computer code
* '''<nowiki><output></nowiki>''' Defines the result of a calculation
* '''<nowiki><pre></nowiki>''' Defines pre-formatted text in which whitespace will be preserved
* '''<nowiki><script></nowiki>''' Defines a script for your page (we will learn a lot more about this in later modules)
* '''<nowiki><div></nowiki>''' Defines a block section of your document (useful for styling)
* '''<nowiki><span></nowiki>''' Defines an inline section of your document (useful for styling)

=== High School Analogy ===

<nowiki>In more ways than not, HTML can be thought of as a markup language for five-paragraph essays that you wrote in history class in high school. <blockquote> is used to denote long quotations; <h1> through <h6> denote the outline; <p> denotes new paragraphs; <figure> and <figcaption> represent exhibits; <section> could represent chapters if you were writing a longer report; and so on.</nowiki>

Take home message: HTML defines the ''content'' of your page. Use it to its full ability.

== Introduction to CSS ==

Notice that we haven't said a word about how things look yet. This is because that is what CSS is for!

CSS stands for ''Cascading Style Sheets'', and it defines the ''appearance'' of your page. CSS is composed of ''rules'', and each rule consists of a ''selector'' and one or more ''declarations''. Let's see an example:

<source lang="css">
header {
color: blue;
font-family: Verdana, sans-serif;
}
</source>

The above CSS rule does three things:

* It ''selects'' all <code><nowiki><header></nowiki></code> elements
* It ''declares'' the ''property'' '''color''' (i.e. the text color) of the selected elements to be blue
* It ''declares'' the ''property'' '''font-family''' (i.e. the font "face") of the selected elements to be Verdana, or alternatively any sans-serif font if Verdana is not available

All CSS rules follow this general format. The following sections will discuss more detail on CSS selectors and declarations.

=== Selectors ===

{{DoctypeTV
|youtube_id=W9H95NcbTSw
|time=5m27s
|desc=CSS Selectors, Part 1
}}

In the previous section's example, the most basic CSS selector was used: selecting by the ''tag name''. To select by the ''class name'', use a period, like so:

<source lang="css">
.info {
font-weight: bold;
}
</source>

{{DoctypeTV
|youtube_id=0a4r4bm1nQA
|time=1m29s
|desc=CSS Selectors, Part 2
}}

A third common way to select an element is by its ID. To select by ID, use a number sign, like so:

<source lang="css">
#medal_table {
border-collapse: collapse;
}
</source>

Selectors can be combined. For example, to select all hyperlinks in any paragraph having the class "alert", you could do:

<source lang="css">
p.alert a {
font-style: italic;
}
</source>

The <code>p.alert</code> selects all <code><nowiki><p></nowiki></code> tags with the class name "alert". The space tells CSS to look for all descendants of such paragraphs. Finally, the <code>a</code> selects all <code><nowiki><a></nowiki></code> elements in the resulting set.

It is also very common to use a right-angle bracket to select a ''child'' rather than a ''descendant'', the distinction being that ''descendants'' could be nested at any depth: child, grandchild, and so on, while a ''child'' must be at the next level down in the DOM. For example:

<source lang="css">
ul.fruits > li {
text-decoration: underline;
}
</source>

Some common CSS selectors are listed below. For a complete list of CSS selectors, see [http://www.w3.org/TR/CSS/#selectors section 4.2 of the CSS Specification].

* '''foo''' selects an element with tag name ''foo''
* '''.foo''' selects an element with the class name ''foo''
* '''#foo''' selects an element with the ID ''foo''
* '''[foo="bar"]''' selects an element with the attribute ''foo'' whose value is ''bar''
* '''foo bar''' selects an element matching ''bar'' that is a descendant of an element matching ''foo''
* '''foo > bar''' selects an element matching ''car'' that is a child of an element matching ''foo''
* '''foo + bar''' selects an element matching ''bar'' that is the next sibling of an element matching ''foo''

==== Pseudo-Classes ====

Elements can also be selected based on their current state using ''pseudo-classes''. Pseudo-classes always begin with a colon. For example, this is how you could change the color of all visited links on your web page:

<source lang="css">
a:visited {
color: #99FF99; /* this example uses a hexadecimal RGB definition for the color, which allows you to
mix over 16 million colors */
}
</source>

Some common pseudo-classes are listed below. For a complete list, see [http://www.w3.org/TR/CSS/#selectors section 4.2 of the CSS Specification].

* '''foo:first-child''' selects an element matching ''foo'' that is the first child of its parent (i.e., any ''foo'' that doesn't have older siblings)
* '''foo:last-child''' selects an element matching ''foo'' that is the last child of its parent
* '''foo:empty''' selects any element matching ''foo'' that has no children
* Pseudo-Classes for Form Elements:
** '''input:checked''' selects all checkboxes and radio buttons that are checked
* Pseudo-Classes for Hyperlink Elements:
** '''a:link''' selects all hyperlinks that have not been visited yet
** '''a:visited''' selects all hyperlinks that have been visited
* Pseudo-Classes for Interactive Elements (like buttons, hyperlinks, etc):
** '''foo:active''' selects elements matching ''foo'' that are being pressed on
** '''foo:hover''' selects elements matching ''foo'' that are being hovered over
** '''foo:focus''' selects elements matching ''foo'' that are selected (no pun intended)

=== Properties ===

Selectors are used to select elements that need to have styles applied to them, and properties are used to actually define those styles. Throughout this section, you've seen properties including '''color''', '''font-family''', '''font-style''', and '''text-decoration'''. There are dozens more properties you can define, some of which are listed below.

For a complete list of CSS properties, see [http://www.w3.org/TR/CSS/#properties section 4.1 of the CSS Specification].

* '''background-image''' sets the background image of an element. Usage: <code>background-image: url(path/to/image.png);</code>
* '''background-color''' sets the background color of an element (note: the image takes precedence over the color; the color will be displayed if the image can't be found)
* For Tables:
** '''border-collapse''' removes the spacing between table cells. Usage: <code>border-collapse: collapse;</code>
** Note: You can select td elements that are grandchildren of a table element, and then specify border properties on the td's, like this: <code>#myTable > tr > td { border: 1px solid black; }</code>
* '''border''' defines the border around an element. Usage: <code>border: 1px dashed red;</code>
* '''border-radius''' lets you have rounded corners on your elements
* '''float''' makes the text of a document flow around the element. Usage: <code>float: left;</code> (or <code>right</code>)
** '''clear''' makes an element stop wrapping around floats and instead move down to where the floats end. Usage: <code>clear: both;</code>
** Note: If you specify multiple object in a for as floating, they will appear next to each other horizontally.
* '''cursor''' lets you change the type of cursor that appears then your element is in focus. Example usage: <code>cursor: pointer;</code>
* '''font''' lets you specify the font-size, line-height, and font-family in one fell swoop. Usage: <code>font: 14px/18px Verdana, Arial, sans-serif;</code>
* '''list-style-type''' specifies the type of number or bullet used on <code><nowiki><ol></nowiki></code>'s and <code><nowiki><ul></nowiki></code>'s
* '''text-align''' lets you justify text on the left, center, or right
* '''display''' lets us specify an element as inline or block (see below), and it also enables us to "turn off" an element from being displayed on a page. Example usage: <code>display: none;</code>

==== Units ====

Some CSS properties require that you specify numerical values for things (font-size, line-height, border-width, and so on). CSS supports a number of units, the most common of which include:

* '''px''', which defines a distance in pixels (relative to screen resolution).
* '''em''', which defines a distance relative to font size. (Note: an ''em'' is the width of the capital letter M. No, I'm not kidding.)
* '''rem''', which defines a distance relative to the font size of the root element. Compare to '''em''', which defines a distance relative to the font size of the current element (which might have a different font size than the document root).
*: '''Note:''' As of October 2012, '''rem''' support covers 79% of the browser market ([http://caniuse.com/rem more info]). If you intend to build a web application usable by the other 21%, you might not want to avoid '''rem'''s in your CSS.
* '''pt''', which is a traditional print unit equal to 1/72 of an inch (should appear the same size on all screens regardless of resolution).
* '''%''', which defines a distance relative to that property of its parent element. For the most part, you'll only use % when working with the Box Model (see below).

=== The Box Model ===

For the most part, all elements fall into one of two categories:

* Inline (Examples: a, span, strong)
* Block (Examples: p, div, section)

The properties we've seen thus far apply mostly to inline elements. As it turns out, CSS has an additional set of properties that describe block elements. These properties compose the ''box model''.

While inline elements flow with the text, block elements stand on their own. You can define the space between the block element and the next closest element on the page using ''margin'', the block element's border using ''border'', and the space between the block element's border and its content using ''padding'':

[[File:Box.png]]

For example, you could make a padded box that is centered on the page using this CSS:

<source lang="css">
div.box {
width: 500px;
margin: 0 auto; /* when two "arguments" are passed to margin or padding, the first defines top
and bottom margin/padding and the second defines left and right margin/padding */
padding: 25px; /* when only one "argument" is passed to margin or padding, it defines the
margin/padding on all four sides */
border: 1px solid black; /* the 1px defines the border-width; the solid defines the border-style;
the black defines the border-color */
}
</source>

Here is what the resulting box looks like:

[[File:CSSBoxExample.png]]

Note that the ''width'' defines only the ''content width''. To compute the actual "width" of the element, you need to add the left and right padding border, and margin.

This is only scraping the surface of the CSS box model. All advanced web sites utilize the box model to its full extent to produce the complex layouts you have come to expect on the internet. For more information on the CSS box model, read [http://www.w3.org/TR/css3-box/ the W3C specification].

=== Typography ===

Traditionally, Web developers were limited to a small subset of fonts that were commonly installed on all computers:

* Andale Mono
* Arial
* Arial Black
* Comic Sans MS
* Courier New
* Georgia
* Impact
* Times New Roman
* Trebuchet MS
* Verdana
* Webdings

That was it. Incredibly limiting.

However, fonts other than these are used widely on the Web. How? CSS has evolved to the point where it now allows you to upload a font to your server, and use that font on your site. My favorite place to go for free Web fonts is [http://fontsquirrel.com/ FontSquirrel]. For more information and more places to get Web fonts, [http://www.sitepoint.com/5-of-the-best-css3-font-tools/ read this article on SitePoint].

== Using HTML and CSS in your Web Page ==

Recall that HTML defines the ''content'' of your page, while CSS defines the ''appearance''.

Most of the HTML you write will be in the <code><body></code> tag, because, naturally, this is where the ''content'' of your page should reside. CSS, on the other hand, is supplemental to the content, and so it should be included in the <code><head></code> tag, as shown in the following section.

=== How to Include CSS ===

There are three options for using CSS in your web page:

# Loading external stylesheets
# Embedding stylesheets in the document
# Inline styles using the style attribute

The first option is almost always preferred in production applications for the following reasons:

* Browsers can cache external stylesheets, so once they've loaded the stylesheet once, they won't have to load it again, making future pages load faster and reducing requests to your server
* External stylesheets are more modular; that is, they can be included in multiple pages on your web site without the need for copying and pasting embedded stylesheets

To include external stylesheets in your document, place the following empty HTML tag in your <code><head></code>:

<source lang="html4strict">
<link rel="stylesheet" type="text/css" href="path/to/stylesheet.css" />
</source>

It may be convenient during development to use embedded stylesheets, because then you don't have to click back and forth between files in your IDE and clear your browser cache. You may place embedded stylesheets in a <code><style></code> tag, also in your <code><head></code>:

<source lang="html4strict">
<style type="text/css">
styles {
go: here;
}
</style>
</source>

For a variety of reasons, inline styles should almost always be avoided. Instead of using inline styles, give your element a CSS class, and assign styles to that class in your stylesheet:

<source lang="css">
p.notice {
color: blue;
}
</source>
<source lang="html4strict">
<p class="notice">Well done using classes instead of inline styles!</p>
</source>

Just so you know it when you see it, the following example shows the usage of inline styles, which are declared using the '''style''' attribute.

<source lang="html4strict">
<p style="color:red;">You'd better think twice about using inline styles.</p>
</source>

=== Quick and Easy Page Layout ===

I like to use the following code when I just want a simple, aesthetically pleasing web page:

<source lang="html4strict">
<!DOCTYPE html>
<head>
<meta charset="utf-8"/>
<title>My Web Page</title>
<style type="text/css">
body{
width: 760px; /* how wide to make your web page */
background-color: teal; /* what color to make the background */
margin: 0 auto;
padding: 0;
font:12px/16px Verdana, sans-serif; /* default font */
}
div#main{
background-color: #FFF;
margin: 0;
padding: 10px;
}
</style>
</head>
<body><div id="main">



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

Put your document where the <code><nowiki></nowiki></code> is. Your page will go instantly from dull-looking to presentable. ;-)

=== The HTML5 Shiv ===

Some browsers (*cough cough* IE < version 9) do strange things when you apply CSS styles to the newest HTML elements that were introduced with HTML5. Fortunately, there is a painless solution. Simply include the following code in your '''<head>''' tag:

<source lang="html4strict">

</source>

This so-called '''HTML5 Shiv''' will make older versions of Internet Explorer render your pages more closely to how modern browsers do.

== Validation ==
{{XKCD
|id=1144
|name=tags
}}

HTML and to a lesser extent CSS are forgiving when it comes to syntactical errors in your code. However, it is not good practice to ignore your syntax errors for a variety of reasons:

* '''Faster and More Reliable Rendering.''' Don't leave it up to your client's browser to decide what you meant when you made your syntax error.
* '''Interoperability with Compliant Browsers.''' Although a web page may ''look'' right in your ''testing'' browser, you need to remember that there are ''lots'' of different user agents: other browsers, mobile devices, and screen readers, just to name a few.
* '''Accessibility.''' Valid HTML code enables you to be confident that your page will be accessible to people with disabilities, such as the blind.
* '''Search Engine Optimization.''' Web sites with valid HTML syntax rank higher in search engines like Google.
* '''Future Proofing.''' The W3C specification will not be made backwards-incompatible, so writing valid HTML syntax ensures that your page will work well into the future.
* '''More Professional.''' No seasoned web developer will publish a page with accidental syntax errors.

The industry standard tool for HTML and CSS syntax checking is the '''[http://validator.w3.org/ W3C Validator]'''. '''You should ALWAYS validate your code before completing your project!''' The Validator gives very helpful feedback to help you find and fix syntax errors.

For more information on why it is important to validate, see [http://validator.w3.org/docs/why.html the W3C's recommendation].

=== But why don't… ===

As you play around with the validator, you may have discovered that household name sites like [http://www.google.com/ Google] and [http://www.yahoo.com/ Yahoo] do not pass the validator. This is a deliberate act on the part of these web sites because of the following reasons:

* '''Download Speed.''' Sometimes, but not always, valid code adds bytes to the file size. Sites that serve tens of thousands of requests per second are highly concerned with the increased file size.
* '''Interoperability with Non-Compliant Browsers.''' ''Very'' old browsers like Netscape Navigator and Internet Explorer 5 do not respond the way that modern browsers do to the same markup.

However, do not take these as reasons to not validate your own code. The reasons listed in the previous section almost always outweigh the counterpoints in this section.

[[Category:Module 1]]

Node.JS

2014-10-14T06:46:55Z

Shane: /* Node.JS Conventions */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The unofficial instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably ''use-nave-no-shell.sh''.

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

''npm'' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

'''Note:''' When using npm to install local dependencies, '''''do not use sudo'''''. It will screw up your file permissions.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O. There may be quiz questions about this code.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

Here is a good slideshow introducing Node.JS as well as some security vulnerabilities to look out for: http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

'''Tip:''' Once you set up your ''package.json'' file, you can automatically add a dependency to it by using the ''--save'' argument on ''npm install'': <code>npm install --save socket.io</code>

[[Category:Module 7]]

Node.JS

2014-10-14T06:46:31Z

Shane: /* Node.JS Conventions */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The unofficial instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably ''use-nave-no-shell.sh''.

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

''npm'' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

'''Note:''' When using npm to install local dependencies, '''''do not use sudo'''''. It will screw up your file permissions.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O. There may be quiz questions about this code.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

Here is a good slideshow introducing Node.JS as well as some security vulnerabilities to look out for: http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

'''Tip:''' Once you set up your ''package.json'' file, you can automatically add a dependency to it by using the ''--save'' argument on ''npm install'': <code>npm install --save nave socket.io</code>

[[Category:Module 7]]

JavaScript

2014-10-14T06:39:06Z

Shane: /* JavaScript Language Components */

JavaScript is the most widely used scripting language for implementing client-side functionality in Web applications. Unlike PHP, JavaScript code is interpreted and executed in a client's web browser (not on the web server).

== JavaScript? Did you mean Java? ==

'''JavaScript''' is a prototype-based programming language focussed on web interactivity. It was first introduced in Netscape Navigator, and it in turn gave rise to what is now '''[http://www.ecmascript.org/ ECMAScript]'''. Originally, JavaScript was called "LiveScript". Sun, the developer of Java at the time, wanted a language that would complement its compiled Java language, and so LiveScript was renamed JavaScript.

Beyond that, '''Java and JavaScript are as similar as Ham and Hamster.'''

Java and JavaScript have similar syntax, but the under workings are quite different. For example, Java requires strict typing, but JavaScript allows for dynamic typing. Java is object-oriented, but JavaScript is prototype-oriented. Java is compiled, but JavaScript is interpreted. Java supports event listeners, but JavaScript makes them a fundamental part of the language. Java variables are scoped to the innermost method or loop, but JavaScript variables are scoped only to the innermost function.

== JavaScript Language Components ==

This section highlights some features of the JavaScript language that differentiate it from other languages. For a more comprehensive JavaScript tutorial, the following tutorials are both quality:

* [http://docs.webplatform.org/wiki/javascript WebPlatform]: Great for learning JavaScript for the first time. Advocates best practices for modern JavaScript development.
* [http://www.quirksmode.org/js/contents.html QuirksMode]: More advanced than the WebPlatform tutorial, but it thoroughly covers the most powerful aspects of pure JavaScript and gives unparalleled advice on browser compatibility.

Advice: Do '''NOT''' Google for "JavaScript Tutorial". The first few hits advocate bad or outdated practices. Stick with the ones listed here.

=== Variables and Scope ===

To define a variable in JavaScript, use the '''var''' keyword.

<source lang="javascript">
var foo = "bar";
</source>

All variables are objects. In the case above, the variable '''foo''' is an object of the class '''String'''.

Notice that like PHP, you do not have to explicitly define a type for a variable like '''int''' or '''String'''; this is because JavaScript and PHP are ''dynamically typed languages''.

JavaScript code can access any variable higher in the “function tree”, but not vice-versa. This is called '''scope'''. ''All functions create their own scope.''

When you reference a variable, JavaScript will look up through the "function tree" until it finds the variable you asked for. This means that you could define variables of the same name as global variables inside of functions. For demonstration of concept:

<source lang="javascript">
var a = "hello";
var b = "world";

function sayGoodByeWorld(){
var a = "goodbye";

alert(a); // goodbye
alert(b); // world
}

sayGoodByeWorld();

alert(a); // hello
</source>

=== Object Literals ===

A very common way of storing and transporting data in JavaScript is by using objects. You can define an object with certain properties using an '''object literal''':

<source lang="javascript">
var apple = {
color: "red",
flavor: "sweet",
season: "autumn"
}

alert(apple.color); // red
</source>

=== Functions ===

To define a function in JavaScript, use the '''function''' keyword.

<source lang="javascript">
function sayHello(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Pass an argument to a function like this:

<source lang="javascript">
function sayHello(name){
alert("Hello, "+name);
}

sayHello("Todd"); // call the function and pass an argument
</source>

==== Functions are Objects ====

In JavaScript, functions are objects. This means that they can be assigned to variables, manipulated on the fly, and even passed as arguments to other functions! '''''This is an extremely important feature of JavaScript''''' that makes it such a robust language for web development.

You create a function variable like this:

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Observe that you can make [[#Variables and Scope|scope-dependent]] functions in this way.

=== Closures ===

{{DoctypeTV
|youtube_id=HaPlj796ngQ
|time=5m45s
|desc=JavaScript Closures
}}

A '''closure''' is a way to separate a certain snippet of JavaScript code from the global scope. This is useful if you do not want to "muck up" global variables. Closures are nothing more than anonymous functions that are called as soon as they are created:

<source lang="javascript">
var a = "hello";

(function(){
var b = "world";

alert(a); // hello
alert(b); // world
})();

alert(a); // hello
alert(b); // ReferenceError: b is not defined
</source>

{{JSFiddleExample
|title=Passing Variables to a Closure
|desc=This example demonstrates how you can "save" previous versions of a variable using closures. This is possible because of scoping and the fact that function variables can be returned as objects.
|fiddle_id=YURqa
}}

Most JavaScript libraries (like jQuery) write all of their code in a closure. What this means is that except for one or two variable names (jQuery or $), everything associated with the library is completely self-contained.

=== Prototypal Inheritance ===

JavaScript implements '''prototypal inheritance''', as opposed to a language like Java or C++, which implements '''classical inheritance'''. JavaScript is one of only a handful of languages implementing prototype-based inheritance.

Here's how it works. Every callable object (function) has a '''prototype'''. When instances of that object are created, their properties and methods are copied (inherited) from the prototype. Additionally, changes made to the prototype later in the program are "copied" to every instance.

For example, if you wanted to make a method on all strings that added a “!”, you could modify String’s prototype:

<source lang="javascript">
String.prototype.bang = function(){
return this+"!"; // Notice: the context is the instance itself
}

alert("Hello".bang()); // alerts Hello!
</source>

To "extend" an object, just copy its prototype to a new object. However, since classical inheritance and prototypal inheritance are different concepts, copying prototypes may have results that you don't expect. [http://beej.us/blog/data/javascript-prototypes-inheritance/ This article] seems to have a pretty good explanation with example implementations.

=== Context ===

{{DoctypeTV
|youtube_id=0a4r4bm1nQA
|time=4m32s
|desc=The ''this'' Variable in JavaScript
}}

Every function is called on a certain object, which is not necessarily the same object in which it was defined. This is called '''context'''.

To call a function on an arbitrary context, use either '''call''' or '''apply'''. ''call'' takes a list of arguments, while ''apply'' takes them all in an array.

To access the current context, use the '''this''' keyword. Demonstration of concept:

<source lang="javascript">
var sayThisColor = function(){
alert(this.color);
}

var apple = { color: "red" }

sayThisColor(); // undefined
sayThisColor.call(apple); // red
</source>

== Events ==

Events are really what make JavaScript such a powerful language for web development.

Rather than being thread based, JavaScript is event based. Since all JavaScript code runs in a single thread, '''there are no concurrency issues'''. When an event occurs, JavaScript automatically calls the ''event callback'' as soon as all previous events' callbacks have finished executing.

Code in the form of a '''callback function''' is associated with events via a '''listener'''. For example, the following JavaScript causes ''sayHello()'' (the callback function) to be run whenever the button with ID "hello" is clicked (the event):

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

document.getElementById("hello").addEventListener("click", sayHello, false);
</source>

{{JSFiddleExample
|title=Binding Callbacks to a Button Click
|fiddle_id=L8c4Z
|cse330=true
|desc=In this example, notice how we bind the callback function when the ''DOMContentLoaded'' event fires. This is because JavaScript requires that the button has been parsed by the browser before it can add event listeners to it.
}}

The '''addEventListener''' method takes three parameters:
* The event type
* The callback function
*: The callback function is passed one parameter: the event object.
* A boolean representing bubble (false) or capture (true) phase
*: You usually want Bubble phase. For more information on event phase, see [[#Event Phase]]

Note that versions of Internet Explorer prior to version 9 required that you use a different, albeit similar, function for assigning event listeners called '''attachEvent'''. attachEvent takes the same arguments as addEventListener, except you need to put '''on''' before the event type (e.g. "onclick"), and the third argument (phase) is not necessary.

It is perfectly valid to use an '''anonymous function''' as your callback function:

<source lang="javascript">
document.getElementById("hello").addEventListener("click", function(event){
alert("Hello, World! Event Type: "+event.type);
}, false);
</source>

QuirksMode has perhaps the best series of articles about the ins and outs of JavaScript events on the internet: http://www.quirksmode.org/js/contents.html#events

=== The Event Object ===

Callback functions are passed one argument: an ''event object''. You see above that one property of the event object is ''event.type''. To see the full list of properties of the event object, you could run the code:

<source lang="javascript">
document.getElementById("my_btn").addEventListener("click", function(event){
var strout = "";
for(var i in event){
strout += i + ": " + event[i] + "\n";
}
console.log(strout);
}, false);
</source>

Some of the most useful properties and methods include:
* '''event.target''' references the object on which the event occurred.
* '''event.currentTarget''' references the object whose listener is currently being processed.
*: ''Note:'' event.target and event.currentTarget might be the same or might be different, depending on whether you are listening for bubbled events.
* '''event.preventDefault()''' stops the normal result of the event from being executed. For example, if you listen for a form's ''submit'' event, you can call event.preventDefault() to stop the form from being submitted.
* '''event.stopPropagation()''' prevents any other event listeners from being executed. For more detail, read the section on Event Phase below.

For more detail on the event object, see [http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#interface-Event the W3C specification].

'''Note:''' If your callback function does not take any parameters, it will still run; you just won't have as easy of access to the event object.

=== Event Handlers and Memory Management ===

JavaScript is an automatically garbage-collected language, meaning that memory management is mostly taken care of for you. However, there are some instances when you need to be careful about creating "zombie" objects. One common "gotcha" instance of this is in event listeners.

For example, consider the code:

<source lang="javascript">
// Declare an object
var myObject = {
fn: function(event) {
alert("Hello World");
}
};

// Make a property of that object listen for some event
document.getElementById("my-div").addEventListener("click", myObject.fn, false);
</source>

In the above example, myObject will ''not'' be garbage collected, even if it goes out of scope, so long as its property ''fn'' is a listener for an event on the div. In order to release myObject from memory, you need o do the following:

<source lang="javascript">
// If we want myObject to be garbage collected when it leaves scope, we need to remove the event listener.
document.getElementById("my-div").removeEventListener("click", myObject.fn, false);
</source>

=== Event Phase ===

In JavaScript, events occur in two phases: '''Capture Phase''' and '''Bubble Phase'''. Consider the following HTML document:

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head><title>Event Test</title></head>
<body>
<div id="box">
<button id="btn">
Hello
</button>
</div>
</body>
</html>
</source>

Suppose the user clicks on the "Hello" button. Events will be fired in the following order:

# Capture Phase CLICK on the Document
# Capture Phase CLICK on the Body
# Capture Phase CLICK on the Div#box
# Target Phase CLICK on the Button#btn
# Bubble Phase CLICK on the Div#box
# Bubble Phase CLICK on the Body
# Bubble Phase CLICK on the Document

{{JSFiddleExample
|title=Using Capture Phase to Enable or Disable a Toolbar
|fiddle_id=r32Dz
|desc=We bind an event in the capture phase to the div with ID ''toolbar''. When ''e.stopPropagation()'' is called, the event does not reach the buttons in the toolbar.
}}

Graphically, here is the order in which an event occurs in three generic nested elements:

[[File:EventPhase.gif]]

Why is this useful? Suppose you have a control panel (toolbar, etc) that you want to temporarily deactivate. (For example, Bold/Italic/Underline buttons on a graphic text editor that currently has no content.) You could keep bubble phase event listeners on your buttons, but prevent those events from occurring by stopping the event in the capture phase on the parent element before the event reaches your buttons! Example:

<source lang="javascript">
var disableToolbarFunc = function(e){
e.stopPropogation();
}

// To disable toolbar:
document.getElementById("box").addEventListener("click", disableToolbarFunc, true);

// To re-enable toolbar:
document.getElementById("box").removeEventListener("click", disableToolbarFunc, true);
</source>

'''Word of caution:''' Like many great things in web development, capture phase does not work in versions of Internet Explorer prior to version 9. There is no elegant substitution for older versions of Internet Explorer.

'''Note:''' When the event reaches the innermost element, there is no distinction between capture phase and bubble phase. The order in which event handlers were added to the element determines the order in which those callbacks are evaluated.

== Document Object Model ==

The '''Document Object Model (DOM)''' is what enables JavaScript to manipulate the content of your web page.

=== Nodes and Traversing the DOM ===

Each element on your page, whether it is a <nowiki><p>, <img/></nowiki>, a string of text, or even an attribute, is called a '''node'''.

Every node, except for the document itself, has exactly one parent. A single node may have multiple children.

Consider the following HTML code:

<source lang="html4strict">
<ul id="my-list">
<li class="fruits">Apples</li>
<li class="citrus">Oranges and <strong>Lemons</strong></li>
<li class="berries">Cherries</li>
</ul>
</source>

Here, the ul with ID "my-list" has three child '''element nodes''' (the three li's) as well as four child '''text nodes''' (the whitespace counts as a text node) and a child '''attribute node'''. The second LI has one child '''text node''' as well as one child '''element node''' and one child '''attribute node'''.

The DOM can be traversed in JavaScript. First, let's look at an example.

<source lang="javascript">
e = document.getElementById("my-list").getElementsByClassName("citrus")[0].lastChild.nodeName;
alert(e);
</source>

{{JSFiddleExample
|title=Currently Selected Radio Button
|fiddle_id=SHcng
|desc=In pure JavaScript, in order to determine the currently selected radio button, it is necessary to iterate over an array of pointers to all possible radio buttons, and stop when you find one that is "checked".
}}

The above snippet gets the element with class name '''citrus''' that is a child of the element with ID '''my-list''' (the second LI in the example above), and alerts the type of its second child node (which in this case is '''STRONG''').

Some common methods for traversing the DOM include:

* Node.parentNode
* Node.childNodes - returns an array of nodes
* Node.firstChild - same as Node.childNodes[0]
* Node.lastChild - same as Node.childNodes[Node.childNodes.length-1]
* Node.previousSibling
* Node.nextSibling

You can also search for child (including all descendants) using one of the following methods:

* Node.getElementsByTagName("tag-name") - returns an array of element nodes having the tag name '''tag-name''' that are descendants of Node
* Node.getElementById("id") - returns a single node having the ID '''id''' that is a descendant of Node
* Node.getElementsByName("what-name") - returns an array of element nodes having their '''name''' attribute set to '''what-name'''. Useful for radio buttons and other form elements.
* Node.getElementsByClassName("class") - returns an array of nodes having the class '''class'''
*: '''Note:''' As of October 2012, 82% of the browser market supports Node.getElementsByClassName ([http://caniuse.com/getelementsbyclassname more info]). In order to support the other 18%, you need to either add your own getElementsByClassName to Node's prototype or use a JavaScript library like jQuery or MooTools.

It is common in JavaScript to have long statements like the one in the example above, where you call methods on several objects in sequence.

=== Creating, Moving, and Removing Nodes ===

You will frequently find yourself wanting to modify the DOM. JavaScript provides methods that help you do this.

Consider the same HTML as above. If you wanted to add another element to the list, you could use this code:

<source lang="javascript">
var newLi = document.createElement("li"); // creates a node with the tag name li
newLi.appendChild(document.createTextNode("Broccoli"));
newLi.setAttribute("class", "veggies");
document.getElementById("my-list").appendChild(newLi);
</source>

If you wanted to remove the apples from the list, you could do:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").removeChild(apple);
</source>

If you wanted to move the apples to the end of the list, you could do this:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").appendChild(apple);
</source>

Notice that '''Node.append()''' both removes a node from its previous location ''and'' appends it to its new location, which is always going to be as the last child of the parent node.

In summary, here are the methods to know from this section:

* Node.append(otherNode) - removes otherNode from its current location in the DOM (if applicable) and then adds it as the last child of Node
* Node.removeChild(otherNode) - removes otherNode, a child of Node, from the DOM
* document.createElement("tag-name") - create a new node with the tag name "tag-name"
* document.createTextNode("text") - create a node containing only the string '''text'''
* Node.setAttribute("attribute", "value") - sets the attribute node of name "attribute" to "value"

=== DOM Shortcuts ===

In the above sections, we have been creating, reading, modifying, and deleting Nodes. This is the most "correct" way to change the content of a web page from inside JavaScript.

This section documents a few shortcuts that are not as "pure" as using Nodes but can be less confusing and cumbersome.

{{JSFiddleExample
|title=Displaying Information
|fiddle_id=Q3BPZ
|desc=This example shows how to use some of the shortcut methods for using JavaScript to display information on the page.
}}

==== textContent ====

Using textContent to display information is probably the easiest method out there. For example, the following code overwrites whatever is in the element with ID "holder" with the string "Hello World":

<source lang="javascript">
document.getElementById("holder").textContent = "Hello World";
</source>

If you wanted to instead append the text, simply use '''+=''' instead of '''=''':

<source lang="javascript">
document.getElementById("holder").textContent += " - Later, he said Hello World - ";
</source>

Note that textContent displays strings literally; that is, it does not allow for HTML. Setting the textContent property also removes any HTML that may have already been in that element.

==== innerHTML ====

If you need to use HTML in your output but don't want to use the method described earlier in this section, a straightforward strategy is to use the innerHTML property of an element. For example, the following code would add a paragraph saying "Hello World" to the element with ID "holder":

<source lang="javascript">
document.getElementById("holder").innerHTML += "<p>Hello World</p>";
</source>

'''Important:''' You need to be careful to prevent XSS-type attacks if you display information using innerHTML. For example, be sure to escape a user-supplied string before appending it to innerHTML.

=== JavaScript Inspectors ===

{{DoctypeTV
|youtube_id=PKzrmbN-pMg
|time=4m13s
|desc=Using Firebug, WebKit Inspector, and IE Developer Tools
}}

Various browsers and browser plugins give you, the developer, tools to debug your code, inspect the DOM, and much more. Using these tools is essential for an efficient workflow.

* '''Firebug'''. Firebug is a plugin for Firefox that is a toolkit full of web developer tools, one of which is a DOM inspector. To inspect the DOM of a web page, simply open the Firebug window while viewing the web page.
* '''WebKit Inspector'''. The WebKit Inspector, which is available in both Chrome and Safari, enables you to see the DOM tree and relationships between elements. However, its DOM inspection tools are not as robust as those of Firebug.
* '''Opera Dragonfly'''. The web browser Opera comes with a web developer toolkit similar to the WebKit Inspector called Dragonfly. It is important that you test your sites in Opera, because although Opera has only a small fraction of the desktop browser market, it is second only to WebKit on the mobile market. Opera also has extremely strong CSS support, so it is good for testing for bugs in your CSS.

All of the above-mentioned tools enable you to look at the DOM of your web page and find what properties and methods are associated with each node. This is helpful because if you have JavaScript that manipulates HTML elements, you cannot tell which properties are associated with which elements by looking at the source code alone.

[[Category:Module 6]]

Node.JS

2014-10-03T08:10:37Z

Shane: /* Installing Packages */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The unofficial instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably ''use-nave-no-shell.sh''.

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

''npm'' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

'''Note:''' When using npm to install local dependencies, '''''do not use sudo'''''. It will screw up your file permissions.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O. There may be quiz questions about this code.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

Here is a good slideshow introducing Node.JS as well as some security vulnerabilities to look out for: http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

[[Category:Module 7]]

Node.JS

2014-10-03T08:10:13Z

Shane: /* Installing Packages */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The unofficial instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably ''use-nave-no-shell.sh''.

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

''npm'' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

'''Note:''' When using npm to install local dependencies, '''''please do not use sudo'''''.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O. There may be quiz questions about this code.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

Here is a good slideshow introducing Node.JS as well as some security vulnerabilities to look out for: http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

[[Category:Module 7]]

Node.JS

2014-10-03T08:08:28Z

Shane: /* Installing Node.JS */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The unofficial instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably ''use-nave-no-shell.sh''.

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

'''npm''' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O. There may be quiz questions about this code.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

Here is a good slideshow introducing Node.JS as well as some security vulnerabilities to look out for: http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

[[Category:Module 7]]

Node.JS

2014-10-03T08:07:53Z

Shane: /* Installing Node.JS */

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The official instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably ''use-nave-no-shell.sh''.

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

'''npm''' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O. There may be quiz questions about this code.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

Here is a good slideshow introducing Node.JS as well as some security vulnerabilities to look out for: http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

[[Category:Module 7]]

Node.JS

2014-10-03T08:07:12Z

Shane: /* Installing Node.JS */ Fixing Node.JS installation process. The one-liner I posted last year sadly doesn't work anymore.

AJAX is a useful technology for web applications that need to pull periodic updates from your server. But what do you do when you have thousands of clients all requesting data that changes real-time? A PHP+AJAX approach would choke. It is situations like these that Node.JS comes to the rescue.

== Non-Blocking I/O ==

You dabbled in the concept of non-blocking I/O when you implemented AJAX in the previous JavaScript module. Node.JS uses this execution model at its core.

The core idea is the use of '''''anonymous functions''''' as ''callbacks'' for processing the results of intensive operations. Consider the pseudo-code:

<source lang="javascript">
// Blocking I/O Pseudo-Code

var data = database.query("select * from news");
print data[0].title;
</source>

The above pseudo-code queries a database, saves the result of the query in a variable named ''data'', and then prints out the first title in ''data''. The problem arises when multiple clients all want to access the server at the same time. ''In a blocking I/O model, a client needs to wait until all other clients are finished before it can start its process.'' With intensive operations and thousands of clients, this can easily crash your server!

The solution is to use ''non-blocking I/O''. Consider this revised pseudo-code:

<source lang="javascript">
// Non-Blocking I/O Pseudo-Code

database.query("select * from news", function(data){
print data[0].title;
});
</source>

The revised pseudo-code achieves the same end result as the first version. However, ''it allows other clients to perform tasks while this process is waiting for the database to be queried!'' The code occurs in two parts: first, we start the query. Second, ''when the query is complete'', our '''anonymous callback function''' is executed. In Node.JS, callback functions are usually passed one or more parameters.

Better yet, with non-blocking I/O, you have no concurrency issues, because everything runs in just one thread. Nifty!

== Installing Node.JS ==

You can get Node.JS from yum or apt-get, but the versions are going to be out dated. Remember that Node.JS is a rapidly changing language, so a version of Node from last year is going to be drastically different than a version of Node today.

The official instructions for installing Node.JS can be found here: https://gist.github.com/isaacs/579814

There are several choices, but my favorite is probably *use-nave-no-shell.sh*.

== Your First Node.JS Application: Hello World ==

Let's try running the example application given on the front page of nodejs.org:

<source lang="javascript">
var http = require('http');
http.createServer(function (req, res) {
res.writeHead(200, {
'Content-Type': 'text/plain'
});
res.end('Hello World\n');
}).listen(1337);
console.log('Server running at http://localhost:1337/');
</source>

Paste the example into a file named `hello.js`, and then run it by calling `node hello.js`. You should now be able to see your Hello World by visiting your server at port 1337! (Press ^C to stop the application.) '''Note:''' If you're running the code from your EC2 instance, you will need to open port 1337.

Let's walk through each line in the above example.

* <code>var http = require('http');</code> enables us to use Node's built-in HTTP server. We've been spoiled that languages like PHP automatically load all of the libraries that we need. However, '''''most functionality in Node.JS is NOT loaded by default.''''' When you want to use any non-fundamental feature of Node, you need to ''require'' it into a variable, as this example does with the HTTP package. You should be familiar with this concept when you needed to use ArrayList and other specialty packages in Java in CSE 132.
* <code>http.createServer(function (req, res) { ... }).listen(1337);</code> uses the HTTP server API to listen for HTTP connections on port 1337. The anonymous callback function will be called whenever a connection is made.
* <code>res.writeHead(200, { 'Content-Type': 'text/plain' });</code> specifies the Content-Type header to be "text/plain".
* <code>res.end('Hello World\n');</code> writes "Hello World" to the response.

Note the use of non-blocking I/O, even in this one little example. ''Whenever a connection is made, the callback function will be called and passed parameters associated with that connection.''

== A Static Fileserver Using Node.JS ==

Node.JS does not automatically serve up static files in the way that an Apache/PHP does. We need to either use an extension that handles this for us, like Express, or we need to write our own code to make a simple static fileserver. The latter option is really not all that difficult, and it gives good insight into how a static fileserver works.

=== Installing Packages ===

In order for the example code below to work, you need to install the ''mime'' package. To do this, '''cd to the working directory where you will save your Node.JS JavaScript file''' and run:

<source lang="bash">$ npm install mime</source>

'''npm''' is the package manager for Node.JS. Unlike all of the package managers we've used up to this point, ''npm'' installs dependencies locally, ''not'' globally. This means that you can have two different projects using different versions of the same package. ''npm'' will create a ''node_modules'' directory in the CWD and will install the packages into it.

=== Static Fileserver Code ===

The following code will make an HTTP server on port 3456 that serves up all static files in <STATIC DIRECTORY NAME> relative to app.js.

'''Make an attempt to understand this code.''' It's important that you are comfortable with the non-blocking nature, as well as how we handle file I/O. There may be quiz questions about this code.

<source lang="javascript">
// Require the functionality we need to use:
var http = require('http'),
url = require('url'),
path = require('path'),
mime = require('mime'),
path = require('path'),
fs = require('fs');

// Make a simple fileserver for all of our static content.
// Everything underneath <STATIC DIRECTORY NAME> will be served.
var app = http.createServer(function(req, resp){
var filename = path.join(__dirname, "<STATIC DIRECTORY NAME>", url.parse(req.url).pathname);
(fs.exists || path.exists)(filename, function(exists){
if (exists) {
fs.readFile(filename, function(err, data){
if (err) {
// File exists but is not readable (permissions issue?)
resp.writeHead(500, {
"Content-Type": "text/plain"
});
resp.write("Internal server error: could not read file");
resp.end();
return;
}

// File exists and is readable
var mimetype = mime.lookup(filename);
resp.writeHead(200, {
"Content-Type": mimetype
});
resp.write(data);
resp.end();
return;
});
}else{
// File does not exist
resp.writeHead(404, {
"Content-Type": "text/plain"
});
resp.write("Requested file not found: "+filename);
resp.end();
return;
}
});
});
app.listen(3456);
</source>

=== Port 3456 ===

We are running our server on port 3456 as opposed to the default web server port, which of course is 80. We therefore need to open our Node.JS application like this:

http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com:3456/path.extension

However, this won't work on the first time. ''Why?'' (Try to figure this out on your own before reading the next paragraph.)

We need to open port 3456 on our Amazon EC2 instance. Remember when you opened port 80 way back in Module 2? We need to do the same sort of procedure again now.

# Log into your EC2 management console
# Go to "Security Groups"
# Select your security group from Module 2
# Under "Inbound", create a custom TCP rule for port 3456, and apply your changes.

== Node.JS Security ==

Just because we're writing in JavaScript doesn't mean that we can forget about the security practices you've been learning in the last three months of CSE 330. XSS is still a problem, as is the use of ''eval'', CSRF attacks, and so on.

Here is a good slideshow introducing Node.JS as well as some security vulnerabilities to look out for: http://www.slideshare.net/ASF-WS/asfws-2012-nodejs-security-old-vulnerabilities-in-new-dresses-par-sven-vetsch

== Node.JS Conventions ==

There ought to be a standard way to save metadata about your app, right? Well, ''npm'' introduces a straightforward way to do this in the form of a ''package.json'' file.

To make your ''npm'' file with a step-by-step prompt, run in your project root directory:

<source lang="bash">
$ npm init
</source>

One nifty feature of ''package.json'' is the way it automatically handles dependencies. For example, you can put the following lines in your ''package.json'':

<source lang="javascript">
"dependencies": {
"mime": "~1.2.11",
"socket.io": "~0.9.16",
},
</source>

Then, back on the command line, when you run

<source lang="bash">
$ npm install
</source>

it automatically installs the dependencies for you! No more headaches of trying to figure out which modules you need to install; all that information is saved for you in your code base.

[[Category:Module 7]]

JavaScript

2014-09-19T02:10:20Z

Shane: /* innerHTML */

JavaScript is the most widely used scripting language for implementing client-side functionality in Web applications. Unlike PHP, JavaScript code is interpreted and executed in a client's web browser (not on the web server).

== JavaScript? Did you mean Java? ==

'''JavaScript''' is a prototype-based programming language focussed on web interactivity. It was first introduced in Netscape Navigator, and it in turn gave rise to what is now '''[http://www.ecmascript.org/ ECMAScript]'''. Originally, JavaScript was called "LiveScript". Sun, the developer of Java at the time, wanted a language that would complement its compiled Java language, and so LiveScript was renamed JavaScript.

Beyond that, '''Java and JavaScript are as similar as Ham and Hamster.'''

Java and JavaScript have similar syntax, but the under workings are quite different. For example, Java requires strict typing, but JavaScript allows for dynamic typing. Java is object-oriented, but JavaScript is prototype-oriented. Java is compiled, but JavaScript is interpreted. Java supports event listeners, but JavaScript makes them a fundamental part of the language. Java variables are scoped to the innermost method or loop, but JavaScript variables are scoped only to the innermost function.

== JavaScript Language Components ==

This section highlights some features of the JavaScript language that differentiate it from other languages. For a more comprehensive JavaScript tutorial, the following tutorials are both quality:

* [http://docs.webplatform.org/wiki/javascript/tutorials WebPlatform]: Great for learning JavaScript for the first time. Advocates best practices for modern JavaScript development.
* [http://www.quirksmode.org/js/contents.html QuirksMode]: More advanced than the WebPlatform tutorial, but it thoroughly covers the most powerful aspects of pure JavaScript and gives unparalleled advice on browser compatibility.

Advice: Do '''NOT''' Google for "JavaScript Tutorial". The first few hits advocate bad or outdated practices. Stick with the ones listed here.

=== Variables and Scope ===

To define a variable in JavaScript, use the '''var''' keyword.

<source lang="javascript">
var foo = "bar";
</source>

All variables are objects. In the case above, the variable '''foo''' is an object of the class '''String'''.

Notice that like PHP, you do not have to explicitly define a type for a variable like '''int''' or '''String'''; this is because JavaScript and PHP are ''dynamically typed languages''.

JavaScript code can access any variable higher in the “function tree”, but not vice-versa. This is called '''scope'''. ''All functions create their own scope.''

When you reference a variable, JavaScript will look up through the "function tree" until it finds the variable you asked for. This means that you could define variables of the same name as global variables inside of functions. For demonstration of concept:

<source lang="javascript">
var a = "hello";
var b = "world";

function sayGoodByeWorld(){
var a = "goodbye";

alert(a); // goodbye
alert(b); // world
}

sayGoodByeWorld();

alert(a); // hello
</source>

=== Object Literals ===

A very common way of storing and transporting data in JavaScript is by using objects. You can define an object with certain properties using an '''object literal''':

<source lang="javascript">
var apple = {
color: "red",
flavor: "sweet",
season: "autumn"
}

alert(apple.color); // red
</source>

=== Functions ===

To define a function in JavaScript, use the '''function''' keyword.

<source lang="javascript">
function sayHello(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Pass an argument to a function like this:

<source lang="javascript">
function sayHello(name){
alert("Hello, "+name);
}

sayHello("Todd"); // call the function and pass an argument
</source>

==== Functions are Objects ====

In JavaScript, functions are objects. This means that they can be assigned to variables, manipulated on the fly, and even passed as arguments to other functions! '''''This is an extremely important feature of JavaScript''''' that makes it such a robust language for web development.

You create a function variable like this:

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Observe that you can make [[#Variables and Scope|scope-dependent]] functions in this way.

=== Closures ===

{{DoctypeTV
|youtube_id=HaPlj796ngQ
|time=5m45s
|desc=JavaScript Closures
}}

A '''closure''' is a way to separate a certain snippet of JavaScript code from the global scope. This is useful if you do not want to "muck up" global variables. Closures are nothing more than anonymous functions that are called as soon as they are created:

<source lang="javascript">
var a = "hello";

(function(){
var b = "world";

alert(a); // hello
alert(b); // world
})();

alert(a); // hello
alert(b); // ReferenceError: b is not defined
</source>

{{JSFiddleExample
|title=Passing Variables to a Closure
|desc=This example demonstrates how you can "save" previous versions of a variable using closures. This is possible because of scoping and the fact that function variables can be returned as objects.
|fiddle_id=YURqa
}}

Most JavaScript libraries (like jQuery) write all of their code in a closure. What this means is that except for one or two variable names (jQuery or $), everything associated with the library is completely self-contained.

=== Prototypal Inheritance ===

JavaScript implements '''prototypal inheritance''', as opposed to a language like Java or C++, which implements '''classical inheritance'''. JavaScript is one of only a handful of languages implementing prototype-based inheritance.

Here's how it works. Every callable object (function) has a '''prototype'''. When instances of that object are created, their properties and methods are copied (inherited) from the prototype. Additionally, changes made to the prototype later in the program are "copied" to every instance.

For example, if you wanted to make a method on all strings that added a “!”, you could modify String’s prototype:

<source lang="javascript">
String.prototype.bang = function(){
return this+"!"; // Notice: the context is the instance itself
}

alert("Hello".bang()); // alerts Hello!
</source>

To "extend" an object, just copy its prototype to a new object. However, since classical inheritance and prototypal inheritance are different concepts, copying prototypes may have results that you don't expect. [http://beej.us/blog/data/javascript-prototypes-inheritance/ This article] seems to have a pretty good explanation with example implementations.

=== Context ===

{{DoctypeTV
|youtube_id=0a4r4bm1nQA
|time=4m32s
|desc=The ''this'' Variable in JavaScript
}}

Every function is called on a certain object, which is not necessarily the same object in which it was defined. This is called '''context'''.

To call a function on an arbitrary context, use either '''call''' or '''apply'''. ''call'' takes a list of arguments, while ''apply'' takes them all in an array.

To access the current context, use the '''this''' keyword. Demonstration of concept:

<source lang="javascript">
var sayThisColor = function(){
alert(this.color);
}

var apple = { color: "red" }

sayThisColor(); // undefined
sayThisColor.call(apple); // red
</source>

== Events ==

Events are really what make JavaScript such a powerful language for web development.

Rather than being thread based, JavaScript is event based. Since all JavaScript code runs in a single thread, '''there are no concurrency issues'''. When an event occurs, JavaScript automatically calls the ''event callback'' as soon as all previous events' callbacks have finished executing.

Code in the form of a '''callback function''' is associated with events via a '''listener'''. For example, the following JavaScript causes ''sayHello()'' (the callback function) to be run whenever the button with ID "hello" is clicked (the event):

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

document.getElementById("hello").addEventListener("click", sayHello, false);
</source>

{{JSFiddleExample
|title=Binding Callbacks to a Button Click
|fiddle_id=L8c4Z
|cse330=true
|desc=In this example, notice how we bind the callback function when the ''DOMContentLoaded'' event fires. This is because JavaScript requires that the button has been parsed by the browser before it can add event listeners to it.
}}

The '''addEventListener''' method takes three parameters:
* The event type
* The callback function
*: The callback function is passed one parameter: the event object.
* A boolean representing bubble (false) or capture (true) phase
*: You usually want Bubble phase. For more information on event phase, see [[#Event Phase]]

Note that versions of Internet Explorer prior to version 9 required that you use a different, albeit similar, function for assigning event listeners called '''attachEvent'''. attachEvent takes the same arguments as addEventListener, except you need to put '''on''' before the event type (e.g. "onclick"), and the third argument (phase) is not necessary.

It is perfectly valid to use an '''anonymous function''' as your callback function:

<source lang="javascript">
document.getElementById("hello").addEventListener("click", function(event){
alert("Hello, World! Event Type: "+event.type);
}, false);
</source>

QuirksMode has perhaps the best series of articles about the ins and outs of JavaScript events on the internet: http://www.quirksmode.org/js/contents.html#events

=== The Event Object ===

Callback functions are passed one argument: an ''event object''. You see above that one property of the event object is ''event.type''. To see the full list of properties of the event object, you could run the code:

<source lang="javascript">
document.getElementById("my_btn").addEventListener("click", function(event){
var strout = "";
for(var i in event){
strout += i + ": " + event[i] + "\n";
}
console.log(strout);
}, false);
</source>

Some of the most useful properties and methods include:
* '''event.target''' references the object on which the event occurred.
* '''event.currentTarget''' references the object whose listener is currently being processed.
*: ''Note:'' event.target and event.currentTarget might be the same or might be different, depending on whether you are listening for bubbled events.
* '''event.preventDefault()''' stops the normal result of the event from being executed. For example, if you listen for a form's ''submit'' event, you can call event.preventDefault() to stop the form from being submitted.
* '''event.stopPropagation()''' prevents any other event listeners from being executed. For more detail, read the section on Event Phase below.

For more detail on the event object, see [http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#interface-Event the W3C specification].

'''Note:''' If your callback function does not take any parameters, it will still run; you just won't have as easy of access to the event object.

=== Event Handlers and Memory Management ===

JavaScript is an automatically garbage-collected language, meaning that memory management is mostly taken care of for you. However, there are some instances when you need to be careful about creating "zombie" objects. One common "gotcha" instance of this is in event listeners.

For example, consider the code:

<source lang="javascript">
// Declare an object
var myObject = {
fn: function(event) {
alert("Hello World");
}
};

// Make a property of that object listen for some event
document.getElementById("my-div").addEventListener("click", myObject.fn, false);
</source>

In the above example, myObject will ''not'' be garbage collected, even if it goes out of scope, so long as its property ''fn'' is a listener for an event on the div. In order to release myObject from memory, you need o do the following:

<source lang="javascript">
// If we want myObject to be garbage collected when it leaves scope, we need to remove the event listener.
document.getElementById("my-div").removeEventListener("click", myObject.fn, false);
</source>

=== Event Phase ===

In JavaScript, events occur in two phases: '''Capture Phase''' and '''Bubble Phase'''. Consider the following HTML document:

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head><title>Event Test</title></head>
<body>
<div id="box">
<button id="btn">
Hello
</button>
</div>
</body>
</html>
</source>

Suppose the user clicks on the "Hello" button. Events will be fired in the following order:

# Capture Phase CLICK on the Document
# Capture Phase CLICK on the Body
# Capture Phase CLICK on the Div#box
# Target Phase CLICK on the Button#btn
# Bubble Phase CLICK on the Div#box
# Bubble Phase CLICK on the Body
# Bubble Phase CLICK on the Document

{{JSFiddleExample
|title=Using Capture Phase to Enable or Disable a Toolbar
|fiddle_id=r32Dz
|desc=We bind an event in the capture phase to the div with ID ''toolbar''. When ''e.stopPropagation()'' is called, the event does not reach the buttons in the toolbar.
}}

Graphically, here is the order in which an event occurs in three generic nested elements:

[[File:EventPhase.gif]]

Why is this useful? Suppose you have a control panel (toolbar, etc) that you want to temporarily deactivate. (For example, Bold/Italic/Underline buttons on a graphic text editor that currently has no content.) You could keep bubble phase event listeners on your buttons, but prevent those events from occurring by stopping the event in the capture phase on the parent element before the event reaches your buttons! Example:

<source lang="javascript">
var disableToolbarFunc = function(e){
e.stopPropogation();
}

// To disable toolbar:
document.getElementById("box").addEventListener("click", disableToolbarFunc, true);

// To re-enable toolbar:
document.getElementById("box").removeEventListener("click", disableToolbarFunc, true);
</source>

'''Word of caution:''' Like many great things in web development, capture phase does not work in versions of Internet Explorer prior to version 9. There is no elegant substitution for older versions of Internet Explorer.

'''Note:''' When the event reaches the innermost element, there is no distinction between capture phase and bubble phase. The order in which event handlers were added to the element determines the order in which those callbacks are evaluated.

== Document Object Model ==

The '''Document Object Model (DOM)''' is what enables JavaScript to manipulate the content of your web page.

=== Nodes and Traversing the DOM ===

Each element on your page, whether it is a <nowiki><p>, <img/></nowiki>, a string of text, or even an attribute, is called a '''node'''.

Every node, except for the document itself, has exactly one parent. A single node may have multiple children.

Consider the following HTML code:

<source lang="html4strict">
<ul id="my-list">
<li class="fruits">Apples</li>
<li class="citrus">Oranges and <strong>Lemons</strong></li>
<li class="berries">Cherries</li>
</ul>
</source>

Here, the ul with ID "my-list" has three child '''element nodes''' (the three li's) as well as four child '''text nodes''' (the whitespace counts as a text node) and a child '''attribute node'''. The second LI has one child '''text node''' as well as one child '''element node''' and one child '''attribute node'''.

The DOM can be traversed in JavaScript. First, let's look at an example.

<source lang="javascript">
e = document.getElementById("my-list").getElementsByClassName("citrus")[0].lastChild.nodeName;
alert(e);
</source>

{{JSFiddleExample
|title=Currently Selected Radio Button
|fiddle_id=SHcng
|desc=In pure JavaScript, in order to determine the currently selected radio button, it is necessary to iterate over an array of pointers to all possible radio buttons, and stop when you find one that is "checked".
}}

The above snippet gets the element with class name '''citrus''' that is a child of the element with ID '''my-list''' (the second LI in the example above), and alerts the type of its second child node (which in this case is '''STRONG''').

Some common methods for traversing the DOM include:

* Node.parentNode
* Node.childNodes - returns an array of nodes
* Node.firstChild - same as Node.childNodes[0]
* Node.lastChild - same as Node.childNodes[Node.childNodes.length-1]
* Node.previousSibling
* Node.nextSibling

You can also search for child (including all descendants) using one of the following methods:

* Node.getElementsByTagName("tag-name") - returns an array of element nodes having the tag name '''tag-name''' that are descendants of Node
* Node.getElementById("id") - returns a single node having the ID '''id''' that is a descendant of Node
* Node.getElementsByName("what-name") - returns an array of element nodes having their '''name''' attribute set to '''what-name'''. Useful for radio buttons and other form elements.
* Node.getElementsByClassName("class") - returns an array of nodes having the class '''class'''
*: '''Note:''' As of October 2012, 82% of the browser market supports Node.getElementsByClassName ([http://caniuse.com/getelementsbyclassname more info]). In order to support the other 18%, you need to either add your own getElementsByClassName to Node's prototype or use a JavaScript library like jQuery or MooTools.

It is common in JavaScript to have long statements like the one in the example above, where you call methods on several objects in sequence.

=== Creating, Moving, and Removing Nodes ===

You will frequently find yourself wanting to modify the DOM. JavaScript provides methods that help you do this.

Consider the same HTML as above. If you wanted to add another element to the list, you could use this code:

<source lang="javascript">
var newLi = document.createElement("li"); // creates a node with the tag name li
newLi.appendChild(document.createTextNode("Broccoli"));
newLi.setAttribute("class", "veggies");
document.getElementById("my-list").appendChild(newLi);
</source>

If you wanted to remove the apples from the list, you could do:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").removeChild(apple);
</source>

If you wanted to move the apples to the end of the list, you could do this:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").appendChild(apple);
</source>

Notice that '''Node.append()''' both removes a node from its previous location ''and'' appends it to its new location, which is always going to be as the last child of the parent node.

In summary, here are the methods to know from this section:

* Node.append(otherNode) - removes otherNode from its current location in the DOM (if applicable) and then adds it as the last child of Node
* Node.removeChild(otherNode) - removes otherNode, a child of Node, from the DOM
* document.createElement("tag-name") - create a new node with the tag name "tag-name"
* document.createTextNode("text") - create a node containing only the string '''text'''
* Node.setAttribute("attribute", "value") - sets the attribute node of name "attribute" to "value"

=== DOM Shortcuts ===

In the above sections, we have been creating, reading, modifying, and deleting Nodes. This is the most "correct" way to change the content of a web page from inside JavaScript.

This section documents a few shortcuts that are not as "pure" as using Nodes but can be less confusing and cumbersome.

{{JSFiddleExample
|title=Displaying Information
|fiddle_id=Q3BPZ
|desc=This example shows how to use some of the shortcut methods for using JavaScript to display information on the page.
}}

==== textContent ====

Using textContent to display information is probably the easiest method out there. For example, the following code overwrites whatever is in the element with ID "holder" with the string "Hello World":

<source lang="javascript">
document.getElementById("holder").textContent = "Hello World";
</source>

If you wanted to instead append the text, simply use '''+=''' instead of '''=''':

<source lang="javascript">
document.getElementById("holder").textContent += " - Later, he said Hello World - ";
</source>

Note that textContent displays strings literally; that is, it does not allow for HTML. Setting the textContent property also removes any HTML that may have already been in that element.

==== innerHTML ====

If you need to use HTML in your output but don't want to use the method described earlier in this section, a straightforward strategy is to use the innerHTML property of an element. For example, the following code would add a paragraph saying "Hello World" to the element with ID "holder":

<source lang="javascript">
document.getElementById("holder").innerHTML += "<p>Hello World</p>";
</source>

'''Important:''' You need to be careful to prevent XSS-type attacks if you display information using innerHTML. For example, be sure to escape a user-supplied string before appending it to innerHTML.

=== JavaScript Inspectors ===

{{DoctypeTV
|youtube_id=PKzrmbN-pMg
|time=4m13s
|desc=Using Firebug, WebKit Inspector, and IE Developer Tools
}}

Various browsers and browser plugins give you, the developer, tools to debug your code, inspect the DOM, and much more. Using these tools is essential for an efficient workflow.

* '''Firebug'''. Firebug is a plugin for Firefox that is a toolkit full of web developer tools, one of which is a DOM inspector. To inspect the DOM of a web page, simply open the Firebug window while viewing the web page.
* '''WebKit Inspector'''. The WebKit Inspector, which is available in both Chrome and Safari, enables you to see the DOM tree and relationships between elements. However, its DOM inspection tools are not as robust as those of Firebug.
* '''Opera Dragonfly'''. The web browser Opera comes with a web developer toolkit similar to the WebKit Inspector called Dragonfly. It is important that you test your sites in Opera, because although Opera has only a small fraction of the desktop browser market, it is second only to WebKit on the mobile market. Opera also has extremely strong CSS support, so it is good for testing for bugs in your CSS.

All of the above-mentioned tools enable you to look at the DOM of your web page and find what properties and methods are associated with each node. This is helpful because if you have JavaScript that manipulates HTML elements, you cannot tell which properties are associated with which elements by looking at the source code alone.

[[Category:Module 6]]

JavaScript

2014-09-19T02:06:23Z

Shane: /* Events */ Fixing broken link

JavaScript is the most widely used scripting language for implementing client-side functionality in Web applications. Unlike PHP, JavaScript code is interpreted and executed in a client's web browser (not on the web server).

== JavaScript? Did you mean Java? ==

'''JavaScript''' is a prototype-based programming language focussed on web interactivity. It was first introduced in Netscape Navigator, and it in turn gave rise to what is now '''[http://www.ecmascript.org/ ECMAScript]'''. Originally, JavaScript was called "LiveScript". Sun, the developer of Java at the time, wanted a language that would complement its compiled Java language, and so LiveScript was renamed JavaScript.

Beyond that, '''Java and JavaScript are as similar as Ham and Hamster.'''

Java and JavaScript have similar syntax, but the under workings are quite different. For example, Java requires strict typing, but JavaScript allows for dynamic typing. Java is object-oriented, but JavaScript is prototype-oriented. Java is compiled, but JavaScript is interpreted. Java supports event listeners, but JavaScript makes them a fundamental part of the language. Java variables are scoped to the innermost method or loop, but JavaScript variables are scoped only to the innermost function.

== JavaScript Language Components ==

This section highlights some features of the JavaScript language that differentiate it from other languages. For a more comprehensive JavaScript tutorial, the following tutorials are both quality:

* [http://docs.webplatform.org/wiki/javascript/tutorials WebPlatform]: Great for learning JavaScript for the first time. Advocates best practices for modern JavaScript development.
* [http://www.quirksmode.org/js/contents.html QuirksMode]: More advanced than the WebPlatform tutorial, but it thoroughly covers the most powerful aspects of pure JavaScript and gives unparalleled advice on browser compatibility.

Advice: Do '''NOT''' Google for "JavaScript Tutorial". The first few hits advocate bad or outdated practices. Stick with the ones listed here.

=== Variables and Scope ===

To define a variable in JavaScript, use the '''var''' keyword.

<source lang="javascript">
var foo = "bar";
</source>

All variables are objects. In the case above, the variable '''foo''' is an object of the class '''String'''.

Notice that like PHP, you do not have to explicitly define a type for a variable like '''int''' or '''String'''; this is because JavaScript and PHP are ''dynamically typed languages''.

JavaScript code can access any variable higher in the “function tree”, but not vice-versa. This is called '''scope'''. ''All functions create their own scope.''

When you reference a variable, JavaScript will look up through the "function tree" until it finds the variable you asked for. This means that you could define variables of the same name as global variables inside of functions. For demonstration of concept:

<source lang="javascript">
var a = "hello";
var b = "world";

function sayGoodByeWorld(){
var a = "goodbye";

alert(a); // goodbye
alert(b); // world
}

sayGoodByeWorld();

alert(a); // hello
</source>

=== Object Literals ===

A very common way of storing and transporting data in JavaScript is by using objects. You can define an object with certain properties using an '''object literal''':

<source lang="javascript">
var apple = {
color: "red",
flavor: "sweet",
season: "autumn"
}

alert(apple.color); // red
</source>

=== Functions ===

To define a function in JavaScript, use the '''function''' keyword.

<source lang="javascript">
function sayHello(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Pass an argument to a function like this:

<source lang="javascript">
function sayHello(name){
alert("Hello, "+name);
}

sayHello("Todd"); // call the function and pass an argument
</source>

==== Functions are Objects ====

In JavaScript, functions are objects. This means that they can be assigned to variables, manipulated on the fly, and even passed as arguments to other functions! '''''This is an extremely important feature of JavaScript''''' that makes it such a robust language for web development.

You create a function variable like this:

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

sayHello(); // call the function
</source>

Observe that you can make [[#Variables and Scope|scope-dependent]] functions in this way.

=== Closures ===

{{DoctypeTV
|youtube_id=HaPlj796ngQ
|time=5m45s
|desc=JavaScript Closures
}}

A '''closure''' is a way to separate a certain snippet of JavaScript code from the global scope. This is useful if you do not want to "muck up" global variables. Closures are nothing more than anonymous functions that are called as soon as they are created:

<source lang="javascript">
var a = "hello";

(function(){
var b = "world";

alert(a); // hello
alert(b); // world
})();

alert(a); // hello
alert(b); // ReferenceError: b is not defined
</source>

{{JSFiddleExample
|title=Passing Variables to a Closure
|desc=This example demonstrates how you can "save" previous versions of a variable using closures. This is possible because of scoping and the fact that function variables can be returned as objects.
|fiddle_id=YURqa
}}

Most JavaScript libraries (like jQuery) write all of their code in a closure. What this means is that except for one or two variable names (jQuery or $), everything associated with the library is completely self-contained.

=== Prototypal Inheritance ===

JavaScript implements '''prototypal inheritance''', as opposed to a language like Java or C++, which implements '''classical inheritance'''. JavaScript is one of only a handful of languages implementing prototype-based inheritance.

Here's how it works. Every callable object (function) has a '''prototype'''. When instances of that object are created, their properties and methods are copied (inherited) from the prototype. Additionally, changes made to the prototype later in the program are "copied" to every instance.

For example, if you wanted to make a method on all strings that added a “!”, you could modify String’s prototype:

<source lang="javascript">
String.prototype.bang = function(){
return this+"!"; // Notice: the context is the instance itself
}

alert("Hello".bang()); // alerts Hello!
</source>

To "extend" an object, just copy its prototype to a new object. However, since classical inheritance and prototypal inheritance are different concepts, copying prototypes may have results that you don't expect. [http://beej.us/blog/data/javascript-prototypes-inheritance/ This article] seems to have a pretty good explanation with example implementations.

=== Context ===

{{DoctypeTV
|youtube_id=0a4r4bm1nQA
|time=4m32s
|desc=The ''this'' Variable in JavaScript
}}

Every function is called on a certain object, which is not necessarily the same object in which it was defined. This is called '''context'''.

To call a function on an arbitrary context, use either '''call''' or '''apply'''. ''call'' takes a list of arguments, while ''apply'' takes them all in an array.

To access the current context, use the '''this''' keyword. Demonstration of concept:

<source lang="javascript">
var sayThisColor = function(){
alert(this.color);
}

var apple = { color: "red" }

sayThisColor(); // undefined
sayThisColor.call(apple); // red
</source>

== Events ==

Events are really what make JavaScript such a powerful language for web development.

Rather than being thread based, JavaScript is event based. Since all JavaScript code runs in a single thread, '''there are no concurrency issues'''. When an event occurs, JavaScript automatically calls the ''event callback'' as soon as all previous events' callbacks have finished executing.

Code in the form of a '''callback function''' is associated with events via a '''listener'''. For example, the following JavaScript causes ''sayHello()'' (the callback function) to be run whenever the button with ID "hello" is clicked (the event):

<source lang="javascript">
var sayHello = function(){
alert("Hello World");
}

document.getElementById("hello").addEventListener("click", sayHello, false);
</source>

{{JSFiddleExample
|title=Binding Callbacks to a Button Click
|fiddle_id=L8c4Z
|cse330=true
|desc=In this example, notice how we bind the callback function when the ''DOMContentLoaded'' event fires. This is because JavaScript requires that the button has been parsed by the browser before it can add event listeners to it.
}}

The '''addEventListener''' method takes three parameters:
* The event type
* The callback function
*: The callback function is passed one parameter: the event object.
* A boolean representing bubble (false) or capture (true) phase
*: You usually want Bubble phase. For more information on event phase, see [[#Event Phase]]

Note that versions of Internet Explorer prior to version 9 required that you use a different, albeit similar, function for assigning event listeners called '''attachEvent'''. attachEvent takes the same arguments as addEventListener, except you need to put '''on''' before the event type (e.g. "onclick"), and the third argument (phase) is not necessary.

It is perfectly valid to use an '''anonymous function''' as your callback function:

<source lang="javascript">
document.getElementById("hello").addEventListener("click", function(event){
alert("Hello, World! Event Type: "+event.type);
}, false);
</source>

QuirksMode has perhaps the best series of articles about the ins and outs of JavaScript events on the internet: http://www.quirksmode.org/js/contents.html#events

=== The Event Object ===

Callback functions are passed one argument: an ''event object''. You see above that one property of the event object is ''event.type''. To see the full list of properties of the event object, you could run the code:

<source lang="javascript">
document.getElementById("my_btn").addEventListener("click", function(event){
var strout = "";
for(var i in event){
strout += i + ": " + event[i] + "\n";
}
console.log(strout);
}, false);
</source>

Some of the most useful properties and methods include:
* '''event.target''' references the object on which the event occurred.
* '''event.currentTarget''' references the object whose listener is currently being processed.
*: ''Note:'' event.target and event.currentTarget might be the same or might be different, depending on whether you are listening for bubbled events.
* '''event.preventDefault()''' stops the normal result of the event from being executed. For example, if you listen for a form's ''submit'' event, you can call event.preventDefault() to stop the form from being submitted.
* '''event.stopPropagation()''' prevents any other event listeners from being executed. For more detail, read the section on Event Phase below.

For more detail on the event object, see [http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#interface-Event the W3C specification].

'''Note:''' If your callback function does not take any parameters, it will still run; you just won't have as easy of access to the event object.

=== Event Handlers and Memory Management ===

JavaScript is an automatically garbage-collected language, meaning that memory management is mostly taken care of for you. However, there are some instances when you need to be careful about creating "zombie" objects. One common "gotcha" instance of this is in event listeners.

For example, consider the code:

<source lang="javascript">
// Declare an object
var myObject = {
fn: function(event) {
alert("Hello World");
}
};

// Make a property of that object listen for some event
document.getElementById("my-div").addEventListener("click", myObject.fn, false);
</source>

In the above example, myObject will ''not'' be garbage collected, even if it goes out of scope, so long as its property ''fn'' is a listener for an event on the div. In order to release myObject from memory, you need o do the following:

<source lang="javascript">
// If we want myObject to be garbage collected when it leaves scope, we need to remove the event listener.
document.getElementById("my-div").removeEventListener("click", myObject.fn, false);
</source>

=== Event Phase ===

In JavaScript, events occur in two phases: '''Capture Phase''' and '''Bubble Phase'''. Consider the following HTML document:

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head><title>Event Test</title></head>
<body>
<div id="box">
<button id="btn">
Hello
</button>
</div>
</body>
</html>
</source>

Suppose the user clicks on the "Hello" button. Events will be fired in the following order:

# Capture Phase CLICK on the Document
# Capture Phase CLICK on the Body
# Capture Phase CLICK on the Div#box
# Target Phase CLICK on the Button#btn
# Bubble Phase CLICK on the Div#box
# Bubble Phase CLICK on the Body
# Bubble Phase CLICK on the Document

{{JSFiddleExample
|title=Using Capture Phase to Enable or Disable a Toolbar
|fiddle_id=r32Dz
|desc=We bind an event in the capture phase to the div with ID ''toolbar''. When ''e.stopPropagation()'' is called, the event does not reach the buttons in the toolbar.
}}

Graphically, here is the order in which an event occurs in three generic nested elements:

[[File:EventPhase.gif]]

Why is this useful? Suppose you have a control panel (toolbar, etc) that you want to temporarily deactivate. (For example, Bold/Italic/Underline buttons on a graphic text editor that currently has no content.) You could keep bubble phase event listeners on your buttons, but prevent those events from occurring by stopping the event in the capture phase on the parent element before the event reaches your buttons! Example:

<source lang="javascript">
var disableToolbarFunc = function(e){
e.stopPropogation();
}

// To disable toolbar:
document.getElementById("box").addEventListener("click", disableToolbarFunc, true);

// To re-enable toolbar:
document.getElementById("box").removeEventListener("click", disableToolbarFunc, true);
</source>

'''Word of caution:''' Like many great things in web development, capture phase does not work in versions of Internet Explorer prior to version 9. There is no elegant substitution for older versions of Internet Explorer.

'''Note:''' When the event reaches the innermost element, there is no distinction between capture phase and bubble phase. The order in which event handlers were added to the element determines the order in which those callbacks are evaluated.

== Document Object Model ==

The '''Document Object Model (DOM)''' is what enables JavaScript to manipulate the content of your web page.

=== Nodes and Traversing the DOM ===

Each element on your page, whether it is a <nowiki><p>, <img/></nowiki>, a string of text, or even an attribute, is called a '''node'''.

Every node, except for the document itself, has exactly one parent. A single node may have multiple children.

Consider the following HTML code:

<source lang="html4strict">
<ul id="my-list">
<li class="fruits">Apples</li>
<li class="citrus">Oranges and <strong>Lemons</strong></li>
<li class="berries">Cherries</li>
</ul>
</source>

Here, the ul with ID "my-list" has three child '''element nodes''' (the three li's) as well as four child '''text nodes''' (the whitespace counts as a text node) and a child '''attribute node'''. The second LI has one child '''text node''' as well as one child '''element node''' and one child '''attribute node'''.

The DOM can be traversed in JavaScript. First, let's look at an example.

<source lang="javascript">
e = document.getElementById("my-list").getElementsByClassName("citrus")[0].lastChild.nodeName;
alert(e);
</source>

{{JSFiddleExample
|title=Currently Selected Radio Button
|fiddle_id=SHcng
|desc=In pure JavaScript, in order to determine the currently selected radio button, it is necessary to iterate over an array of pointers to all possible radio buttons, and stop when you find one that is "checked".
}}

The above snippet gets the element with class name '''citrus''' that is a child of the element with ID '''my-list''' (the second LI in the example above), and alerts the type of its second child node (which in this case is '''STRONG''').

Some common methods for traversing the DOM include:

* Node.parentNode
* Node.childNodes - returns an array of nodes
* Node.firstChild - same as Node.childNodes[0]
* Node.lastChild - same as Node.childNodes[Node.childNodes.length-1]
* Node.previousSibling
* Node.nextSibling

You can also search for child (including all descendants) using one of the following methods:

* Node.getElementsByTagName("tag-name") - returns an array of element nodes having the tag name '''tag-name''' that are descendants of Node
* Node.getElementById("id") - returns a single node having the ID '''id''' that is a descendant of Node
* Node.getElementsByName("what-name") - returns an array of element nodes having their '''name''' attribute set to '''what-name'''. Useful for radio buttons and other form elements.
* Node.getElementsByClassName("class") - returns an array of nodes having the class '''class'''
*: '''Note:''' As of October 2012, 82% of the browser market supports Node.getElementsByClassName ([http://caniuse.com/getelementsbyclassname more info]). In order to support the other 18%, you need to either add your own getElementsByClassName to Node's prototype or use a JavaScript library like jQuery or MooTools.

It is common in JavaScript to have long statements like the one in the example above, where you call methods on several objects in sequence.

=== Creating, Moving, and Removing Nodes ===

You will frequently find yourself wanting to modify the DOM. JavaScript provides methods that help you do this.

Consider the same HTML as above. If you wanted to add another element to the list, you could use this code:

<source lang="javascript">
var newLi = document.createElement("li"); // creates a node with the tag name li
newLi.appendChild(document.createTextNode("Broccoli"));
newLi.setAttribute("class", "veggies");
document.getElementById("my-list").appendChild(newLi);
</source>

If you wanted to remove the apples from the list, you could do:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").removeChild(apple);
</source>

If you wanted to move the apples to the end of the list, you could do this:

<source lang="javascript">
var apple = document.getElementById("my-list").getElementsByClassName("fruits")[0];
document.getElementById("my-list").appendChild(apple);
</source>

Notice that '''Node.append()''' both removes a node from its previous location ''and'' appends it to its new location, which is always going to be as the last child of the parent node.

In summary, here are the methods to know from this section:

* Node.append(otherNode) - removes otherNode from its current location in the DOM (if applicable) and then adds it as the last child of Node
* Node.removeChild(otherNode) - removes otherNode, a child of Node, from the DOM
* document.createElement("tag-name") - create a new node with the tag name "tag-name"
* document.createTextNode("text") - create a node containing only the string '''text'''
* Node.setAttribute("attribute", "value") - sets the attribute node of name "attribute" to "value"

=== DOM Shortcuts ===

In the above sections, we have been creating, reading, modifying, and deleting Nodes. This is the most "correct" way to change the content of a web page from inside JavaScript.

This section documents a few shortcuts that are not as "pure" as using Nodes but can be less confusing and cumbersome.

{{JSFiddleExample
|title=Displaying Information
|fiddle_id=Q3BPZ
|desc=This example shows how to use some of the shortcut methods for using JavaScript to display information on the page.
}}

==== textContent ====

Using textContent to display information is probably the easiest method out there. For example, the following code overwrites whatever is in the element with ID "holder" with the string "Hello World":

<source lang="javascript">
document.getElementById("holder").textContent = "Hello World";
</source>

If you wanted to instead append the text, simply use '''+=''' instead of '''=''':

<source lang="javascript">
document.getElementById("holder").textContent += " - Later, he said Hello World - ";
</source>

Note that textContent displays strings literally; that is, it does not allow for HTML. Setting the textContent property also removes any HTML that may have already been in that element.

==== innerHTML ====

If you need to use HTML in your output but don't want to use the method described earlier in this section, a straightforward strategy is to use the innerHTML property of an element. For example, the following code would add a paragraph saying "Hello World" to the element with ID "holder":

<source lang="javascript">
document.getElementById("holder").innerHTML += "<p>Hello World</p>";
</source>

'''Important:''' You need to be careful to prevent XSS-type attacks if you display information using innerHTML. You should be sure, for example, that your JSON data is sanitized on the server.

=== JavaScript Inspectors ===

{{DoctypeTV
|youtube_id=PKzrmbN-pMg
|time=4m13s
|desc=Using Firebug, WebKit Inspector, and IE Developer Tools
}}

Various browsers and browser plugins give you, the developer, tools to debug your code, inspect the DOM, and much more. Using these tools is essential for an efficient workflow.

* '''Firebug'''. Firebug is a plugin for Firefox that is a toolkit full of web developer tools, one of which is a DOM inspector. To inspect the DOM of a web page, simply open the Firebug window while viewing the web page.
* '''WebKit Inspector'''. The WebKit Inspector, which is available in both Chrome and Safari, enables you to see the DOM tree and relationships between elements. However, its DOM inspection tools are not as robust as those of Firebug.
* '''Opera Dragonfly'''. The web browser Opera comes with a web developer toolkit similar to the WebKit Inspector called Dragonfly. It is important that you test your sites in Opera, because although Opera has only a small fraction of the desktop browser market, it is second only to WebKit on the mobile market. Opera also has extremely strong CSS support, so it is good for testing for bugs in your CSS.

All of the above-mentioned tools enable you to look at the DOM of your web page and find what properties and methods are associated with each node. This is helpful because if you have JavaScript that manipulates HTML elements, you cannot tell which properties are associated with which elements by looking at the source code alone.

[[Category:Module 6]]

Choosing a Platform

2014-09-04T03:51:57Z

Shane: /* Node.JS Cons */

You've learned a large variety of platforms in this course. Which one should you use? This page summarizes some of the pros and cons of each platform.

== PHP ==

[[PHP]] is a language built for server-side web development. You built a [[Module 2|file sharing application]] and a [[Module 3|news syndication site]] in PHP.

=== PHP Pros ===

* '''Largest support community:''' Easy to find help if you get stuck.
* '''Distribution:''' Runs on virtually any web server in existence.
* '''Easy to Debug:''' Because there is no framework involved and the PHP interpreter is robust, it is easier to pinpoint bugs and wrap your head around what is going on behind the scenes.

=== PHP Cons ===

* '''Language:''' Few people will say that PHP is the most elegant language known to mankind. The language makes it easy to fall into the trap of bad coding practices.
* '''Security:''' PHP does very little for you automatically in terms of web security.

== Django ==

[[Web Frameworks|Django]] is a web frameworks written in the [[Python]] scripting language. In more ways than not, it is the Python equivalent of [[wikipedia:Ruby on Rails|Ruby on Rails]].

=== Django Pros ===

* '''Less Code:''' Implementing common web design patterns, like social login or commenting, is usually as easy as a ''pip install''.
* '''Conventions:''' Django forces you to write neat and organized code, leading to better software engineering practices and scalability down the road.
* '''Security:''' Django automatically implements common security practices, leading to a more robust web application.

=== Django Cons ===

* '''Difficult to Debug:''' Django's high level of abstraction is a double-edged sword, because bugs and errors are sometimes difficult to find and can take hours to fix.
* '''Heavyweight:''' Django is designed for larger web applications, and it is not suitable for smaller projects with just one or two controllers.

== Bottle and Flask ==

Bottle is a web ''microframework'' written in the [[Python]] scripting language. Flask is similar option. Although you did not explicitly use Bottle or Flask during a module, it's worth listing on this page. In more ways than not, Bottle and Flask are the Python equivalents of the better-known [[wikipedia:Sinatra (software)|Sinatra]], a Ruby microframework.

=== Bottle and Flask Pros ===

* '''Lightweight:''' There are few enough files that you can find your way around and be in full control of your application logic.
* '''Access to Python Libraries:''' A lot of the things you do in Django you can do in Bottle and Flask, except that you have more control over the ways that they are implemented.

=== Bottle and Flask Cons ===

* '''Lack of Conventions:''' Bottle and Flask give you the tools you need to build maintainable code, but unlike Django, they don't force you to. It's easy to end up with Python scripts containing hundreds of lines of unrelated application logic.

== Node.JS and Express ==

[[Node.JS]] is a low-level implementation of JavaScript that enables you to write networked and web applications. Express is a Sinatra-like microframework that runs on top of Node.jS.

It is also worth bringing your attention to [http://www.meteor.com/ Meteor], a bleeding-edge framework for Node.JS that abstracts away client-server communications. (Watch the promo video; it's pretty awesome.)

=== Node.JS Pros ===

* '''Speed:''' Node.JS is the fastest of the options on this page. It is easy to scale up your Node.JS applications.
* '''Modern:''' Node.JS is also the newest of the options on this page, so most of the plugins you find for it use the best and latest practices.
* '''Language:''' With Node.JS, you can use just one language for both your server-side and client-side logic.
* '''Real-Time Options:''' Node.JS enables you to write real-time applications with ease, for example, with Socket.IO.

=== Node.JS Cons ===

* '''Lack of Conventions:''' Like Bottle, Flask, and most other microframeworks, Node.JS and Express don't force you to stick to predefined conventions, giving the potential to build messy code.
* '''Poor Error Handling:''' PHP and many other options run under tried-and-true Apache, so if your program throws an exception, other concurrent requests will still be processed. However, a single exception in Node.JS will crash your entire server. You therefore need to be extra careful in error handling, more so than in PHP, Django, and so on.

[[Category:Module 8]]

JavaScript Frameworks

2014-08-25T08:11:41Z

Shane: Adding "Former Content" category tag

There is a large variety of JavaScript frameworks. In this article, we document how to go about performing common tasks in Prototype, MooTools, Dojo (AMD), jQuery, and ExtJS.

== Task 1: Perform a Task on DOM Content Loaded ==

=== Prototype ===

<source lang="javascript">
document.observe("dom:loaded", function() {
alert("DOM Content Loaded!");
});
</source>

=== MooTools ===

<source lang="javascript">
window.addEvent('domready', function() {
alert("DOM Content Loaded!");
});
</source>

=== Dojo ===

<source lang="javascript">
require(["dojo/domReady!"], function() {
alert("DOM Content Loaded!");
});
</source>

=== jQuery ===

<source lang="javascript">
$(document).ready(function(){
alert("DOM Content Loaded!");
});
</source>

=== ExtJS ===

<source lang="javascript">
Ext.onReady(function(){
alert("DOM Content Loaded!");
});
</source>

== Task 2: Add a Click Listener to a Button and Alert the Button's Label ==

=== Prototype ===

<source lang="javascript">
$('myButton').observe('click', function(event) {
var element = event.element();
var text = element.textContent;
alert("You Clicked My Button: "+text);
});
</source>

=== MooTools ===

<source lang="javascript">
$('myButton').addEvent('click', function(){
var text = this.get('text');
alert("You Clicked My Button: "+text);
});
</source>

=== Dojo ===

<source lang="javascript">
require(["dojo/query"], function(query){
query("#myButton").on("click", function(e){
var text = this.textContent;
alert("You Clicked My Button: "+text);
});
});
</source>

=== jQuery ===

<source lang="javascript">
$("#myButton").click(function(){
var text = $(this).text();
alert("You Clicked My Button: "+text);
});
</source>

=== ExtJS ===

<source lang="javascript">
Ext.get("myButton").on("click", function(event, element, options){
var text = element.textContent; // option 1: use the DOM
var text = this.getHTML(); // option 2: use ExtJS's API
var text = Ext.get(element).getHTML(); // option 3: useful when the scope of the callback is not an Ext Element
alert("You Clicked My Button: "+text);
});

// Alternative syntax that also allows you to pass parameters:
Ext.get("myButton").on({
"click": {
fn: function(event, element, options){
var text = element.textContent;
alert("You Clicked My Button: "+text+" "+options.hello);
},
hello: "world"
}
});
</source>

== Task 3: Create a new list item containing a strong tag, and then append it to the document ==

=== Prototype ===

<source lang="javascript">
var li = Builder.node('li', {
title: "My New List Item"
}, [
Builder.node('strong', "To Do:"),
"Water The Garden"
]);
$("myList").appendChild(li);
</source>

=== MooTools ===

<source lang="javascript">
var li = new Element('li', {
title: "My New List Item"
});
var strong = new Element('strong');
strong.appendText("To Do:");
li.inject(strong);
li.appendText("Water the Garden");
$("myList").inject(li);
</source>

=== Dojo ===

<source lang="javascript">
require(["dojo/dom-construct"], function(domConstruct){
var li = domConstruct.create("li", {
title: "My New List Item",
innerHTML: "<strong>To Do:</strong> Water the Garden"
}, "myList");
});
</source>

=== jQuery ===

<source lang="javascript">
var li = $("<li><strong>To Do:</strong> Water the Garden</li>");
li.attr("title", "My New List Item");
$("#myList").append(li);
</source>

=== ExtJS ===

<source lang="javascript">
Ext.DomHelper.useDom = true; // optional: forces text node creation on strings rather than innerHTML manipulation

Ext.DomHelper.append("myList", {
tag: "li",
title: "My New List Item",
children: [
{ tag: "strong", html: "To Do: " },
"Water the Garden"
]
});
</source>

== References ==

Much of the content on this page was inspired by http://davidwalsh.name/mootools-jquery-dojo

[[Category:Module 6]]
[[Category:Former Content]]

Extensible Calendar

2014-08-25T08:08:51Z

Shane: Adding "Former Content" category tag

This page documents a tutorial for using the [http://ext.ensible.com/products/calendar/ Extensible Calendar Pro API] with Django as the back end.

== REST ==

The Extensible Calendar is going to connect to your server via AJAX calls. These calls conform to a web application paradigm known as '''REST''', or ''REpresentational State Transfer''. In particular, the application will automatically send requests with the following HTTP methods:

* '''GET''' when it wants to read something
* '''POST''' when it wants to create something
* '''PUT''' when it wants to change something
* '''DELETE''' when it wants to remove something

You recognize ''GET'' and ''POST'' from Module 2. All along, there were actually more than just these two request methods. REST simply takes advantage of all of them.

'''Note:''' In practice, since older browsers do not support the additional HTTP request methods required by REST, the actual implementation of ''PUT'' and ''DELETE'' will most likely be ''POST'' with an additional header defining the request type. The frameworks takes care of this difference under the hood.

== The Back End ==

First, we will set up the back end.

=== Creating the App with Source Control ===

Start by making a new Django project and app.

<source lang="bash">
$ django-admin.py startproject cse330calendar
$ cd cse330calendar
$ python manage.py startapp cal
</source>

Right now would be a good time to set up your IDE and source control. Create a new Komodo project in the "cse330calendar" directory, and set up a repo on the "cse330calendar" in SourceTree. Make frequent commits after each step of the process.

=== Initial Configuration ===

Go into ''settings.py'' and configure your database.

Enable the admin panel, which requires editing both ''settings.py'' and ''urls.py''. Add the ''cal'' application to the admin panel by creating ''cal/admin.py'' with the following content:

<source lang="python">
from django.contrib import admin

# We will create these models in the next step
from cal.models import Cal, Event

admin.site.register(Cal)
admin.site.register(Event)
</source>

Finally, add "cal" to the INSTALLED_APPS list in ''settings.py''.

=== Creating the Models ===

Set up the models required for the Extensible Calendar. We have already done this work for you. Copy the following code into your ''cal/models.py'' file.

<source lang="python">
from django.db import models

# Extensible wants two models: a "calendar" model and an "event" model.
# The "calendar" model represents a collection of events. Note that the end
# application supports multiple calendars in the same view, with the events
# in each calendar having a different background color.
#
# First we will define our calendar model, `Cal`, and then we will define
# our event model, `Event`.

class Cal(models.Model):
# Title of the calendar
title = models.CharField(max_length=50)

# Text description of the calendar
description = models.CharField(max_length=200)

# Color ID (1-32)
color = models.IntegerField(default=1)

# Boolean for whether the calendar is hidden by default
hidden = models.BooleanField(default=False)

class Event(models.Model):
# Declare a one-to-many relationship with Cal
cal = models.ForeignKey(Cal)

# Title of the event
title = models.CharField(max_length=50)

# DateTime of event start
start = models.DateTimeField()

# DateTime of event end
end = models.DateTimeField()

# Additional information that can be associated with an event:
loc = models.CharField(max_length=50) # Location
notes = models.CharField(max_length=200) # Notes
url = models.CharField(max_length=100) # URL
ad = models.BooleanField(default=False) # Is this an all-day event
rem = models.CharField(max_length=200) # Reminder
</source>

Finally, sync the db. After you do this, run the Django server and play around with the admin panel to make sure everything is in working order.

<source lang="bash">
$ python manage.py syncdb
</source>

=== Tastypie ===

Django does not come with REST support out of the box, so we need to install an additional framework. I have so far had success with '''[http://django-tastypie.readthedocs.org/en/latest/tutorial.html Tastypie]''', and I will be using Tastypie throughout this tutorial.

Start by installing Tastypie. There are instructions on the above link.

Your ''cal/api.py'' file can contain simply:

<source lang="python">
from tastypie.resources import ModelResource
from tastypie.paginator import Paginator
from cal.models import Cal, Event
from tastypie.fields import ToOneField

class CalResource(ModelResource):
class Meta:
queryset = Cal.objects.all()
paginator_class = Paginator

class EventResource(ModelResource):
cid = ToOneField(CalResource, "cal", full=True)
class Meta:
queryset = Event.objects.all()
paginator_class = Paginator
always_return_data = True
def dehydrate_cid(self, bundle):
return bundle.obj.cal.id
</source>

In the above snippet, we also are installing the ''Paginator'' utility. The Extensible Calendar requires that your data have pagination.

You will be modifying this file later on in this tutorial.

I also recommend making JSON the default output format for Tastypie. To do this, add the following line to your ''settings.py'' file:

<source lang="python">
TASTYPIE_DEFAULT_FORMATS = ['json']
</source>

While you're inside ''settings.py'', go ahead and add the following line as well. It may save you headaches down the road.

<source lang="python">
APPEND_SLASH=True
TASTYPIE_ALLOW_MISSING_SLASH=False
</source>

=== Routing ===

Let's create an empty ''index.html'' for our site. We will be modifying it later. Create the file in ''cal/templates/cal/index.html''. Then add it to ''cal/views.py'':

<source lang="python">
from django.shortcuts import render

def index(request):
return render(request, 'cal/index.html', {})
</source>

Also add it to ''cal/urls.py'':

<source lang="python">
from django.conf.urls import patterns, url

from cal import views

urlpatterns = patterns('',
url(r'^$', views.index, name='index')
)
</source>

Finally, add ''cal'' to your core ''urls.py'' file, which by now should look something like this:

<source lang="python">
from django.conf.urls import patterns, include, url
from cal.api import CalResource, EventResource

# Uncomment the next two lines to enable the admin:
from django.contrib import admin
admin.autodiscover()

# RESTful setup:
cal_resource = CalResource()
event_resource = EventResource()

urlpatterns = patterns('',
# Admin page
url(r'^admin/', include(admin.site.urls)),

# Templates
url(r'^', include('cal.urls')),

# RESTful URLs
url(r'^', include(cal_resource.urls)),
url(r'^', include(event_resource.urls)),
)
</source>

Try launching [http://localhost:8000/cal/ http://localhost:8000/cal/] in your browser. If everything is working properly, you should see a JSON representation of the data in your calendar.

=== Additional Work on the Back End ===

In the above example, we have implemented a read-only API for your calendar. You will need to use Django Auth to add users and to only reveal those calendars associated with a user. You will also need to implement the writing site of Tastypie. Almost all of these steps are in the Tastypie documentation.

== The Front End ==

So far, all of our work has been setting up our database, models, and server API. Now, we need to set up the front end that takes the JSON data and displays it in a GUI for the end user.

=== Installing Extensible ===

Start by downloading the Extensible library from the official web site. Save the download in ''cal/static/vendor/extensible''.

=== Extensible Config File ===

Copy the file at ''cal/static/vendor/extensible/Extensible-config.js'' into the ''cal/static/cal'' directory. Make the following changes:

# Change the Ext JS version on line 59 from '''4.2.0''' to '''4.1.1'''
# Comment out the line that includes the ''examples.js'' file (around line 179)

=== The Core Extensible Code ===

The examples on the Extensible documentation are helpful, but if you have never used Ext.JS before, it is easy to get lost. We have therefore written an ''index.html'' file and an ''app.js'' file to get you started.

Put the following code in ''cal/templates/cal/index.html'':

<source lang="html4strict">
<!DOCTYPE html>
{% load staticfiles %}
<html>
<head>
<title>Calendar</title>
<script type="text/javascript" src="{% static 'cal/Extensible-config.js' %}"></script>
<script type="text/javascript" src="{% static 'cal/app.js' %}"></script>
</head>
<body>

<div id="calbox" style="width:600px; height:400px;"></div>
<span id="app-msg" class="x-hidden"></span>

</body>
</html>
</source>

Put the following code in ''cal/static/cal/app.js'':

<source lang="javascript">
// Demo Extensible Calendar App
// Created for CSE 330S by Shane Carr
// Washington University in St. Louis

// Ext.JS wants you to use `Ext.define` when making a custom component.
Ext.define("CSE330.Calendar", {

// List the classes we use inside this component. This enables Ext.JS to load
// the files containing the definitions for these classes more efficiently.
requires: [],

// Main code for our component
constructor: function(){
// Set up the calendar store
this.calendarStore = Ext.create("Extensible.calendar.data.MemoryCalendarStore", {
autoLoad: true,
storeId: "Calendars",
proxy: {
type: "rest",
url: "/cal/",
startParam: "offset",
reader: {
type: "json",
root: "objects"
},
writer: {
type: "json",
nameProperty: "mapping"
}
}
});

// Set up the event store
this.eventStore = Ext.create("Extensible.calendar.data.MemoryEventStore", {
autoLoad: true,
storeId: "Events",
proxy: {
type: "rest",
url: "/event/",
startParam: "offset",
reader: {
type: "json",
root: "objects",
},
writer: {
type: "json",
nameProperty: "mapping"
}
}
});

// Set up the panel (view)
this.container = Ext.create('Extensible.calendar.CalendarPanel', {
renderTo: Ext.get("calbox"),
title: "My CSE330 Calendar",
width: "100%",
height: "100%",
id: "ext-calendar-main",
eventStore: this.eventStore,
calendarStore: this.calendarStore,
monthViewCfg: {
showHeader: true // show the days of the week
}
});

}
});

Ext.onReady(function(){
Ext.create("CSE330.Calendar");
});
</source>

You should be able to load [http://localhost:8000/ http://localhost:8000/] and see an empty calendar with all events you have thusfar put in your database. Exciting!

=== Additional Work on the Front End ===

Again, right now you have a read-only calendar without any sort of authentication. You need to tie these two pieces together.

If you look at the web inspector, you can see the requests that Extensible sends to your server when you try to create or modify an event using the front-end GUI. You need to make sure that your server and Extensible work together, both sending and receiving compatible formats.

You can implement log in and log out over AJAX via the Tastypie API. There are examples of how to do this in the documentation.

== Help with Debugging ==

Wrapping your head around Extensible, Django-Tastypie, and how to make the two frameworks talk to each other is a daunting task. The goal of this section is to help you learn how to debug this process.

=== Tutorial for Debugging the Create Event Mechanism ===

Let's first take a look at what happens when you try to add a new event via the Extensible GUI. When you click somewhere on the calendar, a little dialog opens, and in it you can specify the details of your event. However, when you press "Save", you see the following error in the console:

[[File:Extensible-Debugging-Unauthorized.png]]

Whoopsy daisy, we got a '''401 Unauthorized''' from the server! This means that Django-Tastypie thinks that we don't have enough permissions to edit this resource. We need to tell Tastypie that we do indeed have such permissions.

Let's temporarily open up the event to be globally editable. Refer to [http://django-tastypie.readthedocs.org/en/latest/tutorial.html#hooking-up-the-resource-s this section of the Tastypie guide] for an example of how to do this. Try figuring it out on your own before reading on.

You may have figured out that we need to specify these changes inside the ''cal/api.py'' file. In particular, if we add the following line to the ''Meta'' of the ''EventResource'' class, we in effect open up the resource to be globally editable.

<source lang="python">
# Add to the Event meta
authorization = Authorization()

# don't forget to put an import statement at the top of your file!
# from tastypie.authorization import Authorization
</source>

Great! Now let's try sending our request again. You'll see that you get a '''400 Bad Request''' error. That sounds scary! What's happening?

Let's head on over to the "Network" panel of the web inspector. Scroll to the bottom of the page to find the latest network request. Click it, and then choose the "Response" tab. You'll see something like this:

[[File:Extensible-Debugging-Response-Error.png]]

Hey, look! There's an error that we can fix. Let's look at it in more detail.

<source lang="text">
The 'cid' field was given data that was not a URI, not a dictionary-alike and does not have a 'pk' attribute: 1.
</source>

It sounds like Tastypie doesn't like whatever we're sending as the ''cid'' field. Let's go check on what we're actually sending. To do this, click on the "Headers" tab in the web inspector, and scroll down to "Request Payload".

[[File:Extensible-Debugging-Request-Payload.png]]

So we're clearly sending an integer calendar ID in the ''cid'' field. Why wouldn't Tastypie like this? I don't know; let's google the error!

Note that when we google something, we need to take specific field names out of our search. In our case, this is the "cid" field name as well as the value of "1". With that in mind, here are the hits:

[[File:Extensible-Debugging-Google-Hits.png]]

Look at that! We're clearly not the first people to run into this error.

The first Stack Overflow question looks verbose. Let's try the second one.

Hey, you find something that might provide you a clue!

[[File:Extensible-Debugging-StackOverflow-Answer.png]]

So we need to make our data field resemble one of those two options: either a dictionary with a "pk" field or a resource URL.

But how can we change the data format? We could do it from the Extensible side, or we could do it from the Tastypie side. Since we have greater control over Tastypie than Extensible, let's do it on the Tastypie side.

[http://django-tastypie.readthedocs.org/en/latest/resources.html The Resources guide for Tastypie] seems like a reasonable place to start. Read it and try to find the method that enables you to modify incoming data before Tastypie puts it into the model.

If you pinpointed the ''hydrate_FOO'' method, you were right! We simply need to define this method to transform the incoming data into the format that Tastypie wants.

Based on the "simple example" under ''hydrate_FOO'', the following definition seems reasonable.

<source lang="python">
# Part of the EventResource class

def hydrate_cid(self, bundle):
bundle.data["cid"] = "/cal/%d/" % bundle.data["cid"]
return bundle
</source>

Here, we are transforming the incoming ''cid'' number to a resource URL. For example, '''3''' will be transformed into '''/cal/3/''', the format that Tastypie wants according to the Stack Overflow post.

Okay, great! Let's save and see where we stand. Try creating an event through the GUI.

Hey, it looks like something happened! We received a ''201'' request back from the server! Let's take a peek at our database. Enter a Django shell and enter the following commands.

<source lang="python">
# Run these commands inside a Django shell
from cal.models import Cal, Event
map(lambda v: "%d %s" % (v.id, v.title), Event.objects.all())
</source>

The first line imports your modules into the shell, and the second line queries them via ORM and displays a list of the events with an ID and a title.

What do you see that's interesting? Hey, the "Banana Event" that I just added has ID 0! That's not cool. How do we fix it?

You may remember from the Django tutorial that Django will automatically assign the next available ID if you leave the ''id'' field empty in the new model. So, let's go ahead and transform all '''0''' IDs in Tastypie to '''None'''.

Try writing the necessary ''hydrate_id'' method. You should get something like the following:

<source lang="python">
# Part of the EventResource class

def hydrate_id(self, bundle):
if bundle.data["id"] == 0:
bundle.data["id"] = None
return bundle
</source>

Save and try again. What do you know, it works now! Each new event is now assigned a unique ID.

=== Next Steps ===

So hopefully you now have the knowledge you need to complete the module. In summary, when you need help, do the following:

# Look at the web inspector console
# Look at the network activity
# Look at the server log
# When you find an error that looks useful, google it (remove application-specific terms)
# When fixing the problem, refer to documentation
# When the problem is fixed, commit your code!

If you still need help, ask in class or come to office hours.

[[Category:Module 6]]
[[Category:Former Content]]

Ext JS

2014-08-25T08:08:22Z

Shane: Adding "Former Content" category tag

Ext JS is a ''JavaScript Framework''. It serves two main functions:

* Simplifies common operations that would take many lines in pure JavaScript
* Provides a selection of APIs for client-side gadgets

As you read through this article, you might find it helpful to play with some of the examples. Feel free to open up a new [http://jsfiddle.net/ JSFiddle], and where it says "Choose a Framework", select a recent version of Ext JS (version 4+).

== Using Ext JS in Your Site ==

For the purposes of this class, you can go ahead and hot-link Ext JS from Sencha's CDN (Content Delivery Network) by putting the following line in your <head> section:

<source lang="html4strict"><script src="//cdn.sencha.io/ext-4.2.0-gpl/ext-all-dev.js"></script></source>

That's it! You can now use Ext in your web application and follow along with the examples below.

=== A Note about File Size ===

While convenient, the above version of Ext JS from Sencha's CDN is ''huge'', over 5 MB. There are two main reasons for this:

# The above version is the '''dev''' version, which will give you helpful errors in the WebKit Inspector.
# The above version comes with a whole bunch of GUI tools that you probably will never be using.

A functionally equivalent version (minus the dev tools) that is 1 MB in size is also available from Sencha's CDN:

<source lang="html4strict"><script src="//cdn.sencha.io/ext-4.2.0-gpl/ext-all.js"></script></source>

However, if you don't plan on using the GUI features of Ext JS, you can use this 213 KB version:

<source lang="html4strict"><script src="//cdn.sencha.io/ext-4.2.0-gpl/ext.js"></script></source>

=== A Note about Licensing ===

Sencha's Ext JS platform, as well as most Ext APIs like [[#Extensible Calendar|Extensible's Calendar Pro]], is dual-licensed: you can use it under ''either'' the free [http://www.gnu.org/licenses/gpl.html GNU GPL] ''or'' a paid commercial license.

For the purposes of this course, you may use both Ext and all of its APIs for free under the terms of the GNU GPL. Indeed, you may continue using them for free even when you're developing a finished commercial application in real life. The catch is that it is not legal to use GNU GPL components in a finished product unless that project is also released under the GNU GPL. At that point, if you don't want to post your source code for others to see and modify, you'll need to pay Sencha for the license.

== Selecting an Element ==

In pure JavaScript, you used functions like ''document.getElementById()'' in order to select elements. The functions provided by the W3C work fine, but they are often limiting. Ext Core provides functionality that lets you make more advanced element selections in fewer lines.

=== Select by ID ===

To select an element by its ID and then perform an action on it, use '''Ext.fly(id)''':

<source lang="javascript">
// Add the class "required" to the element with id "myDiv":
Ext.fly("myDiv").addCls("required");
</source>

If you need to pass the element by reference, use '''Ext.get(id)''' instead:

<source lang="javascript">
// Add the class "required" to an element passed as an argument:
function setElementRequired( element ){
element.addCls("required");
}

// Call the above function, passing the element with id "myDiv" as the argument:
setElementRequired( Ext.get("myDiv") );
</source>

'''Note:''' Ext.fly() is faster than Ext.get(). However, Ext.fly() does not return a useful reference like Ext.get() does.

'''Note:''' element.addCls() adds a CSS class to that element. Prior to version 4 of Ext JS, it was simply element.addClass().

Calls to most Ext Element methods can be chained:

<source lang="javascript">
// Add the class "required" to the element with id "myDiv", then make it slowly fade away,
// all in one line:
Ext.fly("myDiv").addClass("required").ghost();

// The above line is functionally equivalent to:
Ext.fly("myDiv").addClass("required");
Ext.fly("myDiv").ghost();
</source>

{{JSFiddleExample
|title=Ext Core Select
|fiddle_id=M4LAn
|desc=This example illustrates one use of '''Ext.select()'''. Notice how the Ext selector for the "games" list works exactly the same as the selector for the "movies" list.
}}

=== Select by CSS Selector ===

CSS provides a syntax with which you are already familiar for selecting elements. Ext enables us to use CSS selectors within JavaScript to select elements via '''Ext.select(selector)'''. For example:

<source lang="javascript">
Ext.select("ul.games li:nth-child(2n)").addClass("required");
</source>

== Document Ready ==

When a browser loads JavaScript from a server, it runs the code as soon as it is treated. This can cause problems if your JavaScript depends on content later in the document. Consider the following example:

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head>
<title>JavaScript Execution Order</title>
<script>
alert( Ext.fly("myDiv").getHTML() );
</script>
</head>
<body>
<div id="myDiv">Hello World</div>
</body>
</html>
</source>

This raises the following exception: "Uncaught TypeError: Cannot read property 'textContent' of null." Why? ''Because the JavaScript is run before the Div is created!''

Ext solves this problem by enabling us to bind JavaScript code to the '''DOMContentLoaded''' event, which fires as soon as the document is loaded. (This is different from the '''load''' event, which fires when the ''entire web page'' is loaded, including images.) Simply use '''Ext.onReady''':

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head>
<title>JavaScript Execution Order</title>
<script>
Ext.onReady(function(){
alert( Ext.fly("myDiv").getHTML() );
});
</script>
</head>
<body>
<div id="myDiv">Hello World</div>
</body>
</html>
</source>

While you could do this in pure JavaScript, there are backwards compatibility issues with that approach which Ext handles behind the scenes.

== Utility Methods ==

Ext JS provides a variety of tools that enable you to perform other common tasks more easily.

=== Strings ===

{{JSFiddleExample
|title=String Utility Functions
|fiddle_id=2APe8
|desc=Demonstration of some of Ext's string utility functions.
}}

You can access Ext's String utility functions inside '''Ext.String'''. See the JSFiddle example for a demonstration. Some of the useful functions include:

* '''Ext.String.trim(str)''' trims ''str'' of leading whitespace.
* '''Ext.String.ellipsis(str, len)''' puts a (fake) ellipsis after ''len'' characters in ''str''
* '''Ext.String.escape(str)''' escapes ' and \ characters from ''str''
* '''Ext.String.format(format, arg0, arg1, ...)''' is Ext's version of ''sprintf'' (see the example for a demonstration)
* '''Ext.String.htmlEncode(str)''' encodes HTML special characters to make a string safe for display; similar to PHP's ''htmlentities()'' or ''htmlspecialchars()''
*: Note: This is aliased as '''Ext.util.Format.htmlEncode(str)'''

A complete list is available [http://localhost/~sffc/libraries/ext-4.1.1a/docs/index.html#!/api/Ext.String in the Ext JS documentation].

=== Creating DOM Elements ===

{{JSFiddleExample
|title=Creating Elements
|fiddle_id=Dgn5r
|desc=Demonstration of how Ext can create elements for the DOM.
}}

Ext JS makes it easy to create new DOM elements on the fly. The following code creates a new list item inside the unordered list with ID "myList":

<source lang="javascript">
Ext.DomHelper.useDom = true; // See next section for an explanation of this line

Ext.fly("myList").createChild({
tag: "li",
children: [
{
tag: "strong",
children: [
"To Do: "
]
},
"Water the garden"
]
});
</source>

The HTML generated by the above example would be:

<source lang="html4strict">
<li><strong>To Do: </strong>Water the Garden</li>
</source>

See the JSFiddle example for a demonstration.

==== Preventing HTML Injection ====

If you pass a string where Ext JS expects a child element, Ext will treat the string as an HTML string by default. This may open your application to XSS vulnerabilities if you are not careful. It is therefore recommended that you force Ext to create text nodes (thereby displaying strings literally) by putting this line at the top of your JavaScript file:

<source lang="javascript">
Ext.DomHelper.useDom = true;
</source>

=== Event Binding ===

{{JSFiddleExample
|title=Event Binding
|fiddle_id=JRRNC
|desc=How to use Ext to bind events. Gives examples of the `scope` and `options` parameters.
}}

Event binding is relatively straightforward using Ext:

<source lang="javascript">
Ext.fly("myButton").on("click", function(){
alert("You clicked my button");
});
</source>

The ''Ext.Element.on()'' method takes four parameters: the event type, the callback function, the scope of the callback function, and an options object. The callback function is passed three parameters: the event object, the target element, and the options object. For example:

<source lang="javascript">
var myObject = {
say: function(message){
alert(message);
}
};
Ext.fly("myButton").on("click", function(event, element, options){
this.say(options.message);
}), myObject, {
message: "Hello World"
});
</source>

=== Other Helpful Utilities ===

* '''Ext.Number.constrain(num, min, max)''' returns ''num'' iff it is between ''min'' and ''max'', or otherwise ''min'' if the number was smaller or ''max'' if the number was bigger
* '''Ext.Number.randomInt(min, max)''' returns a random integer between ''min'' and ''max'' inclusive.
* '''Ext.Object.getKeys(obj)''' returns all keys from the object literal ''obj''
* '''Ext.Object.each(obj, fn)''' iterates through the object literal ''obj'', calling ''fn(key, value)'' on each key/value pair.
* '''Ext.each(arr, fn)''' iterates through the array ''arr'', calling ''fn(value, index)'' on each item in the array.
* '''Ext.Array.map(arr, fn)''' returns an array containing the return value of ''fn(value, index)'' on each item in ''arr''.
* '''Ext.Array.min(arr)''' and '''.max(arr)''' and '''.mean(arr)''' return the maximum value, minimum value, and average value of ''arr'', respectively.
* '''Ext.toArray(non_arr)''' converts the iterable ''non_arr'' into a true Array. Especially useful for dealing with the ''arguments'' non-array: <code>alert( Ext.Array.toArray(arguments).join(" - ") );</code>

== AJAX ==

Ext Core makes AJAX easy. The following code fetches and parses the contents of '''data.json''' and then displays it on the page:

<source lang="javascript">
Ext.Ajax.request({
url: "data.json",
success: function(response){
var jsonData = Ext.decode(response);
Ext.fly("myDiv").setHTML( jsonData.description );
},
failure: function(respose){
console.log( "Error loading data; received error code " + response.status );
}
});
</source>

The following code sends a comment ID to '''comment_ajax.php''', which responds with a JSON object containing the comment's HTML:

<source lang="javascript">
Ext.Ajax.request({
url: "comment_ajax.php",
params: {
comment_id: 45
},
success: function(response){
var jsonData = Ext.decode(response);
// Sanitize the response before displaying it on the page:
var sanitizedComment = Ext.util.Format.htmlEncode( jsonData.contents );
Ext.fly("myDiv").setHTML( sanitizedComment );
},
failure: function(respose){
console.log( "Error loading data; received error code " + response.status );
}
});
</source>

'''Note:''' When parameters are given, Ext sends a POST request by default. If no parameters are given, Ext sends a GET request. If you want to send a GET request but also prevent caching, set the ''disableCaching'' option to ''true''.

'''Note:''' We use '''Ext.util.Format.htmlEncode(str)''' in the above example. This is Ext's closest equivalent to PHP's '''htmlencode($str)'''.

=== Submitting an Entire Form over AJAX ===

Ext gives us another handy feature for AJAX requests: it enables us to automatically send the entire contents of a form. For example, suppose we had the following form in HTML:

<source lang="html4strict">
<form id="myForm" action="login.php">
<label>Username: <input type="text" name="usr" /></label>
<label>Password: <input type="password" name="pwd" /></label>
</form>
</source>

We can submit this form asynchronously in just one line of Ext:

<source lang="javascript">
Ext.Ajax.request({ form: "myForm" });
</source>

In practice, you may want to bind a function that submits the form in this manner to the ''submit'' event of that form.

<source lang="javascript">
Ext.fly("myFormId").on("submit", function(event, element){
event.preventDefault();
Ext.Ajax.request({
form: element,
success: function(response) {
console.log("Success", response);
},
failure: function(response) {
console.log("Failure", response);
}
});
});
</source>

== Model View Controller ==

What really sets Ext.JS apart from other JavaScript libraries is the toolset it gives you to create GUI components. Ext.JS has an MVC engine that works on the front end of your application.

=== Models, Stores, and Proxies ===

Ext.JS adds a fourth concept to the MVC pattern: '''stores'''. A "store" is a collection of ''records'', where a ''record'' is an instance of a ''model''. In a lot of ways, if a model in Ext.JS is like a row in SQL, then a store in Ext.JS is like a table in SQL.

Ext.JS also introduces the concept of '''proxies''': a mechanism that syncs the data in your front-end application to the server. In Ext.JS, a proxy is typically associated with a store. Ext.JS conforms to the ''RESTful paradigm'' in web application development.

For an example of models, stores, and proxies, see [[Extensible Calendar]].

=== The Lino Framework ===

This wiki would not be complete without mentioning [http://www.lino-framework.org/ Lino], a framework that integrates Ext.JS into the Django stack. You may earn creative portion points on Module 6 if you choose to implement your project using the Lino framework.

[[Category:Module 6]]
[[Category:Former Content]]

Workflow

2014-06-13T20:35:13Z

Shane: /* Bitbucket */

The few minutes it takes to optimize your workflow will be the best few minutes you will spend in CSE 330 and your career. It is remarkable how many hours you can save just by using the best interface for text editing and deployment.

== Overview ==

There are going to be several aspects to our workflow in CSE 330, and we will be switching between multiple different programs. Here is how they all fit together.

=== Running Commands ===

''Mac OS X:'' You will be running commands on your local machine using '''Terminal''', which you can find in your Applications -> Utilities folder. You will be connecting to your server via SSH also in Terminal.

''Windows:'' You will be running commands on your local machine using '''Cygwin''', which you will install in the next section. You will be connecting to your server via SSH also in Cygwin.

=== Version Control ===

You will be using '''SourceTree''' as a frontend to the '''Git''' version control system. Git enables you to keep track of changes to your source code.

=== Text Editing ===

You will be using '''Komodo Edit''' as your text editing tool.

=== File Transfer ===

You will be using '''FileZilla''' as your tool for uploading files from your local working directory to your remote server.

=== Flowchart ===

If you are more visual, this flowchart might help:

[[File:CSE-330-Workflow.png]]

The flowchart illustrates 3 methods to copy files to your cloud instance: via your text editor, via an external SFTP client, and by cloning your remote Git repository. We will be primarily using '''Option 2''' in CSE 330 this semester.

In the flowchart, your ''Git Client'' is SourceTree and your ''Text Editor'' is Komodo. The ''SFTP Client'' could be FileZilla.

== Cygwin ==

{{RequiredInstructions|content=

'''Cygwin''' is a Linux Terminal emulator for Windows.

Mac OS X users do not need to install Cygwin since OS X itself is a derivative of Unix, which is an ancestor of Linux. The Terminal utility is all you need.

=== Installation ===

The CEC lab machines already have Cygwin installed. Follow these instructions to get Cygwin up and running on your personal PC.

# Run ''setup.exe'' from http://www.cygwin.com/
# Keep the Cygwin directory as the default, ''C:\cygwin''. Choose a place like ''C:\cygwin\downloads'' to download the installation files. Choose any download site, although probably one with a .com suffix is best when you're in the US.
# In the "Select Packages" screen, select the following packages:
#* Net -> openssh
#* Net -> openssl
#* Python -> python (you will need this for Module 4)
#* Devel -> git (version control system)
#* One or more of the following:
#** Editors -> vim
#** Editors -> emacs
#** Editors -> nano
# Allow the installation to complete.

Throughout the rest of this course, when we say to "open a terminal", if you are on Windows, we mean to "open Cygwin".

Thanks to [http://inside.mines.edu/~gmurray/HowTo/sshNotes.html our colleagues at Mines] for some tips on configuring Cygwin and SSH.

}}

== Bitbucket ==

{{RequiredInstructions|content=

'''Bitbucket''' is a service that enables you to store your code for free in the cloud. It is similar in spirit to Github, but with a different mission statement.

=== Creating a Bitbucket Account ===

Go to [https://bitbucket.org/account/signup/ Bitbucket.org] to create an account.

'''Important:''' Use your @wustl.edu e-mail address to create your account. This will put your account on the "educational plan", which removes some limitations of the free account.

'''Note:''' If you know someone who uses Bitbucket, you can ask them to invite you as a friend. This will increase the member limit on the inviter's private repos.

=== Adding Your Key to Bitbucket ===

# First make sure that you've finished the [[SSH]] guide configuration instructions.
#: We will use the same key for connecting to your remote server as for connecting to Bitbucket. (This is completely valid practice.)
# Go to the "SSH keys" section of the settings panel (Manage Account -> SSH Keys)
# Add a new key.
#* I recommend naming it after the computer you're using; if you're in the CEC, for example, you could name it "Warehouse Cygwin".
#* The contents of your key is the contents of your ''id_rsa.pub''. It looks like <code>ssh-rsa AAAAB3blahblahblahblah yourname@somedomain</code>. It is exactly the same thing that you had to paste into the ''authorized_keys'' file on your EC2 instance.

You will now be able to push code to your Bitbucket repository using your personal SSH key.

}}

== SourceTree ==

'''SourceTree''' is a tool that enables you to perform version control using a graphical user interface. It is free and available for Windows 7+ and Mac OS X 10.6+.

SourceTree is available on the Mac App Store. Windows users (and OS X users who don't like the App Store) may install it from http://sourcetreeapp.com/

=== Git ===

'''[[wikipedia:Git (software)|Git]]''' is a ''distributed version control system'' that enables you to track changes to your code and work with collaborators on the same code base. In CSE 132, you used ''Subversion (SVN)'', which is also version control system.

Git, like SVN, is a command-line tool. However, SourceTree enables you to use Git without having to pull up a Terminal window every time you need to perform an action.

[[Git|In Module 5]], you will learn more advanced techniques for using Git. However, for Modules 2-4, you will be using Git primarily as a method to push your changes to your remote repository.

=== Configuring Git/SourceTree ===

{{RequiredInstructions|content=

Once you install SourceTree, you need to tell it your name so that it knows how to tag changes you make.

# Open the SourceTree Preferences (SourceTree->Preferences on OS X or Tools->Options on Windows).
# Check the box that says "Allow SourceTree to modify your global Mercurial and Git configuration files".
# Enter your name and e-mail address.
#: '''Note:''' This actually does the same thing as running <code>git config --global user.name <NAME HERE></code> and <code>git config --global user.email <EMAIL HERE></code> from the command line.
# Go to the "Git" tab, and make the following changes:
#* Uncheck "Use the staging area". You will learn about staging in Git in Module 5, but for Modules 2-4 we will skip the staging area.
#* Check "Disable SSL certificate validation". This is necessary for the git repos hosted in the CEC. (Note: this semester we are using BitBucket repos instead of CEC repos, so you can leave this box unchecked if you prefer.)
# Close the preferences window.

}}

=== Cloning a Repository ===

[[File:SourceTree-Clone.png|400px|thumb|right|Screenshot of cloning a repository in SourceTree]]

We will start by ''cloning'' a remote Git repository.

"Cloning" in Git is much like "checking out" in SVN: a remote copy of the repository is copied down to a local working directory. '''Word of Caution:''' Git uses the term "checkout" to mean something different (which you will learn in Module 5), so ''do not'' use the words "clone" and "checkout" interchangeably.

If you wanted to clone a repository on the command line, the command would be:

<source lang="bash">$ git clone git://www.example.com/url-of-repo destination-path</source>

In SourceTree, go to '''File->New''', enter the remote repository URL and the destination path, and press "Clone". The destination path is where you want the repository's files to be copied on your personal computer; the path should point to either an empty or a nonexistent directory on your personal computer. In the screenshot, I am cloning the repository for the Fedora Linux kernel.

The remote repository will now be cloned onto your personal computer and all ready to use.

=== Committing ===

[[File:SourceTree-commit.jpg|400px|thumb|right|Screenshot of committing to a repository in SourceTree]]

When you make changes to files or add new files, you need to ''commit'' them to your working repository. '''Note:''' When you "commit" something in SVN, it means that you are sending your changes to the remote repository. This is ''not'' the case in Git, as we will see shortly.

To prepare your commit, press the "Commit" button in the SourceTree toolbar. See the screenshot for an example.

Select the files you want to commit, and enter a commit message summarizing the changes you've made since your last commit. When you're ready, press "Commit".

The command line equivalent of this would be:

<source lang="bash">
$ git add --all # adds untracked files to the repository and stages them for the commit
$ git commit -am "This is an example commit"
</source>

What happens now is that your changes are recorded ''in your own local working copy of the Git repository''. The changes have '''''not''''' been saved in the remote repository. You need to do this by ''pushing'' them.

=== Pushing ===

Git is different from SVN in that you can use it completely independently from a remote repository. Thus, in Git, you need to perform the "commit" and "push" steps separately.

''After'' you perform a commit, you need to ''push'' your commit to your remote repository. To do this, press the "Push" button in SourceTree, and then press "OK". The command line equivalent is:

<source lang="bash">$ git push master # assuming your branch is still named the default "master"</source>

'''Note:''' You do not need to push after every commit. You could have 4 or 5 commits before you actually perform the push. When you push, all commits will be pushed.

=== Pulling ===

In SVN, if you want to download changes from your remote repository, you performed an ''update''. In Git, you perform a ''pull''.

Pulling is (usually) as simple as pressing the "Pull" button in SourceTree. The command line equivalent is:

<source lang="bash">$ git pull master</source>

'''Note:''' If you want to download the changes from the remote repository but not overwrite your current working copy, you can perform a ''fetch'' instead.

== Pageant and PuTTYgen: SSH Keys for Windows ==

{{RequiredInstructions|content=

'''Pageant''' is a Windows utility that enables applications like SourceTree and Komodo Edit (which we will install in the next step) to be able to use your SSH keys when authenticating on remote services (like Bitbucket and your EC2 instance). '''PuTTYgen''' is a utility that converts SSH keys into a format that Pageant can understand.

'''Mac OS X and Linux users may skip this section.'''

=== Installing Pageant and PuTTYgen ===

Pageant and PuTTYgen both come bundled with SourceTree, so you do not need to install them separately. However, if you weren't using SourceTree, you could install them from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html

=== Using PuTTYgen ===

We will use PuTTYgen to convert our SSH keys into Pageant's format, ''*.ppk''.

# Launch PuTTYgen. If you downloaded ''puttygen.exe'', just open it; if you are using the SourceTree version, you can find it under the Tools menu:
#: [[File:LaunchPuTTYgen.jpg]]
# Inside PuTTYgen, click "Load" next to "Load an existing private key file". We want to load the private key we generated in [[SSH|the SSH guide]] using ''ssh-keygen''.
#* If you are using a CEC machine, the key will be at: <code>H:\.ssh\id_rsa</code>
#* If you are using your own computer, the key should be at: <code>C:\cygwin\home\<your name>\.ssh\id_rsa</code>
#: Note that you might need to choose "All Files (*.*)" in order to see the file.
# When the key gets loaded, click "Save private key"
#: FileZilla, which will also need this *.ppk key, does not play nicely with passphrases, so leave the passphrase blank.
#: A good place to save the file would be back in Cygwin's ''.ssh'' directory:
#* CEC lab machines: <code>H:\.ssh\id_rsa.ppk</code>
#* Personal machines: <code>C:\cygwin\home\<your name>\.ssh\id_rsa.ppk</code>
# Close PuTTYgen.

=== Using Pageant ===

To launch Pageant, either run ''pageant.exe'' or select it from the Tools menu in SourceTree:

[[File:LaunchPageant.jpg]]

The first time you launch pageant, it will ask you to select a key. Select the ''*.ppk'' file you saved in the previous section.

If you wish to add more keys to Pageant, right-click on its icon down in the start bar:

[[File:UsePageant.jpg]]

}}

=== Adding Pageant as a Startup Item ===

If you are using your own computer, it may be convenient to add Pageant as a startup item so that you don't need to go into SourceTree and turn it on every time you reboot your computer.

# Download ''pageant.exe'' if you were using SourceTree
# Open your Startup Items folder, located at Start Menu -> All Programs -> Startup (right-click and say "Open")
# Right-click inside the folder and say "New -> Shortcut". For the location, enter:
#: <source lang="text">"C:\path\to\pageant.exe" "c:\path\to\key.ppk"</source>
#: This will cause Pageant to open and automatically load your key.
# Press "Next". Enter a name and press "Finish".

Thanks to [http://www.ualberta.ca/CNS/RESEARCH/LinuxClusters/pka-putty.html the University of Alberta] for this tip.

== FileZilla ==

{{RequiredInstructions|content=

You can use SFTP from the command line, or you can use any GUI file transfer client. All FTP clients I have seen also support SFTP. One popular FTP client is [http://www.filezilla-project.org/ Filezilla].

# Download and install FileZilla from http://filezilla-project.org/download.php?type=client
#: If you are using a lab computer, you can save it to your H drive.
# When you launch FileZilla, go to Edit→Settings or FileZilla→Preferences, and go to the SFTP options (under Connection). Click "Add keyfile…".
#* '''Windows users:''' Choose the *.ppk file that you made earlier using Puttygen.
#* '''Unix users:'''
#*# Choose your ''id_rsa'' file. '''OS X Tip:''' Press Shift+Command+Period to reveal hidden files in the file chooser window.
#*# FileZilla will want to make a *.ppk file. A good place to save it would be the .ssh directory as ''id_rsa.ppk''.
#: When finished, press '''OK''' (not the red ×) to save your changes.
# Back on the main FileZilla screen, there are four fields: Host, Username, Password, and Port. Fill them in as follows:
#* '''Hostname:''' sftp://ec2-xxx-xx-xx-xxx.compute-1.amazonaws.com/
#* '''Username:''' The username you created on your server.
#* '''Password:''' Since you are using a key, you may leave this blank.
#*: If you changed your SSH settings to allow password-based authentication, then you could put your password in here.
#* '''Port:''' 22
# Then click Quickconnect. If everything is configured correctly, FileZilla should log into your server.

[[File:FileZilla.png]]

On the left and right of the FileZilla window, you can drag files between your computer and your server. Thus, you can edit a file in a text editor like Notepad++ on your decktop, and then upload it to your server by simply dragging it from the left pane to the right pane in FileZilla.

}}

== Komodo Edit ==

{{RequiredInstructions|content=

[[File:Komodo.png|200px]]

This semester in CSE 330, we will be using Komodo Edit as our editor of choice. We chose this editor because:

# It is free for everyone.
# It runs on Windows, Mac OS X, and Linux.
# It supports all of the languages we will be using in this class.
# It has a decent amount tools like auto-completion that will speed up your workflow.

=== Installation ===

Komodo Edit is already installed on the CEC lab machines. If you prefer to use your personal computer, download it from the web site: http://www.activestate.com/komodo-edit

}}

=== SSH Access ===

You can configure Komodo Edit to connect to your EC2 instance (to implement option 1 in the flowchart above) . However, because of a buggy and incomplete implementation in Komodo, '''this is not recommended or required for the purposes of CSE 330.''' For the brave-hearted, instructions can be found here: [[Komodo Edit with SSH Access]]

== Starting a Project ==

Start a new Komodo Project whenever you start a new assignment.

# Create a repo on Bitbucket and clone it to your local machine.
# In Komodo, choose '''Project -> New Project''' (or press shift-ctrl-N).
# Navigate to the cloned directory, enter a name for the project (e.g., ''Module2Group.komodoproject''), and press "Save".
# You should now see a window like this:
#: [[File:Workflow-1.png]]
# Press ctrl-N (or cmd-N) to create a new file. Save it in your project. For example, you could create a page named ''index.html'' with the [[HTML and CSS#Quick and Easy Page Layout|Quick and Easy Page Layout]]:
#: [[File:Workflow-2.png]]

'''Tip:''' To change between files without using a mouse, press ctrl-PageUp and ctrl-PageDown (cmd instead of ctrl on OS X). Many computers without explicit PageUp and PageDown buttons bind them to fn-Up and fn-Down. For example, on a MacBook Pro, to change to the next tab, you would press three keys: fn+cmd+down.

When you are ready, use FileZilla to upload your files to your server via SFTP.

[[Category:Module 2]]

Module 2

2014-05-02T19:39:05Z

Shane: Clarification from fall semester

__NOTOC__
Module 2 introduces you to Linux, a command-line environment, the Apache web server, and PHP. You will create and configure your own cloud instance, install Apache and related software, and then form groups to make a simple file sharing site.

<span style="font-size:1.3em; line-height:1.2em; color:blue;">'''DO NOT WAIT UNTIL THE LAST MINUTE TO START ON THIS (or any) MODULE!''' The most common reason students perform poorly in this class is procrastination. You have been warned.</span>

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Linux]]
* [[Bash]]
* [[Amazon Web Services]]
* [[SSH]]
* [[Apache]]
* [[PHP]]
* [[Workflow]]
* [[Web Application Security, Part 1]]

== Individual Assignments ==

{{RequiredInstructions|content=

<span style="color:red">There are a lot of wiki pages that you need to read in order to complete the individual portion of Module 2. The wiki pages contain an assortment of required steps, optional steps, and information. To make things easier, we have highlighted the ''required steps'' with a red bar, like you see on the left of this message. Do not skip anything marked with a red bar, or else you will not have a perfectly configured instance.</span>

}}

=== Learn About Linux ===

Linux is an open-source operating system based on UNIX. Linux is highly versatile and is used in a wide range of applications.

If you are not a Linux guru, read the Linux guide to get started: [[Linux]]

=== Install Cygwin: Windows Users Only ===

You will need Cygwin in order to log into and configure your EC2 instance. Cygwin is already installed on the CEC machines. Instructions for installing Cygwin on your personal machine are located in [[Workflow#Cygwin|the Workflow guide]].

Mac OS X users should located the "Terminal" application, which is installed by default; you will need this in the coming steps.

=== Create an AWS EC2 Instance ===

Once you understand [[Linux]], you need to set up your Amazon EC2 Instance. Use the AWS article to guide you through the process: [[Amazon Web Services]]

=== Configure SSH ===

Follow the instructions in [[SSH#SSH Configuration|the SSH guide]] to do the following:

# Create your own SSH key pair
# Log in as the default user to your EC2 instance
# Create a new user
# Give the new user your SSH public key

From now on, when you need to log into your EC2 instance as an administrator, just pop up a terminal and run:

<source lang="bash">
$ ssh your-username@ec2-xx-xx-xx-xx.compute-1.amazonaws.com
</source>

=== Install Essential Packages ===

Recall that software installation in Linux instances is usually handled through '''apt''' (Debian) or '''yum''' (RHEL). For more information, refer to [[Linux#Repository-Based Package Managers|the Linux guide]].

To make sure everything is working properly, '''install your first package(s) according to the ''Essential Packages'' subsection in the Linux guide.'''

=== Set the Timezone ===

'''Set your server to use US Central time (America/Chicago).''' Instructions are in the Linux guide: [[Linux#Synchronizing Date and Time]]

=== Set Up the Apache Web Server ===

You need to '''install the Apache web server on your EC2 instance'''. Refer to [[Apache|the Apache guide]].

In order for your web server to be accessible, you need to '''open up Port 80 on your EC2 instance'''. Instructions are in the AWS guide: [[Amazon Web Services#Enabling Web Access to your EC2 Instance]]

'''Enable the UserDir module in Apache.''' Instructions are in the Apache guide: [[Apache#The UserDir Module]]

=== Install PHP ===

You need to '''install PHP on your EC2 server'''. Instructions are at the top of the PHP guide: [[PHP]]

You need to '''configure PHP to show errors'''. Instructions are immediately below installation in the PHP guide.

=== Learn the PHP Language ===

Before you can continue, you will need to make yourself acquainted with PHP language components. Read the PHP guide for an overview: [[PHP#PHP Language Components]]

=== Set Up your Workspace ===

You are now ready to set up the workspace that you will be using for the rest of the semester. Follow the instructions in [[Workflow]] to:

# Make an account on Bitbucket
# Make a repository for your individual work for CSE 330
# Install SourceTree
# '''Windows only:''' Set up Pageant so that SourceTree can conect to Bitbucket
# Clone your CSE 330 repo from Bitbucket
# Install Komodo Edit
# Create a Komodo Edit Project inside of your Git repository
# Add the ''*.komodoproject'' file to ''.gitignore''
# Install FileZilla
# Connect FileZilla to your remote instance

=== Calculator ===

'''Make a calculator using PHP and an HTML form.''' The form should have two inputs. The form should submit a GET request either back to the same page or to a different results page. The calculator should support addition, subtraction, multiplication, and division by means of a radio button group on the page. (Consider edge cases!)

== Group Project ==

You will work in pairs (that means you and one other person) on this project.

<span style="font-size:1.3em; line-height:1.2em; color:blue;">In this module, and all future modules, the group portion builds off of material you learn in the individual portion. You should therefore complete the individual portions prior to working on the group portions. (Trust us: it will make your life easier!)</span>

'''Important Reminder:''' frequently commit your work to your repository as a backup!

=== Simple File Sharing Site ===

You will be making a simple file sharing site that supports uploading, viewing, and deleting files associated with various users. Details:

* You should have a file named '''users.txt''' stored in a secure place on your filesystem. It should have at least three usernames, with one username per line.
*: Passwords add an extra layer of complexity (encryption) that we will cover in Module 3. You will not earn credit for implementing passwords as your creative portion for this module.
* Users of the file sharing site should be able to enter their username and then log in.
*: You may implement logins using session variables, or you may implement them using a GET parameter that is passed between pages. You will need to always use sessions starting in Module 3.
* Users should see a list of all files associated with their username after the log in.
* Users should be able to view, upload, and delete files associated with their username.
* The URI should NOT reveal the internal file structure of your web site.
** Example of what not to do: http://www.example.com/download.php?file=/home/paul/file.txt
** Another bad example: http://www.example.com/~user/file.txt
** Good example: http://www.example.com/view.php?user=music&name=file.txt
*: In general, don't reveal any internal information about the site.
*: '''Food for thought:''' Given that Apache processes (with the exception of the main process) do not run as root, but rather as the user apache, how can you allow both your user account and the php scripts to read and write the necessary files?
* You should customize your file sharing site by implementing an additional feature or two as part of the '''creative portion'''.

You will probably find the PHP guide on this wiki to be helpful: [[PHP#Other PHP Tips]]

=== Web Security and Validation ===

Your project needs to demonstrate that thought was put into web security and best practice. For more information, see this week's Web Application Security guide: [[Web Application Security, Part 1]]

In particular:

* '''Your application needs to follow the conventions of FIEO (Filter Input and Escape Output)'''. Things you should filter include file names, usernames, and so on.
* '''Your project must pass the W3C Validator with no errors'''. For more information, see the HTML and CSS guide: [[HTML and CSS#Validation]]

== Grading ==

We will be grading the following aspects of your work. There are 100 points total.

# '''Cloud Instance and Web Server (30 Points):'''
#* You can SSH into your instance using your own custom username and SSH key (15 points)
#* Your custom username is able to perform SUDO commands (5 points)
#* The time zone is correct on your instance (5 points)
#* The UserDir Apache module is working (5 points)
# '''PHP Calculator (15 Points):'''
#* The calculator is able to perform all four functions (2 points each)
#* Each function is given as a radio button choice (4 points)
#* The calculator page passes the W3C HTML validator (3 points)
# '''File Sharing Site (40 Points):'''
#* '''''File Management (25 Points):'''''
#** Users should not be able to see any files until they enter a username and log in (4 points)
#**: ''Remember that users.txt should be stored in a secure location on your filesystem. That is, '''you should not be able to type any URL into your browser and see the raw users.txt file!'''''
#** Users can see a list of all files they have uploaded (4 points)
#** Users can open files they have previously uploaded (5 points)
#**: ''Note: Users should be able to open not only plain text files but also other file formats: images, spreadsheets, etc.''
#** Users can upload files (4 points)
#**: ''Note: Like users.txt, uploaded files should be stored in a secure location on your filesystem. That is, '''do not keep your uploads directory underneath a directory served by Apache!'''''
#** Users can delete files. If a file is "deleted", it should actually be removed from the filesystem (4 points)
#** The directory structure is hidden (2 points)
#** Users can log out (2 points)
#**: ''Note: If using session variables, you must ''actually'' log out the user by destroying their session; i.e., don't just redirect them to the login screen.''
#* '''''Best Practices (10 Points):'''''
#** Code is well formatted and easy to read (4 points)
#** The site follows the FIEO philosophy (3 points)
#** All pages pass the W3C validator (3 points)
#* '''''Usability (5 Points):'''''
#** Site is intuitive to use and navigate (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion (15 Points)''' (see below)

=== Creative Portion ===

This module, and all future modules, will require that you invest some time into creating additional features for your group project. Plan to invest at least 60 minutes of your time into the creative portion.

* The creative portion is an opportunity for you to learn material of your own interest.
* You will not earn credit for a creative-portion feature that simply rehashes something you've already done in a previous module.

If you need ideas for a creative portion, or if you want to know whether or not your creative portion idea is "hard enough", ask a TA.

[[Category:Module 2]]
[[Category:Modules]]

SSH

2014-05-02T19:29:18Z

Shane: AWS has upgraded from Precise to Trusty

Secure SHell, or '''SSH''', is the leading interface for connecting as an administrator from your local computer to something on the cloud. You will be using exclusively SSH to execute commands and upload files to your cloud instance. If you use a Git hosting service like BitBucket or Github, you will need SSH in order to save your changes there as well.

SSH access requires that the ''sshd'' daemon is running on the remote machine. By default, SSH is preinstalled on your EC2 instance. If you are not using an EC2 instance, simply install '''ssh''' from yum or apt on the remote machine.

== SSH Keys ==

SSH can work using password-based authentication, but it is more common nowadays, and also more secure, to use ''public and private keys'', also known as a ''key pair''.

Here's how it works. You have a private copy of your key, called your '''private key'''. Servers to which you want to connect have an analog to your private key called your '''public key'''. When you attempt to connect to a server using your private key, the server checks to see if any of its public keys "fits" your private key, and if it finds a match, it lets you in.

You can think of the ''private key'' as the "key" and the ''public key'' as the "lock".

== SSH Configuration ==

This section discusses how to set up your computer and your remote instance for SSH. You need to do this only once.

{{RequiredInstructions|content=

=== Creating an SSH Key Pair ===

You should create your own SSH Key Pair. You will keep the private key on your own computer, and you will upload the public key to all places to which you need to connect.

To generate a key pair, open Terminal or [[Workflow#Cygwin|Cygwin, which you will need to install if on a personal Windows computer,]] and run the following command:

<source lang="bash"># Run on Local Machine in Terminal or Cygwin
$ ssh-keygen</source>

'''Important:''' Don't name the file unless you are using a CEC machine. If you are using a CEC machine, name the file ''/cygdrive/h/.ssh/id_rsa''

For the purposes of this course, you do not need to enter a passphrase, although you would probably want one in real life.

Your keys should have been created in ~/.ssh. Check to make sure they exist using the ''ls'' command:

<source lang="bash">
$ ls ~/.ssh
id_rsa id_rsa.pub
</source>

''id_rsa'' is your private key, and ''id_rsa.pub'' is the corresponding public key. Let's look at the public signature of your key pair:

<source lang="bash">
$ cat ~/.ssh/id_rsa.pub
ssh-rsa AAAA3Bblahblahblahblah yourname@somedomain
</source>

We will need this later. Let's now add our key to the ''ssh-agent''.

==== SSH Agent: OS X ====

Run the following command to add your key to the SSH agent in Mac OS X.

<source lang="bash"># Non-Cygwin
$ ssh-add</source>

==== SSH Agent: Cygwin ====

In order to make the SSH agent run when you start Cygwin, you need to run a couple more commands (these will add a line to your .bashrc file, which runs automatically on startup):

<source lang="bash">
# Cygwin only
$ echo "eval \`ssh-agent -s\`; ssh-add" >> ~/.bashrc
$ source ~/.bashrc # reload the Bash shell
</source>

If you get this scary-looking error after you run the second command…

<source lang="text">
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: UNPROTECTED PRIVATE KEY FILE! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
</source>

…then you need to do the following to fix the permissions:

<source lang="bash">
# Cygwin only
$ chgrp Users /path/to/id_rsa
$ chmod 600 /path/to/id_rsa
</source>

=== Amazon EC2 SSH Configuration ===

When you first created your EC2 instance, you downloaded a *.pem file. This is the ''private key'' for the default user ('''ubuntu''' on Ubuntu or '''ec2-user''' on AMI). We need use this key to connect to your instance using the default user, at which point we will create a new custom user. We will give that new user the public key that you created in the previous step. You will then be able to log into your custom user using your personal key pair, so you won't need the default user again (although you should keep the *.pem file around just in case).

==== Logging In as the Default User ====

To connect to the default user on your Amazon EC2 instance, run this command in Terminal or Cygwin:

<source lang="bash">
# Run on Local Machine
$ ssh -i /path/to/default-privatekey.pem ubuntu@ec2-xx-xx-xx-xx.compute-1.amazonaws.com # or ec2-user@... for AMI
</source>

'''Important:''' As soon as you are able to successfully log in, commands you type into your prompt will be executed on the remote instance, ''not'' your local machine.

If you get this scary-looking warning:

<source lang="text">
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: UNPROTECTED PRIVATE KEY FILE! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
</source>

…then you need to correctly set the permissions on your *.pem file. You should know how to do this from the Linux guide, but in case you didn't catch that detail, run:

<source lang="bash">
# Run on Local Machine

# Cygwin Only:
$ chgrp Users /path/to/default-privatekey.pem

# Terminal and Cygwin:
$ chmod 600 /path/to/default-privatekey.pem
</source>

'''Food for Thought:''' Why you wouldn't want other people viewing your private key file?

==== Creating a New User with SSH Permissions ====

First, you need to create your new user with sudo and SSH permissions. Again, the instructions for this are in the Linux guide, but to keep everything in one place, the commands are:

<source lang="bash">
# Run these on your instance, not on your local machine!

# Don't forget to customize `My Full Name` and `<username here>`:
$ sudo useradd -r -m -c "My Full Name" <username here>
$ sudo passwd <username here>

# Ubuntu only:
$ sudo chsh -s /bin/bash <username here>

# You need to add your username to the sudoers list. Refer to the Linux guide for details.
# Ubuntu: Look around line 19.
# Amazon AMI: Look around line 99.
$ sudo visudo

# Ubuntu only: add your user to the SSH whitelist:
$ echo "AllowUsers <username here> ubuntu" | sudo tee -a /etc/ssh/sshd_config

# Restart the SSH server:
$ sudo service ssh restart || sudo service sshd restart
</source>

Okay, cool: we have created our custom username on our remote instance. Now, we need to enable this account to accept our SSH key when authenticating. To do this, we need to add our public key to a file named '''authorized_keys''', which is stored in your remote username's SSH configuration directory.

To create the directory and edit the file, run on your instance:

<source lang="bash">
# Switch to our own user to ensure that permissions are set correctly:
$ su <username here>

# Change the working directory to our user's home directory:
$ cd

# Make the nonexistent SSH configuration directory and set its permissions:
$ mkdir .ssh
$ chmod 700 .ssh

# Create the `authorized_keys` file and set the permissions
$ touch .ssh/authorized_keys
$ chmod 600 .ssh/authorized_keys

# Edit the `authorized_keys` file
$ nano .ssh/authorized_keys
</source>

For more detail on editing files on the command line, see [[Linux#File Editors|the Linux guide]].

Inside of the `authorized_keys` file, paste in your public key. Your public key is the content of `~/.ssh/id_rsa.pub` '''on your local machine''' (it starts with "ssh-rsa"). There are a few ways to get it onto your clipboard:

# '''OS X Only:''' Open a new Terminal and run: <source lang="bash">cat ~/.ssh/id_rsa.pub | pbcopy</source> This immediately copies the contents of your public key to your clipboard.
# '''Windows Only:''' Navigate to id_rsa.pub manually, open it in your favorite text editor (like Notepad++), select all, and copy. The location of id_rsa.pub might be: ''C:\cygwin\home\username\.ssh\id_rsa.pub''
# '''*NIX Only:''' Open a new Terminal and copy the output of the following command: <source lang="bash">cat ~/.ssh/id_rsa.pub</source> Note that this won't work as advertised in Cygwin because Cygwin adds extra line breaks when you try to copy out of it.

When finished, save and close `authorized_keys`.

'''Food for Thought:''' How would you enable your remote user to authenticate over SSH using the same default key instead of the one you created using ''ssh-keygen''?

==== Logging In as your New User ====

Let's test whether we can log into our instance using our own username and our own key pair. Open up a new Terminal or Cygwin and run:

<source lang="bash">
$ ssh <username here>@ec2-xx-xx-xx-xx.compute-1.amazonaws.com
</source>

This is how you will be SSHing into your instances for the remainder of the semester.

}}

=== Troubleshooting ===

Almost everyone receives the following error at some point in their career: <code>Permission denied (publickey)</code>.

Here are some possible causes for the error.

==== The Authorized Keys File ====

Make sure that your remote ''authorized_keys'' file contains ''exactly'' your public signature from ''id_rsa.pub''.

===== Pasting into Vi =====

If you used vi to edit your file and you forgot to enter "insert" mode before pasting in your key, it is possible that you lost the first "s" in "ssh-rsa".

Check the contents of authorized_keys via <code>cat ~/.ssh/authorized_keys</code> on your server. If the output starts with "sh-rsa" instead of "ssh-rsa", edit the authorized_keys file and add the second '''s'''.

===== Unintentional Line Breaks =====

If you got your key via a <code>cat ~/.ssh/id_rsa.pub</code> and then copied it from the terminal, it's possible that you unintentionally introduced line breaks. Ensure that the key is represented by only one line of text.

==== Permissions ====

They need to be correct on both the client side and on the server side.

* Local ''.ssh'' = 700
* Local ''id_rsa'' = 600
* Remote ''.ssh'' = 700
* Remote ''authorized_keys'' = 600

If you are in Cygwin and the permissions don't seem to change, you might need to add the troubled file to a usergroup, like this:

<source lang="bash">
$ chgrp Users .ssh/id_rsa
</source>

==== The SSH Agent ====

You need to be sending the correct key along with your SSH Agent. Run the following command, and you should see some output:

<source lang="bash">
$ ssh-add -l
2048 ab:cd:ef:ab:cd:ef:ab:cd:ef:ab:cd:ef:ab:cd:ef:ab:cd /path/to/.ssh/id_rsa (RSA)
</source>

If you don't see any output, or if the output does not contain your ''id_rsa'', then you need to run:

<source lang="bash">
$ ssh-add /path/to/.ssh/id_rsa
</source>

=== More SSH Server Configurations ===

Up to this point, we have been using all of the default SSH configurations. Like most things in Linux, SSH can be customized.

For the purposes of CSE 330, the additional configurations in this short section are optional; this serves only as a reference.

==== Disabling Root Access ====

It is almost always a good idea to disable root access over ssh. This could be done by editing ''/etc/ssh/sshd_config'' and setting

<source lang="text">PermitRootLogin no</source>

You will need to restart the SSH server for changes to take effect:

<source lang="bash">
$ sudo service ssh restart # Debian version
$ sudo service sshd restart # RHEL version
</source>

==== Enabling Password-Based Authentication ====

Up to this point, we have been using key pairs for SSH. A public/private key pair is generally considered to be more secure, but it requires that you always have access to your private key file when you want to log into your remote machine.

By default, EC2 instances allow only public/private key pair authentication. You can enable password-based authentication by setting the PaswordAuthentication option in ''/etc/ssh/sshd_config'' to '''yes''':

<source lang="text">PasswordAuthentication yes</source>

There may be a line with this option that you can un-comment. For me, it is line 25. You will need to restart the server for changes to take effect.

If possible, however, you should restrict yourself to using private and public keys.

== Using SSH ==

Once you have completed the [[#SSH Configuration]] section above, all you need to do in order to SSH into your instance is to open a terminal and run:

<source lang="bash">
$ ssh <username here>@ec2-xx-xx-xx-xx.compute-1.amazonaws.com
</source>

=== PuTTY ===

'''This short section about PuTTY serves only as a reference.'''

If you have Cygwin available, you should use it to SSH into your instance. However, if you are using a different computer, you might not have Cygwin at your fingertips. In this case, a lighter-weight SSH client called '''PuTTY''' is available for Windows.

You can download PuTTY from: http://www.chiark.greenend.org.uk/~sgtatham/putty/

Amazon provides [http://docs.amazonwebservices.com/AWSEC2/latest/GettingStartedGuide/ConnectToInstanceLinux.html#connect-from-windows-machine a great tutorial on how to connect to a virtual machine from Windows].

PuTTY is fairly simple and straight forward with one caveat: Amazon's ''*.pem'' files are SSH private key files, and they need to be converted to PuTTY's own '''.ppk''' format. To do this, use the ''puttygen.exe'' utility available from the same page as PuTTY. Select "Import" under the conversions menu, load the amazon ''*.pem'' key file, and press the "Save Private Key" button.

Copy and paste works similarly to the X Window System in Unix. You use the left mouse button to select text in the PuTTY window. The act of selection automatically copies the text to the clipboard: there is no need to press Ctrl-Ins or Ctrl-C or anything else. In fact, pressing Ctrl-C will send a Ctrl-C character to the other end of your connection (just like it does the rest of the time), which may have unpleasant effects. The only thing you need to do, to copy text to the clipboard, is to select it.

To paste the clipboard contents into a PuTTY window, by default you click the right mouse button. If you have a three-button mouse and are used to X applications, you can configure pasting to be done by the middle button instead, but this is not the default because most Windows users don't have a middle button at all.

Here is a good PuTTY tutorial that you might find useful to get started: http://kb.mediatemple.net/questions/1595/Using+SSH+in+Putty+%28Windows%29

== SSHFS and SFTP ==

In addition to just SSH, your SSH server also supports '''SSHFS''', which enables you to mount your remote instance as a disk on your local computer, and '''SFTP''', which is a file transfer protocol that enables you to upload files directly to your instance.

=== SSHFS ===

SSHFS is a filesystem client which allows secure mounting of remote file systems. While there are other ways to mount remote file systems, SSHFS has the advantage of being able to mount a file system located on any host that has an SSH daemon running without any host side installation or configuration. This means that you can easily access and edit your files using all of your local applications including IDEs.

As you may have inferred from the name, the underlying implementation utilizes SSH File Transfer Protocol in combination with FUSE, a package now included in the kernel that allows unprivileged users to easily create their own file systems in userspace (see the wikipedia entry for more information [http://en.wikipedia.org/wiki/Filesystem_in_Userspace]).

To mount a share using password based authentication, the command is:

<source lang="bash">
$ sshfs user@domain:/path/to/remote/directory /path/to/local/mountpoint
</source>

For example, to mount the directory /home/joe/myfiles in the user ''joe'''s home directory for a machine with the domain schmoesfiles.org using SSHFS you would enter the command

<source lang="bash">
$ sshfs joe@www.schmoesfiles.org:myfiles
</source>

Note that if you are using public key authentication, the command to mount the remote filesystem may need to be slightly different:

<source lang="bash">
$ sshfs -o IdentityFile=/path/to/private/key user@domain:/path/to/remote/directory /path/to/local/mountpoint
</source>

To unmount the filesystem, you can use the following command:

<source lang="bash">
$ fusermount -u /path/to/local/mountpoint
</source>

=== SFTP ===

Any server running an SSH server is also compatible with '''SFTP''' or Secure File Transfer Protocol. (Compare to FTP, or File Transfer Protocol.) SFTP is a convenient way to edit files on your computer and then upload them to your server in just a few clicks.

[[Category:Module 2]]

Amazon Web Services

2014-05-02T19:29:08Z

Shane: AWS has upgraded from Precise to Trusty

Amazon Web Services provides a method to publish web sites on virtual machines in the "cloud." In CSE330, you will be using an EC2 instance to host your web site.

Before reading this guide, you should be familiar with Linux and the various distributions of Linux. Fore more information, refer to [[Linux#Linux Distributions|the Linux guide]].

== Creating and Configuring your EC2 Instance ==

{{RequiredInstructions|content=

Follow these steps to get to the AWS Management Console:

# Create an AWS account: http://aws.amazon.com/
# Sign up for the EC2 Web Service: http://aws.amazon.com/ec2/
# Log in to the AWS Management Console

To create your new virtual machine, click '''Launch Instance'''. Do the following to configure your instance:

# Use the Classic Wizard.
# Now choose what distribution of Linux you would like to use. For more information on distributions, refer to [[Linux#Linux Distributions|the Linux guide]]. The following are both good choices, and throughout the wiki, the instructions are equally comprehensive for both. This semester, we will be teaching this class using Ubuntu, but you are free to use either one.
#* Ubuntu Server 14.04 LTS (based on Debian)
#* Amazon Linux AMI (based on RHEL)
# The default instance variables are all fine. Click Continue until you get to the "Create Key Pair" screen.
# Create a new Key Pair. Enter some name for it, and then click "Create & Download your Key Pair". '''Save your key somewhere secure.''' In addition to using it to authenticate for this instance, you will be able to use the same key for additional instances.
# Create a new Security Group. The security groups you create determine whether a port is open or blocked for your server.
#* You need to open the SSH port on your server. To do this, select "SSH" from the drop-down box, and then click "Add Rule."
#: We will be opening more ports by modifying the security group at a later time. Click Continue.
# You are now ready to launch your virtual server! Click Launch.

}}

== Starting and Stopping your EC2 Instance ==

You can start and stop your instance by right-clicking on the instance. The options are down in the "Instance Lifecycle" section.

=== Amazon EC2 Gives You One Free Micro Instance ===

It is free to keep '''''one''''' micro instance running at all times. Keeping your instance running around the clock will make your life easier, because then you won't need to always change your hostname in your SSH clients.

For additional Micro instances, or for larger instances, you will be charged hourly for their use. One non-free Micro instance costs about $14/month; a Small instance costs about $43/month.

=== Terminate vs Stop ===

Never "terminate" your instance, as this PERMANENTLY DELETES the instance! Any time you are done using the instance you should instead "stop" the instance and then when you are ready to resume work you should "start" the instance.

'''Note:''' Frequently committing your work to your repository is a safety net in case something horrible happens to your instance.

== Enabling Web Access to your EC2 Instance ==

{{RequiredInstructions|content=

Once you have configured [[Apache]] (which you will do later in this Module), you will need to open up your EC2 instance to web traffic. (By default amazon blocks all traffic to our instance.)

Go to the Security Groups under Network & Security on the EC2 webpage. Select your security group, click on the Inbound Tab. Add a new Custom TCP rule with a Port range of 80. Leave the Source at 0.0.0.0/0 (for all traffic). Click Add Rule, and then click Apply Rule Change.

To make sure things are working, create a file, like '''hello.txt''', in your web server root. Give it some content (might I suggest "Hello, world!").

* In the Amazon AMI, the web server root is at /var/www/html
* In Ubuntu 12.04 LTS, the web server root is at /var/www

For more information on editing files on the command line, refer to [[Linux#File Editors|the Linux guide]].

You should now be able to visit your server load up the file using your web browser! Example Link: http://ec2-xxx-xxx-xxx-xx.compute-1.amazonaws.com/hello.txt

}}

[[Category:Module 2]]

Apache

2014-05-02T19:28:56Z

Shane: AWS has upgraded from Precise to Trusty

''Apache'' is the industry standard web server for Linux distributions. It is highly configurable and has a wide range of modules ready for different needs.

{{XKCD
|name=permanence
|id=910
}}

== What is a web server? ==

A web server is software that listens for connections to your machine, and when a connection is receive, processes the request and responds with the appropriate information. Most web servers listen on port 80, which is reserved for the purpose, and use the HTTP protocol.

For example, when you visit this wiki, you are sending a request over the internet to some machine that is probably located somewhere in EIT (the user seldom knows exactly where the machine is located). The web server receives your request, and it processes the data you sent. Finally, the server prepares a response (the web page), and sends it back to you.

== Installing Apache ==

{{RequiredInstructions|content=

In yum, Apache is distributed under the package name '''httpd''' (for ''hypertext transfer protocol daemon''). In apt, it is distributed under the name '''apache2'''. Use the package manager associated with your distribution to install Apache. (For more information on how to use yum and apt, see [[Linux#Repository-Based Package Managers|the Linux guide]].)

For example:

<source lang="bash">
# Debian version
$ sudo apt-get update
$ sudo apt-get install apache2

# RHEL version
$ sudo yum install httpd
</source>

When Apache is installed through apt, the HTTP Daemon will be automatically to added as a startup item. If you are using the Amazon AMI, you need to run this command to add Apache as a startup item:

<source lang="bash">
$ sudo /sbin/chkconfig --levels 235 httpd on # RHEL only
$
</source>

In RHEL, all Apache configurations are stored in ''/etc/httpd/conf/httpd.conf''. Debian takes a more modular approach, having separate directories for each type of configuration, all located in ''/etc/apache2/''. For more detail on Debian's approach, see http://www.control-escape.com/web/configuring-apache2-debian.html

}}

== Apache Directives ==

You define your settings for Apache using ''directives''. Some of the directives you will likely encounter include:

* '''DocumentRoot:''' The path to the directory where the top level web files are going to be stored.
* '''IfModule:''' The following block would be included if specified module exists.
* '''User:''' Which user apache2 will run as.
* '''Group:''' Which group will have group access to default web files.
* '''AccessFileName:''' The name of the access file (that specifies user names/passwords and other limitations to files/directories).
* '''ErrorLog:''' Where any errors will be written.
* '''Include:''' Include some other files.
* '''LogFormat:''' How to write a log message.
* '''ErrorDocument:''' Files to display for some HTTP errors (500, 404, 402 etc.).
* '''Alias:''' Map a directory URL to some other location on your filesystem. Requires that the ''Alias'' module be loaded.

=== .htaccess Files ===

You can also specify some Apache configurations without delving into the master configuration file. To do this, put a file named ''.htaccess'' in any directory that Apache is serving. All directives in it will be interpreted as if they were in a Directory directive in the master configuration file.

'''VERY IMPORTANT:''' The directory containing ''.htaccess'' must not have the '''AllowOverride None''' directive in the master configuration file in order for '''.htaccess''' to be read. In Debian, '''AllowOverride None''' is enabled by default! The Apache configuration file you need to edit in Debian is ''/etc/apache2/sites-available/default'' (remove the '''AllowOverride None''' located on line 11).

=== Directory Directive ===

Use the Directory directive to assign other directives to a specific directory. For example:

<source lang="apache">
<Directory /var/www/>
Options Indexes FollowSymLinks
AllowOverride None
Order allow,deny
allow from all
RedirectMatch ^/$ /apache2-default/
</Directory>
</source>

This sets options for the ''/var/www'' directory.
# The '''Options''' directive says that:
## If no index page is present in a directory, display a directory index page instead
## Apache will follow symbolic links in the directory
# '''AllowOverride None''' says that ''.htaccess'' files cannot alter the Apache options in this directory and all sub-directories
# '''Order allow,deny''' and '''Allow from all''' specifies that anybody is allowed to access this server via HTTP.

Note that this directory is actually the root directory of the web server.

== The UserDir Module ==

{{RequiredInstructions|content=

The UserDir module lets you access files for any user on the server with a ~, e.g., http://ec2-xxx-xxx-xxx-xx.compute-1.amazonaws.com/~paul/

This module comes installed, but not activated by default.

=== Enabling UserDir in Debian ===

If you are using a Debian-based distribution for your server (like Ubuntu Server), simply run the following command to enable the module:

<source lang="bash">
$ sudo a2enmod userdir
</source>

Then [[#Restarting Apache and Testing|restart Apache]] for the changes to take effect. Now, all users will be able to store their own personal web site in public_html inside their home directory.

To make sure everything is working, create a test file in your home directory under public_html, and then point your browser to it: http://ec2-xxx-xx-xx-xxx.compute-1.amazonaws.com/~yourUserName/hello.txt

'''Note:''' The UserDir configuration file, which already has all the correct settings, is located at ''/etc/apache2/mods-available/userdir.conf''

'''Note:''' Users need to manually create public_html. It is not created automatically.

=== Enabling UserDir in RHEL ===

If you are using an RHEL-based distribution for your server (like the Amazon AMI), you need to edit the master Apache configuration file.

Open ''/etc/httpd/conf/httpd.conf'' in your favorite text editor. For more information on command-line text editors, refer to [[Linux#File Editors|the Linux guide]].

Find the line that says

<source lang="apache">UserDir disabled</source>

and change it to

<source lang="apache">UserDir disabled root</source>

Additionally, find the line that says

<source lang="apache">#UserDir public_html</source>

and uncomment it; that is, remove the # so that you have

<source lang="apache">UserDir public_html</source>

This tells Apache that the directory containing each user's html files is a subdirectory of their home directory called public_html.

'''Note:''' Users need to manually create public_html. It is not created automatically.

You may also need to change the permissions of your user directory and your public_html directory to allow Apache to read and execute inside them. To do this, run the following commands:

<source lang="bash">
$ sudo chmod o+x /home/myUserName
$ sudo chmod o+rx /home/myUserName/public_html
$
</source>

Finally, [[#Restarting Apache and Testing|restart Apache]].

}}

=== Remapping UserDir ===

If you want to change the name of the UserDir web server root from '''public_html''' to something else like '''.html''', follow these instructions. (You do not need to do this for the purposes of CSE 330; this serves as a reference.)

# Rename your '''public_html''' to '''.html'''
#* The "." in front of the directory name means that the directory is a hidden one. You will not see it with the normal "ls" command. Use "ls -a" to see hidden files as well.
# Edit the UserDir configuration file.
#* In RHEL, edit the master Apache configuration file at ''/etc/httpd/conf/httpd.conf''
#* In Debian, edit the UserDir configuration file at ''/etc/apache2/mods-available/userdir.conf''
# Find the line that reads <code>UserDir public_html</code> and change it to <code>UserDir .html/</code>
# [[#Restarting Apache and Testing|Restart Apache]].

== Apache Logs ==

Apache creates two log files: one for all access attempts to your server, and one for errors. The locations of these log files are:

* '''Debian:'''
** '''Access Log:''' /var/log/apache2/access.log
** '''Error Log:''' /var/log/apache2/error.log
* '''RHEL:'''
** '''Access Log:''' /var/log/httpd/access_log
** '''Error Log:''' /var/log/httpd/error_log

You might find it helpful to see access and errors appear "live" in your terminal window as they are created. To do this, you can use the [[Linux#Command Reference|tail -f]] command. Since the log files have strict permissions, you will need to also use sudo. Example on Debian:

<source lang="bash">
$ sudo tail -f /var/log/apache2/error.log
</source>

== Virtual Hosts ==

'''Virtual Hosts''' are used to run multiple Apache web servers from the same machine. Virtual hosts can listen for connections on different ports and/or different hostnames, serving completely different web sites to each. For example:

<source lang="apache">
<VirtualHost cse330.dyndns.org>
ServerAdmin webmaster@localhost
ServerName cse330.dyndns.org
DocumentRoot /home/www/cse330/
ErrorLog /var/log/httpd/error_log
LogLevel warn
CustomLog /var/log/apache2/access_log combined
ServerSignature On
</VirtualHost>
</source>

This configuration enables any requests that use a host name of ''cse330.dyndns.org'' will use ''/home/www/cse330'' as the root document directory. Make sure that the DocumentRoot directory exists and is readable by the httpd process. In RHEL, Apache runs as the '''apache''' user. In Debian, it runs as the '''www-data''' user.

It is good practice to put raw server configuration files in ''/etc/httpd/sites-available'' in RHEL or ''/etc/apache2/sites-available'' in Debian. To activate a site, create a symlink from the configuration in ''sites-available'' to a sibling directory called ''sites-enabled''. In Debian, these directories are already set up for you, and Debian Apache even provides the '''a2ensite''' and '''a2dissite''' commands to create or destroy the symlinks! In RHEL, you have to do this by hand.

== Restarting Apache and Testing ==

Whenever you make changes to the Apache configuration files, you will need to restart Apache for the changes to take effect. There are several different ways to restart Apache; they all functionally do (almost) the same thing, so choose your favorite:

<source lang="bash">
$ sudo /usr/sbin/apachectl restart # works on both Debian and RHEL
$ sudo apachectl restart # if /usr/sbin is in your PATH (which it is by default in Debian, but not RHEL)
$ sudo /etc/init.d/httpd restart # on RHEL
$ sudo /etc/init.d/apache2 restart # on Debian
$ sudo /sbin/service httpd restart # on RHEL
$ sudo /usr/sbin/service apache2 restart # on Debian
$ sudo service httpd restart # on RHEL
$ sudo service apache2 restart # on Debian
</source>

If you're torn for which version is the "best" to use, the commands involving '''apachectl''' (think "Apache Control") are written by the Apache folks themselves. This has a couple advantages:
* They show you errors in the startup process (if there are any)
* They give you the option to perform a "soft" restart; that is, a restart that allows any pending connections to complete. To perform a soft restart, use ''graceful'': <code>sudo apachectl graceful</code>
In my anecdotal experience, the '''apachectl''' commands are also faster than the '''service''' or '''init.d''' commands.

To make sure everything is working, create a test file in your home directory under public_html, and then point your browser to it: http://ec2-xxx-xx-xx-xxx.compute-1.amazonaws.com/~yourUserName/hello.txt

[[Category:Module 2]]

Choosing a Platform

2014-01-11T12:00:59Z

Shane: /* PHP Pros */

Choosing a Platform

2014-01-11T11:58:18Z

Shane:

You've learned a large variety of platforms in this course. Which one should you use? This page summarizes some of the pros and cons of each platform.

== PHP ==

[[PHP]] is a language built for server-side web development. You built a [[Module 2|file sharing application]] and a [[Module 3|news syndication site]] in PHP.

=== PHP Pros ===

* '''Largest support community:''' Easy to find help if you get stuck.
* '''Distribution:''' Runs on virtually any web server in existence.
* '''Easy to Debug:''' Because there is no framework involved and the PHP interpreter is well maintained, it is easier to pinpoint bugs and wrap your head around what is going on behind the scenes.

=== PHP Cons ===

* '''Language:''' Few people will say that PHP is the most elegant language known to mankind. The language makes it easy to fall into the trap of bad coding practices.
* '''Security:''' PHP does very little for you automatically in terms of web security.

== Django ==

[[Web Frameworks|Django]] is a web frameworks written in the [[Python]] scripting language. In more ways than not, it is the Python equivalent of [[wikipedia:Ruby on Rails|Ruby on Rails]].

=== Django Pros ===

* '''Less Code:''' Implementing common web design patterns, like social login or commenting, is usually as easy as a ''pip install''.
* '''Conventions:''' Django forces you to write neat and organized code, leading to better software engineering practices and scalability down the road.
* '''Security:''' Django automatically implements common security practices, leading to a more robust web application.

=== Django Cons ===

* '''Difficult to Debug:''' Django's high level of abstraction is a double-edged sword, because bugs and errors are sometimes difficult to find and can take hours to fix.
* '''Heavyweight:''' Django is designed for larger web applications, and it is not suitable for smaller projects with just one or two controllers.

== Bottle and Flask ==

Bottle is a web ''microframework'' written in the [[Python]] scripting language. Flask is similar option. Although you did not explicitly use Bottle or Flask during a module, it's worth listing on this page. In more ways than not, Bottle and Flask are the Python equivalents of the better-known [[wikipedia:Sinatra (software)|Sinatra]], a Ruby microframework.

=== Bottle and Flask Pros ===

* '''Lightweight:''' There are few enough files that you can find your way around and be in full control of your application logic.
* '''Access to Python Libraries:''' A lot of the things you do in Django you can do in Bottle and Flask, except that you have more control over the ways that they are implemented.

=== Bottle and Flask Cons ===

* '''Lack of Conventions:''' Bottle and Flask give you the tools you need to build maintainable code, but unlike Django, they don't force you to. It's easy to end up with Python scripts containing hundreds of lines of unrelated application logic.

== Node.JS and Express ==

[[Node.JS]] is a low-level implementation of JavaScript that enables you to write networked and web applications. Express is a Sinatra-like microframework that runs on top of Node.jS.

It is also worth bringing your attention to [http://www.meteor.com/ Meteor], a bleeding-edge framework for Node.JS that abstracts away client-server communications. (Watch the promo video; it's pretty awesome.)

=== Node.JS Pros ===

* '''Speed:''' Node.JS is the fastest of the options on this page. It is easy to scale up your Node.JS applications.
* '''Modern:''' Node.JS is also the newest of the options on this page, so most of the plugins you find for it use the best and latest practices.
* '''Language:''' With Node.JS, you can use just one language for both your server-side and client-side logic.
* '''Real-Time Options:''' Node.JS enables you to write real-time applications with ease, for example, with Socket.IO.

=== Node.JS Cons ===

* '''Lack of Conventions:''' Like Bottle, Flask, and most other microframeworks, Node.JS and Express don't force you to stick to predefined conventions, giving the potential to build messy code.

[[Category:Module 8]]

Choosing a Platform

2014-01-11T11:55:32Z

Shane:

You've learned a large variety of platforms in this course. Which one should you use? This page summarizes some of the pros and cons of each platform.

== PHP ==

[[PHP]] is a language built for server-side web development. You built a [[Module 2|file sharing application]] and a [[Module 3|news syndication site]] in PHP.

=== PHP Pros ===

* '''Largest support community:''' Easy to find help if you get stuck.
* '''Distribution:''' Runs on virtually any web server in existence.
* '''Simplicity:''' More than any of the other options, PHP is easy to develop.

=== PHP Cons ===

* '''Language:''' Few people will say that PHP is the most elegant language known to mankind. The language makes it easy to fall into the trap of bad coding practices.
* '''Security:''' PHP does very little for you automatically in terms of web security.

== Django ==

[[Web Frameworks|Django]] is a web frameworks written in the [[Python]] scripting language. In more ways than not, it is the Python equivalent of [[wikipedia:Ruby on Rails|Ruby on Rails]].

=== Django Pros ===

* '''Less Code:''' Implementing common web design patterns, like social login or commenting, is usually as easy as a ''pip install''.
* '''Conventions:''' Django forces you to write neat and organized code, leading to better software engineering practices and scalability down the road.
* '''Security:''' Django automatically implements common security practices, leading to a more robust web application.

=== Django Cons ===

* '''Difficult to Debug:''' Django's high level of abstraction is a double-edged sword, because bugs and errors are sometimes difficult to find and can take hours to fix.
* '''Heavyweight:''' Django is designed for larger web applications, and it is not suitable for smaller projects with just one or two controllers.

== Bottle and Flask ==

Bottle is a web ''microframework'' written in the [[Python]] scripting language. Flask is similar option. Although you did not explicitly use Bottle or Flask during a module, it's worth listing on this page. In more ways than not, Bottle and Flask are the Python equivalents of the better-known [[wikipedia:Sinatra (software)|Sinatra]], a Ruby microframework.

=== Bottle and Flask Pros ===

* '''Lightweight:''' There are few enough files that you can find your way around and be in full control of your application logic.
* '''Access to Python Libraries:''' A lot of the things you do in Django you can do in Bottle and Flask, except that you have more control over the ways that they are implemented.

=== Bottle and Flask Cons ===

* '''Lack of Conventions:''' Bottle and Flask give you the tools you need to build maintainable code, but unlike Django, they don't force you to. It's easy to end up with Python scripts containing hundreds of lines of unrelated application logic.

== Node.JS and Express ==

[[Node.JS]] is a low-level implementation of JavaScript that enables you to write networked and web applications. Express is a Sinatra-like microframework that runs on top of Node.jS.

It is also worth bringing your attention to [http://www.meteor.com/ Meteor], a bleeding-edge framework for Node.JS that abstracts away client-server communications. (Watch the promo video; it's pretty awesome.)

=== Node.JS Pros ===

* '''Speed:''' Node.JS is the fastest of the options on this page. It is easy to scale up your Node.JS applications.
* '''Modern:''' Node.JS is also the newest of the options on this page, so most of the plugins you find for it use the best and latest practices.
* '''Language:''' With Node.JS, you can use just one language for both your server-side and client-side logic.
* '''Real-Time Options:''' Node.JS enables you to write real-time applications with ease, for example, with Socket.IO.

=== Node.JS Cons ===

* '''Lack of Conventions:''' Like Bottle, Flask, and most other microframeworks, Node.JS and Express don't force you to stick to predefined conventions, giving the potential to build messy code.

[[Category:Module 8]]

Regular Expressions

2014-01-11T11:53:05Z

Shane: Adding Regex XKCD

Is this string a phone number? Is it an e-mail address? Is it a URL? How do I parse the time of day out of this date string? How do I find all words in the string that contain the letter "a"?

The tool we use to answer these questions is '''regular expressions'''. Regular expressions are a powerhouse for string matching.

This guide serves as an introduction to regular expressions. However, there is enough to discuss about them that regular expressions could be their ''own class''. We will only be scratching the surface so that you can get up and running with regular expressions and start to use them in your projects.

{{XKCD
|name=regex_golf
|id=1313
}}

== Testing Regular Expressions ==

There are several tools freely available online to assist you when writing regular expressions. In this wiki, we will be using two:

* '''[http://regexpal.com/ RegExPal]:''' Performs a global search on an input string. Best for writing regular expressions used for parsing text.
* '''[http://www.debuggex.com/ Debuggex]:''' Matches a regular expression against the input string, but does not support searches. Shows a schematic to help you understand what your regular expression is doing. Best for fine-tuning regular expressions that act on known input formats.

You can view all regular expressions on this page in RegExPal or Debuggex by pressing "View in _____" above each example.

== Your First Regular Expression ==

Here we go. If you wish to follow along, click "View in RegExPal" below; Debuggex does not work well for this example.

{{RegexExample
|regex=\b\ware\b
|str=The tortoise and the hare took on a dare to find the rare Aare.
|method=regexpal
}}

This regular expression finds all words of the form "_are", where _ is an alphanumeric character, and matches that first letter. Let's go through the parts of this regular expression.

* '''\b''' means "word boundary". If we didn't have the '''\b''''s, then this regular expression would also match words like "dayc'''are'''" or "app'''are'''l" or "'''are'''st".
* '''\w''' means "any alphanumeric character or underscore". Thus, this regular expression will match '''dare''', '''care''', '''zare''', '''5are''', '''_are''', and so on.
* '''are''' are literal characters in the regular expression.

Here is a little animation to help you visualize how this regular expression is assembled:

[[File:RegexExampleAnimation-32.gif]]

== Regular Expression Syntax ==

Character classes and modifiers enable you to fine-tune your matches..

=== Character Classes ===

A '''character class''' enables you to match any one of a set of characters. Surround your characters of interest in square brackets.

The following regular expression matches all occurrences of a vowel:

{{RegexExample
|regex=[aeiou]
|str=The quick brown fox jumps over the lazy dog.
|method=regexpal
}}

Character classes can be ''negated'' by starting the character set with a caret '''^'''. For example, the following regular expression matches all occurrences of a consonant:

{{RegexExample
|regex=[^aeiou\W]
|str=The quick brown fox jumps over the lazy dog.
|method=regexpal
}}

The '''\W''' is a shorthand character class that prevents the above regular expression from also matching non-word characters.

=== Shorthand Character Classes ===

Some character classes are provided for you by default.

{| style="text-align:center; font-size:1.2em;" cellpadding="10"
!Description
!Literal Character Class
!Shorthand
|-
|Digit
|[0-9]
|\d
|-
|Word Character
|[A-Za-z0-9_]
|\w
|-
|Whitespace
|[ \t\r\n]
|\s
|-
|Non-Digit
|[^0-9]
|\D
|-
|Non-Word Character
|[^A-Za-z0-9_]
|\W
|-
|Non-Whitespace
|[^ \t\r\n]
|\S
|-
|Wildcard character except for line breaks
|[^\r\n]
|.
|}

=== Quantifiers ===

For a character, character class, or group, you can specify a required number of occurrences.

{| style="text-align:center; font-size:1.2em;" cellpadding="10"
!Description
!Syntax
!Example
|-
|Zero or more of
| *
|Match any string, even the empty string: <code>.*</code>
|-
|One or more of
| +
|Match any string, except for the empty string: <code>.+</code>
|-
|Zero or one of
| ?
|Match either "color" or "colour": <code>colou?r</code>
|-
|''N'' of
| {N}
|Match all three-digit numbers: <code>\b\d{3}\b</code>
|-
|Between ''M'' and ''N'' of
| {M,N}
|Match all two- or three-digit numbers: <code>\b\d{2,3}\b</code>
|}

==== Greedy and Lazy Quantifiers ====

By default, the '''*''' and '''+''' quantifiers are '''greedy''': this means that they will continue searching until the end of the string if they can. More often, however, you want them to stop as soon as something matching the next part of your regular expression is found. This is where '''lazy''' modifiers come into play.

To make '''*''' or '''+''' lazy, simply add a '''?''', as in '''*?''' and '''+?'''.

For example, you might write the following regular expression to match all HTML tags (view in RegExPal to follow along):

{{RegexExample
|regex=<.+>
|str=Hello <p><strong>Roses</strong> are <em class="red">Red</em></p> Goodbye
|method=regexpal
}}

However, this will not separately match the HTML tags; instead, it will start from the first occurrence of '''<''' and continue until the ''last'' occurrence of '''>'''. This is the ''greedy'' behavior. The following regular expression will perform what you want:

{{RegexExample
|regex=<.+?>
|str=Hello <p><strong>Roses</strong> are <em class="red">Red</em></p> Goodbye
|method=regexpal
}}

Now, the match will stop as soon as a '''>''' is encountered.

=== Anchors ===

If your regular expression begins with a cared '''^''', you will generate only one match, which must be at the beginning of the string. If your regular expression ends with a dollar sign '''$''', you will generate only one match, which must be at the end of the string. If your regular expression starts with a '''^''' ''and'' ends with a '''$''', you will match if and only if the entire string matches the entire regular expression.

For example, the following regular expression generates a match on all strings that start with a capital letter:

{{RegexExample
|regex=^[A-Z]
|str=Hello World
|method=regexpal
}}

The following regular expression tests whether the entire string is a valid US phone number:

{{RegexExample
|regex=^\d{3}-\d{3}-\d{4}$
|str=314-935-5555
|method=regexpal
}}

=== Groups ===

'''Groups''' enable you to perform operations on multi-character strings. To specify a group, surround it with parentheses '''()'''.

For example, the following regular expression crudely matches a domain name:

{{RegexExample
|regex=[\w\-]+(\.[\w\-]+)+
|str=example.co.uk
|method=debuggex
}}

First, we match one or more word character or hyphen, and then we match one or more suffixes, each suffix consisting of a period followed by one or more word characters.

== Regular Expression Examples ==

You know know enough to write some pretty sophisticated regular expressions.

Can you figure out what the following regular expression matches?

{{RegexExample
|regex=^[\w!#$%&'*+/=?^_`{}~-]+@[\w\-]+(\.[\w\-]+)+$
|str=me@example.com
|method=debuggex
}}

If you guessed "e-mail address", you are correct! You can recognize that our domain-name regular expression has been copied after the "@" sign, and before the "@" sign is simply one or more of an alphanumeric or a handful of other characters. We also surrounded the regex with '''^''' and '''$''' to ensure that we match the entire string.

Can you guess this one?

{{RegexExample
|regex=^\d{1,3}(\.\d{1,3}){3}$
|str=128.252.202.246
|method=debuggex
}}

This will match an IP address (IPv3). We use the quantifier-on-group trick like we did earlier when we matched valid domain names.

Note: Both of these examples are crude. You should use formal regular expressions issued by organizations like the IETF when matching e-mail addresses and the like.

== Groups ==

One use of regular expressions is when you want to extract information of a known format out of a string. This is when ''groups'' come into play.

For example, consider the phone number expression from before. Suppose we test it against the phone number "123-456-7890":

{{RegexExample
|regex=\d{3}-(\d{3})-\d{4}
|str=123-456-7890
|method=debuggex
}}

Notice how we put parentheses around the second set of digits. This makes the second set of digits a ''group''. View the regular expressin in Debuggex, and you can see how the second set of numbers in the phone number is matched as the group.

What happens if we put parentheses around all three?

{{RegexExample
|regex=(\d{3})-(\d{3})-(\d{4})
|str=123-456-7890
|method=debuggex
}}

We now have ''three'' groups matched:

# '''123'''
# '''456'''
# '''7890'''

We can also have groups within other groups. For example, we could match the area code (the first set), the office code (the second set), the station code (the third set), and the subscriber code (the second and third sets combined):

{{RegexExample
|regex=(\d{3})-((\d{3})-(\d{4}))
|str=123-456-7890
|method=debuggex
}}

Open that in Debuggex to visualize how the groups are formed.

Different programming languages all have different ways to extract groups from a match. These different methods are documented in the next section.

=== Non-Capturing Groups ===

You can ignore certain groups from being matched by appending '''?:''' to the start of the parentheses. For example, if you wanted to ignore matches from the group in the URL regex we made above, you would add '''?:''' in the correct spot:

{{RegexExample
|regex=[\w\-]+(?:\.[\w\-]+)+
|str=bbc.co.uk
|method=debuggex
}}

== Using Regular Expressions in Programming Languages ==

You are learning three new programming languages in CSE 330: [[PHP]] (from Module 2), [[Python]] (from Module 4), and [[JavaScript]] (from Module 6). Below, you may find how to implement regular expressions in each of these three languages.

The example is a function that tests whether a string matches a regular expression representing an e-mail address, and if it does, the function returns the domain name from the e-mail.

=== PHP ===

The magic function in PHP is '''preg_match($regex, $str, $matches)''', where ''$regex'' is the regular expression, ''$str'' is the string to test, and ''$matches'' is an extra argument which will be modified to contain the matches array. By convention, the regular expression itself must be surrounded in forward slashes.

<source lang="PHP">
function domain_from_email($str){
$email_regex = "/^[\w!#$%&'*+\/=?^_`{|}~-]+@([\w\-]+(?:\.[\w\-]+)+)$/";
if(preg_match($email_regex, $str, $matches)){
return $matches[1];
} else return false;
}

echo domain_from_email("sam@bbc.co.uk"); // bbc.co.uk
</source>

If you want to perform a global search for ''all'' matches of a regular expression, use '''preg_match_all($regex, $str, $matches)''' instead.

<source lang="PHP">
function find_all_email_domains($str){
$email_regex = "/\b[\w!#$%&'*+\/=?^_`{|}~-]+@([\w\-]+(?:\.[\w\-]+)+)\b/";
preg_match_all($email_regex, $str, $matches);
return $matches[1];
}

print_r(find_all_email_domains("sam@bbc.co.uk, julie@amazon.com, rick@wustl.edu"));
// Array ( [0] => bbc.co.uk [1] => amazon.com [2] => wustl.edu )
</source>

=== Python ===

To use regular expressions in Python, you need to import the '''re''' module. From there, you can compile your regular expression and perform searches with it.

<source lang="python">
import re

email_regex = re.compile(r"^[\w!#$%&'*+/=?^_`{|}~-]+@([\w\-]+(?:\.[\w\-]+)+)$")

def domain_from_email(test):
match = email_regex.match(test)
if match is not None:
return match.group(1)
else:
return False

print(domain_from_email("sam@bbc.co.uk")) # bbc.co.uk
</source>

Note that we prefix our regex string with an "r", for a "raw string". This is to prevent Python from trying to parse special characters in our regular expression.

To perform global searches, use the regex '''findall''' method:

<source lang="python">
import re

email_regex = re.compile(r"\b[\w!#$%&'*+/=?^_`{|}~-]+@([\w\-]+(?:\.[\w\-]+)+)\b")

def find_all_email_domains(test):
return email_regex.findall(test)

print(find_all_email_domains("sam@bbc.co.uk, julie@amazon.com, rick@wustl.edu"))
# ['bbc.co.uk', 'amazon.com', 'wustl.edu']
</source>

In Python if you want to use the \b in a regex string (without declaring the string as raw) you need to use the \\b instead of \b . Consider the examples below, which provide the same output, the first uses the raw input parameter, the second does not.

<source lang="python">
import re

re.match(r"\bhello world\b","hello world").group()

re.match("\\bhello world\\b","hello world").group()
</source>

=== JavaScript ===

{{DoctypeTV
|youtube_id=7dVfzg22ono
|time=3m58s
|desc=Basics of Regular Expressions. Uses JavaScript as the language of focus.
}}

Regular expressions in JavaScript are their own native data type, so native that they are expressed using literals surrounded with forward slashes and not even strings.

To perform a simple match, call the '''test''' method on the regular expression:

<source lang="javascript">
alert(/^\d+$/.test("123")); // true
</source>

To find a match, call the '''exec''' method on the regular expression:

{{DoctypeTV
|youtube_id=vpqV8n56J6w
|time=5m34s
|desc=Regular Expressions in JavaScript Part 2.
}}

<source lang="javascript">
var emailRegex = /^[\w!#$%&'*+\/=?^_`{|}~-]+@([\w\-]+(?:\.[\w\-]+)+)$/

function domainFromEmail(str){
if(match=emailRegex.exec(str)){
return match[1];
}
}

alert(domainFromEmail("sam@bbc.co.uk")); // bbc.co.uk
</source>

{{DoctypeTV
|youtube_id=WwsNPSO7J-I
|time=1m48s
|desc=Regular Expressions in JavaScript Part 3.
}}

Continue calling the '''exec''' method to produce more matches:

<source lang="javascript">
var emailRegex = /\b[\w!#$%&'*+\/=?^_`{|}~-]+@([\w\-]+(?:\.[\w\-]+)+)\b/g

function findAllEmailDomains(str){
var matches = []
while(match=emailRegex.exec(str)){
matches.push(match[1]);
}
return matches;
}

alert(findAllEmailDomains("sam@bbc.co.uk, julie@amazon.com, rick@wustl.edu"));
// bbc.co.uk,amazon.com,wustl.edu
</source>

'''Note:''' In order to make the regular expression "searchable", we need to add the '''g''' flag in its definition. The flag goes after the closing forward slash.

== Using Regular Expressions in Your Workflow ==

Regular expressions aren't limited to use in programming languages. In fact, you can use them ''right now'' in your text editor!

In Komodo, go to '''File->Find''', and in the dialog, select "Regex". Bam: whatever you type into the search box will be evaluated as a regular expression! Here is an example where I find all end tags in my document:

[[File:KomodoRegexSearch.jpg]]

You can also do regular expression '''find and replace''' in Komodo. You can use groups, too: in the "Replace with" box, a '''\1''' will insert your first group, a '''\2''' will insert your second group, and so on. Nifty!

[[Category:Module 4]]

Extensible Calendar

2014-01-04T07:39:05Z

Shane:

Module 3

2013-12-22T05:30:46Z

Shane: Adding link to coderesponsibly.org

__NOTOC__
In Module 3, you will learn about MySQL, a web application database.

This article contains your assignments for Module 3.

== Reading ==

The following articles on the online class wiki textbook contain information that will help you complete the assignments.

* [[Introduction to MySQL]]
* [[MySQL Schema and State]]
* [[PHP and MySQL]]
* [[Web Application Security, Part 2]]

== Individual Assignments ==

You will create a simple grades database containing four tables.

'''IMPORTANT:''' The individual assignment is to be done by writing queries by hand. (You can use phpMyAdmin to run the queries, but '''do not let phpMyAdmin write your queries for you!''') Writing your own queries gives you a greater understanding of the underlying mechanisms and databases in general. Additionally, having SQL knowledge and experience is a very marketable trait.

=== Install MySQL and phpMyAdmin ===

Before you start, '''you need to install MySQL''' on your EC2 instance. You may also install phpMyAdmin, a web frontend to MySQL, if you choose to do so.

You may find the following article to be very helpful: [[Introduction to MySQL]]

=== Set Up a Database ===

You may find the following article to be very helpful: [[Introduction to MySQL]]

# Create a database named '''wustl'''
# Create a user named '''wustl_inst''' and give them the password '''wustl_pass'''

=== Create Tables ===

You may find the following article to be very helpful: [[MySQL Schema and State]]

When creating tables, keep the following items in mind:

* You should create all tables such that they use the InnoDB storage engine, since we wish to make use of its support of foreign keys. In other database engines, foreign key constraints are not enforced. (If you mess up, you can use ALTER TABLE to change the storage engine.)
* Where it is appropriate, you should take advantage of the ability to define fields NOT NULL so that you do not inadvertently insert incomplete data for a row.

Create the following tables:

# Create a table named '''students''' with the following fields:
#* '''id''' of an appropriately-sized unsigned integer type (we will never need to process more than a million students)
#* '''first_name''' of type '''VARCHAR(50)'''
#* '''last_name''' of type '''VARCHAR(50)'''
#* '''email_address''' of type '''VARCHAR(50)'''
#: The primary key should be on the '''id''' field.
# Create a table named '''departments''' with the following fields:
#* '''school_code''' of type '''ENUM''' (e.g. "L" for ArtSci and "E" for Engineering). The options are as follows:
#*: 'L', 'B', 'A', 'F', 'E', 'T', 'I', 'W', 'S', 'U', 'M'
#* '''dept_id''' of an appropriately-sized unsigned integer type (in the foreseeable future there will never be more than 200 departments in a school)
#* '''abbreviation''' of type '''VARCHAR(9)''' (e.g. CSE, ChemE, etc)
#* '''dept_name''' of type '''VARCHAR(200)''' (e.g. Computer Science and Engineering)
#: The primary key should be on two fields: '''school_code''' and '''dept_id'''
#: '''Note:''' Why not just use the department ID for the primary key? The ID numbers are sometimes reused across schools. For instance, department 33 in The College of Arts and Sciences is Psychology while department 33 in The School of Engineering and Applied Sciences is Energy, Environmental and Chemical Engineering. Thus we must also include the school code to differentiate them such that the record for E33 is distinct from that of L33.
# Create a table named '''courses''' with the following fields:
#* '''school_code''' of type '''ENUM'''
#*: This should have the same letters in the same order as the '''school_code''' '''ENUM''' field in the '''departments''' table.
#* '''dept_id''' of the same size of integer as in the '''departments''' table
#* '''course_code''' of type '''CHAR(5)''' (this will hold course codes; e.g., '330S', '131', '2960')
#* '''name''' of type '''VARCHAR(150)'''
#: The appropriate fields in this table should make a foreign key reference to the corresponding fields in '''department'''.
#: In addition, it is up to you to determine the field(s) for the primary key.
#: '''Note:''' If you are unsure which fields to make the foreign keys and feel the need to beg your friends or the TAs to give you the answer, bang your head on your desk whilst repeating "I WILL EXERCISE REASON AND COMMON SENSE AND I WILL CURTAIL MY DESIRE TO BLINDLY FOLLOW DIRECTIONS"
#: ''Disclaimer: don't actually bang your head on your desk, the resulting head trauma may in fact make it harder for you to determine which fields should have associated foreign keys.''
# Create a table named '''grades''' with the following fields:
#* '''pk_grade_ID''' of an appropriately-sized unsigned integer type (should be larger than the one you chose for the '''students''' table)
#*: You should declare this field to be '''auto_increment''' and make it the primary key.
#*: This is called a ''surrogate key'' as opposed to a ''natural key'' because it doesn't arise "naturally" from the data; that is to say that it is not derived from application data. The use of surrogate keys vs. natural keys is a polemic issue amongst database designers. For a decently unbiased take on the issue, see this page: http://www.agiledata.org/essays/keys.html#Comparison
#*: '''Food for thought:''' Aside from simply exposing you to the concept, can you think of any reasons why a surrogate key might be preferable for this table? Alternatively, what attributes, if any, could you use as a natural key, and what might be the drawbacks of doing so?
#* '''student_id''' of the same integer (unsigned) type that you chose in the '''students''' table
#* '''grade''' of type '''decimal(5,2)'''
#* '''school_code''' of type '''ENUM'''
#*: Can you guess what entries to use for the enum?
#* '''dept_id''' of the same integer type that you've used for this field in other tables
#* '''course_code''' of the same type you chose for the course code in the '''courses''' table
#: The '''grades''' table should have foreign keys to both the '''students''' table and the '''courses''' table.

=== Populate Tables ===

Now, populate the tables by downloading the text files given below and loading them into the appropriate tables.

'''Note:''' Do not insert all the values manually; instead, use the MySQL's ability to load in data from text files.

You may find the following article to be very helpful: [[MySQL Schema and State]]

The files containing the data are:
* students: http://classes.engineering.wustl.edu/cse330/content/students_data.txt
* courses: http://classes.engineering.wustl.edu/cse330/content/courses.txt
* departments: http://classes.engineering.wustl.edu/cse330/content/departments_data.txt
* grades: http://classes.engineering.wustl.edu/cse330/content/grades_data.txt

=== Insert More Data ===

Insert the following data into the tables that you have created and populated:

# Insert an entry for CSE 330
#: ''If you don't know CSE's department code, how can you find out using the tables in the database?''
# Insert the grades given for the students named below. You may choose to make the entries for whichever classes you like, with the one condition that all of the students must have a grade for CSE 330 (who wouldn't want to take that class: I hear the professor and TAs are amazing!)
#* '''Ben Harper'''
#** E-mail: '''bharper@ffym.com'''
#** Student ID: '''88'''
#** Grades:
#*** 35.5 (CSE 330 grade)
#*** 0
#*** 95
#* '''Matt Freeman'''
#** E-mail: '''mfreeman@kickinbassist.net'''
#** Student ID: '''202'''
#** Grades:
#*** 100 (CSE 330 grade)
#*** 90.5
#*** 94.8
#* '''Marc Roberge'''
#** E-mail: '''mroberge@ofarevolution.us'''
#** Student ID: '''115'''
#** Grades:
#*** 75 (CSE 330 grade)
#*** 37
#*** 45.5
#: You may choose any 3 classes you'd like for them to be enrolled in, with at least one class, "CSE 330S", in which they are all enrolled.

=== Querying Your Database ===

Now that you have a fully-functional, populated database, let's do some queries on it!

Please take a screenshot of running the following '''select''' queries and show them to a TA (be sure to include your query command and the response:

# Select the entire grades table.
# Select all fields describing the courses offered in the school of arts and sciences (school code L).
# The names, student IDs, and grades of the students who are in CSE330.
#: '''Note:''' This query should involve joins. You don't need to use any aggregation functions.
# The names, e-mails, and average grades of any student with an average below 50 so that the dean can send them an email notification that they are now on academic probation.
#: ''You should be able to do this in only one query, without making any temporary tables. You will need to use aggregation functions and the '''having''' keyword.''
# An individual report card for Jack Johnson, consisting of his student ID, e-mail address, and average grade.
#: ''Again, you should be able to do this in just one query, using the correct combination of aggregation functions and joins.''
#: '''Note:''' Your query must look for students with the name Jack Johnson instead of hard-coding the student ID.

== Group Project ==

You will work in pairs on this project. You may work with the same partner from Module 2, or change to someone else.

'''Important Reminder:''' frequently commit your work to your subversion repository as a backup!

=== Simple News Web Site ===

'''Examples:'''
* http://digg.com/
* http://slashdot.org/

You should use '''PHP''' unless you get permission to use another web technology from the instructor. You may also use phpMyAdmin to help set up databases.

You may find this wiki article helpful: [[PHP and MySQL]]

==== Requirements ====

* Users can register for accounts and then log in to the website.
* Accounts should have both a username and a ''secure'' password. '''NEVER store plaintext passwords in a database!'''
*: For more information on password security, refer to [[Web Application Security, Part 2#Password Security|the Web Application Security guide]].
* Registered users can submit story commentary and links to those stories.
*: You do not have to make a distinction between the two types of stories, although if you want to, you could do something with this for the creative portion of your project.
* Registered users can comment on any story.
* Unregistered users can only view stories and comments.
* Registered users can edit and delete their stories and comments.
* All data must be kept in a MySQL database (user information, stories, comments, and categories).
* Creative Portion

=== Web Security and Validation ===

No application is finished until much thought is put into web security and best practice. Throughout this course, we heavily emphasize the dogma of [http://coderesponsibly.org/ responsible] coding.

Read this week's Web Application Security guide: [[Web Application Security, Part 2]]. In particular, your project needs to:

* '''Your application needs to be secure from SQL injection attacks'''. If you are using prepared queries, you should already be safe on this front.
* '''Your passwords need to be securely salted''' to prevent rainbow table attacks.
* '''You should pass tokens in forms''' to prevent CSRF attacks.
* '''You should check all preconditions on the server side''' to prevent Abuse of Functionality attacks.

You shouldn't forget the practices you learned last week:

* '''Your page should validate''' with no errors through the W3C validator.
* '''Filter Input and Escape Output''', but not the other way around.

== Grading ==

We will be grading the following aspects of your work. There are 100 points total.

# '''MySQL Queries (25 Points):'''
#* A MySQL server is running on your instance (2 points)
#* Tables fields, including data types, are correct (4 points)
#* Foreign keys are correct (4 points)
#* The output of each of the five queries is correct (3 points each)
# '''News Site (60 Points):'''
#* '''''User Management (20 Points):'''''
#** A session is created when a user logs in (3 points)
#** New users can register (3 points)
#** Passwords are hashed using salted one-way encryption (3 points)
#** Users can log out (3 points)
#** A user can edit and delete his/her own stories and comments but cannot edit or delete the stories or comments of another user (8 points)
#* '''''Story and Comment Management (20 Points):'''''
#** Relational database is configured with correct data types and foreign keys (4 points)
#** Stories can be posted (3 points)
#** A link can be associated with each story using a separate database field (3 points)
#** Comments can be posted in association with a story (4 points)
#** Stories can be edited and deleted (3 points)
#** Comments can be edited and deleted (3 points)
#**: ''Note: Although there are only 6 points allocated for editing/deleting in this section, there are 8 more points at stake in the User Management section that cannot be earned unless editing/deleting is implemented. Implementing editing but not deleting, or vice-versa, will result in earning half the points.''
#* '''''Best Practices (15 Points):'''''
#** Code is well formatted and easy to read (3 points)
#** Safe from SQL Injection attacks (2 points)
#** Site follows the FIEO philosophy (3 points)
#** All pages pass the W3C validator (2 points)
#** CSRF tokens are passed when creating, editing, and deleting comments and stories (5 points)
#* '''''Usability (5 Points):'''''
#** Site is intuitive to use and navigate (4 points)
#** Site is visually appealing (1 point)
# '''Creative Portion (15 Points)'''

[[Category:Module 3]]
[[Category:Modules]]

Module 8

2013-11-24T10:19:59Z

Shane: Adding out-of-date disclaimer

''THIS PAGE IS OUT OF DATE AND IS HERE FOR REFERENCE ONLY.''

Module 5 is your chance to complete a project of your own creation. There's a reason this class has "Creative Programming" in the title.

== Objective ==

Your project should incorporate topics we have learned throughout this corse, but it should be focussed primarily on some new concept or concepts relating to web development. You should continue the best practices and security protocols you have learned in previous modules as well.

== Technologies ==

We have looked through the projects submitted by all groups, and we have picked out a few technologies that turned up frequently. Below is a short summary of these technologies and the TAs who can help answer questions about them.

=== HTML5 Canvas ===

The HTML5 '''<nowiki><canvas></nowiki>''' element enables you to render dynamic graphics in real-time in the browser. In many ways, you can think of HTML5 Canvas as a substitute for Flash Player: most tasks that Flash Player can do, '''<nowiki><canvas></nowiki>''' can do just as well.

Here are examples of some things you can do with the HTML5 Canvas: http://www.hongkiat.com/blog/48-excellent-html5-demos/

You may want to consider using a dedicated JavaScript library for interfacing with the Canvas. This will ensure better compatibility, and the documentation should be more helpful than trying to figure out the native Canvas methods. Here are some promising Canvas libraries:

* [http://kineticjs.com/ KineticJS]
* [http://fabricjs.com/ Fabric.JS]
* [http://calebevans.me/projects/jcanvas/index.php jCanvas (built on jQuery)]

==== TAs Knowledgeable about Canvas ====

* Paul
* Marc

=== Node.JS and Socket.IO ===

In Module 4, you learned how to use AJAX, which is a technology by which a client can communicate with the server asynchronously. However, AJAX requires that a client '''''ask for data''''' from a server, and the server then sends a ''response''. This approach fails in real-time applications: think chatrooms and online action games.

Socket.IO is a technology that enables the server to send data to the client '''''without the client having to request it first'''''. Node.JS is a server built from the ground up to handle real-time requests efficiently, more so than a server like Apache.

It is important to understand that Socket.IO and Node.JS ''replace'' AJAX, PHP, and Apache in your web application. You can use a technology like [http://expressjs.com/ express] to serve static files so that you don't even need to have Apache running.

It is worth noting that Linux distributions based on Debian are more friendly to Node.JS than distributions based on RHEL. If your main server is running the Amazon Linux AMI, you may want to consider launching a new EC2 instance running Ubuntu Server if you are using Node.JS in your project.

==== TAs Knowledgeable about Node.JS ====

* Shane
* Todd

=== Maps ===

It is common to see maps embedded in web sites. [https://developers.google.com/maps/ Google Maps], [http://api.maps.nokia.com/en/overview.html Nokia Maps], and [http://developer.mapquest.com/ Mapquest] are three examples.

Cendors like Google, Nokia, and Mapquest provide APIs that make it easy for you, the developer, to use their maps on your site. For example, this is all the code you need to display a map of Wash U's campus using the Nokia Map API:

<source lang="javascript">
map = new nokia.maps.map.Display(document.getElementById("mapDiv"), {
zoomLevel: 15,
center: [38.648044, -90.304881]
});
</source>

==== TAs Knowledgeable about Maps ====

* Sid
* Todd

=== Alternate Authentication Methods ===

You have probably used sites that allow you to log in using your Google, Yahoo, Facebook, Twitter, or some other account rather than making a new account with a new password.

It is relatively easy to implement alternate authentication methods like this. OpenID, which is a gateway to account providers like Google and Yahoo, is documented in [[Web Application Security, Part 2#OpenID]].

==== TAs Knowledgeable about Alternate Authentication Methods ====

* Paul
* Shane
* Todd

=== HTML5 Video and Audio ===

In the past, a plugin like Flash was required for viewing media on the web. With HTML5 Video, these plugins are no longer necessary.

In its simplest form, an HTML5 video can be loaded in one line of HTML:

<source lang="html4strict">
<video src="my_video.mp4" type="video/mp4" controls></video>
</source>

Video formats are more complicated than image formats, however, and so it is necessary for you to define multiple source files for the same video, encoded in different formats. For example:

<source lang="html4strict">
<video controls>
<source src="my_video.mp4" type="video/mp4" />
<source src="my_video.ogv" type="video/ogg" />
<source src="my_video.webm" type="video/webm" />
</video>
</source>

I highly recommend that you take the time to read this informative article about HTML5 Video if you choose to employ this technology in your project: http://diveintohtml5.info/video.html

==== TAs Knowledgeable about HTML5 Video and Audio ====

* Shane
* Sid
* Todd

=== CSS 3 ===

CSS 3 adds features to CSS that reduce the need for background images and JavaScript for layout purposes, resulting in a more centralized and robust stylesheet. CSS 3 also enables developers to be more creative with their layouts and typography.

Here are examples of some nifty things that you can do with CSS 3: http://webdesignerwall.com/trends/47-amazing-css3-animation-demos

==== TAs Knowledgeable about CSS 3 ====

* Sid
* Paul
* Shane
* Marc

=== Other APIs ===

Above, we mentioned the Map APIs provided by some vendors. In reality, there are APIs provided for applications extending far beyond Maps. Some of these additional APIs include:

* [http://developer.yahoo.com/finance/ Yahoo Finance]
* [http://www.twilio.com/docs/libraries Twilio]
* [https://dev.twitter.com/docs/twitter-libraries Twitter]
* [http://developers.facebook.com/ Facebook]

==== TAs Knowledgeable about Other APIs ====

* Todd
* Marc

== Grading ==

You should have already turned in a printed copy of your grade sheet. We will grade everyone's projects in class on '''Wednesday, November 14'''. Because of the nature of Module 5 and since everyone's grade sheets are different, '''''you MUST be in class on time and ready to demo, or you risk a severe late penalty (almost 2 letter grades per day).''''' If you wish to demo early, you must do so either in class on Monday or in Marc's office hours on Tuesday. Thanks for your understanding.

[[Category:Module 8]]
[[Category:Modules]]

CSE 330 Online Textbook - Table of Contents

2013-11-24T10:19:16Z

Shane: Adding Module 8

<div style="text-align:center;">[[File:CSE330Banner.png]]</div>

__NOTOC__
<div style="column-width: 300px; -moz-column-width: 300px; -webkit-column-width: 300px;">
{{FrontPageModule
|num=1
|subject=HTML and CSS Fundamentals
|links=
* [[HTML and CSS]]
* [[HTML Forms]]
}}

{{FrontPageModule
|num=2
|subject=Linux, Apache, and PHP
|links=
* [[Linux]]
* [[Bash]]
* [[Amazon Web Services]]
* [[SSH]]
* [[Apache]]
* [[PHP]]
* [[Workflow]]
* [[Web Application Security, Part 1]]
}}

{{FrontPageModule
|num=3
|subject=SQL Databases
|links=
* [[Introduction to MySQL]] (installation)
* [[MySQL Schema and State]] (queries)
* [[PHP and MySQL]] (using MySQL from PHP)
* [[Web Application Security, Part 2]]
}}

{{FrontPageModule
|num=4
|subject=Scripting for Rapid Prototyping
|links=
* [[Python]]
* [[Regular Expressions]]
}}

{{FrontPageModule
|num=5
|subject=Version Control Systems and Web Frameworks
|links=
* [[Git]]
* [[Web Frameworks]]
}}

{{FrontPageModule
|num=6
|subject=JavaScript and APIs
|links=
* [[JavaScript]]
* [[AJAX and JSON]]
* [[Ext JS]]
* [[Extensible Calendar]]
* [[Web Application Security, Part 3]]
}}

{{FrontPageModule
|num=7
|subject=Real-Time Web Applications
|links=
* [[Node.JS]]
* [[Socket.IO]]
* [[Pong Game]]
}}

{{FrontPageModule
|num=8
|subject=Creative Project
|links=
* [[Choosing a Platform]]
}}

</div>

== Reference ==

Use this wiki as a starting place for your projects in CSE 330. However, web development is a large field, so it is impossible for us to document everything you might need to know. Here are some other places you should look when you need to find something:

* [http://www.webplatform.org/ WebPlatform.org], a community-driven source containing documentation and tutorials for Web technologies
* [http://www.w3.org/community/webed/wiki/Main_Page The Web Education Community Group Wiki], also sponsored by the W3C.
* [http://reference.sitepoint.com/html SitePoint], which has a reference page as well as quality articles and tutorials
* Also take a look at [http://designfestival.com/13-time-saving-tools-for-web-designers/ this list of productivity tools] for web development.

If you can't find what you need in any of these places, try using your favorite search engine. '''Be wary of sites that come up on search engines.''' Many HTML reference sites document bad practices and dated techniques. If you're unsure whether a reference site you find is legitimate, ask a TA.

== Want to Learn More? ==

The limited amount of time in CSE 330 means that we can cover only a subset of the wide range of possible topics in the field of rapid prototyping and web development. Indeed, the exact topics covered in CSE 330 change from year to year.

Feel free to browse some of the topics that have previously been covered in CSE 330: [[:Category:Former Content|CSE 330 Former Content]]

You should also consider following blogs like [http://www.sitepoint.com/ SitePoint] to keep up-to-date on the latest developments in the field of web development.

== Content License ==

The content of this wiki is copyright (c) 2013, Washington University in St. Louis, Department of Computer Science. All rights reserved.

=== Modified BSD License ===

Redistribution and use in source and binary forms, with or without modification, by a Third Party who has not completed and is not in the process of completing CSE 330, of the code examples or concepts on this wiki, are permitted, provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of the Washington University School of Engineering and Applied Science nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS TO ALL PARTIES "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=== What it Means ===

If you are a student in CSE 330, you may use the code from this wiki freely in your projects without the need for attribution. If you are not a student in CSE 330, you may use the code from this wiki freely in your projects with attribution. Either way, the code examples are provided "as is", without any warranty, and Washington University holds no liability for problems arising from the use of the content in this wiki.

Choosing a Platform

2013-11-24T10:18:33Z

Shane: Creating with all new content

You've learned a large variety of platforms in this course. Which one should you use? This page summarizes some of the pros and cons of each platform.

== PHP ==

[[PHP]] is a language built for server-side web development. You built a [[Module 2|file sharing application]] and a [[Module 3|news syndication site]] in PHP.

=== PHP Pros ===

* '''Largest support community:''' Easy to find help if you get stuck.
* '''Distribution:''' Runs on virtually any web server in existence.

=== PHP Cons ===

* '''Language:''' Few people will say that PHP is the most elegant language known to mankind. The language makes it easy to fall into the trap of bad coding practices.
* '''Security:''' PHP does very little for you automatically in terms of web security.

== Django ==

[[Web Frameworks|Django]] is a web frameworks written in the [[Python]] scripting language. In more ways than not, it is the Python equivalent of [[wikipedia:Ruby on Rails|Ruby on Rails]].

=== Django Pros ===

* '''Less Code:''' Implementing common web design patterns, like social login or commenting, is usually as easy as a ''pip install''.
* '''Conventions:''' Django forces you to write neat and organized code, leading to better software engineering practices and scalability down the road.
* '''Security:''' Django automatically implements common security practices, leading to a more robust web application.

=== Django Cons ===

* '''Difficult to Debug:''' Django's high level of abstraction is a double-edged sword, because bugs and errors are sometimes difficult to find and can take hours to fix.
* '''Heavyweight:''' Django is designed for larger web applications, and it is not suitable for smaller projects with just one or two controllers.

== Bottle and Flask ==

Bottle is a web ''microframework'' written in the [[Python]] scripting language. Flask is similar option. Although you did not explicitly use Bottle or Flask during a module, it's worth listing on this page. In more ways than not, Bottle and Flask are the Python equivalents of the better-known [[wikipedia:Sinatra (software)|Sinatra]], a Ruby microframework.

=== Bottle and Flask Pros ===

* '''Lightweight:''' There are few enough files that you can find your way around and be in full control of your application logic.
* '''Access to Python Libraries:''' A lot of the things you do in Django you can do in Bottle and Flask, except that you have more control over the ways that they are implemented.

=== Bottle and Flask Cons ===

* '''Lack of Conventions:''' Bottle and Flask give you the tools you need to build maintainable code, but unlike Django, they don't force you to. It's easy to end up with Python scripts containing hundreds of lines of unrelated application logic.

== Node.JS and Express ==

[[Node.JS]] is a low-level implementation of JavaScript that enables you to write networked and web applications. Express is a Sinatra-like microframework that runs on top of Node.jS.

It is also worth bringing your attention to [http://www.meteor.com/ Meteor], a bleeding-edge framework for Node.JS that abstracts away client-server communications. (Watch the promo video; it's pretty awesome.)

=== Node.JS Pros ===

* '''Speed:''' Node.JS is the fastest of the options on this page. It is easy to scale up your Node.JS applications.
* '''Modern:''' Node.JS is also the newest of the options on this page, so most of the plugins you find for it use the best and latest practices.
* '''Language:''' With Node.JS, you can use just one language for both your server-side and client-side logic.
* '''Real-Time Options:''' Node.JS enables you to write real-time applications with ease, for example, with Socket.IO.

=== Node.JS Cons ===

* '''Lack of Conventions:''' Like Bottle, Flask, and most other microframeworks, Node.JS and Express don't force you to stick to predefined conventions, giving the potential to build messy code.

[[Category:Module 8]]

Pong Game

2013-11-20T09:48:09Z

Shane: /* Connecting to Socket.IO */ Changing to conventional notation

Socket.IO

2013-11-20T09:47:00Z

Shane: /* The Chat Server */ Changing to conventional notation

AJAX is useful when one-way communication is satisfactory for your web application. However, what happens when you need two-way communication, like a chat client or multiplayer game? AJAX isn't the tool for the job. This is where '''Socket.IO''' comes in.

Built to work natively with Node.JS, Socket.IO enables asynchronous, two-way communication between the server and the client. This means that the server can send messages to the client without the client having to ask first, as is the case with AJAX. As you learn Socket.IO, Non-Blocking I/O will become your best friend!

== Installing Socket.IO ==

Before you install Socket.IO, you need to install [[Node.JS]] and NPM, which is often installed automatically when you install Node.JS.

The NPM package manager is different from many of the package managers we've used in that you need to install remote packages for every project in which you use them. This means that you need to '''cd''' to the working directory in which you want to keep your Node.JS JavaScript file, ''and then'' run the following command:

<source lang="bash">
$ npm install socket.io
</source>

'''Note:''' If you pass the ''-g'' to ''npm install'', then the package will be installed "globally" on your instance, so all Node.JS projects will be able to use it. However, this is not recommended for all projects. [http://blog.nodejs.org/2011/04/06/npm-1-0-link/ Read Node.JS's justification here.]

== Messaging ==

Socket.IO works by having clients send messages to the server and the server send messages to clients. For example, consider the code:

<source lang="javascript">
// Computer A:
socket.emit("info", {
"hello": "world"
});

// Computer B:
socket.on("info", function (data) {
console.log(data.hello);
});
</source>

Computer A could be ''either the client or the server'', and Computer B would be the other. When '''socket.emit(name, data)''' is called on either end, the callback function in '''socket.on''' that listens for the message named ''name'' is called with the ''data'' from '''socket.emit'''.

== A First Socket.IO Application: Chat Server and Client ==

Building a chat client is surprising simple using Socket.IO and Node.JS, and it gives great insight into the workings of Socket.IO. Take the time to understand how this example works, and ask questions; if you understand this, the group portion will be easy!

=== The Chat Server ===

You can make a file called ''chat-server.js'' with the following code:

<source lang="javascript">
// Require the packages we will use:
var http = require("http"),
socketio = require("socket.io"),
fs = require("fs");

// Listen for HTTP connections. This is essentially a miniature static file server that only serves our one file, chat.html:
var app = http.createServer(function(req, resp){
// This callback runs when a new connection is made to our HTTP server.
fs.readFile("chat.html", function(err, data){
// This callback runs when the chat.html file has been read from the filesystem.
if(err) return resp.writeHead(500);
resp.writeHead(200);
resp.end(data);
});
});
app.listen(3456);

// Do the Socket.IO magic:
var io = socketio.listen(app);
io.sockets.on("connection", function(socket){
// This callback runs when a new Socket.IO connection is established.
socket.on("message", function(content){
// This callback runs when the client sends us a "message" event
console.log("message: "+content); // log it to the Node.JS output
socket.broadcast.emit("someonesaid", content); // broadcast the message to other users
});
});
</source>

The above code makes a simple HTTP server that responds to all connections with the contents of the file "chat.html", which we will make in the next step. We tell Socket.IO to listen for "message" events, and when it hears one, it should emit a new event called "someone said" back to the connected clients.

=== The Chat Client ===

Here is a front-end client that could work with our server, in ''chat.html'':

<source lang="html4strict">
<!DOCTYPE html>
<html>
<head>
<title>Chat Client</title>


<script src="/socket.io/socket.io.js"></script>
<script src="//cdn.sencha.io/ext-4.1.1-gpl/ext-all-dev.js"></script>


<script>
Ext.DomHelper.useDom = true; // prevent XSS

var socket = io.connect();
socket.on("someonesaid", function(content){
// This callback runs when the server sends us a "someonesaid" event
Ext.fly("messages").createChild({
tag: "li",
children: [content]
});
});
Ext.onReady(function(){
Ext.fly("send").on("click", function(){
// When the "send" button is clicked, emit a "message" event to the server containing a chat message
socket.emit("message", Ext.fly("comment").getValue());
});
});
</script>

</head>
<body>
<ul id="messages">
</ul>

<p>
<textarea id="comment"></textarea>
<button id="send">Send Comment</button>
</p>
</body>
</html>
</source>

'''Note:''' This example passes strings as the event data, but you can pass any JavaScript datatype, including object literals.

To see this in action, save these two files in the same directory, cd over to the directory, and start the server:

<source lang="bash">$ node chat-server.js</source>

Fire up your favorite browser and navigate to http://localhost:3456/. Open the page in two windows. Violà: you have your (very basic) chat client!

== Resources ==

The [http://socket.io/ Socket.IO web site] has concise examples that tell you pretty much all you need to know in order to build a functional Socket.IO web application.

[[Category:Module 7]]

Pong Game

2013-11-19T06:06:14Z

Shane: Adding flow chart

This article documents ''pong-game.js'', a pre-built JavaScript file that helps you implement your pong game.

== Setup ==

First thing first: set up a static file server running Node.JS. We will need it in order to serve up our HTML and JavaScript content.

=== File 1: pong-game.js ===

The first file you can save in your ''static'' directory will be ''pong-game.js'', which you can download from here: http://classes.engineering.wustl.edu/cse330/content/pong-game.js

We created the ''pong-game.js'' file for you to save you time and so that you can focus on the Node.JS and Socket.IO aspects of this module. This file contains the core Pong engine, but it does ''not'' establish communication between users of any kind.

=== File 2: client.js ===

You should create an additional file, ''client.js'', which you include into ''client.html'' and which contains the client-side logic for your Pong game. It should load after ''pong-game.js''. You will be saving all of you client-side code in this file.

=== File 3: client.html ===

The third file you can save in your ''static'' directory should be an HTML file created from your favorite [[HTML and CSS#Quick and Easy Page Layout|Quick and Easy Page Layout]]. You need to add the following CSS rules:

<source lang="css">
#gameContainer{
margin: 0 auto;
width: 960px;
height: 500px;
}
#controls{
height: 20px;
text-align: center;
}
#game{
width: 960px;
height: 480px;
border: 1px solid black;
}
</source>

Add the following HTML inside your ''main'' div; this is what will contain the Pong game canvas:

<source lang="html4strict">
<div id="gameContainer" style="display:none;">
<div id="game"></div>
</div>
</source>

You also need to require ''pong-game.js'' and ''client.js''.

<source lang="html4strict">
<script src="pong-game.js"></script>
<script src="client.js"></script>
</source>

=== Connecting to Socket.IO ===

Now that you have your static fileserver running that serves up your three files (''pong-game.js'', ''client.html'', and ''client.js''), we need to connect everything with Socket.IO.

Set up a static fileserver by following the instructions in [[Node.JS|the Node.JS guide]]. When finished, add the following lines:

<source lang="javascript">
io.listen(app).sockets.on("connection", function(socket){
// This closure runs when a new Socket.IO connection is established.

// Listen for client messaging server:
socket.on("message", function(content){
// do stuff
});

// Send a message from the server to the client:
socket.emit("message", {some:"data"});
});
</source>

Don't forget to require socket.io at the top of your file!

<source lang="javascript">
io = require("socket.io")
</source>

You also need to make sure to install ''socket.io'' from npm.

Inside of the ''io.listen'' callback function is where most of your server-side code will go.

On the client side, you need to include the Socket.IO library (put this above ''pong-game.js'' and ''client.js''):

<source lang="html4strict"><script src="/socket.io/socket.io.js"></script></source>

And finally, you need to connect your client to the Socket.IO server (put this in ''client.js''):

<source lang="javascript">var socket = io.connect(window.location.origin);</source>

But enough of us giving you all the code! It's time for you to start being creative.

== The API ==

For the remainder of this module, your work will be in three files:

* app.js (or whatever you called your Node.JS file)
* client.html
* client.js

What you need to do is to build a system that enables two players who are both viewing ''client.html'' to choose each other (e.g., from a lobby) and play a game of Pong.

You should be wondering, "how do I interact with the Pong game?" The public interface is as follows.

=== Methods ===

* '''pong.init()'''
*: Initialize the game client.
* '''pong.resetBall([x, y])'''
*: Arbitrarily set the position of the ball. Defaults to the center if no arguments are given. Cancels all animations currently acting on the ball.
* '''pong.launch(angle, direction)'''
*: Launch the ball ''from its current position'' in the specified ''angle'' (-89 to +89) and direction (-1 for left or 1 for right).
* '''pong.updateOpponentPaddle(position)'''
*: Set the position of the opponent paddle to ''position''. (Hint: the ''position'' value should have been generated by the opponent's '''paddlemove''' event)
* '''pong.pauseOrResumeGame()'''
*: Set the game in a paused state, or remove the game from a paused state.
* '''pong.ready()'''
*: Returns true if the game is not in a "paused" state.
* '''pong.setScore(score)'''
*: Display score on the game canvas. ''score'' is an object literal containing two fields: left and right.

=== Events ===

All events for the pong game are fired on the window.

* '''paddlemove'''
*: The player's paddle has moved.
*: This event will fire only after the paddle has moved 15 pixels or more.
** '''event.detail.position'''
**: The new y coordinate of the paddle.
* '''paddlehit-left'''
*: The ball has hit the left side of the screen.
** '''event.detail.hit'''
**: True if the ball hit the player's paddle; false otherwise.
** '''event.detail.angle'''
**: If the ball was reflected, the new angle of the ball's rightward movement.
** '''event.detail.position'''
**: The position at which the ball hit the left side.

=== Problems with Our Interface ===

There are at least two major problematic issues with our API:

* We are firing events on the window. We should have taken the time to make our Pong class implement the EventTarget interface directly.
* We are putting more trust in the client than we should, because the client can fake any angle and position upon the '''paddlehit-left''' event and manipulate the game in his or her favor. The trajectory should be computed on the Node.JS side.

Just be aware of the above issues as you complete this lab. You won't be required to fix them, although if you do (and if you recompile your modified code with Lime) you may be a candidate for extra credit.

=== Enabling a Player to Pause ===

''You do not need to implement pausing for the purposes of Module 7. If you do, you can earn 5 points of creative portion.''

Implementing a game pause is more difficult for a network game than it is for a game that runs on just one computer: you need to make sure that the game is in a state such that you won't run into any race conditions, etc.

One situation during a Pong game when it makes sense to enable a user to pause the game is after a user has lost a round. Since the game at that point in time is waiting for the player to launch the next ball, we shouldn't have any race conditions.

If you implement pausing, the '''pong.pauseOrResumeGame()''' and '''pong.ready()''' functions will come in handy.

== Examples ==

=== Starting a Pong Game ===

Once two players have formed a pair, one of them needs to initialize the game with a certain angle and direction for the ball. Here is how you might go about doing this:

<source lang="javascript">
// generate an initial angle between -60 degrees and +60 degrees:
var initAngle = -60 + 120*Math.random();

// randomly choose the initial direction of the ball:
var initDirection = Math.random() < 0.5 ? -1 : 1;

// show the game canvas:
document.getElementById("gameContainer").style.display = "block";

// initialize the game canvas:
pong.init();

// move the ball to the center:
pong.resetBall();

// set the ball into motion:
pong.launch(initAngle, initDirection);

// tell the server about the ball's initial angle and direction. For example:
socket.emit("launch", {
angle: initAngle,
direction: initDirection
});
</source>

=== When a Player Reflects the Ball ===

When the ball hits a player's side, the '''paddlehit-left''' event fires on the window. Here is how you might listen for this event in your ''client.js'' and transmit this information over your socket:

<source lang="javascript">
window.addEventListener("paddlehit-left", function(e){
// e.detail.hit will be true if the client hit the ball with his/her paddle.
if (e.detail.hit) {
console.log("HIT PADDLE. New angle: %f", e.detail.angle); // log a message to the console

// Tell our opponent via Socket.IO about the ball's new angle and position:
socket.emit("reflect", {
angle: e.detail.angle,
position: e.detail.position
});

// Note: The game automatically launches the ball and determines the angle based on the ball's position relative to the paddle position. We therefore do not need to call pong.launch() in here (but our opponent will, as shown below).
}else{
console.log("MISSED PADDLE");

// in here, we will update the score, check for victory condition, launch a new ball (perhaps after a timeout), etc.
}
});
</source>

Here is what you might have in ''app.js'' inside of your Socket.IO callback function:

<source lang="javascript">
// Listen for the "reflect" message from the client
socket.on("reflect", function(data){
// Tell our opponent about the reflection.
// Note: In this sample implementation, we store the opponent in `socket.opponent`.
// You might use a different mechanism for storing the opponent's socket.
socket.opponent.emit("reflect", data);
});
</source>

Finally, here is what you might have on the opponent's end (hint: this is also in ''client.js''):

<source lang="javascript">
// Listen for the "reflect" message from the server
socket.on("reflect", function(data){
// In order to make up for any network lag, immediately move the ball to its correct position:
pong.resetBall(960, data.position);

// Finally, launch the ball on our local game client:
pong.launch(data.angle, -1);
});
</source>

== Flow Chart ==

If you are a visual learner, this flow chart of the logic you need to build for the pong game might be useful.

[[File:Module 7 Flow Chart.png]]

== How We Built pong-game.js ==

If you are curious, we used the [http://www.limejs.com/ LimeJS] framework as the backbone of ''pong-game.js''. You can find the pre-compiled source code for the Pong game here:

* http://classes.engineering.wustl.edu/cse330/content/pong.js
* http://classes.engineering.wustl.edu/cse330/content/ball.js

We then used the [https://developers.google.com/closure/compiler/ Google Closure Compiler] to compile all of the libraries you need into the one modular JavaScript file.

Just to be clear, ''for the purposes of Module 7, you do not need to bother with either LimeJS or Google Closure.''

[[Category:Module 7]]