Skip to content

Advance Usage ‐ Behavior System Guide

Jump to bottom
yibie edited this page Jan 17, 2025 · 2 revisions

Behavior System Guide

What is the Behavior System?

The Behavior System is one of the core features of org-supertag that enables tags to automatically execute predefined actions. In simple terms:

  • It’s a “tag-driven” automation system
  • When you add specific tags, the system automatically executes corresponding behaviors
  • These behaviors can be single operations or combinations of multiple operations

Two Ways to Define Behaviors

  1. Direct behavior definition using Lambda functions in :action 
(org-supertag-behavior-register "@overdue-archive"
  :trigger :on-schedule
  :schedule "0 0 * * 0"  
  :action (lambda (node-id)
            (org-supertag-behavior--check-deadline node-id
              '(scope subtree
                days 0
                action (lambda (heading deadline)
                        (when (member (org-get-todo-state) 
                                    org-done-keywords)
                          (org-archive-subtree-default)))))))

Lambda function use cases:

  • Complex conditional logic
  • Multiple Emacs/Org API calls
  • One-time special logic
  • Need to capture external variables in closures
  1. Template-based behavior definition (covered in detail below)

Types of Behaviors

1. Basic Behaviors Layer

  • Serves as parameter definition layer, not recommended for direct use
  • Defines parameter types and structures accepted by behaviors
  • Provides parameter specifications for higher-level behaviors
;; @todo behavior defines that it accepts a 'state' parameter
(org-supertag-behavior-register "@todo"
  :trigger :on-add
  :action #'org-supertag-behavior--set-todo
  :params '(state))                    ; Parameter definition

;; @property behavior defines that it accepts 'name' and 'value' parameters
(org-supertag-behavior-register "@property"
  :trigger :on-add
  :action #'org-supertag-behavior--set-property
  :params '(name value))               ; Parameter definition

2. Shortcut Behaviors Layer

  • Built on basic behavior parameter definitions
  • Preset specific parameter combinations
  • Designed for daily use cases
;; Using @todo behavior's parameter definition, preset DONE state
(org-supertag-behavior-register "@done"
  :trigger :on-add
  :list '("@todo=DONE"))

;; Using @priority behavior's parameter definition, preset priority A
(org-supertag-behavior-register "@urgent"
  :trigger :on-add
  :list '("@priority=A"))

3. Workflow Behaviors Layer

  • Combines multiple shortcut behaviors
  • Creates complete workflows
  • Implements complex business scenarios
;; Meeting workflow: combining multiple preset behaviors
(org-supertag-behavior-register "@meeting"
  :trigger :on-add
  :list '("@todo=TODO"               ; Using @todo parameter definition
          "@property=TYPE,meeting"   ; Using @property parameter definition
          "@clock"))                 ; Using @clock parameter definition

Basic Usage

1. Parameter Definition

Use `@behavior=parameter` format:

* A Task
  @todo=DONE          ; Set task state to DONE
  @priority=A         ; Set priority to A
  @timestamp=now      ; Add current timestamp

2. Parameter Passing Rules

  1. Single Parameter Format @todo=DONE ; One parameter
  2. Multiple Parameter Format @property=TYPE,meeting ; Two parameters, comma-separated
  3. No Parameter Format @clock ; Direct use, no equals sign needed

3. Common Use Cases

  1. Task Management
* Project Meeting
  @meeting             ; Automatically adds meeting-related properties and states
  Meeting content...
  1. Time Tracking
* Coding Task
  @start              ; Start task and record time
  Code implementation...
  @done              ; Complete task and record time spent
  1. Archiving Operations
* Completed Task
  @archive           ; Automatically complete archiving process

Behavior Configuration Guide

Configuration File Location

Behavior definitions are stored in `~/.emacs.d/org-supertag/org-supertag-custom-behavior.el`

Basic Behavior Configuration

(org-supertag-behavior-register "@todo"
  :trigger :on-add                                  ; Trigger condition
  :action #'org-supertag-behavior--set-todo         ; Execution function
  :params '(state)                                  ; Parameter definition
  :style '(:face (:foreground "blue" :weight bold)  ; Display style
          :prefix "☐"))                             ; Prefix icon

Trigger Types

The system supports multiple trigger types:

  1. Event Triggers
    • :on-add - Triggered when tag is added
    • :on-remove - Triggered when tag is removed
    • :on-change - Triggered when content changes
    • :on-schedule - Triggered on schedule
    • :always - Responds to all events
  2. Scheduled Triggers
(org-supertag-behavior-register "@daily-check"
  :trigger :on-schedule
  :schedule "0 9 * * *"    ; Every day at 9:00 AM
  :action #'check-function)

Workflow Behavior Configuration

Workflow behaviors combine multiple behaviors using the :list keyword:

(org-supertag-behavior-register "@meeting"
  :trigger :on-add
  :list '("@todo=TODO"               ; Set TODO state
          "@property=TYPE,meeting"   ; Set meeting property
          "@clock")                  ; Start time tracking
  :style '(:face (:foreground "purple" :weight bold)
          :prefix "📅"))

Schedule Trigger Usage

  1. Time Format Support:

    A. Cron-style Format:

    • Format: “minute hour date month weekday”
    • Examples:
      • "0 9 * * 1-5" - 9:00 AM on weekdays
      • "30 * * * *" - The 30th minute of every hour
      • "*/5 * * * *" - Every 5 minutes
    • Components:
      • Minute: 0-59
      • Hour: 0-23
      • Date: 1-31
      • Month: 1-12
      • Weekday: 0-6 (0 represents Sunday)
    • Special Characters:
      • * - Any value
      • - - Range (e.g., 1-5)
      • , - List (e.g., 1,3,5)

    B. Org Timestamp Integration:

    • Native SCHEDULED/DEADLINE support:
      • "scheduled" - Use node’s SCHEDULED timestamp
      • "deadline" - Use node’s DEADLINE timestamp
    • Absolute timestamps:
      • Format: "<YYYY-MM-DD HH:MM>" or "[YYYY-MM-DD HH:MM]"
      • Example: "<2024-03-20 Wed 14:30>"
    • Relative time expressions:
      • Format: "now±Nh/d/w/m/y"
      • Examples:
        • "now+2h" - 2 hours from now
        • "now-1d" - 1 day ago
        • "now+1w" - 1 week from now
    • Property-based timing:
      • Format: "${prop:PROPERTY}±Nh/d/w/m/y"
      • Example: "${prop:DEADLINE}-2h" - 2 hours before DEADLINE
  2. Use Cases:
    • Regular deadline checks
    • Automated status updates
    • Scheduled task execution
    • Periodic reminders
    • Time-based notifications
    • Deadline-driven actions
  3. Behavior Definition Examples: 
    ;; Using cron format
(org-supertag-behavior-register "@daily-check"
  :trigger :schedule
  :schedule "0 9 * * *"    ; 9:00 AM every day
  :action #'some-function)

;; Using org timestamp
(org-supertag-behavior-register "@meeting-reminder"
  :trigger :schedule
  :schedule "scheduled"     ; Use node's SCHEDULED timestamp
  :list '("@notify=Meeting starting soon"
          "@todo=NEXT"))

;; Using deadline-based timing
(org-supertag-behavior-register "@deadline-alert"
  :trigger :schedule
  :schedule "${prop:DEADLINE}-2h"  ; 2 hours before deadline
  :list '("@notify=Deadline approaching"
          "@priority=A"))

