The Basics

Create a Database

There is no limit to how many databases can be created or opened on the device. You can think of a database as a namespace for documents and several databases can be used in the same app (one database per user of the app is a common pattern).

The snippet below creates an empty database for a given user in a directory with the same name as the username.

Open the fileLoginModel.cs. We will review the Task<CouchbaseSession> StartSessionAsync(string username, string password) method.

public async Task<CouchbaseSession> StartSessionAsync(string username, string password) {
  ...
}

We create a folder for the user database if one does not exist and specify that as the database Directory in the DatabaseConfiguration object. Note the use of the service provider to find the default directory for the platform.

var options = new DatabaseConfiguration();

// Borrow this functionality from Couchbase Lite
var defaultDirectory = Service.Provider.GetService<IDefaultDirectoryResolver>().DefaultDirectory();
var userFolder = Path.Combine(defaultDirectory, username);
if (!Directory.Exists(userFolder)) {
    Directory.CreateDirectory(userFolder);
}

options.Directory = userFolder;

The Couchbase Lite Database is created with specified name and DatabaseConfiguration object

db = new Database(DbName, options);

Try it out

  • Build and Run the Travel Sample Mobile App

  • On Login screen select “Proceed as Guest” option.

  • This will log you into app in Guest Mode. Signing in as Guest will create a new empty database for “guest” account if one does not exist

  • Confirm that you see the “Bookmarked Hotels” page. It will be empty the very first time. =

Create and Update a Document

Bookmarked hotels are persisted in a separate document with type of bookmarkedhotels.

The first time a hotel is bookmarked, the bookmarkedhotels document is created with the document ID of that hotel document in the hotels property. The hotel’s information is persisted in a separate hotels type document.

Subsequently, every time a hotel is bookmarked, the process repeats.

{
  "_id": "hotel1",
  "name": "San Francisco Hotel",
  "address": "123, Park Street, San Francisco"
}

{
  "type": "bookmarkedhotels",
  "hotels": ["hotel1", "hotel2"]
}

Open the fileHotelListModel.cs. We will review the void ToggleBookmark(HotelListCellModel hotel) method.

public void ToggleBookmark(HotelListCellModel hotel) {
    ...
}

Fetch the document of type bookmarkedhotels. Don’t worry too much about how you query for document of specific type from the database. We will examine queries in a future lesson.

Create document of type bookmarkedhotels if one does not exist.

using (var document = UserSession.FetchGuestBookmarkDocument()?.ToMutable()) {
  var doc = document;
  if (document == null) {
      ...

      doc = new MutableDocument(new Dictionary<string, object> {["type"] = "bookmarkedhotels"});
  }

Next, add the ID of the passed hotel to the current list of bookmarked hotel Ids from the hotels property of the bookmarkedhotels document, or remove it based on the current action.

var bookmarked = doc.GetArray("hotels") ?? new MutableArrayObject();
if (hotel.IsBookmarked) {
    // Remove the bookmark
    for (int i = 0; i < bookmarked.Count(); i++) {
        if (bookmarked.GetString(i) == (hotel.Source.ContainsKey("id") ? hotel.Source["id"] as String : null) ){
            bookmarked.RemoveAt(i);
            break;
        }
    }
} else {
    bookmarked.AddString(hotel.Source.ContainsKey("id") ? hotel.Source["id"] as String : null);
}

doc.SetArray("hotels", bookmarked);
UserSession.Database.Save(doc);

Persist the hotel information as separate documents of type hotels (or delete it if this is a bookmark removal). First, determine if the document with specified hotel Id already exists. If so, update it with the selected hotel details. If not, create a new hotel document.

// Add the hotel details document
if (hotel.Source["id"] is string id) {
    using (var detailDoc = UserSession.Database.GetDocument(id)?.ToMutable() ?? new MutableDocument(id)) {
        detailDoc.SetData(hotel.Source.ToDictionary(x => x.Key, x => x.Value));
          UserSession.Database.Save(detailDoc);
    }
}

Try it out

  • As Guest User, tap on “hotels” button

  • In "location" text field , enter "London"

  • You will see list of hotels.

  • The list of hotels is pulled from the Couchbase Server via the Travel Sample Web Services API. The list of hotels is not displayed unless there is an open connection the python web app so make sure you have your Travel Sample Web app running

  • Right click/tap on the first hotel cell

  • You will see the button to “Bookmark”

  • Tap “bookmark”

  • This should display a "bookmark" icon on the hotel cell

  • Tap "Back" button

  • Verify that you see the bookmarked hotel in the “Bookmarked Hotels” screen. A motivation for having separate docs for each bookmarked hotel is if they become sharable between users via the sync function.

The screen capture is for UWP version of the app.

uwp basics add document

=

Delete a Document

A document can be deleted using the Delete method. This operation actually creates a new tombstoned revision in order to propagate the deletion to other clients.

Open the fileBookmarkedHotelModel.cs. We will review the public void RemoveBookmark(HotelListCellModel bookmark) method.

public void RemoveBookmark(HotelListCellModel bookmark) {
  ...
}

The unbookmarking process removes the hotel Id from the "bookmarkedhotels" document and deletes the unbookmarked "hotels" document from the database. Note that in addition to deleting the "hotels" document, the unbookmarking process updates the "bookmarkedhotels" document by removing the the hotel Id from the hotels array.

if (bookmark.Source["id"] is string idToRemove) {
    var doc = UserSession.Database.GetDocument(idToRemove);
    if (doc != null) {
        UserSession.Database.Delete(doc);
    }
}

Try it out

  • Follow the steps in Update a Document section to bookmark a hotel

  • Confirm that you see the bookmarked hotels in the "Bookmarked Hotels" screen. If not, make sure you go through the instructions in Update a Document section

  • Right click/tap on the first Hotel cell

  • You will get button to “UnBookmark”

  • Tap “unbookmark”

  • Verify that the unbookmarked hotel does not show up in list

The screen capture is for UWP version of the app.

uwp basics delete document