Create Your First NativeScript App_part 1

In the last article, I introduced you to NativeScript. There you learned the basics of NativeScript and how it differs from other mobile development frameworks. This time you'll be getting your hands dirty by creating your first NativeScript app. I'll walk you through the whole process of building an app with NativeScript, from setting up your development environment to running the app on your device. Here's an outline of what I'll discuss:

1. Setting up NativeScript
2. Building the app
3. Running the app
4. Debugging the app

We'll be specifically running the app on the Android platform. But you can still follow along if you want to deploy to iOS as the code will be pretty much the same. The only differences are in the process for setting up NativeScript and the commands that you execute when running the app.

The completed source code for this app is available from the tutorial GitHub repo.

1. Setting Up NativeScript

To set up NativeScript, you first have to install Node.js. Once Node.js is installed, you can install the NativeScript command-line tool by executing npm install -g nativescript on your terminal.

The final step is to install the development tool for each platform that you want to deploy to. For Android, this is the Android SDK. For iOS, it's XCode. You can follow the installation guide on the NativeScript website for more detailed instructions on how to set up the necessary software for your development environment.

Once you've set up your environment, execute tns doctor to make sure that your environment is ready for NativeScript development. If you're on Linux or Windows, you'll see something like this if your environment is ready:

1. NOTE: You can develop for iOS only on Mac OS X systems.
2. To be able to work with iOS devices and projects, you need Mac OS X Mavericks or later.
3. Your components are up-to-date.
4. No issues were detected.

There's a note in there that you can only develop for iOS only on Mac OS X systems. This means that if you're on a PC, you'll only be able to deploy to Android devices. However, if you're on Mac, you'll be able to deploy on both iOS and Android platforms.

If you run into any problems during the setup, you can get an invitation to join the NativeScript Slack Community and once you have joined, go to the getting started channel and ask your questions in there.

2. Creating the App

The app that we're going to build is a note-taking app. It will allow the user to create notes, each with an optional image attachment that will be captured with the device camera. The notes are persisted using NativeScript application settings, and can be individually deleted.

Here's what the app is going to look like:

Start by executing the following command to create a new NativeScript project:

1. tns create noter --appid "com.yourname.noter"

noter is the name of the project, and com.yourname.noter is the unique app ID. This will be used later on to identify your app once you submit it to the Play or App Store. By default, the tns create command will create the following folders and files for you:

• app
• node_modules
• platforms
• package.json

You'll typically only have to touch the files inside the app directory. But there are also instances where you might need to edit files inside the platforms/android directory. One such case is when a plugin that you're trying to use doesn't automatically link the dependencies and assets that it needs.

Next, navigate to the app directory and delete all files except the App_Resources folder. Then create the following files:

• app.js
• app.css
• notes-page.js
• notes-page.xml

These are the files that will be used by the NativeScript runtime. Just like when building web pages, .css files are used for styling, and .js files for functionality. But for the markup of the app, we use XML instead of HTML. Usually you would create a separate folder for each screen of the app (e.g. login, sign up, or dashboard) and have XML, CSS, and JavaScript files inside each folder. But since this app has only one screen, we created all the files inside the root directory.

If you need more information about the NativeScript directory structure, check out Chapter 2 of the NativeScript Getting Started Guide.

3. The Entry Point File

Open the app.js file and add the following code:

1. var application = require("application");
2. application.start({ moduleName: "notes-page" });

This is the entry point for a NativeScript application. It uses the application module and its start method to specify the module used for the initial page of the app. In this case, we've specified notes-page, which means that the module is notes-page.js, the markup is notes-page.xml, and the styling for the page is notes-page.css. This is a convention used in NativeScript, that all files for a specific page have to have the same name.

4. Adding the UI Markup

Open the notes-page.xml file and add the following code:

