⌘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(defaultValue = "false")
    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 = "",
    val defaultValue: String = ""
)
Parameters
  • description: A brief description of the data binding.
  • deprecated: Indicates if the data binding is deprecated.
  • deprecatedReason: Reason for deprecation, if applicable.
  • defaultValue: The default value for the data binding, if applicable.

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 = "",
    val defaultValue: String = ""
)
Parameters
  • description: A brief description of the property.
  • valuePicker: Specifies the type of value picker to use for this property.
  • valuePickerGroup: Defines the grouping of the value picker for UI purposes.
  • valuePickerOptions: Array of selectable options, if applicable.
  • deprecated: Indicates if the property is deprecated.
  • deprecatedReason: Reason for deprecation, if applicable.
  • defaultValue: The default value for the property, if applicable.

Example

@NativeActionProp(
    description = "Enable animation",
    valuePicker = NativeActionValuePicker.DROPDOWN,
    defaultValue = "true"
)
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
}