Topic and comment builders

A set of builder classes exist to ease the process of creating and updating topics and comments. These builders are optional but provide some important advantages.

Request objects

All creations and updates of annotations made to an annotation repository are made through request objects.

• To create a topic in the repository, you must provide an ITopicCreation object containing the topic information.
• To update a topic in the repository, you must provide an ITopicUpdate object containing the updated topic information.
• To create a comment on topic, you must provide an ICommentCreation object containing the comment information.
• To update a comment on topic, you must provide an ICommentUpdate object containing the updated comment information.

You can provide your own implementations of these interfaces. By default, the package contains default implementations of the following:

• TopicCreation
• TopicUpdate
• CommentCreation
• TopicUpdate

Alongside the default implementations for these objects, a set of fluent builders for each object are also available and described on this page.

Creation and update builders

Using the default implementations for TopicCreation, TopicUpdate, CommentCreation, and CommentUpdate, you can initialize the necessary information by using object initializers or by setting the properties directly. These are slightly verbose and don't process the provided input at all.

public class ObjectInitializerExamples
{
    public async Task CreateTopicAndCommentInRepository(IAnnotationRepository repository)
    {
        // Use object initializer for TopicCreation request object
        ITopicCreation topicCreation = new TopicCreation()
        {
            Title = "Topic Title",
            Description = "A descriptive description."
        };

        ITopic createdTopic = await repository.CreateTopicAsync(topicCreation);

        // Use object initializer for CommentCreation request object
        ICommentCreation commentCreation = new CommentCreation()
        {
            Text = "A comment."
        };

        var createdComment = await createdTopic.CreateCommentAsync(commentCreation);
    }

    public async Task UpdateTopicAndCommentInRepository(ITopic topicToUpdate, IComment comment, IAnnotationRepository repository)
    {
        // Use object initializer for TopicCreation request object
        var topicUpdate = new TopicUpdate(topicToUpdate);
        topicUpdate.Title = "Updated Title";
        topicUpdate.Description = "An updated description.";

        ITopic updatedTopic = await repository.UpdateTopicAsync(topicUpdate);

        // Use object initializer for CommentUpdate request object
        var commentUpdate = new CommentUpdate(comment);
        commentUpdate.Text = "An updated comment.";

        var updatedComment = await updatedTopic.UpdateCommentAsync(commentUpdate);
    }

}

The builders for the request object classes provide a fluent builder pattern allowing you to set all the information for the request object.

public class BuilderExamples
{
    public async Task CreateTopicInRepository(IAnnotationRepository repository)
    {
        // Use builder to populate topic creation information
        ITopicCreationBuilder topicCreationBuilder = new TopicCreationBuilder();
        topicCreationBuilder.SetTitle("Topic Title")
            .SetDescription("A descriptive description.");

        ITopic createdTopic = await repository.CreateTopicAsync(topicCreationBuilder.GetTopicCreation());

        // Use builder to populate comment creation information
        ICommentCreationBuilder commentCreationBuilder = new CommentCreationBuilder();
        commentCreationBuilder.SetText("A comment.");

        IComment createdComment = await createdTopic.CreateCommentAsync(commentCreationBuilder.GetCommentCreation());
    }

    public async Task UpdateTopicAndCommentInRepository(IAnnotationRepository repository)
    {
        // Use builder to populate topic update information
        ITopicUpdateBuilder topicUpdateBuilder = new TopicUpdateBuilder();
        topicUpdateBuilder.SetTitle("Updated Title")
            .SetDescription("An updated description.");

        ITopic updatedTopic = await repository.UpdateTopicAsync(topicUpdateBuilder.GetTopicUpdate());

        // Use builder to populate comment update information
        ICommentUpdateBuilder commentUpdateBuilder = new CommentUpdateBuilder();
        commentUpdateBuilder.SetText("An updated comment.");

        IComment updatedComment = await updatedTopic.UpdateCommentAsync(commentUpdateBuilder.GetCommentUpdate());
    }

}

The builders have the added advantage of offering some default calculations for the local and world transform fields available to topics. By providing the annotation Vector3 world position, the target camera's Transform, and information about the selected object in the form of an ITopicObject, the builder automatically calculates all the local and world transform fields for the topic. All transforms will be calculated relative to the world position and center of the Bounds specified in the ITopicObject.

public class BuilderTransformHelpersExamples
{
    public async Task<ITopic> CreateTopicInRepository(IAnnotationRepository repository,
        string instanceId,
        Vector3 topicPosition,
        Transform cameraTransform,
        ITopicObject objectToAnnotate)
    {
        // The CalculateAndSetTransforms method calculates all the transform fields
        // based on the camera and object transform information.
        ITopicCreationBuilder topicCreationBuilder = new TopicCreationBuilder();
        topicCreationBuilder.SetInstanceId(instanceId)
            .SetTitle("Topic Title")
            .SetDescription("A descriptive description.")
            .CalculateAndSetTransforms(topicPosition, cameraTransform, objectToAnnotate);

        ITopicCreation topicCreation = topicCreationBuilder.GetTopicCreation();
        ITopic createdTopic = await repository.CreateTopicAsync(topicCreation);

        return createdTopic;
    }

    public async Task<ITopic> UpdateTopicInRepository(IAnnotationRepository repository,
        ITopic topicToUpdate,
        string instanceId,
        Vector3 topicPosition,
        Transform cameraTransform,
        ITopicObject objectToAnnotate)
    {
        // The CalculateAndSetTransforms method calculates all the transform fields
        // based on the camera and object transform information.
        ITopicUpdateBuilder topicUpdateBuilder = new TopicUpdateBuilder(topicToUpdate);
        topicUpdateBuilder.SetInstanceId(instanceId)
            .SetTitle("Updated Title")
            .SetDescription("An description.")
            .CalculateAndSetTransforms(topicPosition, cameraTransform, objectToAnnotate);

        ITopicUpdate topicUpdate = topicUpdateBuilder.GetTopicUpdate();
        ITopic updatedTopic = await repository.UpdateTopicAsync(topicUpdate);

        return updatedTopic;
    }

}

If the default calculations aren't applicable for your implementation, you can also set the transforms with whatever calculation is appropriate for your use cases.