|
| 1 | +[[documents-file-types]] |
| 2 | +== `+documents_file_types+` |
| 3 | + |
| 4 | +ifeval::["{includedSection}" == "uploadcarePlugin"] |
| 5 | +This option specifies which file types (MIME types and extensions) are supported for file uploads in the link dialog when using the Media Optimizer plugin. When both the xref:link.adoc[Link] plugin and the Media Optimizer plugin are enabled, the Media Optimizer plugin automatically configures this option to enable file uploads in the link dialog. |
| 6 | +endif::[] |
| 7 | +ifndef::includedSection[] |
| 8 | +This option specifies which file types (MIME types and extensions) are supported for file uploads in the link dialog. When both the xref:link.adoc[Link] plugin and the xref:link.adoc#files_upload_handler[`+files_upload_handler+`] are configured, the link dialog displays an "Upload" tab that enables file uploads. |
| 9 | +endif::[] |
| 10 | + |
| 11 | +ifeval::["{includedSection}" == "uploadcarePlugin"] |
| 12 | +The option should be a non-empty array of objects, where each object contains: |
| 13 | +endif::[] |
| 14 | +ifndef::includedSection[] |
| 15 | +The option should be an array of objects, where each object contains: |
| 16 | +endif::[] |
| 17 | + |
| 18 | +* `+mimeType+` - A string representing the MIME type (e.g., `+'application/pdf'+`) |
| 19 | +* `+extensions+` - An array of strings representing the file extensions (e.g., `+['pdf']+`) |
| 20 | + |
| 21 | +ifeval::["{includedSection}" == "uploadcarePlugin"] |
| 22 | +[IMPORTANT] |
| 23 | +==== |
| 24 | +If `+documents_file_types+` is set to an empty array or is not a valid array of objects matching the configuration schema, the Media Optimizer plugin will throw an error: "Must be a non-empty array of objects matching the configuration schema." |
| 25 | +==== |
| 26 | + |
| 27 | +When the Media Optimizer plugin is enabled with the `+link+` plugin, it automatically sets a default list of supported file types. The default list includes: |
| 28 | + |
| 29 | +* **Documents:** PDF, Word (doc, docx), Excel (xls, xlsx), PowerPoint (ppt, pps, pptx), RTF, plain text (txt) |
| 30 | +* **iWork files:** Keynote (key), Pages (pages), Numbers (numbers) |
| 31 | +* **Audio files:** WAV, MP3, OGG (with various extensions) |
| 32 | +* **Archive files:** ZIP, GZIP, TAR, 7Z, RAR |
| 33 | + |
| 34 | +This list can be customized by setting `+documents_file_types+` manually in the editor configuration. |
| 35 | + |
| 36 | +endif::[] |
| 37 | + |
| 38 | +ifeval::["{includedSection}" == "uploadcarePlugin"] |
| 39 | +[NOTE] |
| 40 | +==== |
| 41 | +**Priority Behavior** |
| 42 | +
|
| 43 | +When `+documents_file_types+` is set, it acts as the source of truth for supported file types throughout the editor. This means: |
| 44 | +
|
| 45 | +* The xref:link.adoc[Link] plugin uses this custom list instead of its default supported file types |
| 46 | +* The Media Optimizer plugin also uses this list to determine which `+mimeType+` values are allowed for file uploads when both the `+link+` plugin and the Media Optimizer plugin are enabled as they share the same list of supported file types via this option. |
| 47 | +** If a MIME type is blocked by the Uploadcare dashboard on the server side, the MIME type will also be blocked on the client side regardless of whether `+documents_file_types+` is set, resulting in an error message such as "File type not allowed" or "File type not supported". |
| 48 | +
|
| 49 | +If `+documents_file_types+` is not set: |
| 50 | +
|
| 51 | +* The xref:link.adoc[Link] plugin uses its default list of supported file types |
| 52 | +* The Media Optimizer plugin uses its own default list of supported file types (as listed above) |
| 53 | +==== |
| 54 | +endif::[] |
| 55 | +ifndef::includedSection[] |
| 56 | +[NOTE] |
| 57 | +==== |
| 58 | +**Priority Behavior** |
| 59 | +
|
| 60 | +When `+documents_file_types+` is set, it acts as the source of truth for supported file types throughout the editor. This means: |
| 61 | +
|
| 62 | +* The Link plugin uses this custom list instead of its default supported file types |
| 63 | +
|
| 64 | +If `+documents_file_types+` is not set: |
| 65 | +
|
| 66 | +* The Link plugin uses its default list of supported file types |
| 67 | +==== |
| 68 | + |
| 69 | +endif::[] |
| 70 | + |
| 71 | +*Type:* `+Array+` |
| 72 | + |
| 73 | +ifeval::["{includedSection}" == "uploadcarePlugin"] |
| 74 | +*Default value:* `+undefined+`. The Media Optimizer plugin automatically configures this option when both the `+link+` plugin and the Media Optimizer plugin are enabled. The automatically configured list includes documents, iWork files, audio files, and archive files. |
| 75 | +endif::[] |
| 76 | +ifndef::includedSection[] |
| 77 | +*Default value:* `+undefined+` |
| 78 | +endif::[] |
| 79 | + |
| 80 | +ifeval::["{includedSection}" == "uploadcarePlugin"] |
| 81 | +=== Example: Using `documents_file_types` with Media Optimizer |
| 82 | + |
| 83 | +This example shows how to customize the file types when using the Media Optimizer plugin with the xref:link.adoc[Link] plugin: |
| 84 | + |
| 85 | +[source,js] |
| 86 | +---- |
| 87 | +tinymce.init({ |
| 88 | + selector: 'textarea', |
| 89 | + plugins: 'uploadcare link', |
| 90 | + toolbar: 'uploadcare link', |
| 91 | + uploadcare_public_key: '<your-public-key>', |
| 92 | + documents_file_types: [ |
| 93 | + { mimeType: 'application/msword', extensions: [ 'doc' ] }, |
| 94 | + { mimeType: 'application/vnd.ms-excel', extensions: [ 'xls' ] }, |
| 95 | + { mimeType: 'application/vnd.ms-powerpoint', extensions: [ 'ppt', 'pps' ] }, |
| 96 | + { mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', extensions: [ 'docx' ] }, |
| 97 | + { mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', extensions: [ 'xlsx' ] }, |
| 98 | + { mimeType: 'application/vnd.openxmlformats-officedocument.presentationml.presentation', extensions: [ 'pptx' ] }, |
| 99 | + { mimeType: 'application/pdf', extensions: [ 'pdf' ] }, |
| 100 | + { mimeType: 'application/rtf', extensions: [ 'rtf' ] }, |
| 101 | + { mimeType: 'text/plain', extensions: [ 'txt' ] }, |
| 102 | + { mimeType: 'application/x-iwork-keynote-sffkey', extensions: [ 'key' ] }, |
| 103 | + { mimeType: 'application/x-iwork-pages-sffpages', extensions: [ 'pages' ] }, |
| 104 | + { mimeType: 'application/x-iwork-numbers-sffnumbers', extensions: [ 'numbers' ] }, |
| 105 | + { mimeType: 'audio/wav', extensions: [ 'wav', 'wave' ] }, |
| 106 | + { mimeType: 'audio/mpeg', extensions: [ 'mp3' ] }, |
| 107 | + { mimeType: 'audio/ogg', extensions: [ 'ogg', 'oga', 'ogx', 'ogm', 'spx', 'opus' ] }, |
| 108 | + { mimeType: 'application/zip', extensions: [ 'zip' ] }, |
| 109 | + { mimeType: 'application/gzip', extensions: [ 'gz', 'gzip' ] }, |
| 110 | + { mimeType: 'application/x-tar', extensions: [ 'tar' ] }, |
| 111 | + { mimeType: 'application/x-gtar', extensions: [ 'tar.gz', 'tgz' ] }, |
| 112 | + { mimeType: 'application/x-7z-compressed', extensions: [ '7z' ] }, |
| 113 | + { mimeType: 'application/x-rar-compressed', extensions: [ 'rar' ] } |
| 114 | + ] |
| 115 | +}); |
| 116 | +---- |
| 117 | + |
| 118 | +This option is part of the xref:link.adoc[Link plugin] and can also be configured independently. For more information about file upload configuration, see xref:link.adoc#documents-file-types[`+documents_file_types+`] in the Link plugin documentation. |
| 119 | + |
| 120 | +endif::[] |
| 121 | +ifndef::includedSection[] |
| 122 | +=== Example: using `+documents_file_types+` |
| 123 | + |
| 124 | +[source,js] |
| 125 | +---- |
| 126 | +tinymce.init({ |
| 127 | + selector: 'textarea', |
| 128 | + plugins: 'link', |
| 129 | + toolbar: 'link', |
| 130 | + // Configure the file upload handler to handle the file uploads |
| 131 | + files_upload_handler: async (blobInfo, progress) => { |
| 132 | + return { url: 'https://example.com/file.pdf', fileName: 'file.pdf' }; |
| 133 | + }, |
| 134 | + // Configure the list of supported file types |
| 135 | + documents_file_types: [ |
| 136 | + { mimeType: 'application/msword', extensions: [ 'doc' ] }, |
| 137 | + { mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', extensions: [ 'docx' ] }, |
| 138 | + { mimeType: 'application/pdf', extensions: [ 'pdf' ] }, |
| 139 | + { mimeType: 'text/plain', extensions: [ 'txt' ] } |
| 140 | + ] |
| 141 | +}); |
| 142 | +---- |
| 143 | + |
| 144 | +endif::[] |
| 145 | + |
0 commit comments