Go to openweb.com

Flows and Views

Suggest Edits


OpenWeb provides two approaches to add the Conversation module and the general UI to your app: Flows and Views.


Each implementation approach is explained in the Approaches section.


Approaches

Flows

This approach relies upon OpenWeb's default UI. 

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)
}

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

Use the following recipes to configure one of the flows.

📱
iOS SDK: PreConversation Flow
Open Recipe
📱
iOS SDK: Conversation Flow
Open Recipe
📱
iOS SDK: Comment Creation Flow
Open Recipe



Views

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

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)
}

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 ScreenA view for entering a comment

Use the following recipes to configure each view.

📱
iOS SDK: PreConversation View
Open Recipe
📱
iOS SDK: Conversation View
Open Recipe
📱
iOS SDK: Comment Creation View
Open Recipe

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
)

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
)

Property Description
additionalSettings string 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
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
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

Settings Description
commentCreationSettings string Sets the initial comment creation flow settings

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

Possible Values:
  • .regular: (default)
  • .compact
  • .custom(communityGuidelinesStyle: OWCommunityGuidelinesStyle, communityQuestionsStyle: OWCommunityQuestionsStyle, spacing: OWConversationSpacing)
preConversationSettings string 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

Updated 8 days ago

Next Step