top

AppsFramework 2.0 UI Components

Published 2014-10-28 | (Compatible with SDK 4.5,5.0,5.1 and 2013,2014 models)

Introduction to UI Components of Samsung AppsFramework 2.0

** This class will not be supported in 2015.

   All functionalities of AppsFramework are more improved, integrating with CAPH. Therefore Appsframework is not supported since 2015 Smart TV. To use functionalities of Appsframework, refer to here.

Overview

Together with 2012 platform, Samsung introduced AppsFramework 2.0. It contains UI Components - a set of controls like pop-ups, date pickers, scroll bars, loading or progress indicators, that you can use to build attractive, feature rich and user friendly interfaces for Samsung Smart TV applications. If you’re familiar with jQuery, you will find UI Components very easy to use in your applications. UI Components are available on 2012 and 2013 platforms.

Prerequisites

To use UI Components, include Samsung AppsFramework 2.0 in your application by putting the following code in the <head> section of index.html:

<script type="text/javascript" src="$MANAGER_WIDGET/Common/af/2.0.0/loader.js"></script>

Note

A sample application for this article is provided here. Refer to it to see more examples of UI Components usage as this article covers only basic ones.

You will find full API reference for UI Components here.

Available Components

The following components are available:

sfButton
Single or multipart button.
sfCheckBox
Simple component that works in a very similar way to checkboxes on websites.
sfDatePicker
Complete utility to easily pickup dates and times.
sfImage
Component for operating on images.
sfKeyHelp
Bottom bar with a short help on navigation (e.g. remote control keys reference).
sfLabel
Component which adds simple text or HTML to an element.
sfList
List of items that can be used to build e.g. a navigation menu.
sfLoading
Loading or any other time consuming activity indicator.
sfPageIndicator
Component for easy navigation when content exceeds the area of the TV screen.
sfPopup
Different kinds of dialog boxes.
sfProgressBar
Bar that can be used to show the progress of various operations like downloading files etc.
sfTextInput
Component that launches the IME and gets user input.
sfToolTip
Little balloon that can contain text, graphics or both and can be displayed e.g. as a helper for the user.
sfScroll
Vertical scrollbar that can be used to get user input or to scroll the content that exceeds the area of the TV screen.
sfHScroll
Horizontal scrollbar that can be used to get user input or to scroll the content that exceeds the area of the TV screen.
sfSlider
Component that can be used to get input from the user, e.g. can be used as a volume slider.

Note

Every component must be attached to an element in HTML which is a placeholder for that component.

General structure looks like this:

HTML

<div id="elem"></div>

JavaScript

// Create a reference to a DOM node.
var $elem = $('#elem');

// Initialize the component.
// sfExample name is used to illustrate the flow, it is not a real UI component.
$elem.sfExample({
    propertyName: 'value'
});

// Execute the component's method.
$elem.sfExample('hide');

Use a variable name prefixed with a $ sign to stress that this variable contains a reference to a DOM node that we got with jQuery $('#button').

Saving a reference to a DOM node in a variable saves the resources because getting a DOM node with $('#button') makes the browser search the DOM tree each time it is called.

Components Descriptions

sfButton

sfButton is a simple component that can handle events when it is pressed.

Figure: single sfButton

To initialize an sfButton component, use this code:

JavaScript

var $button = $('#button');

$button.sfButton({
    text: 'Sign in'
});

It is possible to set the position of the button and its width with CSS, like this:

CSS

#button {
    position: absolute;
    top: 100px;
    left: 400px;
    width: 300px;
}

sfButton can be a “multibutton”:

Figure: multibutton sfButton

To achieve this, modify the previous JavaScript code:

JavaScript

$button.sfButton({
    text: ['Settings', 'Favourites', 'Sign out']
});

To set the focus on the desired “subbutton”, use the focus method:

JavaScript

// Sets the focus on the 2nd subbutton (index: 1).
$button.sfButton('focus', 1);

In order to read which button is focused (e.g. to get the index of the pressed subbutton), use the getIndex method:

JavaScript

var currentButtonIndex = $button.sfButton('getIndex');

To learn more about sfButton component, refer to sfButton API.

sfToggleButton

The second type of buttons is sfToggleButton, which works like an “On/Off” switch.

Figure: sfToggleButton

Here is the example code:

JavaScript

var $button = $('#button');

$button.sfToggleButton({
    text: {
        on: 'Active',
        off: 'Disabled'
    },
    isOn: false
});

To get the state of the sfToggleButton, use the isOn method:

