Stellar Loyalty Developer Portal

« Back to Kits References

The Punch Cards kit provides screens for displaying user punch cards along with the corresponding progress. If a punch card is completed, the user can claim an award(s) for which that particular punch card is associated.

On this page:

Overview
Theme Customization
Layout Customization
Fully Custom UI

Overview

The Punch Cards kit follows the Master / Detail navigation flow. The master displays the list of available punch cards. And clicking a punch card will open the punch card details view that shows the detailed information about the punch card.

To include the Punch Card kit, open the Gradle Scripts | build.gradle (Module: app) and add the following to the dependencies section:

   implementation 'com.cheetahdigital.android:punchcards:<version>'

Launching the Punch Cards Activity

Assuming that the Punch Cards kit will be launched from a MainActivity, you can follow the succeeding steps to launch the PunchcardListActivity from a Button’s OnClickListener:

Add the following Punch Cards Activities to the AndroidManifest.xml.

PunchcardListActivity
PunchcardDetailsActivity

		<activity android:name="com.cheetahdigital.punchcards.ui.list.PunchcardListActivity" />
     <activity android:name="com.cheetahdigital.punchcards.ui.details.PunchcardDetailsActivity">
         <intent-filter>
             <action android:name="${applicationId}.PUNCHCARD_DETAILS" />

             <category android:name="android.intent.category.DEFAULT" />
         </intent-filter>
     </activity>
     <activity android:name="com.cheetahdigital.punchcards.ui.details.SimplePunchcardDetailsActivity">
         <intent-filter>
             <action android:name="${applicationId}.PUNCHCARD_SIMPLE_DETAILS" />

             <category android:name="android.intent.category.DEFAULT" />
         </intent-filter>
     </activity>

In your activity, add a Button that will launch the starting Activity - StellarPunchcardListActivity:

 button.setOnClickListener(new View.OnClickListener() {
     @Override
     public void onClick(View v) {
         startActivity(new Intent(Actions.Punchcards.getPunchcardsListAction(MainActivity.this)));
     }
 });

Punch Cards Configuration

The manner of displaying the list of punch cards can be configured by overriding the following attributes on your strings.xml:

display_all_punchcards - Set to true to display punchcards with punches greater than or equal to zero. Set to false to display punchcards with punches greater than zero. By default, this is set to true.
```
<bool name="display_all_punchcards">true</bool>
```
punchcard_sort_type - property name that will be used to arrange the list. By default, sort type is expiration_date.
```
<string name="punchcard_sort_type">expiration_date</string>
```
punchcard_sort_dir - sort direction which can be ascending (asc) or descending (desc). By default, sort dir is set to asc.
```
<string name="punchcard_sort_dir">asc</string>
```

Theme Customization

The Kits leverage on Android’s built-in support for Styles and Themes. Overriding the Styles and Themes of the app will also change the corresponding Views used in this kit.

Layout Customization

You can customize the layouts of the different screens in the Punch cards kit by copying the layout XML’s and overriding as desired. To read more about this, please visit the Layout Customization via XML document. The XML’s used are:

activity_punchcard_list.xml - container layout for fragment_punchcard_list
fragment_punchcard_list.xml - layout for displaying the list of punch cards
list_item_punchcard.xml - layout of a punch card item in the list of punch cards
activity_punchcard_details.xml - layout for displaying the details of a punch card
list_item_punch.xml - layout of a punch item in the list of punches
punches_list.xml - layout for displaying the list of punches

Customizing Layouts via Code

There are certain cases that you may want to use a highly-customized layout for an Activity/Fragment. To read more about this, please visit the Layout Customization via Code document. The classes used for the Punch cards kit are:

PunchcardListActivity and PunchcardListFragment for the displaying the list of punch cards
PunchcardDetailsActivity for displaying the details of a punch card

Customizing Handlers

There are certain cases that you may want to change the default behavior of an Activity/Fragment. You can achieve that by extending the Activity/Fragment that you want to customize and overriding as necessary.

Handlers may occur in different places:

Adapters - for lists
Member variables inside Activities or Fragments
Member variables inside custom Widgets - for stand-alone custom Widgets

To start with, you may look at the classes mentioned in Customizing Layouts via Code, along with PunchcardAdapter, which is used for displaying the list of punch cards, and PunchesAdapter for displaying the list of punches in a punch card.

Fully Custom UI

If changing the layout does not suffice for your case, you can always do a full customization. The following are the methods you can use from the PunchCardAPI class:

Querying published Punch Cards

getPunchcardList(@NonNull PunchcardParams punchcardParams,
                                 boolean clearCache,
                                 @NonNull ListenerModel<BaseModel<PunchcardList>, PunchcardList> listener)

Querying a published Punch Card

getPunchcard(@NonNull PunchcardParams punchcardParams, boolean clearCache,
                             @NonNull ListenerModel<BaseModel<Punchcard>, Punchcard> listener)

Querying Punch Card instances

getPunchcardInstanceList(@NonNull PunchcardParams punchcardParams, boolean clearCache,
                                         @NonNull ListenerModel<BaseModel<PunchcardInstanceList>, PunchcardInstanceList> listener)

Querying a Punch Card instance

getPunchcardInstance(@NonNull PunchcardParams punchcardParams, boolean clearCache,
                                     @NonNull ListenerModel<BaseModel<PunchcardInstance>, PunchcardInstance> listener)

Give a punch for a purchase or visit

punch(@NonNull PunchcardParams punchcardParams, @NonNull ListenerModel<BaseModel<PunchcardInstance>, PunchcardInstance> listener)