⌘K

Action Annotations

This document provides an overview of the annotations available in the Nativeblocks Compiler for defining and managing actions in Android. These annotations simplify the creation of structured, reusable actions in Kotlin.

Annotations Overview

1. @NativeAction

Description

Defines a reusable action with metadata and associates it with a specific key and description.

Declaration

@Target(AnnotationTarget.CLASS)
annotation class NativeAction(
    val name: String,
    val keyType: String,
    val description: String,
    val version: Int = 1,
    val deprecated: Boolean = false,
    val deprecatedReason: String = ""
)
Parameters
  • name: A String representing the display name of the action.
  • keyType: A String defining a unique key type identifier for the action.
  • description: A String providing a detailed explanation of the action's purpose.
  • version: An optional Int (default: 1) specifying the version of the action.
  • deprecated: A Boolean (default: false) indicating whether the action is deprecated.
  • deprecatedReason: An optional String explaining the reason for deprecation if applicable.

Example

@NativeAction(
    name = "Show Alert",
    keyType = "ALERT",
    description = "Shows an alert dialog"
)
class ShowAlert{
    @NativeActionParameter
    data class Param(
        @NativeActionData val message: String,
        @NativeActionProp val animated: Boolean,
        @NativeActionEvent(then = Then.SUCCESS) val completion: () -> Unit,
    )
    @NativeActionFunction
    suspend operator fun invoke(param: Param) {
        // implement logic here
        param.completion()
    }
}

2. @NativeActionParameter

Description

Defines a data class to encapsulate the input parameters for an action function. The data class includes all the parameters required by the action.

Declaration

@Target(AnnotationTarget.CLASS)
annotation class NativeActionParameter

Example

@NativeActionParameter
data class Parameter(
    @NativeActionData
    val message: String,
    @NativeActionProp
    val animated: Boolean = false,
    @NativeActionEvent(then = Then.SUCCESS)
    val onComplete: () -> Unit
)

3. @NativeActionFunction

Description

Marks a function within an action class as the main logic handler. The function must take a single parameter annotated with @NativeActionParameter.

Declaration

@Target(AnnotationTarget.FUNCTION)
annotation class NativeActionFunction

Example

@NativeActionFunction
fun execute(param: Parameter) {
    println("Executing action with message: ${param.message}")
    param.onComplete()
}

4. @NativeActionData

Description

Marks a property as a data-binding parameter for the action, typically linked to runtime data.

Declaration

@Target(AnnotationTarget.VALUE_PARAMETER)
annotation class NativeActionData(
    val description: String = "",
    val deprecated: Boolean = false,
    val deprecatedReason: String = ""
)

Example

@NativeActionData(description = "The content of the alert")
val content: String

5. @NativeActionProp

Description

Defines a configurable property for the action, such as settings or options. These properties can be visually configured in Nativeblocks Studio.

Declaration

@Target(AnnotationTarget.VALUE_PARAMETER)
annotation class NativeActionProp(
    val description: String = "",
    val valuePicker: NativeActionValuePicker = NativeActionValuePicker.TEXT_INPUT,
    val valuePickerGroup: NativeActionValuePickerPosition = NativeActionValuePickerPosition("General"),
    val valuePickerOptions: Array<NativeActionValuePickerOption> = [],
    val deprecated: Boolean = false,
    val deprecatedReason: String = ""
)
Parameters
  • description: A String providing details about the property.
  • valuePicker: A NativeActionValuePicker specifying the input type for the property (e.g., TEXT_INPUT, DROPDOWN).
  • valuePickerGroup: A NativeActionValuePickerPosition defining the section or category for the property (default: "General").
  • valuePickerOptions: An array of NativeActionValuePickerOption defining dropdown or combobox options.
  • deprecated: A Boolean (default: false) indicating whether the property is deprecated.
  • deprecatedReason: An optional String giving the reason for deprecation.

Example

@NativeActionProp(description = "Enable animation", valuePicker = NativeActionValuePicker.DROPDOWN)
val animated: Boolean = true

6. @NativeActionEvent

Description

Defines an event for an action, such as a completion handler or callback.

Declaration

@Target(AnnotationTarget.VALUE_PARAMETER)
annotation class NativeActionEvent(
    val description: String = "",
    val dataBinding: Array<String> = [],
    val then: Then = Then.END,
    val deprecated: Boolean = false,
    val deprecatedReason: String = ""
)
Parameters
  • description: A String providing details about the event.
  • dataBinding: An array of String specifying the data bindings for the event.
  • then: A Then enum value indicating the next step after the event (e.g., SUCCESS, FAILURE).
  • deprecated: A Boolean (default: false) indicating whether the event is deprecated.
  • deprecatedReason: An optional String giving the reason for deprecation.

Example

@NativeActionEvent(description = "Called when the action is complete", then = Then.SUCCESS)
val onComplete: () -> Unit

Supporting Types

NativeActionValuePicker

Defines input methods for action properties.

enum class NativeActionValuePicker {
    TEXT_INPUT,
    NUMBER_INPUT,
    DROPDOWN
}

NativeActionValuePickerOption

Provides options for value pickers like dropdowns.

data class NativeActionValuePickerOption(
    val id: String,
    val text: String
)

NativeActionValuePickerPosition

Groups properties into sections.

data class NativeActionValuePickerPosition(
    val text: String
)

Then

Specifies the possible outcomes for an event.

enum class Then {
    SUCCESS,
    FAILURE,
    NEXT,
    END
}