Form

Dynamic form loading and submission with the Proview SDK

What is Form module

The Form module is part of the Proview SDK, exposed as Proview.form. It provides a complete solution for loading, rendering, and managing dynamic forms with integrated authentication.

Once initialized, it lets your application:

• Load forms — render forms dynamically by form ID.
• Submit forms — handle form submission and validation automatically.
• Mount UI — display forms in sidepanel, popup, or inline layout modes.
• React to events — subscribe to ready, submitted, and error events.

---

Quickstart

1. Load the SDK

Ensure the Proview SDK script is loaded (see Getting Started).

<script
  src="https://sdk.tlv.cx"
  async
  crossorigin="anonymous"
></script>

2. Initialize credential

The SDK supports Firebase as a credentialing provider for authentication.

const firebaseCredential = Proview.auth.FirebaseAuthStrategy({
  token: 'your-firebase-auth-token',
});

3. Initialize form module

Initialize the form module with the Firebase credential.

const form = Proview.form.init({
  dsn: 'project-dsn',
  projectId: 'project-123',
  credential: firebaseCredential,
});

4. Access user object

Once initialized, the user object becomes available globally at Proview.user and is Firebase-compatible with getIdToken() method.

const user = Proview.user;
console.log(user.uid, user.email, user.displayName);

// Get ID token when needed
const idToken = await user.getIdToken();

5. Mount UI

Mount the form UI into a container element.

const mounted = form.mount({
  formId: 'form-123',
  containerId: 'form-container',
  mountMode: {
    mode: 'sidepanel', // or 'popup' or 'inline'
  },
});

6. Open form

Open the form to load data and display the UI.

const formInstance = await form.open();

7. Subscribe to events

Listen to form lifecycle events.

formInstance
  .on('ready', () => {
    console.log('Form is ready for user input');
  })
  .on('submitted', () => {
    console.log('Form submitted successfully');
  })
  .on('error', ({ message }) => {
    console.error('Form error:', message);
  });

8. Teardown

When done, unmount the UI.

mounted.unmount();

---

API Reference

Proview.form.init(options)

Creates a form module instance with integrated authentication.

Input

type FormInitOptions = {
  dsn: string;               // Required: Project DSN
  projectId: string;         // Required: Project ID
  credential: Credential;    // Required: Authentication credential (e.g., FirebaseAuthStrategy)
};

Returns — FormModule

type FormModule = {
  mount(options: MountOptions): MountedFormUi;
  open(): Promise<FormInstance>;
};

The authenticated user is available globally at Proview.user after initialization.

---

form.mount(options)

Mounts the form UI into a container element.

Input	MountOptions
Returns	MountedFormUi

MountOptions

type MountOptions = {
  formId: string;                // Required: Form ID to load
  containerId: string;           // Required: DOM element ID
  mountMode: {
    mode: 'sidepanel' | 'popup' | 'inline';  // Required: Layout mode
  };
};

MountedFormUi

type MountedFormUi = {
  unmount(): void;  // Removes UI from DOM
};

Example:

const firebaseCredential = Proview.auth.FirebaseAuthStrategy({
  token: 'your-firebase-auth-token',
});

const form = Proview.form.init({
  dsn: 'project-dsn',
  projectId: 'project-123',
  credential: firebaseCredential,
});

const mounted = form.mount({
  formId: 'form-123',
  containerId: 'form-container',
  mountMode: {
    mode: 'popup',
  },
});

// Later, when done
mounted.unmount();

---

form.open()

Loads form data and displays the form UI. Uses the formId specified in mount().

Input	None
Promise	Promise<FormInstance>
Async	Yes, requires await

FormInstance

type FormInstance = {
  on(event: FormEventName, handler: (payload?: any) => void): FormInstance;
  submit(): Promise<void>;
};

Example:

const form = Proview.form.init({
  dsn: 'project-dsn',
  projectId: 'project-123',
  credential: firebaseCredential,
});

form.mount({
  formId: 'form-123',
  containerId: 'form-container',
  mountMode: { mode: 'sidepanel' },
});

const formInstance = await form.open();

formInstance
  .on('ready', () => console.log('Form ready'))
  .on('submitted', () => {
    console.log('Form submitted');
    // Handle success
  })
  .on('error', ({ message }) => {
    console.error('Form error:', message);
  });

---

User Object

After initializing the form module, Proview.user provides a Firebase-compatible user object accessible globally.

User Interface