JavaScript

// Will return true if sfToggleButton is On, false otherwise.
var isOn = $button.sfToggleButton('isOn');

To learn more about sfToggleButton component, refer to sfToggleButton API.

sfCheckBox

sfCheckBox is another simple component that works in a very similar way to checkboxes on websites.

Figure: sfCheckBoxes with labels (see sfLabel)

To initialize an sfCheckBox component, use the following code:

JavaScript

var $checkbox = $('#checkbox');
$checkbox.sfCheckBox();

The following code shows how to check and uncheck the sfCheckBox and how to test if the sfCheckBox is checked:

JavaScript

// Check the sfCheckBox.
$checkbox.sfCheckBox('check');

// Uncheck the sfCheckBox.
$checkbox.sfCheckBox('uncheck');

// Will return true if sfCheckBox is checked, false otherwise.
var isChecked = $checkbox.sfCheckBox('getChecked');

To learn more about sfCheckBox component, refer to sfCheckBox API.

sfDatePicker

sfDatePicker component allows the user to select dates and times in a convenient way. The returned date is a JavaScript Date.toString() result, so it is possible to get the date in a desired format.

Figure: sfDatePicker - date only

Figure: sfDatePicker - date and time

Here is the example code that will display an sfDatePicker component with date and time (timePicker: true):

JavaScript

var $datePicker = $('#datePicker');

$datePicker.sfDatepicker({
    timePicker: true,
    format: 'yyyy-MM-dd hh:mm:ss a',
    callback: function (date, obj) {
        if (date) {
            alert('Returned value: ' + date);
            alert('JavaScript Date: ' + obj);
        }
    },
    time: 60
});

$datePicker.sfDatepicker('show');

To learn more about sfDatepicker component, refer to sfDatepicker API.

sfImage

sfImage is a component for operating on images.

Here is the example code:

HTML

<!-- Path to an image is relative to the application root folder. -->
<img id="image" src="images/image0.jpg">

JavaScript

var $image = $('#image');

// Initialize the component with a new image.
$image.sfImage({
    src: 'images/image1.jpg'
});

To replace the image with another one, use the option method with a parameter containing the path to the new image:

JavaScript

$image.sfImage('option', 'src', 'images/image2.jpg');

The destroy method destroys the component and restores the src attribute of <img /> element to before initialization state (images/image0.jpg will be displayed in this case).

JavaScript

$image.sfImage('destroy');

To learn more about sfImage component, refer to sfImage API.

sfKeyHelp

sfKeyHelp component displays a bottom bar which can contain short navigation instructions (e.g. remote control keys reference).

Figure: sfKeyHelp

To create an sfKeyHelp, put the following code in the onFocus method of the desired scene of the application.

JavaScript

var $mainKeyhelp = $('#mainKeyhelp');

$mainKeyhelp.sfKeyHelp({
    'user': 'Example User',
    'red': 'Show subtitles',
    'green': 'Toggle language',
    'play': 'Play movie',
    'stop': 'Stop movie',
    'return': 'Return',
    'theme': 'white'
});

The configuration object of the sfKeyHelp component contains pairs of remote control key names and descriptions that will be displayed next to each key shown on the sfKeyHelp. There are three themes available: black (default), white and transparent:

Figure: sfKeyHelp - black theme

Figure: sfKeyHelp - white theme

Figure: sfKeyHelp - transparent theme. There is a background image visible from behind the key help.

For a complete list of parameters (including key names), refer to sfKeyHelp API.

sfLabel

sfLabel component adds a simple text or HTML to an element.

Here is the example code:

HTML

<!-- Component's placeholder with initial content, not necessarily div,
may be any other tag to preserve semantics.  -->
<div id="label">Initial text</div>

JavaScript

var $label = $('#label');

// Initialize the component with a new text.
$label.sfLabel({
    text: 'This is new text'
});

To change the sfLabel content, use the option method:

JavaScript

$image.sfLabel('option', 'text', 'This is <span class="distinct">another</span> text');

The destroy method destroys the component and restores the contents of placeholder to before initialization state (Initial text will be displayed in this case).

JavaScript

$image.sfLabel('destroy');

To learn more about sfLabel component, refer to sfLabel API.

sfList

sfList component is a navigable list of items with paging ability. It takes an array of records and builds a list out of them. sfList component may be used to create e.g. a navigation menu.

Figure: sfList

Here is the example code:

JavaScript

