Image Upload Example

Import Statements

The only thing interesting about the import statements is the API function, createContentDocumentAndVersion. The file upload discussion describes how to use this function.

State Tracking

This component’s state tracking consists of one @api public attribute and five @track internal state attributes.

• recordId is public and allows the component to receive a record context. This context is used to associate (attach) files that are uploaded to the record from which the component is launched. For example, to attach photos of equipment installed to the Service Appointment record of a technician’s visit.
• files holds the currently selected local file prior to being uploaded. This variable is used to hold a file locally while the Title and Description are edited. It’s an array so that, with some minor code changes, you can upload multiple files at a time.
• titleValue and descriptionValue hold the form field values for editing via the form fields.
• uploadingFile indicates active processing and is used to manage the Upload button’s enabled or disabled state.
• errorMessage holds messages about any errors that occur when the actual upload is attempted.

Convenience and Handler Functions

• The fileName getter is used locally only. It’s not relevant to or used for analysis of what to prime, so it’s exempt from the “simple getters only” rule.
• resetInputs resets the form fields and state after a successful upload.
• handleFilesInputChange, handleTitleInputChange, and handleDescriptionInputChange each update internal state values, in response to user changes on the form.

The code for each of these handlers is short, simple, and reasonably self-explanatory. They’re common for any LWC that handles user input via a form. We’ll talk about how they’re used in the next section, but we’ll leave these few lines of implementation code for you to read through yourself.

File Upload Handler Functions

The handleUploadClick and createContentDocumentLink functions together perform all of the work to upload a file to Salesforce, and link that file to an associated record. Both functions are defined as asynchronous using the async keyword.

handleUploadClick handles the user interface event (clicking the Upload button), and also creates the file upload. createContentDocumentLink is a utility function that creates the relationship between the file upload and the “owning” record. These functions are fairly different in how they work, so they’re described separately.

handleUploadClick is called when the user clicks the Upload button, which can only happen after they select a local file to be uploaded. It nevertheless begins by checking for a couple of situations where the upload can’t succeed:

• If an upload is already in progress, don’t start a new one.
• If there’s no actual file to upload, don’t try to upload a nonexistent file.

The user interface state should prevent these situations by disabling the Upload button when either of those conditions are true. However, a well-written function verifies its inputs. These checks ensure that you don’t cause an error if these important assumptions aren’t correct.

The actual upload processing takes place within a try block because all data mutations have the opportunity to fail, especially when you’re allowing for them to occur while offline. The first part of uploading a file is creating a file upload with a call to the new API function.

1const contentDocumentAndVersion =
2  await createContentDocumentAndVersion({
3    title: this.titleValue,
4    description: this.descriptionValue,
5    fileData: file,
6  });

This one call creates two related records. One record is a ContentDocument representing the file, including the name and description. The second is a related ContentVersion record that holds the file data and represents the current version of the uploaded file.

This one call does a lot of work, including creating the relationship between the two records. While you can achieve the same end result using the createRecord adapter, you can do that only while online. Creating and preserving the relationship between the two isn’t possible using createRecord while offline, mostly due to the complexity of the representation of files in Salesforce. createContentDocumentAndVersion abstracts that complexity, making file uploads as simple as the preceding snippet, which is just one line of code, wrapped for readability.

createContentDocumentAndVersion creates a file upload, but it does not associate that uploaded file with the “owning” record for the record context (if any). After it completes the upload (notice the await keyword before the call), we verify that we have a record context (recordId). If so, call the createContentDocumentLink helper function to create that association, in the form of a ContentDocumentLink record.

If handleUploadClick is exotic for using a mobile only API function, createContentDocumentLink is boring, using createRecord, a staple of LWC code since the framework’s release.

1async createContentDocumentLink(recordId, contentDocumentId) {
2  await createRecord({
3    apiName: "ContentDocumentLink",
4    fields: {
5      LinkedEntityId: recordId,
6      ContentDocumentId: contentDocumentId,
7      ShareType: "V",
8    },
9  });

This code is another one-liner when you unwrap it. The trick is knowing enough about the representation of files and their relationship to other object types in Salesforce. In this case, it’s knowing that ContentDocumentLink represents a relationship between an uploaded file and another record, and knowing which fields to stick the relevant record IDs into.

Where’s the “Offline” Part?

You just finished looking at it. And it looks a lot like regular LWC code for an online-only mobile feature. The only thing new is the createContentDocumentAndVersion adapter. There’s nothing offline-specific about the code here—it works fine while you’re online, too. The offline details are behind the scenes. Follow the LWC Offline guidelines for optimizing priming, and you’re good to go.