Title bar control

All Channel Web applications have a title bar. The title bar is automatically placed at the top of the screen where Channel Web Applications run.

 

What’s the title bar?

All Channel Web Applications have a title bar. The title bar is the bar that is placed at the top of the screen where Channel Web Applications run. It is not a part of WebView. It is a native UI element in Android or iOS. The title bar is used for the following purposes:
  • Provide the user with a unified user interface.
  • Give the user a way to return to the LINE app if the page to be displayed inside of WebView fails to load.

Channel web pages and the title bar have different modes and UI components. You can control them using the JavaScript SDK API.

 

Entry pages and subpages

There are two types of pages displayed by Channel Web Applications.
  • Entry page: Top page of a Channel Web Application.
  • Subpages: Any page other than the entry page.
The entry page is displayed when an application is launched. A subpage is displayed when the user clicks a link or button. The user can return to the entry page from a subpage. The application can be closed from any page.

entry_sub_page

 

UI Elements

The title bar consists of three UI elements:
  • Left button: Back button
  • Right button: Close button
  • Center string: Page title string
native_bar1

iOS


native_bar1

Android


You can customize these UI elements (text string, visible/hidden, enabled/disabled) for each page. But to provide a fluid user experience, UI elements should be consistent across all pages (at least subpages).

You can use the JavaScript SDK API to handle touch events for each UI element.

 

Updating the title bar

The title bar is automatically positioned at the top of the screen running a Channel Web Application. It is not a part of WebView. It is a native UI element in Android or iOS. By default, the title bar has a close button on the right that closes the Channel Web Application. The JavaScript SDK can be used to position different buttons on the title bar’s left and right sides and to change the center string.

Use the following function to update the title bar.

Function LCS.Interface.updateTitleBar
Parameter 1 Object containing the details of the change.
Return value None

The object containing the details of the change is set in the parameter and has the following properties.

Property Description
pageKey Required string for identifying the page
titleBar Object containing the details of the changes to be made to the left and right buttons and the center string

The properties of the object set in the titleBar property are as follows:

Property Description
left Optional string for identifying the page object containing the details of the changes to the left button. If omitted, button will be in the shape of an arrow pointing to the left.
center Object containing the details of the changes to the center string. If omitted, nothing will be displayed in the center of the bar.
right Object containing the details of the changes to the right button. If omitted, this will be a close button.

You can use the left and right properties to set an object with a string for the label of the button. You can also determine whether the button is displayed or not, and whether the button can be tapped or not. The properties of the objects are as follows:

Property Description
imgId Sets the required btn_default string
text String to be displayed on the button
visible Sets whether or not the button is displayed.
enable Sets whether or not the button can be tapped.

The center property is used to set an object that contains the center string. It also determines whether the center string is clickable or not.

Property Description
text String to be displayed in the center of the title bar
clickable Sets whether or not the center string is clickable

Make sure the right button is set as a close button which calls the JavaScript SDK.Interface.closeWebView function when tapped so that the user always has a way to return to the LINE app from your application.

The following example shows you how to use this API:

var options = {
  pageKey: "key1",
  titleBar: {
    left: {
      imgId: "btn_default",
      text: "Back",
      visible: true,
      enable: true
    },
    center: {
      text: "Sample game",
      clickable: true
    },
    right: {
      imgId: "btn_default",
      text: "Close",
      visible: true,
      enable: true
    }
  }
};
LCS.Interface.updateTitleBar(options);
 

Handling touch events on the title bar

The left button, right button, and center string of the title bar are each capable of performing independent processes when clicked by the user. The JavaScript SDK is used to register functions to handle touch events.
Function LCS.Interface.registerTitleBarCallback
Parameter 1 Callback function that receives the touch event
Return Value None

The callback function set in Parameter 1 is called when a touch event is generated. An event object is then passed to the callback function as a parameter. You can determine which part of the title bar was tapped by looking at the target property of the event object.

target Property Location
“LBUTTON” Left button (after it has been modified by the updateTitleBar function)
“RBUTTON” Right button (after it has been modified by the updateTitleBar function)
“BACK” Back button
“TITLE” Center of the title bar

The following example shows you how to use this API:

LCS.Interface.registerTitleBarCallback(function(evt) {
  switch(evt.target) {
  case "LBUTTON":
    // Do something for tapping the left button...
    break;
  case "RBUTTON":
    // Do something for tapping the right button...
    break;
  case "BACK":
    // Do something for tapping the back button...
    break;
  case "TITLE":
    // Do something for tapping the title area...
    break;
  }
});
 

Working seamlessly between iOS and Android

The title bar behaves differently for iOS and for Android.

  • iOS:
    • Your application must provide a back button. (iOS does not provide a back button)
    • The left button, right button and center label can be changed using the JavaScript SDK API as iOS does not have a standard UI.
  • Android:
    • Android OS provides a standard back button for all applications.
    • The left button on the title bar is not shown on subpages. (Users use the Android back button)
    • You cannot hide the left button with the JavaScript SDK API.
native_bar_android


 

Entry page

You can choose whether to put a left button on your entry page. If you want a left button on the entry page, use the left attribute in the updateTitleBar() function.

For Android, there will be a left button on the title bar and the standard Android back button. A touch event for the left button can be handled in the callback function registered by the registerTitleBarCallback() function. But when the standard back button is tapped, a touch event for the standard back button is not fired and the Channel Web Application is closed.

Define left attribute? Left button (iOS) Left button (Android) Standard back button (Android)
Yes Shown Shown Shown
No None None Shown

The code for your entry page should look like this:

LCS.Interface.updateTitleBar({
  ...
  entryPage: true,
  titleBar: {
    // You can choose whether or not defining this left button.
    left: {
      ... // imgId, text, visible, enable
    },
    ...
  }
});
LCS.Interface.registerTitleBarCallback(function(evt) {
  switch(evt.target) {
  case "LBUTTON":
    // When the left button is defined and it is tapped
    ...
    break;
  case "BACK":
    // Never called.
    break;
  ...
  }
});
 

Subpages

All subpages must have a back button. The left button should only be used as a back button to take the user to the previous page. For iOS, do not define the left button. By default, the left button takes the user to the previous page and is rendered as a left arrow.

default_back_button_ios


For Android, the left button is not shown on subpages. Even if you define the left button, the definition will be ignored. Users use the standard back button. The standard back button cannot be hidden.

Define left attribute? Left button (iOS) Left button (Android) Standard back button (Android)
Yes Shown (left button) None Shown
No Shown (default back button) None Shown

The code for subpages should look like this:

LCS.Interface.updateTitleBar({
  ...
  entryPage: false,
  titleBar: {
    // You should NOT define a left button.
    ...
  }
});
LCS.Interface.registerTitleBarCallback(function(evt) {
  switch(evt.target) {
  // Left button definition should NOT be defined.
  case "BACK":
    // When the default/standard Back button is tapped
    ...
    break;
  ...
  }
});