var $list = $('#list'),
    listItems = [
        'People',
        'Architecture',
        'Landscapes',
        'Sports and activities',
        'Leisure',
        'Business',
        'Travels',
        'Technology',
        'Abstract',
        'Textures'
    ];

$list.sfList({
    data: listItems,
    itemsPerPage: 5
});

Because the number of items is greater than itemsPerPage parameter value, the list will display the first five items. When the user navigates to the sixth item, the next five items from the list will be displayed.

sfList API provides some methods to operate on the list. The most frequently used are:

getSelectedItem

Returns the index of currently selected item in the list.

JavaScript

$list.sfList('getSelectedItem');
move

Moves focus to the item indicated by the index.

JavaScript

$list.sfList('move', 3);
next and prev

Moves focus to next and previous items on the list.

JavaScript

$list.sfList('next');
$list.sfList('prev');

To see an example of sfList component working in conjuction with sfScroll component, read the sfScroll section.

For more sfList methods, refer to sfList API.

sfLoading

sfLoading component can be used to indicate that time consuming activity like XHR request is ongoing.

Figure: sfLoading

Here is the example code:

JavaScript

var $loading = $('#loading');

// Show the sfLoading, e.g. when the file download starts.
$loading.sfLoading('show');

// Hide the sfLoading.
$loading.sfLoading('hide');

To learn more about sfLoading component, refer to sfLoading API.

sfPageIndicator

sfPageIndicator is a component that can be used in conjunction with scrollable content when it exceeds the area of the TV screen. sfPageIndicator component will indicate the current content position to the user.

Figure: Scrollable content with sfPageIndicator below

To initialize the sfPageIndicator component, use the following code:

JavaScript

var $indicator = $('#indicator');

$indicator.sfPageIndicator({
    count: 5, // Set number of pages.
    index: 0  // Set the initial index.
});

sfPageIndicator component provides four methods:

setIndex

Moves the page to the indicated index.

JavaScript

$indicator.sfPageIndicator('setIndex', 3);
getIndex

Returns index of the current page.

JavaScript

var $page = $indicator.sfPageIndicator('getIndex');
prev and next

Moves to the previous or the next page.

JavaScript

$indicator.sfPageIndicator('next');
$indicator.sfPageIndicator('prev');

To make the sfPageIndicator component work with actual content, some logic must be implemented. First of all you need to create a container in HTML for your content, which should be visually prepared for displaying the paged layout, and a container for sfPageIndicator component, like this:

HTML

<div id="pagesContainer">
    <div>page 0</div>
    <div>page 1</div>
    <div>page 2</div>
</div>
<div id="pageIndicator"></div>

Next you need to create your component and couple it with the content:

JavaScript

var $pageIndicator = $('#pageIndicator'),
    $pagesContainer = $('#pagesContainer'),
    $pages = $('#pagesContainer div'),
    pageWidth = $pages.width(); // Width of each page, we assume horizontal scrolling.
    numberOfPages = $pages.length,
    page = 0; // Set the index of initially displayed page.

function scrollContent() {
    // Move content.
    $pagesContainer.css('margin-left', (pageWidth * page) + 'px');

    // Set index of displayed page in sfPageIndicator.
    $pageIndicator.sfPageIndicator('setIndex', page);
}

$pageIndicator.sfPageIndicator({
    count: numberOfPages, // Set the number of pages.
    index: page // Set the initial index.
});

The last thing to implement is the key handling. Let’s assume using the LEFT and RIGHT keys for navigation:

JavaScript

// On LEFT key pressed
if (page > 0) {
    page--;
    scrollContent();
}

// On RIGHT key pressed
if (page < (numberOfPages - 1)) {
    page++;
    scrollContent();
}

See the attached application to see a complete example of integrating an sfPageIndicator component with scrollable content. To learn more about sfPageIndicator component, refer to sfPageIndicator API.

sfPopup

sfPopup component displays different kinds of dialog boxes.

Figure: sfPopup with title, helpbar and two buttons

The simplest example is an sfPopup that only displays a message and has no buttons, title or helpbar. To initialize such an sfPopup, use the following code:

JavaScript

var $popup = $('#popup'),
    returnedValue;

$popup.sfPopup({
    text: 'The simplest popup',
    buttons: [],
    callback: function (selectedIndex) {
        returnedValue = selectedIndex;
    }
});

In this case an sfPopup component will always return -1, no matter if the user pressed ENTER or RETURN.

In the most complex case, an sfPopup will contain a title, two buttons (may be more) and a helpbar. To initialize such an sfPopup, use the following code:

JavaScript

