File Browser Descriptor API

Quick Start

// Get current descriptor
var descriptor = sync.api.UrlChooser.getFileBrowserDescriptor();

// Add SVG filter option to IMAGE type
descriptor.types.IMAGE.filters.push({
  label: 'SVG Files',
  regex: '\\.(svg)$'
});

// Apply the updated descriptor
sync.api.UrlChooser.setFileBrowserDescriptor(descriptor);

API Reference

Functions:

sync.api.UrlChooser.getFileBrowserDescriptor()
sync.api.UrlChooser.setFileBrowserDescriptor(descriptor)

Descriptor Structure:

The file browser descriptor is a JSON object with the following structure:

{
  "types": {
    "TYPE_NAME": {
      "uploadAcceptAttribute": "string|undefined",
      "allowAllFiles": boolean,
      "filters": [
        {
          "label": "string",
          "regex": "string|null"
        }
      ]
    }
  }
}

Type Configuration Properties:

Filter Configuration Properties:

Use Cases

Add Filter Options (Recommended)

Add additional filter choices without removing defaults.

var descriptor = sync.api.UrlChooser.getFileBrowserDescriptor();

// Add SVG and PNG options to IMAGE type
descriptor.types.IMAGE.filters.push({
  label: 'SVG Files',
  regex: '\\.(svg)$'
});

descriptor.types.IMAGE.filters.push({
  label: 'PNG Files',
  regex: '\\.(png)$'
});

sync.api.UrlChooser.setFileBrowserDescriptor(descriptor);    

Create Custom Types

Define completely new file types.

var descriptor = sync.api.UrlChooser.getFileBrowserDescriptor();

// Add a DOCUMENT type
descriptor.types.DOCUMENT = {
  uploadAcceptAttribute: '.doc,.docx,.pdf,.txt',
  allowAllFiles: true,
  filters: [
    {
      label: 'Document Files',
      regex: '\\.(doc|docx|pdf|txt)$'
    },
    {
      label: 'Office Documents',
      regex: '\\.(doc|docx|xls|xlsx)$'
    }
  ]
};

sync.api.UrlChooser.setFileBrowserDescriptor(descriptor);

// Use the custom type in your file chooser
var context = new sync.api.UrlChooser.Context('DOCUMENT');
workspace.getUrlChooser().chooseUrl(context, function(url) {
  console.log('Selected document:', url);
}, sync.api.UrlChooser.Purpose.CHOOSE);

Disable "All Files" Option

Remove the "All Files" option for specific file types.

var descriptor = sync.api.UrlChooser.getFileBrowserDescriptor();

// Disable "All Files" option for DITA type
descriptor.types.DITA.allowAllFiles = false;

sync.api.UrlChooser.setFileBrowserDescriptor(descriptor);    

Replace Default Filters

Completely replace the default filters for a file type.

var descriptor = sync.api.UrlChooser.getFileBrowserDescriptor();

// Replace IMAGE filters with JPEG-only
descriptor.types.IMAGE = {
  uploadAcceptAttribute: '.jpg,.jpeg',
  allowAllFiles: false,
  filters: [
    {
      label: 'JPEG Images Only',
      regex: '\\.(jpg|jpeg)$'
    }
  ]
};

sync.api.UrlChooser.setFileBrowserDescriptor(descriptor);

Validation

The API logs console warnings for the following common issues:

• descriptor must be an object - Provide valid descriptor object.
• descriptor.types must be an object - Ensure that the types property exists.
• invalid type configuration - Check the type configuration structure.
• invalid filter configuration - Verify that filter objects have the required properties.
• invalid regex - Ensure that regex strings are valid regular expressions.

Troubleshooting