Refresh Animation (Generic)

Refresh Animation (Generic)

Asset Version: 1.0.0
  • Version 1.0.0
Last Published: May 26, 2017 By: Kony Team
105 0 0 9
The refresh animation component can be used as a pull-to-refresh (or swipe-to-refresh) pattern that shows up when a user pulls down on a list of data using touch, in order to retrieve more data.Swipe to refresh works good for lists, grid lists, and card collections that are sorted by recent content (a collection is strictly sorted by descending date).

Requirements

  • Visualizer Enterprise
 

Devices

 

Platforms

Features

  • Easy to achieve the refresh animation without developing it from scratch.
  • Facility to customize the UI as you require

Platforms Supported

  • Android
  • iOS

Prerequisites

  • Kony Visualizer Enterprise
  • A Kony Reference Architecture app created in Kony Visualizer

The Refresh Animation (Generic) component is a user defined animated UI. The refresh animation is used to fill the space when a widget is pulled down to refresh the contents in the form.

Here is a use case that describes the use of the Refresh Animation (Generic) component.

Use Case

Consider a case that you want to develop an online hotel booking app that displays a list of hotels based on the selected location and specified price range. In this app, you can add the Refresh Animation (Generic) component to fill the available space when the list is pulled down to refresh the accommodation fares. You can hide the Refresh Animation component when the list refresh is complete.

The following sections help you use the Refresh Animation (Generic) component in your app:

Prerequisites

Before you start using the Refresh Animation (Generic) component, ensure you have the following:

  1. Kony Visualizer Enterprise 7.3
  2. A Kony Reference Architecture app in Visualizer. You can create a Kony Reference Architecture app in Visualizer using the following procedure:
    1. Open Kony Visualizer.
    2. On the File Menu, click New Project. The New Project dialog appears.
    3. In the Project Name box, type a name for your project.
    4. Select Kony Reference Architecture, and click Create.

Importing the Refresh Animation (Generic) Component

Before you start importing the component to Kony Visualizer, you must download the component from the Kony Marketplace website. You can import the Marketplace components only into the apps that are of the Kony Reference Architecture type.

To import the Refresh Animation (Generic) component, do the following:

  1. Open your app project in Kony Visualizer.
  2. On the File menu, point to Import, and click Component. The Open dialog appears.
  3. Navigate to the location where you downloaded the component (zip file) on your computer, select the component, and click Open. The Import Marketplace Item dialog appears.
    refreshg_import.png
  4. In the Library Name box, type a name if you want to create a new library. Otherwise, you can select the existing library name.
  5. In the Collection Name box, type a name if you want to create a new collection. Otherwise, you can select the existing collection name.
  6. In the Component Name box, the com.konymp.genericrefresh name is displayed by default. If you want, you can rename it.

When you import a component, the component is imported to Visualizer's workspace, but not directly into your app. Thus, after you import a component, you must add the component to your app.

Adding a Refresh Animation (Generic) Component to your App

You can add a Refresh Animation (Generic) component to FlexForms and FlexContainer Widget.

To add a Refresh Animation (Generic) component, do the following:

  1. Open your app, and then open the form to which you want to add the component.
  2. Open the library to which you imported the component. To open the library:
    • Click the context arrow of KonyLibrary, point to Open, and select the library in which the component exists.
      library.png
  3. From the Collections tab, drag the component onto the form on the Visualizer canvas. The component is added to the form. You can also see a new element, com.konymp.genericrefresh, in the Components section on the Templates tab.
Note:

Ensure that the component is set to occupy 100 percent width of the device. You can achieve this by setting the width of the parent widget to 100 percent.

After adding a component to a form, you can configure the component the way you want it using the Look, Skin, and Action tabs on the Properties pane. Configuring the properties on the Properties pane is similar to configuring the properties of any widget in Kony Visualizer. For more information, refer Button Widget.

You can also see that a new tab, Component, is added on the Properties pane. The Component tab contains assorted properties relevant to the component that allow you to customize the component as required. The properties on the Component tab are categorized as Pass Through and Custom properties. The Pass Through properties are the default properties of individual widgets in the component. The Custom Properties are user-defined properties based on the use case of the component.

Note:

Changes made to the Custom properties are reflected only during run time, but not during design time (Visualizer Canvas).

You can also add a Refresh Animation (Generic) component dynamically. To do so,

  1. In the Project Explorer, on the Projects tab, click the context menu arrow of Controllers under the respective channel, and then click FormController. The FormController JavaScript file opens in the Code Editor.
  2. Copy and paste the following code snippet in the JavaScript file:
     /* creating a component's Object */
    var componentInstance = new com.konymp.genericrefresh({
                    "autogrowMode": kony.flex.AUTOGROW_NONE,
                    "clipBounds": true,
                    "height": "30%",
                    "id": "genericrefresh",
                    "isVisible": true,
                    "layoutType": kony.flex.FLOW_VERTICAL,
                    "left": "0%",
                    "masterType": constants.MASTER_TYPE_USERWIDGET,
                    "skin": "CopyslFbox0j0ca36c45e434d",
                    "top": "0%",
                    "width": "106.67%",
                    "zIndex": 1
                }, {}, {});
    /* Setting component's Custom properties */                componentInstance.backgroundSkin = "skinid";               
    /*Adding the Component to the Form*/                this.view.add(componentInstance);

    In the code snippet, you can edit the properties of the component as you require. For more information, see Setting Properties.

  3. Save the file.

