Skip to main content
This guide covers the event callbacks available in Joyfill forms and when they’re triggered.

​
Available Events

EventWhen TriggeredPurpose
onChangeField value changesTrack form changes
onFocusField gains focus, or page gains focusHandle field or page focus
onBlurField loses focus, or page loses focusHandle field or page blur
onUploadFile upload requestedHandle file uploads
onCaptureBarcode scan requestedHandle barcode scanning

​
onChange Event

Triggered when any field value changes in the form. Parameters:
  • changes: [Change] - Array of change objects describing what was modified
  • document: JoyDoc - The fully updated document with all changes applied
func onChange(changes: [Change], document: JoyDoc) {        
     if let firstChange = changes.first {
           print(">>>>>>>>onChange", firstChange.change ?? "")
     }
     // The document parameter contains the fully updated form
}

​
onFocus Event

Triggered when a field receives focus, or when a page becomes the current page (page focus). Parameters:
  • event: Event — Either a field focus or a page focus. Use event.fieldEvent for field focus, or event.pageEvent for page focus.
Event properties:
  • event.fieldEvent — Set for field focus; contains FieldIdentifier (e.g. fieldID, pageID, fieldPositionId).
  • event.pageEvent — Set for page focus; contains PageEvent with type: "page.focus" and page: Page.
func onFocus(event: Joyfill.Event) {
    if let field = event.fieldEvent {
        print("Field focused: \(field.fieldID)")
    } else if let pageEvent = event.pageEvent {
        print("Page focused: \(pageEvent.page.id ?? "")")
    }
}

​
onBlur Event

Triggered when a field loses focus, or when the user leaves a page (page blur). Parameters:
  • event: Event — Either a field blur or a page blur. Use event.fieldEvent for field blur, or event.pageEvent for page blur.
Event properties:
  • event.fieldEvent — Set for field blur.
  • event.pageEvent — Set for page blur; contains PageEvent with type: "page.blur" and page: Page.
func onBlur(event: Joyfill.Event) {
    if let field = event.fieldEvent {
        print("Field blurred: \(field.fieldID)")
    } else if let pageEvent = event.pageEvent {
        print("Page blurred: \(pageEvent.page.id ?? "")")
    }
}

​
onUpload Event

Triggered when a file upload is requested for image or file fields. Parameters:
  • event: UploadEvent - Upload event details
Properties Available:
  • fieldEvent: FieldIdentifier - The field requesting upload
  • multi: Bool - Whether multiple files are allowed
  • uploadHandler: ([String]) -> Void - Callback to provide file URLs
func onUpload(event: UploadEvent) {
        print("📤 Upload requested for field: \(event.fieldEvent.fieldID)")
        
        // Option 1: Present a photo picker for the user to choose an image.
        // Option 2: Directly send pre-uploaded image identifiers or URLs to the upload handler.
        
        let exampleImageURL = "https://example.com/uploads/sample-image.jpg"
        
        // Example: sending a direct image URL or an identifier for the upload
        event.uploadHandler([exampleImageURL])
    }

​
onCapture Event

Triggered when camera capture is requested for Barcode cell. Parameters:
  • event: CaptureEvent - Capture event details
Properties Available:
  • fieldEvent: FieldIdentifier - The field requesting capture
  • captureHandler: (ValueUnion) -> Void - Callback to provide captured content
    func onCapture(event: Joyfill.CaptureEvent) {
        print("📷 Capture requested for field: \(event.fieldEvent.fieldID)")
        print("User can open a barcode scanner to capture the code.")
        event.captureHandler(.string("Scan Button Clicked"))
    }

​
onError Event

  • Used to listen to errors during document processing.
  • error: JoyfillError — details about the failure.
  • Error types include:
    • schemaValidationError — Document schema validation failures
    • schemaVersionError — SDK and document version compatibility issues
func onError(error: Joyfill.JoyfillError) {
        switch error {
        case .schemaValidationError(let schemaError):
            print("❌ Schema Error: \(schemaError)")
        case .schemaVersionError(let versionError):
            print("❌ Schema Error: \(versionError)")
        }
        print("Error occurred: \(error)")
    }