var $popup = $('#popup'),
    returnedValue;

$popup.sfPopup({
    text: 'Two buttons popup',
    buttons: ['OK', 'Cancel'],
    defaultFocus: 1,
    title: 'Example popup',
    keyhelp: {
        'return': 'Return'
    },
    callback: function (selectedIndex) {
        returnedValue = selectedIndex;
    }
});

Don’t use too many buttons in the popups - it may confuse the user. Furthermore, the space for buttons is limited. If the total width of buttons exceeds the width of the sfPopup, excessive buttons will be moved to the next line, which will break the layout of the sfPopup.

In order to display the sfPopup, call the show method:

JavaScript

$popup.sfPopup('show');

To learn more about sfPopup component, refer to sfPopup API.

sfProgressBar

sfProgressBar component can be used to display the progress of various time consuming operations like downloading files or filling in registration forms.

Figure: Four kinds of sfProgressBar

To initialize sfProgressBar component, use this code:

JavaScript

var $progressBar = $('#progressBar');

$progressBar.sfProgressBar({
    max: 100,
    type: 'buffering'
});

type parameter can be set to one of the following values: progress, loading, buffering, status. It changes the appearance of sfProgressBar. See a screenshot above to see the difference.

The most frequently used methods to operate on sfProgressBar component are:

setValue

Sets value of the sfProgressBar to indicated value.

JavaScript

var newValue = 30;
$progressBar.sfProgressBar('setValue', newValue);
getValue

Gets current value of the sfProgressBar.

JavaScript

var value = 0;
value = $progressBar.sfProgressBar('getValue');
next and prev

Increase or decrease value of the sfProgressBar by 1.

JavaScript

$progressBar.sfProgressBar('next');
$progressBar.sfProgressBar('prev');

More methods are described in sfProgressBar API.

sfTextInput

sfTextInput component allows to launch the IME (Input Method Editor - an on screen keyboard) and get user input.

Figure: sfTextInput - numeric keypad mode

Figure: sfTextInput - QWERTY keyboard mode

Here is the example code:

JavaScript

$inputBox.sfTextInput({
    text: 'Initial text',
    maxlength: 128,
    ontextchanged: function (text) {
        alert("Current Text: " + text);
    },
    oncomplete: function (text) {
        if (text) {
            alert('Entered text: ' + $inputBox.sfTextInput('getText'));
        } else {
            alert('Canceled');
        }
    },
    onkeypadchanged: function (keypadtype) {
        // Set the position of the keypad.
        var width = this.$inputBox.width(),
            offset = this.$inputBox.offset();

        if (keypadtype.toLowerCase() === '12key') {
            $inputBox.css('left', '80px');
            $inputBox.sfTextInput('setKeypadPos', offset.left + width, offset.top);
        } else {
            $inputBox.css('left', '50px');
            $inputBox.sfTextInput('setKeypadPos', offset.left + width, offset.top);
        }
    }
}).sfTextInput('focus');

Options set during the initialization are as follows:

maxlength
Maximum length of text input.
text
Initial text. Default value is an empty string.
ontextchanged
The function to be called when the text is changed by the user. This function is called each time when entering a WORD is completed.
oncomplete
The function to be called when entering text is finished. If the entering is canceled by the user, a null value is passed to this function.
onkeypadchanged
The function to be called when the keypad mode is changed (12key or qwerty). Depending on the layout of your application it may be necessary to change the position of the sfTextInput, because 12key and qwerty have different dimensions.

To learn more about sfTextInput component, refer to sfTextInput API.

sfToolTip

sfToolTip component displays a little balloon that can contain text (HTML) or graphics (or both) and can be displayed e.g. as a helper for the user.

Figure: sfToolTip

To display the sfToolTip component use the following code:

JavaScript

var $tooltip = $('#tooltip');

$tooltip.sfToolTip({
    text: 'This is my tooltip text',
    title: 'Tooltip title',
    orientation: down
});

orientation parameter may be set to one of the following values: up, down, left, right. It indicates the direction the arrow of sfToolTip component will point to. It can be changed with the setOrientation method:

JavaScript

$tooltip.sfToolTip('setOrientation', 'right');

Similarly the title and text can be changed:

JavaScript

$tooltip.sfToolTip('setTitle', 'New tooltip title');
$tooltip.sfToolTip('setText', 'New tooltip text');

To learn more about sfToolTip component, refer to sfToolTip API.

sfScroll

