|
| 1 | +--- |
| 2 | +sidebar_label: Working with the server |
| 3 | +title: Working with the server |
| 4 | +description: Learn how RichText communicates with a backend for image uploads, including the request/response contract and how to plug in your own server. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX RichText. |
| 5 | +--- |
| 6 | + |
| 7 | +# Working with the server |
| 8 | + |
| 9 | +RichText runs entirely in the browser and does not need a backend for editing or saving content. Your application is free to persist the content of the editor wherever it wants. The one feature that benefits from a server is **image upload**: when a user inserts an image into the document, RichText can either embed the file inline in the content or post it to an HTTP endpoint and store a link to it. |
| 10 | + |
| 11 | +This guide explains: |
| 12 | + |
| 13 | +- what happens by default when no upload server is configured |
| 14 | +- the exact HTTP contract the server has to implement |
| 15 | +- how RichText uses the URL returned by the server |
| 16 | +- how to try the feature against the demo backend |
| 17 | + |
| 18 | +## Default behavior: inline images |
| 19 | + |
| 20 | +If you do not set the [`imageUploadUrl`](api/config/image-upload-url.md) property, RichText falls back to inline images. When the user inserts an image, RichText reads the file in the browser, encodes the original file as a `data:image/...;base64,...` URL, and writes it directly into the editor content as the `src` of the `<img>` element. RichText constrains the displayed size to fit within a 1024×800 box through the `width`/`height` attributes, but the embedded bytes are the original, full-resolution file — the client does not downscale or re-encode it. |
| 21 | + |
| 22 | +This works without any backend and is handy for quick demos, but it has clear limitations: |
| 23 | + |
| 24 | +- the encoded bytes live inside the document, so the saved HTML grows with every image |
| 25 | +- the same image in two documents is stored twice — there is no shared resource to deduplicate |
| 26 | +- because the bytes are not a separate resource, the server cannot serve them from a CDN or post-process them (resize, re-encode, scan) |
| 27 | +- inline images are not preserved by the built-in DOCX / PDF [export](api/events/export.md) — if you rely on export, configure an upload server so images reference an external URL |
| 28 | + |
| 29 | +## Write your own server |
| 30 | + |
| 31 | +In production apps, point RichText at a server with [`imageUploadUrl`](api/config/image-upload-url.md): |
| 32 | + |
| 33 | +~~~jsx {2} |
| 34 | +new richtext.Richtext("#root", { |
| 35 | + imageUploadUrl: "https://example.com/upload" |
| 36 | + // other configuration properties |
| 37 | +}); |
| 38 | +~~~ |
| 39 | + |
| 40 | +A minimal upload endpoint needs to: |
| 41 | + |
| 42 | +1. Accept a `multipart/form-data` POST with a file field named `upload`. |
| 43 | +2. Validate the file (allowed types, maximum size). |
| 44 | +3. Store the file somewhere the user's browser can fetch (a local disk served over HTTP, S3, a CDN, etc.). |
| 45 | +4. Optionally resize or otherwise process the image. |
| 46 | +5. Respond with a JSON object that contains `status: "server"`, `value` set to the public URL of the stored file, and the image's `width` and `height` in pixels. |
| 47 | + |
| 48 | +### What the client sends |
| 49 | + |
| 50 | +When [`imageUploadUrl`](api/config/image-upload-url.md) is set, RichText posts the selected file directly to that URL (it does not append `/images` or any other path), so the URL you pass is the full POST target. |
| 51 | + |
| 52 | +The request uses standard HTML form upload: |
| 53 | + |
| 54 | +- **Method:** `POST` |
| 55 | +- **Content-Type:** `multipart/form-data` |
| 56 | +- **Body:** one file field named `upload` |
| 57 | + |
| 58 | +### What the client expects back |
| 59 | + |
| 60 | +The server must reply with a JSON object. RichText reads the following fields: |
| 61 | + |
| 62 | +| Field | Type | Meaning | |
| 63 | +| -------- | ------- | ----------------------------------------------------------------------- | |
| 64 | +| `status` | string | Success marker — return `"server"` for a successful upload. The uploader uses this field to tell a completed upload from a failed one; any other value (for example `"error"`) marks the upload as failed. The inserted image itself is built from `value`, `width`, and `height`. | |
| 65 | +| `value` | string | URL of the stored image. RichText writes this string verbatim into the document as the `src` of the inserted `<img>`. | |
| 66 | +| `width` | integer | Width used to size the inserted image, in pixels. | |
| 67 | +| `height` | integer | Height used to size the inserted image, in pixels. | |
| 68 | + |
| 69 | +#### Successful response |
| 70 | + |
| 71 | +A successful upload returns the stored image URL and its dimensions: |
| 72 | + |
| 73 | +~~~json |
| 74 | +{ |
| 75 | + "status": "server", |
| 76 | + "value": "https://cdn.example.com/uploads/abc123.png", |
| 77 | + "width": 320, |
| 78 | + "height": 207 |
| 79 | +} |
| 80 | +~~~ |
| 81 | + |
| 82 | +#### Failed upload |
| 83 | + |
| 84 | +A failed upload returns any status other than `"server"`: |
| 85 | + |
| 86 | +~~~json |
| 87 | +{ |
| 88 | + "status": "error" |
| 89 | +} |
| 90 | +~~~ |
| 91 | + |
| 92 | +### Serve the uploaded image |
| 93 | + |
| 94 | +The `value` URL is the only link between the upload and every later read of the document. RichText puts the URL straight into the document, so any client that opens the saved content (the editor itself, an export, a published page) fetches the image from that URL with a plain `GET`. |
| 95 | + |
| 96 | +That means: |
| 97 | + |
| 98 | +- the URL must be reachable from the user's browser, which usually means it has to be **absolute** |
| 99 | +- the host can be different from the upload endpoint (for example, you can accept uploads on your own server and return a CDN or object-storage URL) |
| 100 | +- if the image host is on a different origin, make sure it allows the page to load the image (CORS or simply public read access) |
| 101 | +- the server must keep that URL working for as long as documents reference it; RichText does not cache or copy the bytes |
| 102 | + |
| 103 | +The URL layout itself is **not** part of the contract. As long as the browser can `GET` the URL and receive image bytes, the path, the query string, and even the scheme are entirely up to the backend. |
| 104 | + |
| 105 | +### Try it against the demo server |
| 106 | + |
| 107 | +A working backend that implements this contract is available to test the feature: |
| 108 | + |
| 109 | +~~~jsx |
| 110 | +new richtext.Richtext("#root", { |
| 111 | + imageUploadUrl: "https://docs.dhtmlx.com/richtext-backend/images" |
| 112 | + // other configuration properties |
| 113 | +}); |
| 114 | +~~~ |
| 115 | + |
| 116 | +The demo server resizes large images, stores them on disk, and returns URLs it serves itself. It is intended for evaluation and demos only. Do not point production editors at it. |
| 117 | + |
| 118 | +**Related articles:** |
| 119 | + |
| 120 | +- [Configuration](guides/configuration.md) |
| 121 | +- [`imageUploadUrl`](api/config/image-upload-url.md) |
0 commit comments