Watch the Livestream
Workshop Documentation
Cordova is an open source version of the popular PhoneGap framework that lets you create apps for Android, Windows Mobile, and iOS with HTML5, JavaScript, and CSS3. It creates a wrapper around them that lets them access more of your phone or tablet’s features than a regular web app can.
We’re going to use only online tools to make it possible for everyone to participate without needing to install any software. Big thanks to Daniel Favand for outlining the process.
Let’s start with the three accounts you need:
- GitHub: DO THIS FIRST. This is where we’ll store the code so the app building service can access it.
- Cloud9: This is the online code editor we’ll use for writing and previewing the apps. USE YOUR GITHUB ACCOUNT TO SIGN IN / CREATE YOUR ACCOUNT.
- PhoneGap Build: this is the service that builds the Android APK from your code. You can sign into this with an Adobe ID if you have one. If not, you’ll be prompted to sign up for one.
So once you’ve signed up for GitHub and you’ve created your Cloud9 account, you’ll see this screen:
Click the Create New Workspace button to create a new workspace where we’ll put our project. Give your app a fancy name like “CoderDojo-First-App” and scroll down the list of build types to find the Custom option. Your creation screen should look like below.
The workspace will be created and show up in your sidebar. The spinning gear saying it’s creating may stay for a while, but once the project has been in your sidebar a bit, it’s safe to refresh the screen. When you click the project in the sidebar, you’ll see a Start Editing button.
This will take you into your Cloud9 editor. You can close the Welcome tab or use it to customize the workspace a bit. I suggest going with the defaults for the moment.
In the bottom half of the screen, there’s a terminal window which is basically like a SSH (Secure Shell) connection right into the virtual server that your workspace is part of. We’re going to install Cordova and the Ionic Framework which provide the basics we need for creating a mobile app with HTML5, CSS, and JavaScript plus a few other extra niceties. We do it by typing this into the terminal:
npm install -g cordova ionic
Once they’re installed, we can issue a simple command to have the Ionic Framework do most of the heavy lifting in building a simple app ready for us to modify.
ionic start dojoFirst
At this point, you literally have a demo app you could build. But we’re going to turn it into our own with two steps.
Step 1: Add a sound
In the project, Ionic will have created a dojoFirst directory. Expand that and you’ll see a number of subdirectories, invluding a www subdirectory. That’s where our app will live. Expand it and you’ll see folders named css, js, etc.
Right-click on the www directory and you’ll get a context menu. Select Open terminal here.
Now we need a sound to pull into our project. Open another browser window or browser tab (control + N, or control + T) and go to our sounds directory. Here I have 5 public domain sounds I picked up from FreeSound.org that I converted to small MP3 files. Try them out. When you find the one you like best, copy the direct link to it.
Now, go back to your project editor in Cloud9, and in the terminal you opened in the WWW directory and download the sound into your project using wget on the command line.
wget [URL of Sound - see below for example]
WARNING: This is not “best practices.” Normally we’d create a directory for resources like sounds and put the sound in there, but we’re “cheating” today to get through everything in the time allotted. We’ll get into some finer points of file management in the next workshop.
Step 2: Change the Index
Find the index.html file in the www directory. Double click it to open it in the editor. There’s a whole bunch of HTML in it that makes up the demo app. We’re not going to concern ourselves with that. We’re going to change the contents of the body tag. Again, this isn’t best practices because we’re putting CSS and JavaScript in the body, but that’s so we can save file management for another session. Also, if you want a line-by line explanation of how the code works, watch the video in our YouTube channel.
We’ll change <body ng-app="starter">[old app content]</body> to this:
<body>
<style>
.btnholder {
text-align: center;
margin-top:20px;
margin-bottom:20px;
}
.btn {
background: #3498db;
background-image: -webkit-linear-gradient(top, #3498db, #2980b9);
background-image: -moz-linear-gradient(top, #3498db, #2980b9);
background-image: -ms-linear-gradient(top, #3498db, #2980b9);
background-image: -o-linear-gradient(top, #3498db, #2980b9);
background-image: linear-gradient(to bottom, #3498db, #2980b9);
-webkit-border-radius: 28;
-moz-border-radius: 28;
border-radius: 28px;
font-family: Arial;
color: #ffffff;
font-size: 20px;
padding: 15px 20px 15px 20px;
text-decoration: none;
}
</style>
<audio id="sound1">
<source src="fartnoise.mp3">
</audio>
<p class="btnholder">My First Sound App</p>
<p class="btnholder">
<span class="btn" id="button1">Play Sound</span>
</p>
<script>
var sound = document.getElementById("sound1");
var button = document.getElementById("button1");
button.addEventListener( 'click' , function(){
sound.play();
} )
</script>
</body>
Obviously you’ll want to change the name of the noise sound file to the one you chose. If you chose fartnoise.mp3 you’re set.
As I said, we’ll walk through this code in the video in our YouTube channel. But for now you can cut and paste that code into your project.
Once it’s done, you’ll want to preview it. Close the terminal you opened at the www directory and open one at the higher-level dojoFirst directory. Issue the following command in the terminal.
ionic preview -p $PORT
It will give you options to run the preview with an IP (such as 168.101.100.1) address or “localhost”. Pick the IP address. Cloud9 will spot that you’ve launched a server and provide you a link to open it. Click the link and app will open within Cloud9 with a web preview. Click the button, hear the sound.
If it looks like that and works, we’re ready for the last two steps…
Step 3: Put it on GitHub
At the very beginning, you started a GitHub account (or made sure you had one). Now it’s time to start a repository on GitHub that you can upload your app to. Why? Because that’s where our build tool will pick it up.
In the upper right of the GitHub interface, click the plus (+) icon and choose to create a new repository. You should create it with no Readme.md or git.ignore files. Something like this…
When you create the repo, it will be empty and GitHub will suggest some instructions of what to do. They’re close to what we’ll want, but not quite.
Open another terminal at the dojoFirst directory, and enter in the following sequence of commands.
git init
git add .
git commit -m 'my first commit'
git remote add origin [url to your repo with ".git" tacked on]
git push -u origin master
It will ask you for your git username and password, then upload everything.
Now that it’s on GitHub, we can build it into a working app.
Step 4: Build it with Adobe
At this point, let’s head over to PhoneGap Build. Once you’re logged in, assuming you have no apps, you’ll be presented with an option to create a new one. Click it.
It will ask you for a link to a repo to build from. Remember the link with.git tagged on at the end that you used to set the origin for your repo? Use it again and select “Pull from Git repository.” It will pull it down, inspect it, and give you an option to build it. Build the app.
Adobe will give you a number of options to download and install an unsigned APK on your Android device. You will get warnings. This should be safe as you programmed it.
Thoughts for between-weeks
Add more sounds than just the 1 to your sound board.