1. <Page xmlns="http://schemas.nativescript.org/tns.xsd" loaded="pageLoaded">
2.     <Page.actionBar>
3.         <ActionBar title="{{ app_title }}">
4.             <ActionBar.actionItems>
5.                 <ActionItem tap="newNote" ios.position="right" android.position="actionBar">
6.                     <ActionItem.actionView>
7.                         <StackLayout orientation="horizontal">
8.                             <Label text="New Item" color="#fff" cssClass="header-item" />
9.                         </StackLayout>
10.                     </ActionItem.actionView>
11.                 </ActionItem>
12.             </ActionBar.actionItems>
13.         </ActionBar>
14.     </Page.actionBar>
15.  
16.     <StackLayout>
17.         <StackLayout id="form" cssClass="form-container">
18.             <TextView text="{{ item_title }}" hint="Title" />
19.             <Button text="Attach Image" cssClass="link label" tap="openCamera" />
20.             <Image src="{{ attachment_img }}" id="attachment_img" cssClass="image" visibility="{{ attachment_img ? 'visible' : 'collapsed' }}" />
21.             <Button text="Save Note" tap="saveNote" cssClass="primary-button" />
22.         </StackLayout>
23.            
24.         <ListView items="{{ notes }}" id="list" visibility="{{ showForm ? 'collapsed' : 'visible' }}">
25.             <ListView.itemTemplate>
26.                 <GridLayout columns="*,*" rows="auto,auto" cssClass="item">
27.                     <Label text="{{ title }}" textWrap="true" row="0" col="0" />
28.                     <Image src="{{ photo }}" horizontalAlignment="center" verticalAlignment="center" cssClass="image" row="1" col="0" visibility="{{ photo ? 'visible' : 'collapsed' }}" />
29.                     <Button text="delete" index="{{ index }}" cssClass="delete-button" tap="deleteNote" row="0" col="1" horizontalAlignment="right" loaded="btnLoaded" />
30.                 </GridLayout>
31.             </ListView.itemTemplate>
32.         </ListView>
33.     </StackLayout>
34. </Page>

When creating app pages in NativeScript, you should always start with the <Page> tag. This is how NativeScript knows you're trying to create a new page. The xmlns attribute specifies the URL to the schema used for the XML file.

If you visit the schema URL specified, you can see the definition of all the XML tags that you can use within NativeScript. The loaded attribute specifies the function to be executed once the page is loaded. We'll take a look at this function definition later on in the notes-page.js file.

1. <Page xmlns="http://schemas.nativescript.org/tns.xsd" loaded="pageLoaded">
2.  ...
3. </Page>

By default, the app header only contains the title of the app. If you wanted to add other UI components, you'd need to redefine it by using <Page.actionBar>. Then inside you define the things that you want to see in the header. The title is specified by using <ActionBar> and setting its title  attribute to the page title that you want.

Below we've used the mustache syntax to output the value of app_title defined in the notes-page.js file. This is how you output values that are bound to the page.

1. <Page.actionBar>
2.     <ActionBar title="{{ app_title }}">
3.         ...
4.     </ActionBar>
5. </Page.actionBar>

To define buttons, first use <ActionBar.actionItems> as the parent, and each <ActionItem> will be the buttons that you want to define. The tap attribute specifies a function to be executed when the button is tapped, while os.position and android.position are the positions of the button in iOS and Android.

To specify the button text, you could use the <ActionItem>'s text attribute. However, NativeScript doesn't currently allow changing the text color of the button through CSS. That's why instead we've used <ActionItem.actionView> to define the content of the button and to set its text color.

1. <ActionBar.actionItems>
2.   <ActionItem tap="newNote" ios.position="right" android.position="actionBar">
3.     <ActionItem.actionView>
4.         <StackLayout orientation="horizontal">
5.           <Label text="New Item" color="#fff" cssClass="header-item" />
6.         </StackLayout>
7.     </ActionItem.actionView>
8.   </ActionItem>
9. </ActionBar.actionItems>

Next is the actual page content. You can arrange the different elements by using one or more of the layout containers. Below we've used two of the available layouts: StackLayout and GridLayout.

StackLayout allows you to stack all the elements inside of it. By default, the orientation of this layout is vertical, so that each UI component is stacked below the last. Think of lego bricks with a downward flow.

On the other hand, GridLayout allows you to arrange elements in a table structure. If you've ever used Bootstrap or other CSS grid frameworks then this should seem natural to you. The GridLayout lets you define rows and columns among which each UI component can be placed. We'll take a look at how this is implemented later on. For now, let's move on to the code.

First, let's define the form for creating a new note. Just like in HTML, you can define attributes such as id and cssClass (equivalent to HTML's class attribute). The id attribute is attached to an element if you want to manipulate it from code. In our case, we want to animate the form later on. cssClass is used to specify the cssClass that you will use to style the element.

