Configuration

This page lists the configuration points reviewers should inspect when checking a docx_editor integration.

Syncfusion Editor Configuration

const config = DocxSyncfusionConfig(
  licenseKey: syncfusionLicenseKey,
  trustedOrigin: 'https://app.example.com',
  toolbarMode: DocxToolbarMode.ribbon,
);

Field	Required	Purpose
licenseKey	Yes	Syncfusion EJ2 license key.
serviceUrl	No	Optional Syncfusion service endpoint for service-backed editor features. Normal conversion is pure Dart.
cdnVersion	No	Syncfusion EJ2 CDN version. Defaults to the package-pinned version.
trustedOrigin	Recommended	Origin used by the editor iframe when posting messages back to the Flutter app.
toolbarMode	No	ribbon for Word-style tabs or toolbar for a compact action toolbar.

Widget Configuration

SyncfusionDocxEditor(
  document: pickedDocument,
  syncfusionConfig: config,
  controller: controller,
  conversionService: const VyuhDocxConversionService(),
  showToolbar: true,
  onReady: () {},
  onContentChanged: () {},
);

Field	Purpose
document	Host-resolved source, capabilities, lifecycle, lock, and metadata for the session.
syncfusionConfig	Syncfusion license, iframe origin, CDN, and toolbar mode.
controller	Optional but expected in regulated flows. Enforces save/export/sign/print policy.
conversionService	Optional override. Defaults to the pure-Dart vyuh_docx bridge where used.
height	Optional editor height.
showToolbar	Shows or hides editor actions. Hiding the toolbar does not grant or remove capabilities.
toolbarItems	Optional toolbar item filter for toolbar mode.
onReady	Called when the editor is ready.
onContentChanged	Called when the editor marks content changed.

Document Source Configuration

Openable source data lives in DocxSource. Business context lives in DocxPickedDocument.

Factory	Use case
DocxSource.docxBase64	The host already has base64 DOCX content.
DocxSource.docxBytes	The host has raw DOCX bytes.
DocxSource.sfdtString	The host has SFDT JSON text.
DocxSource.sfdtJson	The host has decoded SFDT.
DocxSource.blankDocument	Start a new editable blank document.
DocxSource.storageReference	The editor must ask host storage to resolve the document.

Picked document factory	Use case
DocxPickedDocument.localBytes	Local file pick, validated as .docx.
DocxPickedDocument.networkBytes	Network-loaded file with URL metadata.
DocxPickedDocument.serverDocument	Host document record with source id, optional version id, capabilities, lock, hash, and metadata.

Use expectedSha256 and verifyIntegrity() when opening controlled bytes from a known host version.

Controller Configuration

final controller = DocxController(
  capabilities: DocxCapabilities.fromGrants(
    const {DocumentGrant.read, DocumentGrant.review, DocumentGrant.edit},
    singleEditorLockRequired: true,
  ),
  storageAdapter: storage,
  trustedClock: trustedClock,
  actor: actor,
  lifecycleState: lifecycleState,
  requireResolvedCommentsForSign: true,
  signingVocabulary: signingVocabulary,
  onAuditEvent: audit.write,
);

Field	Purpose
capabilities	Action gates for the current actor and document.
storageAdapter	Host implementation for open, save draft, create version, and download URL.
trustedClock	Server-authoritative UTC time for audit and signatures.
onAuditEvent	Durable audit sink callback.
actor	Authenticated user. Used for audit attribution and Syncfusion comment/revision authorship.
lifecycleState	Optional document lifecycle guard. Released states cannot use editable presets.
requireResolvedCommentsForSign	Blocks signing while open review threads remain.
signingVocabulary	Allowed signature meanings for the document type.

Lifecycle Configuration

Use DocxLifecycleBinding.resolve before opening controlled documents.

Lifecycle state	Default posture
draft	Editable by default.
inReview	Revision review by default.
approved	View only.
effective	View only.
superseded	View only.

The controller also has a package-level guard: if a released state is paired with editable capabilities, it throws instead of letting the document open editable.

Capability Configuration

Named presets are available for common roles:

Preset	Use case
DocxCapabilities.fromGrants(grants)	Preferred host-facing API. Expands read, review, and edit document grants into editor action gates.
DocxCapabilities.viewOnly()	Open and search/read a document.
DocxCapabilities.commentOnly()	Add comments and view review state without editing source.
DocxCapabilities.revisionReview()	Accept or reject tracked changes.
DocxCapabilities.fullEdit()	Full authoring, optionally requiring track changes.
DocxCapabilities.editWithLock()	Full authoring that also requires a backend-owned edit lock.

DocxCapability.eSign is intentionally not included in the edit presets. Add it only when the lifecycle step permits sign-off and the controller has an actor and signing vocabulary.

Document Grants

Use Set<DocumentGrant> as the simple host-facing access model:

Grant	Meaning
DocumentGrant.read	Open and search/read.
DocumentGrant.review	Comment, view review state, accept/reject revisions, and export/print review output.
DocumentGrant.edit	Full authoring, save, review actions, export, and print.

If the host grants an empty set, the resulting capability set is empty. That is intentional: access decisions fail closed.

Edit Lock Configuration

Lock factory	Meaning
DocxEditLock.notRequired()	No lock is needed for mutation.
DocxEditLock.ownedByCurrentSession(...)	The current session owns the backend lock and may mutate.
DocxEditLock.ownedByOther(...)	Another session owns the lock; mutation is blocked.

Use editWithLock() or singleEditorLockRequired only when the host can create, renew, and release backend locks.

Conversion Configuration

Configuration point	Purpose
conversionService on SyncfusionDocxEditor	Override the conversion implementation.
VyuhDocxConversionService	Default pure-Dart DOCX/SFDT/PDF bridge backed by vyuh_docx.
Custom DocxConversionService	Integrate another conversion backend while keeping controller policy unchanged.

Review Widget Configuration

Widget	Required inputs	Callback configuration
DocxCompareView	DocxDiffResult or base/revised documents	initialMode, title.
DocxReviewPanel	comment threads	reply, reply-and-resolve, status, resolve, reopen, navigate, create-comment, refresh callbacks.
DocxReviewView	diff or base/revised documents	navigate, comment, suggest, apply suggestion, reject suggestion callbacks.

The widgets are presentational. Persisting comments, statuses, suggestions, and revision decisions remains the host/controller responsibility.

Signing Configuration

Signing requires:

Requirement	Why
DocxCapability.eSign	Explicit lifecycle permission to sign.
DocxActor	Signature attribution.
DocxCredentialVerifier	Fresh reauthentication ceremony.
DocxSigningVocabulary	Controlled allowed meanings.
requireResolvedCommentsForSign when needed	Document type can block approval while comments remain open.

Controlled Print Configuration

ControlledPrintService is configured separately from the editor widget:

final printService = ControlledPrintService(
  policy: policy,
  allocator: allocator,
  clock: clock,
  register: register,
  audit: audit,
);

Contract	Host responsibility
PrintPolicy	Decide whether the actor may issue the requested copy class.
CopyAllocator	Atomically allocate copy numbers and issuance codes.
TrustedClock	Provide the authoritative issue time.
PrintRegister	Persist the issuance record.
AuditSink	Persist immutable print audit events.

Controlled print belongs in docx_editor because it is a workflow operation, not just a PDF rendering operation.