type User = {
  uid: string;                      // User's unique ID
  email: string | null;             // User's email address
  displayName: string | null;       // User's display name
  emailVerified: boolean;           // Email verification status
  isAnonymous?: boolean;            // Is anonymous user
  metadata?: UserMetadata;          // Creation and last sign-in time
  providerData?: ProviderData[];    // Provider-specific info

  // Methods
  getIdToken(forceRefresh?: boolean): Promise<string>;
  getIdTokenResult(forceRefresh?: boolean): Promise<IdTokenResult>;
};

Example:

const firebaseCredential = Proview.auth.FirebaseAuthStrategy({
  token: 'your-firebase-auth-token',
});

const form = Proview.form.init({
  dsn: 'project-dsn',
  projectId: 'project-123',
  credential: firebaseCredential,
});

// Access user properties globally
const user = Proview.user;
console.log(user.uid);
console.log(user.email);
console.log(user.displayName);
console.log(user.emailVerified);

// Get ID token
const idToken = await user.getIdToken();

// Force refresh token
const freshToken = await user.getIdToken(true);

---

Firebase Authentication

Proview.auth.FirebaseAuthStrategy(config)

Creates a Firebase authentication credential for use with the Proview SDK modules.

Input

type FirebaseAuthStrategyConfig = {
  token: string;  // Required: Firebase authentication token
};

Returns — FirebaseAuthStrategy

A credential object that can be passed to any Proview SDK module initialization.

Example:

// Initialize Firebase credential with token
const firebaseCredential = Proview.auth.FirebaseAuthStrategy({
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
});

// Use with form module
const form = Proview.form.init({
  dsn: 'project-dsn',
  projectId: 'project-123',
  credential: firebaseCredential,
});

---

Form Events

The FormInstance emits events that you can subscribe to using the on() method.

Event names and payloads

Event	Payload	Description
ready	void	Form loaded and ready
submitted	void	Form submitted successfully
error	{ message: string }	Error occurred

Example:

form
  .on('ready', () => {
    // Form is ready for input
  })
  .on('submitted', () => {
    // Form was submitted successfully
  })
  .on('error', ({ message }) => {
    // Handle form error
    alert(`Error: ${message}`);
  });

---

Mount Modes

The form module supports three layout modes for the form UI.

Mode	Value	Behavior
Sidepanel	'sidepanel'	Slides in from side of viewport
Popup	'popup'	Centered modal overlay
Inline	'inline'	Embedded in the page flow

Example:

// Sidepanel mode
const mounted1 = form.mount({
  formId: 'form-123',
  containerId: 'form-container',
  mountMode: {
    mode: 'sidepanel',
  },
});

// Popup mode
const mounted2 = form.mount({
  formId: 'form-123',
  containerId: 'form-container',
  mountMode: {
    mode: 'popup',
  },
});

// Inline mode
const mounted3 = form.mount({
  formId: 'form-123',
  containerId: 'form-container',
  mountMode: {
    mode: 'inline',
  },
});

---

Error Handling

Form errors follow a consistent structure.

Error Structure

type FormError = {
  code: string;    // Error code for programmatic handling
  message: string; // Human-readable error message
};

Common Error Codes

Code	Description
FORM_LOAD_ERROR	Failed to load form
PANEL_ERROR	Panel rendering error
TOKEN_INVALID	Authentication token is invalid
TOKEN_EXPIRED	Session token expired
AUTH_FAILED	Authentication failed
FETCH_FAILED	Network or API request failed

Example:

try {
  const firebaseCredential = Proview.auth.FirebaseAuthStrategy({
    token: 'your-firebase-auth-token',
  });

  const form = Proview.form.init({
    dsn: 'project-dsn',
    projectId: 'project-123',
    credential: firebaseCredential,
  });

  const mounted = form.mount({
    formId: 'form-123',
    containerId: 'form-container',
    mountMode: {
      mode: 'popup',
    },
  });

  const formInstance = await form.open();

  formInstance.on('error', ({ message }) => {
    console.error('Form error:', message);
    // Handle error in UI
  });

} catch (error) {
  switch (error.code) {
    case 'AUTH_FAILED':
      alert('Authentication failed. Please log in again.');
      break;

    case 'TOKEN_INVALID':
      alert('Invalid authentication token.');
      break;

    case 'TOKEN_EXPIRED':
      alert('Session expired. Please log in again.');
      break;

    case 'FORM_LOAD_ERROR':
      alert('Failed to load form. Please try again.');
      break;

    case 'PANEL_ERROR':
      alert('Failed to render form panel. Check your page setup.');
      break;

    case 'FETCH_FAILED':
      alert('Network error. Please check your connection.');
      break;

    default:
      alert(`Error: ${error.message}`);
      break;
  }
}