ZIM - Code and Learn Coding with ZIM for JavaScript and HTML Canvas with CreateJS

SKOOL

Practice with ZIM CODE see the Learn Page for tutorials

ALL LESSONS

Lesson 07 - Templates and Building

Theory

We have practiced the basic parts of programming - the commands, the syntax, abstraction and logic. Now it is time to put all these together to make an app.

We will use the term app loosely to mean a game, puzzle, tool, art piece, etc. We can also make a site but sites are more along the lines of what we make with traditional HTML with pages of text and pictures. An app is often one screen perhaps with panels and the user does something - like makes, communicates or plays.


Slides from WHY ZIM video presentation.

In this lesson, we introduce ZIM Frame and the ZIM Templates. We look at the steps to build apps including many common techniques such as using hitTests. Apps can be run in browsers or packaged up as mobile apps.

Let's take a look at REFERENCE and PRACTICE sections for templates and building!

Reference

ZIM Frame ► ZIM Templates
ZIM has a Frame class that makes a canvas tag, a stage, handles scaling and loading of assets. We also store a bunch of ZIM colors - but anytime we use a ZIM color, you are welcome to use any HTML color like "red" or "#C00";

01
// ZIM Frame Fit mode

const frame = new Frame("fit", 1024, 768);
frame.on("ready", ()=>{
    // put code here
});

The ready event is called when the canvas and stage are made. We usually want to get easy access to the stage and its width and height so we store them in shorter variables. We also usually set an outer color for the Browser window and a color for the frame. After our code, we need to update the stage so we see any changes.

02
const frame = new Frame("fit", 1024, 768);
frame.on("ready", ()=>{
    const stage = frame.stage;
    let stageW = frame.stageW; // might be reassigned in resize event
    let stageH = frame.stageH;
    frame.outerColor = dark;
    frame.color = light;

    // put code here


    stage.update(); // to see the changes
});

Scaling Modes ► ZIM Templates
In our lessons, we have been typing code into a textarea and pressing the TEST button. This shows our code in a ZIM Frame in an HTML tag. We call this the TAG mode. Here are the scaling modes for ZIM Frame:

Scaling Modes

Loading Assets ► ASSET Template
We have full control of when to load assets such as images, sound and fonts and events for when they are loaded. In many past ZIM examples, assets were loaded with frame.loadAssets(). Now, we can load assets right in the Frame() call. In the ready event function, we can add the image to the stage, play the sound or use the font.

03
// Loading an image

