Refresh Animation (Rotating Objects)

Refresh Animation (Rotating Objects)

Asset Version: 1.0.0
  • Version 1.0.0
Last Published: Jun 27, 2017 By: Kony Team
123 0 0 19
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 (Rotating Objects) 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 (Rotating Objects) 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 (Rotating Objects) 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 Refresh Animation (Rotating Objects) component is a ready-to-use component. You can import the Refresh Animation (Rotating Objects) component into your app (created in Kony Visualizer), and achieve the Refresh Animation (Rotating Objects) feature without developing it from scratch. The Refresh Animation (Rotating Objects) component also facilitates a set of properties and APIs that helps you customize the UI elements and the functionality.

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

Prerequisites

Before you start using the Refresh Animation (Rotating Objects) 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 (Rotating Objects) 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 (Rotating Objects) 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.
    refreshcircle_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.refreshcircle 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 (Rotating Objects) Component to your App

To add a Refresh Animation (Rotating Objects) 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.refreshcircle, in the Components section on the Templates tab.
Note:

The width of the component is fixed (100%).
The height of the component cannot be changed.

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 (Rotating Objects) 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.refreshcircle({
                    "autogrowMode": kony.flex.AUTOGROW_NONE,
                    "clipBounds": true,
                    "height": "23.90%",
                    "id": "refreshcircle",
                    "isVisible": true,
                    "layoutType": kony.flex.FREE_FORM,
                    "left": "0dp",
                    "masterType": constants.MASTER_TYPE_USERWIDGET,
                    "skin": "slFbox",
                    "top": "0dp",
                    "width": "100%",
                    "zIndex": 1
                }, {}, {});
                componentInstance.backgroundSkin = "sknFlxBackground20223C";
                componentInstance.durationOfAnimation = "1";
    	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 (Rotating Objects) 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";
Animation speed
Category: Custom
Description: Specifies the duration of the animation.
The duration value is specified in seconds.
Syntax: durationOfAnimation
Type: String
Read/Write: Read + Write
Example:
this.view.componentInstance.durationOfAnimation = "1";
Center Circle Source
Category: Pass Through
Description: Specifies the file name of the image to be displayed as the center circle during the refresh animation.
Syntax: centerCircleSource
Type: String
Read/Write: Read + Write
Remarks:

Before setting the property:

  • Ensure that the image file exists in the workspace\resources\common directory.
  • Do not add any uppercase characters in the file name of the image.
  • Ensure that the image is in PNG format.
  • Specify the file name of the image along with the extension.
Example:
this.view.componentInstance.centerCircleSource = "centercircle.png";
Small Circles Source
Category: Pass Through
Description: Specifies the file name of the image to be displayed as the small circles during the refresh animation.
Syntax: smallCircleSource
Type: String
Read/Write: Read + Write
Remarks:

Before setting the property:

  • Ensure that the image file exists in the workspace\resources\common directory.
  • Do not add any uppercase characters in the file name of the image.
  • Ensure that the image is in PNG format.
  • Specify the file name of the image along with the extension.
Example:
this.view.componentInstance.smallCircleSource = "smallcircles.png";
Large Circles Source
Category: Pass Through
Description: Specifies the file name of the image to be displayed as the large circles during the refresh animation.
Syntax: largeCircleSource
Type: String
Read/Write: Read + Write
Remarks:

Before setting the property:

  • Ensure that the image file exists in the workspace\resources\common directory.
  • Do not add any uppercase characters in the file name of the image.
  • Ensure that the image is in PNG format.
  • Specify the file name of the image along with the extension.
Example:
this.view.componentInstance.largeCircleSource = "bigcircles.png";

APIs

The following API pertains to the Refresh Animation (Rotating Objects) 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 in the Segment Widget, do the following:

  1. Import the Refresh Animation (Rotating Objects) 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 (Rotating Objects) component and the Segment Widget onto the FlexContainer Widget.
  5. Set the left and top margin values of the Refresh Animation (Rotating Objects) 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 in the FlexContainer Widget, do the following:

  1. Import the Refresh Animation (Rotating Objects) component.
  2. Drag the Refresh Animation (Rotating Objects) component and the FlexContainer Widget onto the Form.
  3. Set the left and top margin values of the Refresh Animation (Rotating Objects) 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 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.

 

Limitations

The images of the small and big circles must similar to the images displayed below. You can change the color of the circles, but the transparency between the circles must be maintained.

Big Circles

bigcircles.png

Small Circles

smallcircles.png