Overview

In this tutorial, we will be going through the few simple steps needed to get an app running on your device. This section will take 5-10 minutes to complete, and you will learn:

  • How to create a new Supersonic application
  • That Supersonic apps mix native and HTML UI components in an awesome way
  • How to make changes to your Supersonic application
  • How to navigate to different views in your app

Installation

Before we move forward, you need to install the Steroids² tooling. Head on over to our Install Wizard page and follow the instructions there.

Creating a New Project

You can also use the Steroids² CLI with an existing Cordova project. Read the Usage with Cordova guide for more information.

With your brand-new Steroids² CLI up and running, head on over to your terminal app of choice and create your first app. To do so, just type:

steroids create myProject

You will then be prompted to make some selections regarding your project type. To follow this tutorial, choose Multi-Page application (MPA) and based on your preference JavaScript or CoffeeScript for your project configuration. Using these defaults, your project will utilise Angular.js to create the MPA structure and create your project's script files using JavaScript or CoffeeScript.

Note: Even though we recommend using Angular, Supersonic is framework agnostic. If you prefer a different framework, choose Single-Page application when prompted for application type, and create the app structure yourself.

The Steroids² CLI will create a basic project in the myProject/ folder and install some required dependencies like the steroids.js and supersonic.js libraries. Feel free to poke around for a little while, but the app structure will be better explained in a later chapter.

Connecting Your Device

Running your app is super-easy via the AppGyver Scanner. If you haven't done so yet, download the AppGyver Scanner for your Android or iOS device:

Next, head back to the terminal to run your app. In your project folder (myProject/ in this case), enter the following command:

steroids connect

This starts the Steroids Development Server. Among other things, it ensures that changes you make to your project are displayed in the actual devices.

Connecting with an Actual Device

After compiling your project, the Steroids CLI will open up the Connect Screen in a new browser window. The Connect Screen has plenty of features, but for now, focus on the QR code that is shown on the first page:

Connect Screen QR code.

To run your app on a real device, all you have to do is open the AppGyver Scanner you installed previously and scan the displayed QR code. The Scanner app will then download the required files, establish a connection with the Steroids Development Server and start your app.

If you can't connect the Scanner app with your Steroids Development Server, please read through the troubleshooting guide.

Introduction to Native UI Components

A fresh Supersonic project running on a device.

The app starts in the view pictured above. Most of the content on the screen is just plain HTML and CSS. However, the top and bottom of the screen contain native components: a native navigation bar and a native tab bar.

Try rotating your device to see how the components smoothly realign themselves. You can rest assured the components stay in their correct places no matter what!

The native components realign themselves when the device is rotated.

The native components also mean that we don't have to use any JavaScript hacks for scrolling. Try scrolling the view: it's smooth as butter, and if you scroll past the edge of the page, you get the native effects: rubber-band on iOS and the blue highlight on Android.

Next, try switching between the tabs. As you can see, the view changes instantaneously. This is possible because each tab is its own HTML document (wrapped inside its own WebView "browser" instance – more on this later), and switching between them is handled by native UI code.

The tabs live on even when they're not active. Go to the Settings tab, change the position of some of the sliders, and scroll down a bit. Switch to the Index tab and back again. The state is maintained perfectly, because nothing is done to the Settings tab itself – it is just hidden from view by the native UI code.

Making Changes

With your app up and running, we're ready to make some changes. Open the myProject/app/example/views/getting-started.html file in your editor of choice. Find the <super-navbar> element and change the title text:

<super-navbar>
  <super-navbar-title>
    Hello World!
  </super-navbar-title>
</super-navbar>

Save the file. The Steroids Development Server automatically notices that a file has changed and refreshes your project. The app will reload itself, after which you'll see the navigation bar update with your new title.

Done!

In this section we've covered the basics of Supersonic App Development. By now you know:

  • How to create a new Supersonic application
  • That Supersonic apps mix native and HTML UI components in an awesome way
  • How to make changes to your Supersonic application
  • How to navigate to different views in your app

With these skills, you have grasped the core of developing Supersonic apps! Once you're ready, dive into the Second mile tutorial to learn more essential skills, like debugging your app, as well as a deeper insight into how a Supersonic app really works.