Ionic JS Components

Rahat Khanna

November 2015

In this article by Chris Simmonds, author of the book, Getting Started with Ionic, we will cover the various Ionic JS components.

(For more resources related to this topic, see here.)

CSS is used for styling mobile components but Javascript is used to write logic and create the user experience in a hybrid app. Ionic has reusable Angular directives which help developers create mobile specific experience smoothly. Apart from directives, Ionic also has controllers and services in its library to help create mobile specific components. We will be discussing the most important components in this section of the article.

Actionsheet - $ionicActionSheet

The actionsheet component is a sliding panel which comes from bottom and can contain multiple buttons intended to perform some actions in the mobile app. This component has been inspired from the actionsheet component in iOS. $ionicActionSheet is a service in Ionic library which can be injected in any controller and initiated using the show method.

The show method takes an input as a set of options to control the actionsheet component. A new isolated scope is created when the show method is called. Following table shows the various options in the actionsheet component:

Name

Type

Description

buttons

[Object]

If extra buttons need to be shown, it is passed as an array of objects. Each object can contain text property.

titleText

String

Text for the title of actionsheet.

cancelText

String

Text shown for cancel button.

destructiveText

String

Text shown for destructive button.

buttonClicked

Function

Callback called when any extra button is clicked.

cancel

Function

Callback called on click of cancel button.

destructiveButtonClicked

Function

Callback function for destructive button.

cancelOnStateChange

Boolean

Value to define whether to cancel actionsheet on state change.

cssClass

String

Custom CSS class applied on actionsheet.

The code for an example is as follows:

// Action Sheet Initialization using Properties
var sheetId = $ionicActionSheet.show({
titleText: 'Manage Books',
buttons: [ { text: '<b>Add New Book </b>' } ],
cancelText: 'Cancel',
destructiveText: 'Delete Book',
cancel: function() {
   // code when cancel button is clicked
},
buttonClicked: function(index) {
// code which is to be executed on button click
}
});

Backdrop - $ionicBackdrop

Backdrop is a transparent blackish UI screen which appears behind popups, loading, and other overlays. Multiple UI components require backdrop, but only one backdrop appears in DOM. In order to use a backdrop, any component can call the retain method and whenever its usage is over the component can call the release method.

The code for demonstrating its usage is as follows:

$stateProvider.state('homeView',{
//Show a backdrop for one second
$scope.action = function() {
   $ionicBackdrop.retain();
   $timeout(function() {
     $ionicBackdrop.release();
   }, 1000);
};
});

Form inputs

Apart from the normal input elements to take text format inputs, there are special form input directives for checkboxes, radio, and toggle. We have already discussed the CSS styles used for the same, but you can use directives themselves to achieve the functionality along with the style.

ion-checkbox directive

This directive adds the required styles to a checkbox. It renders like a normal angular checkbox. Following is an example of this directive:

<ion-checkbox ng-model="isChecked">Checkbox Label</ion-checkbox>

ion-radio directive

The ion-radio directive is also used style the radio input according to the mobile UI. In order to create a set of radio buttons, please give the same ng-model property to all and use ng-value to assign value for a specific radio element:

<ion-radio ng-model="option" ng-value="'1'">Option 1</ion-radio>
<ion-radio ng-model="option" ng-value="'2'">Option 2</ion-radio>

ion-toggle directive

This directive creates a toggle switch which can manipulate a boolean model.

<ion-toggle ng-model="isOpen" toggle-class='toggle-calm'>Open
Drawer</ion-checkbox>

Gestures and events

In a mobile app, gestures and events are very important in shaping the user experience. The event handling should be perfect and there should be multitude of events available to developer for adding appropriate actions for different events. In Ionic framework, there are different event directives which can be used to bind callbacks for those events. Also, there is an $ionicGesture service which can be used to programmatically bind the events with callbacks.

$ionicGesture service

The methods available under the $ionicGesture service are given in the following sections.

on method

It adds an event listener for a gesture on an element. The signature for the method is as follows:

on(eventType,callback,$element,options)

Following table shows the various parameters used in on method:

Param

Type

Details

eventType

string

It is the gesture event to be registered

callback

function(e)

It is the event listener method to be called when event is triggered

$element

element

It is the element on which the event is bound

options

object

It is used to set extra options

The method returns ionic.Gesture object which is used to detach the event later.

off Method

It removes an event listener for a gesture on an element. The signature for the method is as follows:

off(gesture,eventType,callback)

Following table shows the various parameters used in off method:

Param

Type

Details

gesture

ionic.Gesture

It is the gesture which is to be removed.

eventType

string

It is the gesture name which is to be removed.

callback

function(e)

Callback which needs to be deregistered.

Gesture events

List of gesture events available in Ionic Framework is given in the following table:

Event name

Description

on-hold

It occurs when the touch stays for longer than 500 ms. These are long touch events.

on-tap

It occurs when a quick touch is done on an element.

on-double-tap

It occurs on double tap on a location.

on-touch

It is called immediately when user starts to touch.

on-release

It is called when user ends a touch.

on-drag

It is called when one touch is moved around the page. If dragging is allowed, scrolling should be disabled.

on-drag-up

It is called when element is dragged up.

on-drag-right

It is called when element is dragged right.

on-drag-left

It is called when element is dragged left.

on-drag-down

It is called when element is dragged down.

on-swipe

It is called when touch moves at high speed in any direction.

on-swipe-up

It is called when touch moves at high speed moving up.

on-swipe-right

It is called when touch moves at high speed moving right.

on-swipe-left

It is called when touch moves at high speed moving left.

