58. An Android Studio Primary/Detail Flow Tutorial

This chapter will explain the concept of the Primary/Detail user interface design before exploring, in detail, the elements that make up the Primary/Detail Flow template included with Android Studio. An example application will then be created that demonstrates the steps involved in modifying the template to meet the specific needs of the application developer.

58.1 The Primary/Detail Flow

A primary/detail flow is an interface design concept whereby a list of items (referred to as the primary list) is displayed to the user. On selecting an item from the list, additional information relating to that item is then presented to the user within a detail pane. An email application might, for example, consist of a primary list of received messages consisting of the address of the sender and the subject of the message. Upon selection of a message from the primary list, the body of the email message would appear within the detail pane.

On tablet sized Android device displays in landscape orientation, the primary list appears in a narrow vertical panel along the left-hand edge of the screen. The remainder of the display is devoted to the detail pane in an arrangement referred to as two-pane mode. Figure 58-1, for example, shows the primary/detail, two-pane arrangement with primary items listed and the content of item one displayed in the detail...

58.2 Creating a Primary/Detail Flow Activity

In the next section of this chapter, the different elements that comprise the Primary/Detail Flow template will be covered in some detail. This is best achieved by creating a project using the Primary/Detail Flow template to use while working through the information. This project will subsequently be used as the basis for the tutorial at the end of the chapter.

Although the project creation wizard includes the option to select the Primary/Detail Flow template, greater flexibility in terms of configuring the template is available by adding the activity after the project has been created.

Select the Create New Project quick start option from the welcome screen and, within the resulting new project dialog, choose the No Activity template before clicking on the Next button.

Enter PrimaryDetailFlow into the Name field and specify com.ebookfrenzy.PrimaryDetailFlow as the package name. Before clicking on the Finish button, change the Minimum...

58.3 Modifying the Primary/Detail Flow Template

While the structure of the Primary/Detail Flow template can appear confusing at first, as will become evident, much of the functionality provided by the template can remain unchanged for many primary/detail implementation requirements.

In the rest of this chapter, the PrimaryDetailFlow project will be modified such that the primary list displays a list of web site names and the detail pane altered to contain a WebView object instead of the current TextView. When a web site is selected by the user, the corresponding web page will subsequently load and display in the detail pane.

58.4 Changing the Content Model

The content for the example as it currently stands is defined by the PlaceholderContent class file. Begin, therefore, by selecting the PlaceholderContent.kt file (located in the Project tool window in the app -> java -> com.ebookfrenzy.PrimaryDetailflow -> placeholder folder) and reviewing the code. At the bottom of the file is a declaration for a class named PlaceholderItem which is currently able to store three String objects representing content and details strings and an ID. The updated project, on the other hand, will need each item object to contain an ID string, a string for the web site name, and a string for the corresponding URL of the web site. To add these features, modify the PlaceholderItem class so that it reads as follows:

data class PlaceholderItem(val id: String, val website_name: String,

            val website_url: String) {

    override...

58.5 Changing the Detail Pane

The layout for the detail pane (the screen that is displayed when the user selects an item from the primary list) is contained within the activity_website_detail.xml file which, in turn, contains a FrameContainerView instance which is used to display the actual detail pane content. If the app is displaying in single-pane mode, the frame container will display the layout contained in the fragment_website_detail.xml file, while multi-pane mode will display the fragment_website_detail.xml (sw600dp) layout.

The template layout provided by Android Studio for the fragment_website_detail.xml comprises a Coordinator layout containing an app bar, toolbar, floating action button, and a text view. For this example, all we need to display is a WebView, so open this file and delete all of the views from the layout with the exception of the website_detail_container view. The easiest way to do this is to select all of the unwanted views in the Component Tree as shown...

58.6 Modifying the WebsiteDetailFragment Class

At this point the user interface detail pane has been modified but the corresponding Kotlin class is still designed for working with a TextView object instead of a WebView. Load the source code for this class by double-clicking on the WebsiteDetailFragment.kt file in the Project tool window.

In order to load the web page URL corresponding to the currently selected item only a few lines of code need to be changed. Once this change has been made, the code should read as follows:

package com.ebookfrenzy.PrimaryDetailflow

.

.

import android.webkit.WebResourceRequest

import android.webkit.WebView

import android.webkit.WebViewClient

.

.

class WebsiteDetailFragment : Fragment() {

.

.

    override fun onCreateView(

        inflater: LayoutInflater, container: ViewGroup?,

        savedInstanceState: Bundle...

58.7 Modifying the WebsiteListFragment Class

A minor change also needs to be made to the WebsiteListFragment.kt file to make sure that the web site names appear in the primary list. Edit this file, locate the onBindViewHolder() method and modify the setText() method call to reference the web site name as follows:

override fun onBindViewHolder(holder: ViewHolder, position: Int) {

    val item = mValues[position]

    holder.mIdView.text = item.id

    holder.mContentView.text = item.website_name

.

.

}

58.8 Adding Manifest Permissions

The final step is to add internet permission to the application via the manifest file. This will enable the WebView object to access the internet and download web pages. Navigate to, and load the AndroidManifest.xml file in the Project tool window (app -> manifests), and double-click on it to load it into the editor. Once loaded, add the appropriate permission line to the file:

<?xml version="1.0" encoding="utf-8"?>

<manifest xmlns:android="http://schemas.android.com/apk/res/android"

    package="com.ebookfrenzy.PrimaryDetailflow" >

         

    <uses-permission android:name="android.permission.INTERNET" />

 

    <application

        android:allowBackup="true"

     &...

58.9 Running the Application

Compile and run the application on a suitably configured emulator or an attached Android device. Depending on the size of the display, the application will appear either in small screen or two-pane mode. Regardless, the primary list should appear primed with the names of the three web sites defined in the content model. Selecting an item should cause the corresponding web site to appear in the detail pane as illustrated in two-pane mode in Figure 58-6:

Figure 58-6

58.10 Summary

A primary/detail user interface consists of a primary list of items which, when selected, displays additional information about that selection within a detail pane. The Primary/Detail Flow is a template provided with Android Studio that allows a primary/detail arrangement to be created quickly and with relative ease. As demonstrated in this chapter, with minor modifications to the default template files, a wide range of primary/detail based functionality can be implemented with minimal coding and design effort.