React Native Tutorial

Install Dependencies

In your terminal, go to the directory that contains the client code. If you created the app with the App Services CLI, go to realm-sync-tutorial/frontend/react-native.todo.flex. Otherwise, go to the root of your downloaded or cloned project. Then run following commands to navigate to install the app's dependencies:

npm install

To build and run the app on an iOS device or simulator, install the additional iOS dependencies with CocoaPods.

npx pod-install

Build the App

At this point, you should have a fully functional React Native app that can run on both iOS and Android.

Test the App

When the build completes, you should have a functional app running on your simulator. In the app, register a new account and test the features:

• Add a few to-do items to the list.

• Press the checkbox on one or two items to mark them as complete.

• Press the X on an item to delete it from the list.

• Toggle internet connectivity in the app to simulate offline mode.

If you connect to your Atlas Cluster and query the todo.Item collection you can see your App's data. As long as the React Native app is not in offline mode, new data and changes in the app automatically sync to the todo.Item collection.

Similarly, any changes in the collection automatically sync down to the React Native app. Try changing an item's completion status in your cluster - the React Native app will automatically update with the new value whenever a network connection is available.

Define the Priority Levels

We want to allow a small number of named priority levels, and we want to easily be able sort the levels. To do this, we'll use a helper function to define an enum object that maps a set of ordered level names to and from an integer that represents their priority.

Add the following code directly under the import statements in src/ItemSchema.tsx:

function createEnum(arr) {
  arr.forEach((p, i) => arr[p] = i);
  return arr;
}
// Priority.High === 1
// Priority[Priority.High] === "High"
export const Priority = createEnum([
  "Severe",
  "High",
  "Medium",
  "Low",
])

The priority levels in the enum are ordered from most important to least. The corresponding index value for each level increases from the most important, Priority[0], to the least important, Priority[3]. This means that a higher priority level (meaning more important) has a lower index value.

Update the Item Data Model

Now we have an enum that defines the possible values of the priority field. However, we still have to define the priority field in the Item class.

Add the following lines to your code in src/ItemSchema.tsx to add priority to the Item data model:

export class Item extends Realm.Object<Item> {
  _id!: BSON.ObjectId;
  isComplete!: boolean;
  summary!: string;
  owner_id!: string;
  priority!: string;
  static schema: Realm.ObjectSchema = {
    name: 'Item',
    primaryKey: '_id',
    properties: {
      // This allows us to automatically generate a unique _id for each Item
      _id: {type: 'objectId', default: () => new BSON.ObjectId()},
      // All todo items will default to incomplete
      isComplete: {type: 'bool', default: false},
      summary: 'string',
      owner_id: 'string',
      priority: {
        // Store the index value of the Priority enum rather than the name
        type: 'int',
        default: Priority.High
      },
    },
  };
}

Add a Priority Picker

Your app's data model now includes a priority for each Item object. Let's update the app UI so that you can choose a priority value when you add a new to-do to the list.

First, we'll install an external library to implement the priority picker component. Run the following in your terminal inside of your project root:

npm install @react-native-picker/picker

If you're building for iOS, make sure to link the associated Cocoapods after you've installed the package:

npx pod-install

Now that the package is fully installed, let's update the new to-do creation prompt component to use the picker.

Add the following imports to the top of src/CreateToDoPrompt.tsx:

import {Picker} from '@react-native-picker/picker';
import {Priority} from './ItemSchema';

Then, modify the CreateToDoPrompt component:

• Add priority to the onSubmit() props definition

• Keep track of priority in a state hook

• Connect the state to the Picker component that you imported

• Pass priority to the onSubmit() handler

type Props = {
  onSubmit(args: {summary: string; priority: string;}): void;
};
export function CreateToDoPrompt(props: Props): React.ReactElement<Props> {
  const {onSubmit} = props;
  const [summary, setSummary] = useState('');
  const [priority, setPriority] = useState(Priority.High);
  return (
    <View style={styles.modalWrapper}>
      <Text h4 style={styles.addItemTitle}>
        Add To-Do Item
      </Text>
      <Input
        placeholder="What do you want to do?"
        onChangeText={(text: string) => setSummary(text)}
        autoCompleteType={undefined}
      />
      <Picker
        style={{width: '80%'}}
        selectedValue={priority}
        onValueChange={value => setPriority(value)}>
        {Priority.map(priority  => (
          <Picker.Item
            key={priority}
            label={priority}
            value={Priority[priority]}
           />
        ))}
      </Picker>
      <Button
        title="Save"
        buttonStyle={styles.saveButton}
        onPress={() => onSubmit({summary, priority})}
      />
    </View>
  );
}

In src/ItemListView.tsx, modify the createItem() function to accept and use priority:

