Skip to content
CARP Documentation

CollectionReference

A reference to a collection of JSON documents in CAWS.

Obtained from CarpService.collection or DocumentReference.collection. Collections let an app store and query its own documents, like app resources or user notes, per study.

Note that the collection / document structure is like this:

collection/document/collection/document/...

I.e., that a collection holds a list of documents, which each can hold a list of collections, etc. For example, the following

activities/running/geopositions/pos_1

is a reference to the geoposition document pos_1 in the collection geopositions in the document running in the collection activities.

Inheritance

Properties

cawsPath

String get cawsPath

The full CARP Web Service (CAWS) path to this collection.

collectionUri

String get collectionUri

The full URI for the collection endpoint for this CollectionReference.

collectionUriByID

String get collectionUriByID

The full URI for the collection endpoint for this CollectionReference by its unique id.

Used by rename and delete, so id must be known first.

documents

Future<List<DocumentSnapshot>> get documents

id

int? get id

ID of the referenced collection.

Is null until read from the server with get, and -1 after delete.

name

String get name

The name of the referenced collection.

path

String get path

Returns the path of this collection (relative to the root of the web service).

studyId

String get studyId

The id of the study for this collection.

Methods

add

Future<DocumentReference> add([
  1. String? name,
  2. Map<String, dynamic>? data
])

Adds a data document to this collection and returns a DocumentReference to this document.

If no name is provided, an auto-generated name is used. If no data is provided, this can be set later using the DocumentReference.setData method.

delete

Future<void> delete()

Deletes the collection referred to by this CollectionReference.

Needs a known id; call get first.

document

DocumentReference document([
  1. String? name
])

Returns a DocumentReference with the provided name in this collection.

If no name is provided, an auto-generated name is used.

get

Future<CollectionReference> get()

Reads the collection referenced by this CollectionReference from the server, and updates id and path.

Returns this reference. Throws a CarpServiceRequestException if the collection does not exist on the server.

rename

Future<void> rename(
  1. String newName
)

Renames this collection to newName.

Needs a known id; call get first.

toString

String toString()
override

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.