Setting Properties

The properties provided on the Component tab allow you to customize the UI elements in the Refresh Animation (Generic) component. You can set the properties directly on the Component tab or by writing a JavaScript. This section provides information on how to set properties by writing a JavaScript.

Background Skin
Category: Custom
Description: Specifies the skin to be set as the background of the component.
Syntax: backgroundSkin
Type: String
Read/Write: Write
Remarks: Before you set the property, ensure that the skin ID that you specify already exists in your app project.
Example:
this.view.componentInstance.backgroundSkin = "skinid";

APIs

The following API pertains to the Refresh Animation (Generic) component:

show

The API displays the refresh animation.

Syntax
show()
Parameters

None

Return Value

None

Example
this.view.componentInstance.show();
hide

The API hides the refresh animation.

Syntax
hide()
Parameters

None

Return Value

None

Example
this.view.componentInstance.hide();
isShown

The API notifies whether the refresh animation is displayed or not.

Syntax
isShown()
Parameters

None

Return Value

Boolean

Example
this.view.componentInstance.isShown();

Sample Usage of the Component

Component with the Segment Widget

Consider a use case where user pulls down a list to update the list data. You can use the Refresh Animation component to fill the space when the list (segment widget) is pulled down to refresh the data. You can achieve the use case by following the below procedure.

To use the component with the Segment Widget, do the following:

  1. Import the Refresh Animation (Generic) component.
  2. Add a FlexContainer Widget to the form.
  3. Set the Layout Type of the FlexContainer Widget to Flow Vertical.
  4. Drag the Refresh Animation (Generic) component and the Segment Widget onto the FlexContainer Widget.
  5. Set the left and top margin values of the Refresh Animation (Generic) component to zero percent.
  6. Set the left and top margin values of the Segment Widget to zero percent.
  7. Define the onPull event of the Segment Widget as shown in the following code snippet:
    /* Call onPullCallback on the onPull of the Segment Widget */
    	this.onPullCallback(segmentWidget,scrollDirection);
  8. In the Project Explorer, on the Projects tab, click the context menu arrow of Controllers under the respective channel, and then click FormController. The FormController JavaScript file opens in the Code Editor.
  9. Copy and paste the following code snippet in the FormController JavaScript file:
    /*Define onPullCallback in the formController */
    onPullCallback: function(segmentWidget,scrollDirection){
    	       this.view.componentInstance.show();
    }

    The above code displays the Refresh animation component on triggering the onPull event of the Segment Widget.

  10. Save the file.

  

Component with the FlexContainer Widget

To use the component with the FlexContainer Widget, do the following:

  1. Import the Refresh Animation (Generic) component.
  2. Drag the Refresh Animation (Generic) component and the FlexContainer Widget onto the Form.
  3. Set the left and top margin values of the Refresh Animation (Generic) component to Zero percent.
  4. Set the left and top margin values of the FlexContainer Widget to Zero percent.
  5. Define the onTouchStart, onTouchMove, and onTouchEnd events of the Form as shown in the following code snippet:
    /*Call the methods in the form’s Action editor*/
    
    /*onTouchStart of the Form */ this.onStart(yCoordinates);
    /*onTouchMove of the Form */ this.onMove(yCoordinates);
    /*onTouchEnd of the Form */ this.onEnd();
  6. In the Project Explorer, on the Projects tab, click the context menu arrow of Controllers under the respective channel, and then click FormController. The FormController JavaScript file opens in the Code Editor.
  7. Copy and paste the following code snippet in the FormController JavaScript file:
    /* Define methods in the Form Controller */
    	define({
    	yCoordinates: "0",
    	_top: "0",
    	_started: 0,
    	onStart: function (yy) {
    		this.yCoordinates = yy;
    		if (this._started === 0) {
    			this.view.componentInstance.show();
    			this._started = 1;
    		}
    	},
    	onMove: function (y) {
    		this._top = y - this.yCoordinates;
    		if (this._top > 0) {
    			this.view.flexContainer.top = this._top;
    		} else {
    			this.view.flexContainer.top = 
    parseInt(this.view. componentInstance.height) + this._top + "dp"; } }, onEnd: function () { if (this._top >= 0) { this.view.flexContainer.top = this.view. componentInstance.height; } else { this.view.flexContainer.top = "0dp"; this.view.componentInstance.hide(); this._started = 0; } } });

    The above code displays the Refresh animation component on triggering the Form events.

  8. Save the file.