const createItem = useCallback(
  ({summary, priority}: {summary: string, priority: string}) => {
    realm.write(() => {
      return new Item(realm, {
        summary,
        owner_id: user?.id,
        priority
      });
    });
  },
  [realm, user],
);

Then, modify the create to-do submission handler to accept the priority level and pass it to createItem():

<CreateToDoPrompt
  onSubmit={({summary, priority}) => {
    setShowNewItemOverlay(false);
    createItem({summary, priority});
  }}
/>

Finally, modify the list item template to render the to-do's priority before the summary:

<ListItem
  key={`${item._id}`}
  bottomDivider
  topDivider
  hasTVPreferredFocus={undefined}
  tvParallaxProperties={undefined}>
  <Text>{item.priority}</Text>
  <ListItem.Title style={styles.itemTitle}>
    {item.summary}
  </ListItem.Title>
  <ListItem.Subtitle style={styles.itemSubtitle}>
    {item.owner_id === user?.id ? '(mine)' : ''}
  </ListItem.Subtitle>
  <ListItem.CheckBox
    checked={item.isComplete}
    checkedColor={COLORS.primary}
    iconType="material"
    checkedIcon="check-box"
    uncheckedIcon="check-box-outline-blank"
    onPress={() => toggleItemIsComplete(item._id)}
  />
  <Button
    type="clear"
    onPress={() => deleteItem(item._id)}
    icon={
      <Icon
        type="material"
        name="clear"
        size={12}
        color="#979797"
        tvParallaxProperties={undefined}
      />
    }
  />
</ListItem>

Run and Test the App

Your app should now allow users to set a priority level for new to-do items.

Rebuild the app and open it. Add some new to-do items to confirm that you can choose a priority level and that the list displays each to-do's priority.

Add a Mode Toggle to the UI

First, add a useState() hook to the ItemListView component to keep track of the current mode:

const [showImportantOnly, setShowImportantOnly] = useState(false);

Then, add a new button that toggles the mode to the bottom of the to-do list, after <ListItem>:

<Button
  title={showImportantOnly ? 'Show All' : 'Show Important Only'}
  buttonStyle={{
    ...styles.addToDoButton,
    backgroundColor: showImportantOnly ? '#00A35C' : '#FFC010',
  }}
  onPress={() => setShowImportantOnly(showImportantOnly => !showImportantOnly)}
/>

Update the Sync Subscription

At this point, the app can switch modes in the UI, but we haven't done anything else so the modes are functionally identical. Let's update the sync subscription to only sync data relevant to the current mode.

In the first useEffect of the ItemListView component, add code that checks the current mode and appends an additional priority filter to the query if the showImportantOnly mode is active:

useEffect(() => {
  if (showAllItems) {
    realm.subscriptions.update(mutableSubs => {
      mutableSubs.removeByName(ownItemsSubscriptionName);
      mutableSubs.add(realm.objects(Item), {name: itemSubscriptionName});
    });
  } else if (showImportantOnly) {
    realm.subscriptions.update(mutableSubs => {
      mutableSubs.removeByName(itemSubscriptionName);
      mutableSubs.add(
        realm.objects(Item).filtered(`owner_id == "${user?.id}" && priority <= 1`),
        {name: ownItemsSubscriptionName},
      );
    });
  } else {
    realm.subscriptions.update(mutableSubs => {
      mutableSubs.removeByName(itemSubscriptionName);
      mutableSubs.add(
        realm.objects(Item).filtered(`owner_id == "${user?.id}"`),
        {name: ownItemsSubscriptionName},
      );
    });
  }
}, [realm, user, showAllItems, showImportantOnly]);

Test the App

Your app is now set up to modify its sync subscription based on the current mode. However, if you run the app and switch to only showing important items, you'll see that the list doesn't change and a warning appears in the console:

Possible Unhandled Promise Rejection (id: 0):
Error: Client provided query with bad syntax:
unsupported query for table "Item": key "priority" is not a queryable field

Update the Sync Configuration

We're getting a warning because a sync client can only filter a subscription based on a given field if that field is specifically listed as a queryable field in the Device Sync configuration of your App Services App.

To get everything working, we need to add priority as a queryable field in the App's sync configuration.

First, find the template app's backend directory and modify sync/config.json:

{
    ...,
    "queryable_fields_names": [
        "_id",
        "owner_id",
        "priority"
    ]
}

Then, run the following terminal command from within the backend directory to deploy the updated sync configuration:

npx mongodb-realm-cli push

Run the Completed App

Once your updated sync configuration is deployed, your app is complete and fully functional. Congratulations!

Rebuild and run the app to make sure everything works. You should be able to create, complete, and delete to-do items as well as toggle between viewing all items and only important items.