const assets = "image.jpg";
const frame = new Frame("fit", 1024, 768, lighter, dark, assets);
frame.on("ready", ()=>{
    const image = frame.asset("image.jpg").center();
    etc.

04
// Loading two images - from a folder
const assets = ["image.png", "image2.jpg"];
const path = "assets/";
const frame = new Frame("fit", 1024, 768, lighter, dark, assets, path);
frame.on("ready", ()=>{
    frame.asset("image.jpg").center();
    frame.asset("image2.jpg").loc(100, 100);
    etc.

05
// Loading a sound - using loadAssets with complete event
// could just add the sound to the array in the earlier examples

const loadSound = frame.loadAssets("sound.mp3", "assets/");
loadSound.on("complete", ()=>{
    frame.asset("sound.mp3").play();
    // frame.asset("sound.mp3").play({loop:-1, volume:2});
});

Chrome and Safari give a security ERROR when interacting with local files containing images and sound. The solution is one of the following. Note that this is an error only when testing locally. When your app is on a server or as an app on mobile, there will be no problem.

Remove Security Error

  1. Use Firefox
  2. Put the file on a server
  3. On PC, adjust Chrome as follows:
    • find your Chrome icon or shortcut
    • right click and choose properties
    • under Target, adjust your target to include:
    • --allow-file-access-from-files
    • after the quotes - for example:
    • "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --allow-file-access-from-files
  4. On Mac, adjust Chrome as follows:
    • open your terminal anywhere
    • make sure Google Chrome is currently not running
    • copy paste this line and hit enter
    • open /Applications/Google\ Chrome.app --args --allow-file-access-from-files

06
// Loading a custom font
const assets = {font: "wildwood", src:"wildwood.ttf"};
const path = "assets/";
const frame = new Frame("fit", 1024, 768, lighter, dark, assets, path);
frame.on("ready", ()=>{
    new Label({text:"hello", font:"wildwood"}).center();
});

07
// Loading all together

const assets = [
    "image.png",
    "image2.jpg",
    "sound.mp3",
    {font: "wildwood", src:"wildwood.ttf"}
]; // or put on one line...
const path = "assets/";
const frame = new Frame("fit", 1024, 768, lighter, dark, assets, path);
frame.on("ready", ()=>{
    const img = frame.assets("image.png").center();
    img.on("click", ()=>{
        frame.asset("sound.mp3").play();
        new Label({text:"song title", font:"wildwood"}).center();
        stage.update();
    });

    // rest of your code here...

    stage.update();
}); // end frame ready

Template ► Code Zero - Template
ZIM works within a script tag inside our HTML page. In the past, we guided people to our ZIM ZIP file of HTML templates. Now, we tend to use the easy-to-copy template on the CODE page. We call CreateJS and ZIM libraries then start a script for our code. ZIM makes the canvas in the body. Here is the TOP and BOTTOM of the template:

08
<!-- TEMPLATE TOP -->

<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<title>ZIM Frame - Fit Template</title>

<script src="https://zimjs.org/cdn/1.2.1/createjs_min.js"></script>
<script src="https://zimjs.org/cdn/10.6.0/zim.js"></script>
<!-- use zimjs.com/distill for minified individual functions! -->

<script>
    // our Frame code STARTS here

10
      // our Frame code ENDS here
</script>

<!-- TEMPLATE BOTTOM -->

<meta name="viewport" content="width=device-width, user-scalable=no" />

</head>

<body>
<!-- canvas with id="myCanvas" is made by zim Frame -->
</body>
</html>

So, you can see, that there is not much in the template. Here is a shortened version showing a round draggable circle on the stage:

11
// Small Template
<html>
<script src="https://zimjs.org/cdn/1.2.1/createjs_min.js"></script>
<script src="https://zimjs.org/cdn/10.6.0/zim.js"></script>
<script>
    const frame = new Frame();
    frame.on("ready", ()=>{
        new Circle().center().drag();
        frame.stage.update();
    });
</script>
</html>

Let's practice using templates.

Practice

This practice will be different than our earlier practices in that your are testing things in your own HTML page. Go to the ZIM Code page and from the second grey box section, COPY the ZIM template. Make an HTML page (text page with .html extension) in an editor like ATOM. REMOVE the Circle code from the template then follow the instructions below.

1 Templates Show

Reference

Building ► ZIM Badges - APP
We have the parts of coding and the template to build in - now, how do we build? First of all... it helps to know what we are building ;-) See the Dan Zen Creativity Tour for a guide.

Steps to Build

  1. Come up with an idea - see Creativity Framework
  2. Sketch the idea or draw wireframes
  3. User test the wireframes - do they make sense
  4. Choose a template and start coding

What First?
Build the main part of your app first. You want to know that this will work before you put effort in to the rest of the app. Do not build your intro screen first and have to wait for animation and click through every time you want to get to the main part of your app. That will slow you down. Things like your intro, help and about screens, conclusions - add these last.

Efficiencies
You want to make things easy to test. So leave distracting sounds and animations until the end. At least turn off your animations (see ZIM ANIMATE constant). Often, you can build with Rectangle and Circle shapes as placeholders and substitute final graphics when you know your app will work.

Hard Code
Do one step at a time. Get things on the stage with hard-coded values. If you see that you are repeating code, then you can apply the Abstraction lesson. But generally, get something to work, then make it efficient. Then get something else on the stage, then make it efficient, etc. Try not to wait until the end to make things efficient, but do not try to start efficient.

Build Order
We build in steps and often these go in cycles:

Common Build Order

  1. Add an asset
    • Shape, Image, Component, Sprite, etc.
  2. Apply an event
    • click, mousedown, pressmove, pressup, etc.
  3. Call a function
    • animate, remove, add, move, score, etc.
  4. Repeat

Examples ► ZIM Examples
Most of the ZIM Examples are commented for learning and show a variety of complexities. Note that they have been made through time so see the ZIM Tips for current code techniques.

A great place to practice is the ZIM Badges tutorial called APP that takes you through the many steps of making an app. We do not need the ZIM namespace as we use in the tutorial.

GitHub is an application for keeping track of changes. It can be used to show the actual build steps taken. Here is an advanced application called PsychicPixels in GitHub. Note the first bunch of steps at the bottom of the list. You can read a description of the changes and see the code for each step.

The code for a finished app always looks like a lot and complex. Yet the code is created a step at a time. It does take some practice to keep track of where you are going and what you have done. It almost seems like one problem after another! Yet, that is building. Make sure that you revel when things go right!

Patterns ► What IZ a Pattern? ► Module Pattern? ► MVC?
Patterns can be found when things repeat. We can be efficient if we notice a pattern and store it in a variable, function, loop, class, etc.

There are also build patterns - where the types of apps or parts of apps have similarities across projects. These tend to be advanced so have a look at them when you are ready. There is the Module pattern and the MVC or Model View Controller pattern - and there are certainly more.

Techniques ► ZIM Bits
There are many build techniques that we use over and over in Interactive Media. In other words - these are patterns for the parts of what we build. These are demonstrated in the ZIM Bits site. As we build, we insert code based on these techniques.

Build Techniques

Hit Tests ► TIPS HitTests ► Early HitTest examples ► hitTestPath
A very important technique in Interactive Media is the hitTest. We often want to find out if two DisplayObjects are hitting each other and we must constantly test - not just once. So we test in a Ticker function or in a pressdrag event, etc. See the different types of hitTests down below.

12
// simple hitTestBounds
var rectangle = new Rectangle().center();
var dragRect = new Rectangle().loc(100,100).drag();

// can't just check once if hitting... it would only check at the start
// so put hitTest in pressmove event
dragRect.on("pressmove", function() {
    if (dragRect.hitTestBounds(rectangle)) {
        zog("hitting");
        if (rectangle.color != red) {
            rectangle.color = red;
            stage.update();
        }
    } else {
        if (rectangle.color == red) {
            rectangle.color = black;
            stage.update();
        }
    }
});
// Note - this is a simple example testing two objects
// Often we have to test if an object is hitting many other objects
// To do this we put the many objects in a container
// and loop through the container testing each one!
// See the practice examples

DisplayObjects have a Bounding Box that is a rectangle around the object. It is very quick to find out if two rectangles are hitting - it is a simple equation for the computer. But it is harder to find out if the actual shape (the object's colored part) is hitting. It is TOO SLOW to test if two complex shapes are hitting so we test to see if a Point or points are hitting a shape.

In the diagram below, the hitTestBounds (fast) would be hitting where the hitTestCircleRect (fast) would not which is a better answer. A hitTestCircle (slower) could be used but it would test if the shape of the rect is hitting points around the circle so this is slower and not completely accurate. The hitTestCircle is the best to use if detecting a round pod hitting the complex shape of the asteroid. This would hit if any part of the shape hits a pink dot around the asteroid.

ZIM HitTests with rectangle near circle hitting with bounds but not hitting with hit test circle rect.  Hit test path for testing against blobs and squiggles and then hit test circle to see if a shape is hitting a circular object - just some of the ZIM hit tests

Types of HitTests

Practice

Here are examples of some build techniques. More can be found in at ZIM Bits. We are back to practicing with the TEST button on this page but you are welcome to start building apps in your own template files.

2 Build Techniques Show

Summary

Learning to build takes time. After a while, you start to know how to solve certain problems. Keep coming back to this lesson as you progress and you will find you understand the tips here more as you go.

Programming is the world's best puzzle. Enjoy your time programming and feeling the satisfaction of building! Rest assured, ZIM helps you do things easily. Do not go off to some other framework because you find this hard. It will be just as hard and most likely harder in other frameworks. Help is always available at ZIM SLACK.

LESSON 06 - Conditionals and Debugging LESSON 08 - Controls

VIDEOS ALL LESSONS