Flows and Views

The OWUIFlows and OWUIViews protocols provide two approaches to add the Conversation module and the general UI to your app: Flows and Views.


Either approach enables you to incorporate elements, such as PreConversation, Conversation, and Comment Creation experiences.

public protocol OWUIFlows {
    func preConversation(postId: OWPostId,
                         article: OWArticleProtocol,
                         presentationalMode: OWPresentationalMode,
                         additionalSettings: OWAdditionalSettingsProtocol,
                         callbacks: OWViewActionsCallbacks?,
                         completion: @escaping OWViewCompletion)

    func conversation(postId: OWPostId,
                      article: OWArticleProtocol,
                      presentationalMode: OWPresentationalMode,
                      additionalSettings: OWAdditionalSettingsProtocol,
                      callbacks: OWViewActionsCallbacks?,
                      completion: @escaping OWDefaultCompletion)

    func commentCreation(postId: OWPostId,
                         article: OWArticleProtocol,
                         presentationalMode: OWPresentationalMode,
                         additionalSettings: OWAdditionalSettingsProtocol,
                         callbacks: OWViewActionsCallbacks?,
                         completion: @escaping OWDefaultCompletion)

    func commentThread(postId: OWPostId,
                       article: OWArticleProtocol,
                       commentId: OWCommentId,
                       presentationalMode: OWPresentationalMode,
                       additionalSettings: OWAdditionalSettingsProtocol,
                       callbacks: OWViewActionsCallbacks?,
                       completion: @escaping OWDefaultCompletion)
}
public protocol OWUIViews {
    func preConversation(postId: OWPostId,
                         article: OWArticleProtocol,
                         additionalSettings: OWAdditionalSettingsProtocol,
                         callbacks: OWViewActionsCallbacks?,
                         completion: @escaping OWViewCompletion)

    func conversation(postId: OWPostId,
                      article: OWArticleProtocol,
                      additionalSettings: OWAdditionalSettingsProtocol,
                      callbacks: OWViewActionsCallbacks?,
                      completion: @escaping OWViewCompletion)

    func commentCreation(postId: OWPostId,
                         article: OWArticleProtocol,
                         commentCreationType: OWCommentCreationType,
                         additionalSettings: OWAdditionalSettingsProtocol,
                         callbacks: OWViewActionsCallbacks?,
                         completion: @escaping OWViewCompletion)

    func commentThread(postId: OWPostId,
                       article: OWArticleProtocol,
                       commentId: OWCommentId,
                       additionalSettings: OWAdditionalSettingsProtocol,
                       callbacks: OWViewActionsCallbacks?,
                       completion: @escaping OWViewCompletion)

    func reportReason(postId: OWPostId,
                      commentId: OWCommentId,
                      parentId: OWCommentId,
                      additionalSettings: OWAdditionalSettingsProtocol,
                      callbacks: OWViewActionsCallbacks?,
                      completion: @escaping OWViewCompletion)
}

Each implementation approach is explained in the Approaches section.



Approaches

Flows

This approach relies upon OpenWeb's default UI.

When implementing a Conversation with the Flows approach, you should configure one of the three flows in the following table.

FlowDescription
PreConversationShow a preview of comments at the end of an article to encourage engagement with a Conversation.

This is an entry point if to the full-page Conversation experience.
ConversationShow a full-page Conversation experience that initiates when the user triggers a call-to-action (CTA) button.
Comment ScreenNavigate directly to a page in which the end user can create a new comment
Comment ThreadShow a comment thread, starting from the root comment (commentId)

Use the following recipes to configure one of the flows.



Views

Implementing a Conversation module with the Views approach, gives you the ability to control the behavior between views.


In this workflow, the following occurs:

  1. A user takes an action, such as tapping a button.
  2. The user's action triggers OpenWeb's callbacks API to return a callback, signifying an event occurred.
  3. As the developer, you use this event to make another API call to OpenWeb.
  4. OpenWeb's API responds with the specific view element related to the API call.
  5. As the developer, you manage the presentation of the views or elements returned by OpenWeb. You can decide whether these views or elements are displayed or hidden from the user.

The following table lists the configurable views that are returned.

ViewDescription
PreConversationA preview of comments at the end of an article to encourage engagement with a Conversation
ConversationThe main view for the Conversation
Comment CreationA view for entering a comment
Comment ThreadShow a comment thread, starting from the root comment (commentId)
Report ReasonScreen listing possible report options