;; Using relative time
(org-supertag-behavior-register "@followup"
  :trigger :schedule
  :schedule "now+3d"        ; 3 days from now
  :list '("@todo=NEXT"
          "@notify=Follow-up needed"))

Template Variable System

Example

Here’s a complete review process definition showcasing various uses of the template variable system:

(org-supertag-behavior-register "@review"
  :trigger :on-add
  :list '(
    ;; Get user input
    "@property=REVIEWER=${input:Specify reviewer}"
    ;; Set time using date calculation
    "@property=DUE=${date:now+3d}"
    ;; Use conditional logic
    "@todo=REVIEW{if:REVIEWER}"
    ;; Use property values and context data
    "@notify=${prop:REVIEWER}"))

This example demonstrates:

  1. Using ${input:} for user input
  2. Using ${date:} for deadline calculation
  3. Using {if:} for conditional logic
  4. Using ${prop:} to read property values

Overview

The template variable system makes behavior definitions more flexible and dynamic. It addresses:

  1. User interaction for input
  2. Dynamic time calculations
  3. Reading existing property values
  4. Data sharing in workflow behaviors
  5. Conditional behavior execution

Variable Types

  1. User Input (${input:prompt})
    • Purpose: Get user input during behavior execution
    @property=REVIEWER=${input:Please specify reviewer}
  2. Date Operations (${date:format})
    • Purpose: Handle dates and times, supports current and relative time calculations
    @property=DUE=${date:now+7d}     ; 7 days later
  3. Property Access (${prop:property-name})
    • Purpose: Read existing node property values
    @notify=${prop:REVIEWER}         ; Use existing REVIEWER value
  4. Context Data (${context:key})
    • Purpose: Share data between steps in behavior chains
    @property=INPUT=${input:input}    ; Save input
@notify=${context:INPUT}         ; Use saved input

Conditional Execution

Use {if:condition} to control behavior execution:

@todo=DONE{if:PRIORITY=A}          ; Execute only if priority is A
@notify{if:DEADLINE<${date:now}}   ; Execute only if deadline has passed

Behavior Design Principles

  1. Behavior Creation Guidelines
    • Start new primitive operations with basic behaviors
    • Create shortcut behaviors for common parameter combinations
    • Use workflow behaviors for complex processes
  2. Behavior Properties
    • Each behavior should have a clear, single responsibility
    • Parameters should be meaningful and well-documented
    • Visual styling should indicate behavior type
    • Hooks and triggers should be appropriate for use case
  3. Development Flow
    • First develop and test basic behaviors
    • Then create common shortcut behaviors
    • Finally compose workflow behaviors
Clone this wiki locally