Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix #4460: Add Wiki documentation for adding the spotlight experience to any element #4943

Merged
merged 14 commits into from
Apr 27, 2023
142 changes: 142 additions & 0 deletions wiki/Spotlight Guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
Feature Spotlights
# Introduction

Spotlighting is a visual tool that highlights and brings a user’s focus to an element on the screen. We use them to communicate the purpose of a specific screen element to the user, which they might otherwise miss. Spotlighting involves dimming the other areas on the screen and lighting the element to bring the user’s focus onto it, and explaining what/how that feature should be used.
seanlip marked this conversation as resolved.
Show resolved Hide resolved

# Creating a new spotlight

The [SpotlightFragment](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/app/src/main/java/org/oppia/android/app/spotlight/SpotlightFragment.kt#L44) contains APIs to call spotlights for any in-app screen element. To create a spotlight, call one of these functions:
[requestSpotlight](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/app/src/main/java/org/oppia/android/app/spotlight/SpotlightManager.kt#L26)
seanlip marked this conversation as resolved.
Show resolved Hide resolved
[requestSpotlightWithDelayedLayout](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/app/src/main/java/org/oppia/android/app/spotlight/SpotlightManager.kt#L13)

Both these functions expect a parameter, [SpotlightTarget](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/app/src/main/java/org/oppia/android/app/spotlight/SpotlightTarget.kt#L14). The spotlight target is a holder for the necessary information to show a spotlight.

The spotlight target binds these fields together:
anchor: The view that should be spotlit.
seanlip marked this conversation as resolved.
Show resolved Hide resolved
hint: The helpful text that should appear along the spotlight to describe the element being spotlit.
shape: The preferred shape of the spotlight highlight. Can be one of a circle or rounded rectangle, based on whichever shape best fits the area being highlighted
seanlip marked this conversation as resolved.
Show resolved Hide resolved
feature: The specific app feature that the spotlight is tied to. It’s used to track whether this specific spotlight has been seen.

In order to start spotlighting an element in the UI, three high-level things need to be done:
The feature’s spotlight needs to be defined.
seanlip marked this conversation as resolved.
Show resolved Hide resolved
The new spotlight needs to be hooked up for persistent storage.
The spotlight needs to be hooked up to be shown in the UI.

## Registering a new feature

In the file [spotlight.proto](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/model/src/main/proto/spotlight.proto#L1), two things need to be added.

A new feature (in the [Spotlight](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/model/src/main/proto/spotlight.proto#L10) proto):
```proto
message Spotlight {
// Determines the UI element being spotlit.
oneof feature {
// Corresponds to the onboarding screen's next button.
SpotlightViewState onboarding_next_button = 1;

// Corresponds to the topic fragment's lessons tab.
SpotlightViewState topic_lesson_tab = 2;

// Corresponds to the topic fragment's revision tab.
SpotlightViewState topic_revision_tab = 3;

// Add and describe your new spotlit feature here.
SpotlightViewState your_feature_name = <next_available_index>;
}
```

And somewhere to store it (in [SpotlightStateDatabase](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/model/src/main/proto/spotlight.proto#L53)):
```proto
message SpotlightStateDatabase {
// Corresponds to the onboarding screen's next button.
SpotlightViewState onboarding_next_button = 1;

// Corresponds to the topic fragment's lessons tab.
SpotlightViewState topic_lesson_tab = 2;

// Corresponds to the topic fragment's revision tab.
SpotlightViewState topic_revision_tab = 3;

// Similarly, add storage for your new feature here.
SpotlightViewState your_feature_name = <next_available_index>;
}
```

The new spotlight feature also needs to be added to the [SpotlightStateController](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/domain/src/main/java/org/oppia/android/domain/spotlight/SpotlightStateController.kt#L3). In the [retrieveSpotlightViewState](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/domain/src/main/java/org/oppia/android/domain/spotlight/SpotlightStateController.kt#L80) and the [recordSpotlightStateAsync](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/domain/src/main/java/org/oppia/android/domain/spotlight/SpotlightStateController.kt#L110) method, add the feature to the switch case as so:
seanlip marked this conversation as resolved.
Show resolved Hide resolved
```kotlin
fun retrieveSpotlightViewState(
profileId: ProfileId,
feature: Spotlight.FeatureCase,
): DataProvider<SpotlightViewState> {
return retrieveCacheStore(profileId)
.transformAsync(
RETRIEVE_SPOTLIGHT_CHECKPOINT_DATA_PROVIDER_ID
) {
val viewState = when (feature) {
ONBOARDING_NEXT_BUTTON -> it.onboardingNextButton
TOPIC_LESSON_TAB -> it.topicLessonTab
TOPIC_REVISION_TAB -> it.topicRevisionTab
YOUR_FEATURE_NAME -> it.yourFeatureName
```

Similarly for the [recordSpotlightStateAsync](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/domain/src/main/java/org/oppia/android/domain/spotlight/SpotlightStateController.kt#L110) method.

## Hooking up the spotlight
In order to request a spotlight in the UI, use [SpotlightManager](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/app/src/main/java/org/oppia/android/app/spotlight/SpotlightManager.kt#L4):

```kotlin
checkNotNull(getSpotlightManager()).requestSpotlight(
SpotlightTarget(
seanlip marked this conversation as resolved.
Show resolved Hide resolved
binding.yourFeatureName,
R.string.your_feature_string_string_resource,
SpotlightShape.RoundedRectangle,
Spotlight.FeatureCase.YOUR_FEATURE_NAME
)
seanlip marked this conversation as resolved.
Show resolved Hide resolved
)

private fun getSpotlightManager(): SpotlightManager? {
seanlip marked this conversation as resolved.
Show resolved Hide resolved
return fragment.requireActivity().supportFragmentManager.findFragmentByTag(
SpotlightManager.SPOTLIGHT_FRAGMENT_TAG
) as? SpotlightManager
}
```

For views that are laid out late in the lifecycle (such as recycler views loaded after a data provider call, view pagers, or elements that show up after an enter animation), use [requestSpotlightWithDelayedLayout](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/app/src/main/java/org/oppia/android/app/spotlight/SpotlightManager.kt#L13) instead.

# Testing spotlights
Spotlights are tested by checking if the expected hint is shown on the screen or not.

```kotlin
@Test
fun testPromotedStorySpotlight_setToShowOnSecondLogin_notSeenBefore_checkSpotlightShown() {
logIntoUserTwice()
launch<HomeActivity>(createHomeActivityIntent(internalProfileId1)).use {
testCoroutineDispatchers.runCurrent()
onView(withText(R.string.promoted_story_spotlight_hint))
.check(matches(isDisplayed()))
// Or, use check(doesNotExist()) to verify it is not being shown.
}
}
```

In order to bypass a spotlight without any UI interaction, the ``SpotlightStateController`` should be used to mark the spotlights as seen. A helper function can be introduced and used to mark one or more spotlights as seen.

```kotlin
private fun markAllSpotlightsSeen() {
val profileId = ProfileId.newBuilder().setInternalId(internalProfileId).build()
spotlightStateController.markSpotlightViewed(profileId, TOPIC_LESSON_TAB)
spotlightStateController.markSpotlightViewed(profileId, TOPIC_REVISION_TAB)
spotlightStateController.markSpotlightViewed(profileId, YOUR_FEATURE_NAME)
testCoroutineDispatchers.runCurrent()
}
```

## Disabling the spotlights
If the spotlights need to be disabled, the platform parameter value should be set.
seanlip marked this conversation as resolved.
Show resolved Hide resolved
If the spotlights need to be disabled in the tests, use the ``TestPlatformParameterModule`` to turn off the [enableSpotlightUi](https://github.com/oppia/oppia-android/blob/d2c37dc547f3e5d12dfe62fa97b9b16fbf0fed6e/utility/src/main/java/org/oppia/android/util/platformparameter/PlatformParameterConstants.kt#L218) platform parameter.
seanlip marked this conversation as resolved.
Show resolved Hide resolved

```kotlin
TestPlatformParameterModule.forceEnableSpotlightUi(false)
```

In order to do it in production, turn the value of ``ENABLE_SPOTLIGHT_UI_DEFAULT_VALUE`` to ``false``.