Use the OWViewActionsCallbacks to signal when to display these report options.

Use the following recipes to configure each view.



Methods

The following sections explain the methods available for flows and views.

commentCreation()

Starts the flow or retrieves the view for comment creation

var manager: OWManagerProtocol = OpenWeb.manager

// Retrieve flows layer
let flows: OWUIFlows = manager.ui.flows

flows.commentCreation(
  postId: "somePostId",
  article: article,
  presentationalMode: OWModelPresentationStyle,
  additionalSettings: commentCreationSettings,
  completion: commentClosure
)
var manager: OWManagerProtocol = OpenWeb.manager

// Retrieve views layer
let views: OWUIViews = manager.ui.views

views.commentCreation(
  postId: "somePostId",
  additionalSettings: additionalSettings,
  callbacks: OWViewActionsCallbacks,
  completion: commentCreationViewClosure
)

commentThread()

Starts the flow or retrieves the view for comment creation

var manager: OWManagerProtocol = OpenWeb.manager

// Retrieve flows layer
let flows: OWUIFlows = manager.ui.flows

flows.commentThread(
    postId: "somePostId", 
    article: article,
    commentId: "someCommentId",
    presentationalMode: .push(navigationController: navController),
    additionalSettings: additionalSettings,
    callbacks: nil,
    completion: commentThreadClosure
)
var manager: OWManagerProtocol = OpenWeb.manager

// Retrieve views layer
let views: OWUIViews = manager.ui.views

views.commentCreation(
    postId: "somePostId",
    article: article
    commentId: "someCommentId"
    additionalSettings: additionalSettings,
    callbacks: OWViewActionsCallbacks,
    completion: commentCreationViewClosure
)

conversation()

Starts the flow or retrieves the view for the conversation

var manager: OWManagerProtocol = OpenWeb.manager

// Retrieve flows layer
let flows: OWUIFlows = manager.ui.flows

flows.conversation(
  postId: "somePostId",
  article: article,
  presentationalMode: OWModelPresentationStyle,
  additionalSettings: conversationSettings,
  completion: conversationClosure
)
var manager: OWManagerProtocol = OpenWeb.manager

// Retrieve views layer
let views: OWUIViews = manager.ui.views

views.conversation(
  postId: "somePostId", 
  article: article,
  additionalSettings: additionalSettings,
  callbacks: OWViewActionsCallbacks,
  completion: conversationViewClosure
)

preConversation()

Starts the flow or retrieves the view for the pre-conversation

var manager: OWManagerProtocol = OpenWeb.manager

// Retrieve flows layer
let flows: OWUIFlows = manager.ui.flows

flows.preConversation(
  postId: "somePostId",
  article: article,
  presentationalMode: OWModelPresentationStyle,
  additionalSettings: preConversationSettings,
  completion: preConversationClosure
)
var manager: OWManagerProtocol = OpenWeb.manager

// Retrieve views layer
let views: OWUIViews = manager.ui.views

views.preConversation(
  postId: "somePostId", 
  article: article,
  additionalSettings: additionalSettings,
  callbacks: OWViewActionsCallbacks,
  completion: preConversationViewClosure
)

reportReason()

Retrieves the view for the report reason

var manager: OWManagerProtocol = OpenWeb.manager

// Retrieve views layer
let views: OWUIViews = manager.ui.views

views.reportReason(
  postId: "targetPostId",
  commentId: "targetCommentId",
  parentId: "parentCommentId",
  additionalSettings: additionalSettings,
  callbacks: reportActionsCallbacks,
  completion: reportViewClosure
)

Property Description
additionalSettings OWAdditionalSettingsProtocol Defines the settings of each component in a flow/view

Possible Values:
  • commentCreationSettings
  • conversationSettings
  • preConversationSettings
See: OWAdditionalSettings
article OWArticle Information about the article associated with the flow

See: Article
callbacks OWViewActionsCallbacks Handles the response to a user action after the action has occurred

See OWViewActionsCallbacks
commentId string Unique identifier of a comment
completion function Closure that handles the completion of the flow, success scenarios, and failure scenarios

The closure logic is defined in the relevant recipe.

Possible Values:
  • commentClosure
  • conversationClosure
  • preConversationClosure
