Packages >
Building a collaborative Text Area
Collaborating on text is one of the paradigmatic collaboration scenarios for information workers. In this tutorial, you’ll learn how to create a collaborative text area. Fluid Framework provides a distributed data structure (DDS) called SharedString for precisely this kind of scenario. It is a DDS with specialized features and behaviors for working with text. The UI of the app is based on React .
Note
You can see the completed app at collaborative text area app .
The following image shows a text area open in four browsers. The same text is in all four.
The next image shows the same four clients after an edit was made in one of the browsers. Note that the text has updated in all four browsers.
Note
This tutorial assumes that you are familiar with the Fluid Framework Overview and that you have completed the Quick Start . You should also be familiar with the basics of React , creating React projects , and React Hooks .
Create the project
-
Open a Command Prompt and navigate to the parent folder where you want to create the project, e.g.,
C:\My Fluid Projects
. -
Run the following command at the prompt. (Note that the CLI is npx, not npm. It was installed when you installed Node.js.)
npx create-react-app collaborative-text-area-tutorial --template typescript
-
Navigate to the root of the project with the command
cd collaborative-text-area-tutorial
. -
The project uses three Fluid libraries:
Library Description fluid-framework
Contains the SharedString distributed data structure that synchronizes text across clients. This object will hold the most recent text update made by any client. @fluidframework/tinylicious-client
Defines the connection to a Fluid server and defines the starting schema for the Fluid container . @fluid-experimental/react-inputs
Contains the SharedStringHelper class that provides helper APIs to interact with the SharedString object. Run the following command to install the libraries.
npm install @fluidframework/tinylicious-client @fluid-experimental/react-inputs fluid-framework
Code the project
-
Open the file
\src\App.tsx
in your code editor. Delete all the defaultimport
statements except the one that importsApp.css
. Then delete all the code in theApp()
function. The file should look like the following:import "./App.css"; function App() { } export default App;
-
Add the following
import
statements. About this code, note:TinyliciousClient
is a Fluid service that runs on the local development computer.SharedString
is the DDS that holds the text the collaborators will be writing.SharStringHelper
is a class that provides APIs to interact with the SharedString object.CollaborativeTextArea
is a React component that you will create in a later step.
import { useState, useEffect } from "react"; import { TinyliciousClient } from "@fluidframework/tinylicious-client"; import { ConnectionState, ContainerSchema, IFluidContainer, SharedString } from "fluid-framework"; import { CollaborativeTextArea } from "./CollaborativeTextArea"; import { SharedStringHelper } from "@fluid-experimental/react-inputs";
Get Fluid Data
-
The Fluid runtime will bring changes made to the text from any client to the current client, but Fluid is agnostic about the UI framework. Create a React hook, called
useSharedString
to get the Fluid data from the SharedString object into the view layer (the React state). Add the following code below theimport
statements. This method is called when the application loads the first time, and the returned value is assigned to a React state property.const useSharedString = (): SharedString => { const [sharedString, setSharedString] = useState<SharedString>(); const getFluidData = async () => { // TODO 1: Configure the container. // TODO 2: Get the container from the Fluid service. // TODO 3: Return the Fluid SharedString object. } // TODO 4: Get the Fluid Data data on app startup and store in the state. // TODO 5: Return the SharedString Object }
-
Replace
TODO 1
with the following code.const client: TinyliciousClient = new TinyliciousClient(); const containerSchema: ContainerSchema = { initialObjects: { sharedString: SharedString } };
-
Replace
TODO 2
with the following code. Note thatcontainerId
is being stored on the URL hash, and if there is nocontainerId
a new container is created instead.let container: IFluidContainer; const containerId = window.location.hash.substring(1); if (!containerId) { ({ container } = await client.createContainer(containerSchema)); const id = await container.attach(); window.location.hash = id; // Return the Fluid SharedString object. return container.initialObjects.sharedString as SharedString; } ({ container } = await client.getContainer(containerId, containerSchema)); if (container.connectionState !== ConnectionState.Connected) { await new Promise<void>((resolve) => { container.once("connected", () => { resolve(); }); }); }
-
Replace
TODO 3
with the following code.return container.initialObjects.sharedString as SharedString;
-
Replace
TODO 4
with the following code. Note about this code:- Passing an empty dependency array as the last parameter of
useEffect
ensures that this function is called only once. - The
setSharedString
method updates the view. Since it is a state-changing method, it will cause the ReactApp
component to immediately rerender.
useEffect(() => { getFluidData() .then((data) => setSharedString(data)); }, []);
- Passing an empty dependency array as the last parameter of
-
Finally, replace
TODO 5
with the following code.return sharedString as SharedString;
Move the Fluid Data to the view
Inside the App()
function, add the following code. Note about this code:
- The
sharedString
object returned from the code above is used to create aSharedStringHelper
object, which is a class that provides helper APIs to interact with thesharedString
object. - Next, the
SharedStringHelper
object is passed into theCollaborativeTextArea
React component, which integratesSharedString
with the default<textarea>
HTML element to enable collaboration.
const sharedString = useSharedString();
if (sharedString) {
return (
<div className="app">
<CollaborativeTextArea sharedStringHelper={new SharedStringHelper(sharedString)} />
</div>
);
} else {
return <div />;
}
Create CollaborativeTextArea component
CollaborativeTextArea
is a React component which uses a SharedStringHelper
object to control the text of an HTML <textarea>
element. Follow the below steps to create this component.
-
Create a new file
CollaborativeTextArea.tsx
inside of the\src
directory. -
Add the following
import
statements and declare theCollaborativeTextArea
component:import React from "react"; import { ISharedStringHelperTextChangedEventArgs, SharedStringHelper } from "@fluid-experimental/react-inputs"; interface ICollaborativeTextAreaProps { sharedStringHelper: SharedStringHelper; } export const CollaborativeTextArea = (props: ICollaborativeTextAreaProps) => { // TODO 1: Setup React state and references. // TODO 2: Handle a change event in the textarea. // TODO 3: Set the selection in textarea element (update the UI). // TODO 4: Store current selection from the textarea element in the React ref. // TODO 5: Detect changes in sharedStringHelper and update React/UI as necessary. // TODO 6: Create and configure a textarea element that will be used in App.tsx. }
-
Replace
TODO 1
with the following code. This code sets up the React state and gets a reference to the HTML<textarea>
element. To learn more aboutuseRef
, check out the React documentation .const sharedStringHelper = props.sharedStringHelper; const textareaRef = React.useRef<HTMLTextAreaElement>(null); const selectionStartRef = React.useRef<number>(0); const selectionEndRef = React.useRef<number>(0); const [text, setText] = React.useState<string>(sharedStringHelper.getText());
-
Replace
TODO 2
with the following code. This function will be called when a change is made to the<textarea>
element. You will create thestoreSelectionInReact
in a later step.const handleChange = (ev: React.FormEvent<HTMLTextAreaElement>) => { // First get and stash the new textarea state if (!textareaRef.current) { throw new Error("Handling change without current textarea ref?"); } const textareaElement = textareaRef.current; const newText = textareaElement.value; // After a change to the textarea content we assume the selection is gone (just a caret) const newCaretPosition = textareaElement.selectionStart; // Next get and stash the old React state const oldText = text; const oldSelectionStart = selectionStartRef.current; const oldSelectionEnd = selectionEndRef.current; // Next update the React state with the values from the textarea storeSelectionInReact(); setText(newText); // Finally update the SharedString with the values after deducing what type of change it was. const isTextInserted = newCaretPosition - oldSelectionStart > 0; if (isTextInserted) { const insertedText = newText.substring(oldSelectionStart, newCaretPosition); const isTextReplaced = oldSelectionEnd - oldSelectionStart > 0; if (!isTextReplaced) { sharedStringHelper.insertText(insertedText, oldSelectionStart); } else { sharedStringHelper.replaceText(insertedText, oldSelectionStart, oldSelectionEnd); } } else { // Text was removed const charactersDeleted = oldText.length - newText.length; sharedStringHelper.removeText(newCaretPosition, newCaretPosition + charactersDeleted); } };
-
Replace
TODO 3
with the following code. This function sets the selection directly in the<textarea>
element.const setTextareaSelection = (newStart: number, newEnd: number) => { if (!textareaRef.current) { throw new Error("Trying to set selection without current textarea ref?"); } const textareaElement = textareaRef.current; textareaElement.selectionStart = newStart; textareaElement.selectionEnd = newEnd; };
-
Replace
TODO 4
with the following code. This function gets the selection from the<textarea>
element and sets it in the React refs.const storeSelectionInReact = () => { if (!textareaRef.current) { throw new Error("Trying to remember selection without current textarea ref?"); } const textareaElement = textareaRef.current; const textareaSelectionStart = textareaElement.selectionStart; const textareaSelectionEnd = textareaElement.selectionEnd; selectionStartRef.current = textareaSelectionStart; selectionEndRef.current = textareaSelectionEnd; };
-
Replace
TODO 5
with the following code. Note about this code:- Setting the dependency array in the second parameter of
useEffect
to includesharedStringHelper
ensures that this function is called each time thesharedStringHelper
object is changed.
React.useEffect(() => { const handleTextChanged = (event: ISharedStringHelperTextChangedEventArgs) => { const newText = sharedStringHelper.getText(); setText(newText); if (!event.isLocal) { const newSelectionStart = event.transformPosition(selectionStartRef.current); const newSelectionEnd = event.transformPosition(selectionEndRef.current); setTextareaSelection(newSelectionStart, newSelectionEnd); storeSelectionInReact(); } }; sharedStringHelper.on("textChanged", handleTextChanged); return () => { sharedStringHelper.off("textChanged", handleTextChanged); }; }, [sharedStringHelper]);
- Setting the dependency array in the second parameter of
-
Finally, replace
TODO 6
with the following code to create the<textarea>
element and register all the event handlers for it.return ( <textarea rows={20} cols={50} ref={textareaRef} onBeforeInput={storeSelectionInReact} onKeyDown={storeSelectionInReact} onClick={storeSelectionInReact} onContextMenu={storeSelectionInReact} onChange={handleChange} value={text} /> );
Start the Fluid server and run the application
-
In the Command Prompt, run the following command to start the Fluid service. Note that
tinylicious
is the name of the Fluid service that runs on localhost.npx tinylicious
If Tinylicious is not installed, you will be prompted to install it. When the Fluid service is running, you will see
info: Listening on port ...
in the Command Prompt. -
Open a new Command Prompt and navigate to the root of the project; for example,
C:\My Fluid Projects\collaborative-text-area-tutorial
. Start the application server with the following command. The application opens in your browser.npm run start
-
Paste the URL of the application into the address bar of another tab or even another browser to have more than one client open at a time. Edit the text on any client and see the text change and synchronize on all the clients.
Next steps
- Consider using the Fluent UI React controls
to give the application the look and feel of Microsoft 365. To install them in your project run the following in the command prompt:
npm install @fluentui/react
. - For an example that will scale to larger applications and larger teams, check out the React Starter Template in the FluidExamples repo .
Tip
When you make changes to the code the project will automatically rebuild and the application server will reload. However, if you make changes to the container schema, they will only take effect if you close and restart the application server. Then run npm run start
again.