Skip to content

Commit

Permalink
Helper methods for card view parameters
Browse files Browse the repository at this point in the history
  • Loading branch information
Alex Terentiev committed Oct 16, 2023
1 parent 37592c8 commit ff04905
Showing 1 changed file with 291 additions and 2 deletions.
293 changes: 291 additions & 2 deletions libraries/Microsoft.Bot.Schema/SharePoint/CardView/CardViewParameters.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Newtonsoft.Json;

Expand All @@ -13,6 +14,13 @@ namespace Microsoft.Bot.Schema.SharePoint
/// </summary>
public class CardViewParameters
{
/// <summary>
/// Initializes a new instance of the <see cref="CardViewParameters"/> class.
/// </summary>
protected CardViewParameters()
{
}

/// <summary>
/// Gets or sets card view type.
/// </summary>
Expand All @@ -28,11 +36,13 @@ public class CardViewParameters
public CardImage Image { get; set; }

/// <summary>
/// Gets card view title area (card bar) components.
/// Gets or sets card view title area (card bar) components.
/// </summary>
/// <value>Card bar area components.</value>
[JsonProperty(PropertyName = "cardBar")]
public IEnumerable<CardBarComponent> CardBar { get; } = new CardBarComponent[1];
#pragma warning disable CA2227
public IList<CardBarComponent> CardBar { get; set; }
#pragma warning restore CA2227

/// <summary>
/// Gets or sets card view header area components.
Expand All @@ -54,5 +64,284 @@ public class CardViewParameters
/// <value>Card footer area components.</value>
[JsonProperty(PropertyName = "footer")]
public IEnumerable<BaseCardComponent> Footer { get; set; }

/// <summary>
/// Helper method to create a Basic Text Card View.
/// </summary>
/// <param name="cardBar">Card bar component.</param>
/// <param name="header">Text component to display as header.</param>
/// <param name="footer">Up to two buttons or text input to display as footer.</param>
/// <returns>Card view configuration.</returns>
/// <remarks>The Basic Text card view displays the following:
/// - Card bar
/// - One primary text field
/// - Zero or one button in the Medium card size, up to two buttons in Large card size; or text input.
/// </remarks>
public static CardViewParameters PrimaryTextCardViewParameters(
CardBarComponent cardBar,
CardTextComponent header,
IList<BaseCardComponent> footer)
{
// Validate parameters
if (cardBar == null)
{
throw new ArgumentNullException(nameof(cardBar));
}

if (header == null)
{
throw new ArgumentNullException(nameof(header));
}

ValidateGenericCardViewFooterConfiguration(footer);

return new CardViewParameters()
{
CardViewType = "text",
CardBar = new List<CardBarComponent> { cardBar },
Header = new List<CardTextComponent> { header },
Footer = footer
};
}

/// <summary>
/// Helper method to create a Primary Text Card View.
/// </summary>
/// <param name="cardBar">Card bar component.</param>
/// <param name="header">Text component to display as header.</param>
/// <param name="body">Text component to display as body.</param>
/// <param name="footer">Up to two buttons or text input to display as footer.</param>
/// <returns>Card view configuration.</returns>
/// <remarks>The Primary Text card view displays the following:
/// - Card bar
/// - One primary text field
/// - One description text field
/// - Zero or one button in the Medium card size, up to two buttons in Large card size; or text input.
/// </remarks>
public static CardViewParameters PrimaryTextCardViewParameters(
CardBarComponent cardBar,
CardTextComponent header,
CardTextComponent body,
IList<BaseCardComponent> footer)
{
// Validate parameters
if (cardBar == null)
{
throw new ArgumentNullException(nameof(cardBar));
}

if (header == null)
{
throw new ArgumentNullException(nameof(header));
}

if (body == null)
{
throw new ArgumentNullException(nameof(header));
}

ValidateGenericCardViewFooterConfiguration(footer);

return new CardViewParameters()
{
CardViewType = "text",
CardBar = new List<CardBarComponent> { cardBar },
Header = new List<CardTextComponent> { header },
Body = new List<CardTextComponent> { body },
Footer = footer
};
}

/// <summary>
/// Helper method to create an Image Card View.
/// </summary>
/// <param name="cardBar">Card bar component.</param>
/// <param name="header">Text component to display as header.</param>
/// <param name="footer">Up to two buttons or text input to display as footer.</param>
/// <param name="image">Image to display.</param>
/// <returns>Card view configuration.</returns>
/// <remarks>The Image Card view displays the following:
/// - Card bar
/// - One primary text field
/// - One image
/// - Zero buttons in the Medium card size, up to two buttons in Large card size; or text input.
/// </remarks>
public static CardViewParameters ImageCardViewParameters(
CardBarComponent cardBar,
CardTextComponent header,
IList<BaseCardComponent> footer,
CardImage image)
{
// Validate parameters
if (cardBar == null)
{
throw new ArgumentNullException(nameof(cardBar));
}

if (header == null)
{
throw new ArgumentNullException(nameof(header));
}

if (image == null)
{
throw new ArgumentNullException(nameof(image));
}

ValidateGenericCardViewFooterConfiguration(footer);

return new CardViewParameters()
{
CardViewType = "text",
CardBar = new List<CardBarComponent> { cardBar },
Header = new List<CardTextComponent> { header },
Image = image,
Footer = footer
};
}

/// <summary>
/// Helper method to create a Text Input Card View.
/// </summary>
/// <param name="cardBar">Card bar component.</param>
/// <param name="header">Text component to display as header.</param>
/// <param name="body">Text input component to display as body.</param>
/// <param name="footer">Up to two buttons to display as footer.</param>
/// <param name="image">Optional image to display.</param>
/// <returns>Card view configuration.</returns>
/// /// <remarks>The Text Input Card view displays the following:
/// - Card bar
/// - One primary text field
/// - Zero or one image
/// - Zero text input in Medium card size if image is presented, one text input in Medium card size if no image is presented, one text input in Large card size
/// - Zero buttons in the Medium card size if image is presented, one button in Medium card size if no image is presented, up to two buttons in Large card size; or text input.
/// </remarks>
public static CardViewParameters TextInputCardViewParameters(
CardBarComponent cardBar,
CardTextComponent header,
CardTextInputComponent body,
IList<CardButtonComponent> footer,
CardImage image)
{
// Validate parameters
if (cardBar == null)
{
throw new ArgumentNullException(nameof(cardBar));
}

if (header == null)
{
throw new ArgumentNullException(nameof(header));
}

if (body == null)
{
throw new ArgumentNullException(nameof(body));
}

if (footer.Count > 2)
{
throw new ArgumentException("Card view footer must contain up to two buttons.", nameof(footer));
}

return new CardViewParameters()
{
CardViewType = "textInput",
CardBar = new List<CardBarComponent> { cardBar },
Header = new List<CardTextComponent> { header },
Body = new List<CardTextInputComponent> { body },
Image = image,
Footer = footer
};
}

/// <summary>
/// Helper method to create a Search Card View.
/// </summary>
/// <param name="cardBar">Card bar component.</param>
/// <param name="header">Text component to display as header.</param>
/// <param name="body">Search box to display as body.</param>
/// <param name="footer">Search footer component to display as footer.</param>
/// <returns>Card view configuration.</returns>
/// /// <remarks>The Search Card view displays the following:
/// - Card bar
/// - One primary text field
/// - One search box
/// - One search box footer.
/// </remarks>
public static CardViewParameters SearchCardViewParameters(
CardBarComponent cardBar,
CardTextComponent header,
CardSearchBoxComponent body,
CardSearchFooterComponent footer)
{
// Validate parameters
if (cardBar == null)
{
throw new ArgumentNullException(nameof(cardBar));
}

if (header == null)
{
throw new ArgumentNullException(nameof(header));
}

if (body == null)
{
throw new ArgumentNullException(nameof(body));
}

if (footer == null)
{
throw new ArgumentNullException(nameof(footer));
}

return new CardViewParameters()
{
CardViewType = "search",
CardBar = new List<CardBarComponent> { cardBar },
Header = new List<CardTextComponent> { header },
Body = new List<CardSearchBoxComponent> { body },
Footer = new List<CardSearchFooterComponent> { footer }
};
}

private static void ValidateGenericCardViewFooterConfiguration(IList<BaseCardComponent> footer)
{
if (footer == null)
{
// footer can be empty
return;
}

int componentsCount = footer.Count;

bool hasError;

if (componentsCount == 0)
{
return;
}
else if (componentsCount > 2)
{
// we don't support more than 2 components in the footer.
hasError = true;
}
else if (componentsCount == 2)
{
// both components should be buttons.
hasError = !(footer[0] is CardButtonComponent) || !(footer[1] is CardButtonComponent);
}
else
{
// single component should be either a button or a text input
hasError = !(footer[0] is CardButtonComponent) || !(footer[0] is CardTextInputComponent);
}

if (hasError)
{
throw new ArgumentException("Card view footer must contain up to two buttons or text input", nameof(footer));
}
}
}
}

0 comments on commit ff04905

Please sign in to comment.