on-swipe-down

It is called when touch moves at high speed moving down.

Lists

List is the most popular component used in any mobile app. Generally, all the data displayed in a mobile view is generally in the form of a list. A list can have multiple list items representing rows. A list item can contain any content ranging from text to icons and custom elements.

<ion-list>

This directive represents the list in Ionic framework. This directive supports complex interactions like drag to reorder, swipe to edit, and removing items. The <ion-list> directive can consist of one or more <ion-item> directives representing each row. There are other directives augmenting its functionality like <ion-option-button> used for swipe to edit buttons, <ion-reorder-button> shown while reorder is enabled, and <ion-delete-button> shown while deleting a row item.

The attributes available for this directive are given in the following table:

Attribute (all optional)

Type

Details

delegate-handle

string

It is the handle used for passing the reference of the list with the object $ionicListDelegate

type

string

It indicates the type of the list used (options are list-inset or card)

show-delete

boolean

It is used to show delete buttons or hide them.

show-reorder

boolean

It is used to show reordering buttons or hide them.

can-swipe

boolean

It is used to allow swiping of list to show option buttons.

Following code explains the usage of these attributes:

// Example with complex Scenario
<ion-list ng-controller="AppCtrl"
show-delete="shouldShowDelete"
show-reorder="shouldShowReorder"
can-swipe="listCanSwipe">
<ion-item ng-repeat="row in rows" class="item-thumbnail-left">
   <h2>{{item.title}}</h2>
   <p>{{item.description}}</p>
   <ion-option-button class="button-positive"
   ng-click="share(item)">
     Share
   </ion-option-button>
   <ion-option-button class="button-info" ng-click="edit(item)">
   Edit
   </ion-option-button>
   <ion-delete-button class="ion-minus-circled"
   ng-click="items.splice($index, 1)">
   </ion-delete-button>
   <ion-reorder-button class="ion-navicon"
   on-reorder="reorderItem(item, $fromIndex, $toIndex)">
   </ion-reorder-button>
</ion-item>
</ion-list>

Loading - $ionicLoading

$ionicLoading is an angular service that controls display of an overlay representing a loader. The loading indicator can be configured by passing certain options to the show method of this service.

Following code explains the usage of this service:

// Sample Module
angular.module('MyApp', ['ionic'])
controller('MyCtrl', function($scope, $ionicLoading) {
$scope.show = function() {
   $ionicLoading.show({
     template: 'Loading'
   });
};
$scope.hide = function(){
   $ionicLoading.hide();
};
});

The important options available to be passed to the show method are given in the following table:

Field

Type

Details

template

string

It indicates the HTML content of the indicator

templateUrl

string

It indicates the template URL for the HTML content of indicator

scope

object

It indicates the scope to be a child of

noBackdrop

boolean

It indicates whether to hide the translucent backdrop

hideOnStateChange

boolean

It indicates whether to hide the loader during state change

delay

number

It indicates the delay (in ms) to show the indicator

duration

number

It indiactes the time (in ms) after which indicator will be hidden

Modal - $ionicModal

This is a service which controls displaying a popup over the existing UI temporarily. It uses the <ion-modal-view> directive in its template to represent the modal DOM element. It is used for generally editing an item or showing dialog box or choice box. There are two methods available on $ionicModal service fromTemplate and fromTemplateUrl, which take as input template string or template URL respectively as first parameter. The second argument to both methods is options object which is passed to the initialize method of ionicModal controller instance.

IonicModal controller

This is a controller instantiated by the $ionicModal service. The ionicModal method remove should be called after the use for the modal is over in order to avoid memory leaks.

The different method available to this controller is:initialize(options).

It creates a new modal controller instance. It takes as an argument an options object which should contain the following properties:

  • scope (object): It indicates the scope to be a child of.
  • animation (string): It indicates the animation to show and hide with. Default is slide-in-up.
  • focusFirstInput (boolean): It indicates the control whether to focus first input in modal or not.
  • backdropClickToClose (boolean): It indicates whether to close modal on clicking backdrop.
  • hardwareBackButtonClose (boolean): It indicates control to decide whether modal should be closed using hardware back button or not.
  • show(): This method is used to show the modal instance.
  • hide(): This method is used to hide the modal instance.
  • remove(): This method is used to remove the modal instance from memory.
  • isShown(): This method returns a boolean representing whether the modal is shown or not.

Popover - $ionicPopover

Popover component is also modeled similarly to modal and has two objects $ionicPopover service and ionicPopover controller. Popover is a view that floats above the app's content. The popover can be used to display extra information or take input for a choice. The content of a popover needs to be put inside an <ion-popover-view> element.

The $ionicPopover service exposes similar methods like $ionicModal service – fromTemplate and fromTemplateUrl. The ionicPopover controller also has similar events to ionicModal controller. The initialize method for this controller has options object as input but it does not contain the property animation.

Spinner - ion-spinner

In mobile UI or views, only a particular section of view needs to be refreshed or loaded and a spinner/loader needs to be displayed in that section. <ion-spinner> is a directive which displays loader icons. There are multiple available icons like spiral, ripple, dots, lines, and so on. The theme colors for ionic can also be used along with using the class names like spinner-<theme>.

Following is the usage of this directive:

<ion-spinner icon="spiral spinner-calm"></ion-spinner>

Summary

In this article we discussed the JS components detail. We can also mix and match these components to build more complex directives. We also saw the components such as list, modal, popover, and spinner.

Resources for Article:


Further resources on this subject:


You've been reading an excerpt of:

Getting Started with Ionic

Explore Title