parentId string Unique identifier of the parent comment
postId string Unique article identifier that is specific to the article page

The ideal postId has the following characteristics:
  • Aligns with the URL slug (an-article-title) or article ID (14325)
  • Is less than 50 characters, ideally 15 characters
  • Uses a combination of letters, number, dashes (-), or hyphens (_)
  • Except for the regex [^\w\s\-\:\.\$\~], does not include special characters
presentationalMode Possible Values:
  • .present(viewController: UIViewController, style: OWModalPresentationStyle)
  • .push(navigationController: UINavigationController)
See: OWModelPresentationStyle


Enumerations and Structs

OWAdditionalSettings

public protocol OWAdditionalSettingsProtocol {

    var preConversationSettings: OWPreConversationSettingsProtocol { get }

    var fullConversationSettings: OWConversationSettingsProtocol { get }

    var commentCreationSettings: OWCommentCreationSettingsProtocol { get }

    var commentThreadSettings: OWCommentThreadSettingsProtocol { get }

}
Settings Description
commentCreationSettings OWCommentCreationSettingsProtocol Sets the initial comment creation flow settings

Possible Values:
  • .regular: (default)
  • .floatingKeyboard
  • .light
fullconversationSettings OWConversationSettingsProtocol Sets the initial Conversation flow settings

Possible Values:
  • .regular: (default)
  • .compact
  • .custom(communityGuidelinesStyle: OWCommunityGuidelinesStyle, communityQuestionsStyle: OWCommunityQuestionsStyle, spacing: OWConversationSpacing)
preConversationSettings OWPreConversationSettingsProtocol Sets the initial preConversation flow settings

Possible Values:
  • .regular: (default)
  • .compact
  • .ctaButtonOnly
  • .ctaWithSummary
  • .custom(numberOfComments: Int = Metrics.defaultRegularNumberOfComments, communityGuidelinesStyle: OWCommunityGuidelinesStyle = Metrics.defaultCommunityGuidelinesStyle, communityQuestionsStyle: OWCommunityQuestionsStyle = Metrics.defaultCommunityQuestionsStyle)

OWCommunityGuidelinesStyle

Setting Description
OWCommunityGuidelinesStyle OWCommunityGuidelinesStyle Manner in which the screen is displayed

Possible Values:
  • .none
  • .compact
  • .regular

OWCommunityQuestionsStyle

Setting Description
OWCommunityQuestionsStyle OWCommunityQuestionsStyle Manner in which the screen is displayed

Possible Values:
  • .compact
  • .regular

OWConversationSpacing

Setting Description
OWConversationSpacing OWConversationSpacing Manner in which the screen is displayed

Possible Values:
  • .regular (default)
  • .compact
  • .custom(betweenComments: CGFloat, communityGuidelines: CGFloat, communityQuestions: CGFloat)
    The CGFloat values must be between 5.0 - 40.0.


OWError

Setting Description
OWError string Error returned

OWModalPresentationStyle

Setting Description
OWModalPresentationStyle string Manner in which the screen is displayed

Possible Values:
  • .fullscreen
  • .pageSheet

OWViewActionsCallbacks

typealias OWViewActionsCallbacks = (
  OWViewActionCallbackType, 
  OWViewSourceType, 
  String
) -> Void
Settings Description
OWViewActionCallbackType string User action performed or error that occurred

See OWViewActionCallbackType
OWViewSourceType string View from which information is received

See OWViewSourceType

OWViewActionCallbackType

Settings Description
OWViewActionCallbackType string User action performed or error that occurred

Possible Values:
  • .adClosed
  • .articleHeaderPressed
  • .closeConversationPressed
  • .closeReportReason
  • .communityGuidelinesPressed(url: URL)
  • .communityQuestionsPressed
  • .contentPressed
  • .error(_ error: OWError)
  • .openPublisherProfile(userId: String)
  • .openReportReason(commentId: OWCommentId, parentId: OWCommentId)
  • .postCommentPressed
  • .showMoreCommentsPressed
  • .writeCommentPressed

OWViewCompletion

typealias OWViewCompletion = (
  Result<UIView, 
  OWError>
) -> Void
Argument Description
OWError string Error returned

See: OWError

OWViewSourceType

Settings Description
OWViewSourceType string View from which information is received

Possible Values:
  • .commentCreation
  • .conversation
  • .preConversation