DocumentCard: DocumentCard

In Appsilon/shiny.fluent: Microsoft Fluent UI for Shiny Apps

DocumentCard

Description

A document card (DocumentCard) represents a file, and contains additional metadata or actions. This offers people a richer view into a file than the typical grid view.

For more details and examples visit the official docs. The R package cannot handle each and every case, so for advanced use cases you need to work using the original docs to achieve the desired result.

Usage

DocumentCard(...)

DocumentCardActions(...)

DocumentCardActivity(...)

DocumentCardDetails(...)

DocumentCardImage(...)

DocumentCardLocation(...)

DocumentCardLogo(...)

DocumentCardPreview(...)

DocumentCardStatus(...)

DocumentCardTitle(...)

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.

Details

• actions IButtonProps[]
  The actions available for this document.

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCardActions>⁠
  Gets the component ref.

• styles ⁠IStyleFunctionOrObject<IDocumentCardActionsStyleProps, IDocumentCardActionsStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• views Number
  The number of views this document has received.

• activity string
  Describes the activity that has taken place, such as "Created Feb 23, 2016".

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCardActivity>⁠
  Gets the component ref.

• people IDocumentCardActivityPerson[]
  One or more people who are involved in this activity.

• styles ⁠IStyleFunctionOrObject<IDocumentCardActivityStyleProps, IDocumentCardActivityStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCardDetails>⁠
  Gets the component ref.

• styles ⁠IStyleFunctionOrObject<IDocumentCardDetailsStyleProps, IDocumentCardDetailsStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCardImage>⁠
  Gets the component ref.

• height number
  If provided, forces the preview image to be this height.

• iconProps IIconProps
  The props for the icon associated with this document type.

• imageFit ImageFit
  Used to determine how to size the image to fit the dimensions of the component. If both dimensions are provided, then the image is fit using ImageFit.scale, otherwise ImageFit.none is used.

• imageSrc string
  Path to the preview image.

• styles ⁠IStyleFunctionOrObject<IDocumentCardImageStyleProps, IDocumentCardImageStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• width number
  If provided, forces the preview image to be this width.

• ariaLabel string
  Aria label for the link to the document location.

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCardLocation>⁠
  Gets the component ref.

• location string
  Text for the location of the document.

• locationHref string
  URL to navigate to for this location.

• onClick ⁠(ev?: React.MouseEvent<HTMLElement>) => void⁠
  Function to call when the location is clicked.

• styles ⁠IStyleFunctionOrObject<IDocumentCardLocationStyleProps, IDocumentCardLocationStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCardLogo>⁠
  Gets the component ref.

• logoIcon string
  Describes DocumentCard Logo badge.

• logoName string
  Describe Logo name, optional.

• styles ⁠IStyleFunctionOrObject<IDocumentCardLogoStyleProps, IDocumentCardLogoStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCardPreview>⁠
  Gets the component ref.

• getOverflowDocumentCountText ⁠(overflowCount: number) => string⁠
  The function return string that will describe the number of overflow documents. such as (overflowCount: number) =\> ⁠+${ overflowCount } more⁠,

• previewImages IDocumentCardPreviewImage[]
  One or more preview images to display.

• styles ⁠IStyleFunctionOrObject<IDocumentCardPreviewStyleProps, IDocumentCardPreviewStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• accentColor string
  Hex color value of the line below the card, which should correspond to the document type. This should only be supplied when using the 'compact' card layout.

Deprecated at v4.17.1, to be removed at \>= v5.0.0.

• children React.ReactNode
  Child components to render within the card.

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCard>⁠
  Optional callback to access the IDocumentCard interface. Use this instead of ref for accessing the public methods and properties of the component.

• onClick ⁠(ev?: React.SyntheticEvent<HTMLElement>) => void⁠
  Function to call when the card is clicked or keyboard Enter/Space is pushed.

• onClickHref string
  A URL to navigate to when the card is clicked. If a function has also been provided, it will be used instead of the URL.

• onClickTarget string
  A target browser context for opening the link. If not specified, will open in the same tab/window.