sfScroll component is a vertical scrollbar that can be used e.g. to get user input. It can be also coupled with scrollable content to scroll it in case the content exceeds the area of the TV screen.

Figure: two sfScrolls with different number of “pages”

The code to initialize the vertical sfScroll component is as follows:

JavaScript

var $scroll = $('#scroll');

$scroll.sfScroll({
    pages: 10,
    currentPage: 0 // This parameter is optional, default value is 0.
});

sfScroll API provides following methods to operate on it:

move

Moves the scroll to the position indicated by the index.

JavaScript

$scroll.sfScroll('move', 3);
next and prev

Moves the scroll to the next or the previous index.

JavaScript

$scroll.sfScroll('next');
$scroll.sfScroll('prev');

As already mentioned, sfScroll component can be used with scrollable content. The example below shows how to make the sfScroll component to work with sfList component (but it can be any other scrollable content).

First, initialize both components.

JavaScript

var data = [
    'Choi Kwang-Do', 'Chon-Tu Kwan Hapkido', 'GongKwon Yusul', 'Gungdo',
    'Gwonbeop', 'Gyongdang', 'Haidong Gumdo', 'Han Mu Do', 'Hankido',
    'Hankumdo', 'Hapki Yusul', 'Hapkido', 'Hwa Rang Do', 'Hyeong',
    'Kong Soo Do', 'Korean swordsmanship', 'Kuk Sool Won', 'Kuk Sul Do',
    'Kumdo', 'Kung-fu', 'Kunmudo', 'Moo Duk Kwan Taekwondo', 'Shim Gum Do',
    'Shippalgi', 'Soo Bahk Do', 'Ssireum', 'Subak', 'Sunmudo', 'Tae Soo Do',
    'Taekkyeon', 'Taekwondo', 'Tang Soo Do', 'Yusul'
],

$list = $('#list'),
$scroll = $('#scroll'),

itemsPerPage = 5;
numberOfItems = this.data.length;
pages = Math.ceil(this.numberOfItems / this.itemsPerPage);
currentPage = 0; // Page to be indicated on the sfScroll.
currentItem = 0; // Index of the current item on the sfList.

$list.sfList({
    data: data,
    itemsPerPage: itemsPerPage
});

$scroll.sfScroll({
    pages: pages
});

Browsing the sfList can be handled e.g. by UP and DOWN keys:

JavaScript

switch (keyCode) {
    case sf.key.UP:
        scroll('up');
        break;

    case sf.key.DOWN:
        scroll('down');
        break;
}

To put it all together, create a function that will allow the user to browse the sfList and that will update the sfScroll to indicate the current page and show the user in which part of sfList they are:

JavaScript

function scroll(dir) {
    $list.sfList(dir === 'up' ? 'prev' : 'next');
    currentItem = $list.sfList('getIndex');
    currentPage = Math.floor(currentItem / itemsPerPage);

    if (dir === 'up') {
        if (currentPage < 0) {
            currentPage = pages - 1;
        }
    } else {
        if (currentPage > pages -1) {
            currentPage = 0;
            currentItem = 0;
        }
    }

    $list.sfList('move', currentItem);
    $scroll.sfScroll('move', currentPage);
}

sfScroll and sfList components can interact bidirectionally. Take a look at the attached application to see an example.

To learn more about sfScroll component, refer to sfScroll API.

sfHScroll

sfHScroll component is a horizontal version of sfScroll. It works exactly the same as sfScroll.

Figure: sfHScroll

JavaScript

var $scroll = $('#scroll');

$scroll.sfHScroll({
    pages: 6,
    currentPage: 0 // This parameter is optional, default value is 0.
});

move, next and prev methods works the same way as in sfScroll.

To learn more about sfHScroll component, refer to sfHScroll API.

sfSlider

sfSlider component can be used to get input from the user, e.g. in the case of a volume slider.

Figure: sfSlider with tooltip

Here is the example code:

JavaScript

var $slider = $('#slider');

$slider.sfSlider({
    max: 100, // Set the mximum value.
    value: 40, // Set the initial value.
    showtooltip: true, // Display a tooltip with the current value.
    showprogress: true, // Display a progressbar with the current value.
});

In order to get the current value of the sfSlider, use the getValue method.

JavaScript

var value = 0;
value = $slider.sfSlider('getValue');

To change the value of the sfSlider (e.g. when the user presses UP or DOWN keys), use the setValue method.

JavaScript

var newValue = 60;
$slider.sfSlider('setValue', newValue);

There are many more methods for operating on sfSlider. For a complete list, refer to sfSlider API.