Tutorial: Atlas Device Sync for C++ with FTXUI

Add a Property to the Model

Now that you have confirmed everything is working as expected, you can add changes. In this tutorial, you add a priority property to each Item so that you can filter the items by their priorities.

In a production app, you might add a PriorityLevel enum to constrain the possible values. For this tutorial, we'll use a number property to simplify working with the UI framework.

To do this, follow these steps:

1. Open the client code in your preferred IDE.

2. In the state/ directory, ppen the item.hpp file.

3. Add the following property to the Item struct:

   int64_t priority;

4. Add the new priority property to the REALM_SCHEMA():

   REALM_SCHEMA(Item, _id, isComplete, summary, owner_id, priority)

   The Item model should now resemble:

   namespace realm {
   struct Item {
     realm::primary_key<realm::object_id> _id{realm::object_id::generate()};
     bool isComplete;
     std::string summary;
     std::string owner_id;
     int64_t priority;
   };
   REALM_SCHEMA(Item, _id, isComplete, summary, owner_id, priority)
   }  // namespace realm

Add an Element to the UI to Set the Priority

1. In the state directory, go to home_controller_state.hpp. Add a new int property under the existing newTaskIsComplete property. Then, add a static const int to store the default int value for this property.

   The HomeControllerState struct may now resemble:

   struct HomeControllerState {
     static const int DEFAULT_TASK_PRIORITY = 3;
     // Used for creating a new task.
     std::string newTaskSummary;
     bool newTaskIsComplete{false};
     int newTaskPriority{DEFAULT_TASK_PRIORITY};
     ...more code here...
   };

2. In the controllers directory, go to home_controller.hpp. This controller renders the main view of the app.

   Import the string and vector libraries:

   #include <string>
   #include <vector>

   Create an array of string labels for the new priority UI element:

   std::vector<std::string> priorityLevelLabels = {
     "Severe", "High", "Medium", "Low"
   };

3. Still in the controllers directory, go to home_controller.cpp. This is where we add a UI element to allow the user to set the priority for the item. FTXUI offers two UI elements you could use for this functionality: Radiobox or Dropdown. In this tutorial, we'll use Dropdown, but you might prefer Radiobox if you don't like the way the UI reflows to render the dropdown.

   Add this new UI element input after the auto newTaskCompletionStatus line:

   auto newTaskPriorityDropdown = ftxui::Dropdown(
     &priorityLevelLabels,
     &_homeControllerState.newTaskPriority
   );

   In the auto saveButton function closure, pass the task priority selection to the _dbManager.addNew() function call:

   _dbManager.addNew(
     _homeControllerState.newTaskIsComplete,
     _homeControllerState.newTaskSummary,
     _homeControllerState.newTaskPriority);

   And then add a line to reset the priority selection to the default value:

   _homeControllerState.newTaskPriority = HomeControllerState::DEFAULT_TASK_PRIORITY;

   Add the dropdown selector to the auto newTaskLayout that sets the layout for the interactive elements in the item row container:

   auto newTaskLayout = ftxui::Container::Horizontal(
     {inputNewTaskSummary, newTaskCompletionStatus, newTaskPriorityDropdown, saveButton});

   This section of your code should now resemble:

   auto newTaskCompletionStatus = ftxui::Checkbox("Complete", &_homeControllerState.newTaskIsComplete);
   auto newTaskPriorityDropdown = ftxui::Dropdown(
     &priorityLevelLabels,
     &_homeControllerState.newTaskPriority);
   auto saveButton = ftxui::Button("Save", [this] {
     _dbManager.addNew(
       _homeControllerState.newTaskIsComplete,
       _homeControllerState.newTaskSummary,
       _homeControllerState.newTaskPriority);
     _homeControllerState.newTaskSummary = "";
     _homeControllerState.newTaskIsComplete = false;
     _homeControllerState.newTaskPriority = HomeControllerState::DEFAULT_TASK_PRIORITY;
   });
   auto newTaskLayout = ftxui::Container::Horizontal(
     {inputNewTaskSummary, newTaskCompletionStatus, newTaskPriorityDropdown, saveButton});

4. Finally, farther down in the home_controller.cpp file, add the new UI element to the auto itemListRenderer:

   inputNewTaskSummary->Render() | ftxui::flex,
   newTaskCompletionStatus->Render() | ftxui::center,
   newTaskPriorityDropdown->Render(),
   saveButton->Render(),

   This renders the new element right before the Save button in the UI.

Save the New Property to the Database

1. In the managers directory, go to database_manager.hpp. Update the addNew() function signature to include the int newItemPriority we pass in from the home_controller.cpp:

   void addNew(
     bool newItemIsComplete,
     std::string newItemSummary,
     int newItemPriority);

2. Now go to database_manager.cpp, and update the addNew() implementation. Add int newItemProperty to the function arguments:

   void DatabaseManager::addNew(
     bool newItemIsComplete,
     std::string newItemSummary,
     int newItemPriority) {
     ...implementation...
     }

   Add a new line in the function to set the value of the priority property when we save the Item to the database:

   .priority = newItemPriority

   Your addNew() implementation should now resemble:

   void DatabaseManager::addNew(bool newItemIsComplete, std::string newItemSummary, int newItemPriority) {
     auto item = realm::Item {
       .isComplete = newItemIsComplete,
       .summary = std::move(newItemSummary),
       .owner_id = _userId,
       .priority = newItemPriority
     };
     _database->write([&]{
       _database->add(std::move(item));
     });
   }

Run and Test

At this point, build and run the application again. In your build directory, rebuild the executable with the changes you made:

cmake --build .

And run the app:

./sync_todo /path-to-file/atlasConfig.json

Log in using the account you created earlier in this tutorial. You will see the one Item you previously created. Add a new Item, and you will see that you can now set the priority. Choose High for the priority and save the Item.

Now switch back to the Atlas data page in your browser, and refresh the Item collection. You should now see the new Item with the priority field added and set to 1. The existing Item does not have a priority field.

click to enlarge

Update the subscription

To change the subscription, go to the managers directory and open the database_manager.cpp file. Update the query statement to include documents where the priority is equal to or less than 1. This should only include items of "Severe" (0) or "High" (1) priority.

if (!subs.find(_myItemSubscriptionName)) {
  subs.add<realm::Item>(
    _myItemSubscriptionName,
    [&](auto &item){
      return item.owner_id == _userId && item.priority <= 1;
    }
  );
}

Run and Test

Run the application again. Log in using the account you created earlier in this tutorial. In the Subscription box, press the Switch to Mine button. After an initial moment when the SDK resyncs the document collection, you will only see the new Item of High priority that you created. You may need to move your mouse or use the arrow key to cause the UI to re-render with the new items that have been synced in the background.

The Item document you initially created does not show on the device, because it does not have a priority field. If you want this Item to sync to the device, you can edit the document in the Atlas UI and add a value for the priority field.

If you want to further test the functionality, you can create Items of various priorities. You will see that a new Item with a lower priority briefly appears in the list of Items and then disappears. The Sync error handler helpfully provides a message describing this behavior:

A sync error occurred. Message:
"Client attempted a write that is not allowed; it has been reverted"

In this scenario, the SDK creates the Item locally, syncs it with the backend, and then reverts the write because it doesn't meet the subscription rules.