• role string
  Aria role assigned to the documentCard (Eg. button, link). Use this to override the default assignment.

• styles ⁠IStyleFunctionOrObject<IDocumentCardStyleProps, IDocumentCardStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• type DocumentCardType
  The type of DocumentCard to display.

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCardStatus>⁠
  Gets the component ref.

• status string
  Describe status information. Required field.

• statusIcon string
  Describes DocumentCard status icon.

• styles ⁠IStyleFunctionOrObject<IDocumentCardStatusStyleProps, IDocumentCardStatusStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• className string
  Optional override class name

• componentRef ⁠IRefObject<IDocumentCardTitle>⁠
  Gets the component ref.

• shouldTruncate boolean
  Whether we truncate the title to fit within the box. May have a performance impact.

• showAsSecondaryTitle boolean
  Whether show as title as secondary title style such as smaller font and lighter color.

• styles ⁠IStyleFunctionOrObject<IDocumentCardTitleStyleProps, IDocumentCardTitleStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• theme ITheme
  Theme provided by HOC.

• title string
  Title text. If the card represents more than one document, this should be the title of one document and a "+X" string. For example, a collection of four documents would have a string of "Document.docx +3".

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app.

Best practices

Layout

• Use this control to represent Office documents or other files in aggregate views, such as when you're showing someone’s most trending document.

• Incorporate metadata that is relevant and useful in this particular view. A card can be specialized to be about the document’s latest changes, or about the document’s popularity, as you see fit.

• Use a document card when you're illustrating an event that encompasses multiple files. For example, a card can be configured to represent a single upload action when adding more than one file.

• Don’t use a document card in views where someone is likely to be performing bulk operations in files, or when the list may get very long. Specifically, if you’re showing all the items inside an actual folder, a card may be overkill because the majority of the items in the folder may not have interesting metadata.

• Don’t use a document card if space is at a premium or you can’t show relevant and timely commands or metadata. Cards are useful because they can expose on-item interactions like “Share” buttons or view counts. If your app does not need this, show a simple grid or list of items instead, which are easier to scan.

Examples

# Example 1
library(shiny)
library(shiny.fluent)

title <- "Long_file_name_with_underscores_used_to_separate_all_of_the_words"

previewImages <- list(
  list(
    previewImageSrc = "https://picsum.photos/318/196",
    width = 318,
    height = 196
  )
)

ui <- function(id) {
  ns <- NS(id)
  DocumentCard(
    DocumentCardPreview(previewImages = previewImages),
    DocumentCardTitle(
      title = title,
      shouldTruncate = TRUE
    ),
    DocumentCardActivity(
      activity = "Created a few minutes ago",
      people = list(list(name = "Annie Lindqvist"))
    )
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {})
}

if (interactive()) {
  shinyApp(ui("app"), function(input, output) server("app"))
}

# Example 2
library(shiny)
library(shiny.fluent)

# Using icons in DocumentCardActions
ui <- function(id) {
  previewImages <- list(
    list(
      previewImageSrc = "https://picsum.photos/318/196",
      width = 318,
      height = 200
    )
  )
  fluidPage(
    DocumentCard(
      DocumentCardPreview(previewImages = previewImages),
      DocumentCardTitle(
        title = "Card",
        shouldTruncate = TRUE
      ),
      DocumentCardActivity(
        activity = "2022-03-23",
        people = list(list(name = "Annie Lindqvist"))
      ),
      DocumentCardActions(
        actions = list(
          list(
            iconProps = list(iconName = "Share"),
            onClick = JS("function() { alert('share icon clicked') }")
          ),
          list(
            iconProps = list(iconName = "Pin"),
            onClick = JS("function() { alert('pin icon clicked') }")
          ),
          list(
            iconProps = list(iconName = "Ringer"),
            onClick = JS("function() { alert('ringer icon clicked') }")
          )
        )
      )
    )
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {})
}

if (interactive()) {
  shinyApp(ui("app"), function(input, output) server("app"))
}

Appsilon/shiny.fluent documentation built on June 4, 2024, 7:02 p.m.