Inside the form is a text field for entering the note title, a button for attaching an image, the selected image, and a button for saving the note. The image element is only visible if the attachment_img has a truthy value. That will be the case if an image was previously attached.

1. <StackLayout id="form" cssClass="form-container">
2.   <TextView text="{{ item_title }}" hint="Title" />
3.   <Button text="Attach Image" cssClass="link label" tap="openCamera" />
4.   <Image src="{{ attachment_img }}" id="attachment_img" cssClass="image" visibility="{{ attachment_img ? 'visible' : 'collapsed' }}" />
5.   <Button text="Save Note" tap="saveNote" cssClass="primary-button" />
6. </StackLayout>

Next is the list that shows the notes that were already added by the user. Lists are created by using the ListView component. This accepts items as a required attribute. The value can either be a plain array or an observable array.

If you do not need to perform any form of update (e.g. deleting or updating a field) to each item in the array, a plain JavaScript array will do. Otherwise, use an observable array which allows you to perform updates to the array and have it automatically reflected to the UI. We'll take a look at how an observable array is defined later on.

Also note that a ListView can have an itemTap attribute, which allows you to specify the function to be executed when an item in the ListView is tapped. But in this case we haven't really added it since we don't need to perform any action when an item is tapped.

1. <ListView items="{{ notes }}" id="list" visibility="{{ showForm ? 'collapsed' : 'visible' }}">
2.     ...
3. </ListView>

The items in the ListView can be defined using <ListView.itemTemplate>. Here we're using a <GridLayout>  to create two rows and two columns. The columns attribute is used to specify how many columns you want in each row.

In this case, *,* means that there are two columns, each taking up an equal amount of the available space in the current row. So if the whole row has a total width of 300 pixels, each column will be 150 pixels wide. So basically each * represents one column, and you use a comma to separate each of them.

The rows attribute works similarly, but controls the amount of space used by a single row. auto means it will only consume the amount of space needed by the children of each row.

After defining the columns and rows in the GridLayout, you still have to specify which of its children belongs to which row and column. The first row contains the title of the item (1st column) and the delete button (2nd column). The second row contains the image that was attached to the item (1st column). The row and columns are specified by using the row and col attribute for each element.

Also notice the use of horizontalAlignment and verticalAlignment. You can think of this as the NativeScript equivalent of HTML's text-align attribute. But instead of text, we're aligning UI components. horizontalAlignment can have a value of right, left, center, or stretch, while verticalAlignment can have a value of top, bottom, center, or stretch. Most of these are self-explanatory, except for stretch, which stretches to take up the available horizontal or vertical space.

In this case, horizontalAlignment and verticalAlignment are used to center the image both horizontally and vertically inside its column. And horizontalAlignment is used on the delete button to align it to the right-most part of the second column.

1. <ListView.itemTemplate>
2.   <GridLayout columns="*,*" rows="auto,auto" cssClass="item">
3.     <Label text="{{ title }}" textWrap="true" row="0" col="0" />
4.     <Image src="{{ photo }}" horizontalAlignment="center" verticalAlignment="center" cssClass="image" row="1" col="0" visibility="{{ photo ? 'visible' : 'collapsed' }}" />
5.     <Button text="delete" index="{{ index }}" cssClass="delete-button" tap="deleteNote" row="0" col="1" horizontalAlignment="right" loaded="btnLoaded" />
6.   </GridLayout>
7. </ListView.itemTemplate>

We haven't specified an itemTap attribute for the ListView. Instead, we want to attach a delete action that will be executed whenever a delete button inside a list item is tapped. Each item has an index attribute, which we're passing as a custom attribute for the delete button. This is the unique key used for identifying each item so that we can easily refer to them when needed.

Also notice the loaded attribute. Just as <Page> has a loaded attribute, buttons can also have one. You'll see later on how this is used.
Written by Wernher-Bel Ancheta (continue)

If you found this post interesting, follow and support us.
Suggest for you:

Build Apps with React Native

The Complete Android Developer Course - Build 14 Apps

Ionic by Example: Create Mobile Apps in HTML5

The Complete Android & Java Course - Build 21 Android Apps

Android Application Programming - Build 20+ Android Apps