useCreateLibraryPageWithAuth()

Learn about the useCreateLibraryPageWithAuth() hook and how to enhance your embedded dashboards in your React applications using the `embed-dossier-mstr-react` package.

Import

import { useCreateLibraryPageWithAuth } from "embed-dossier-mstr-react"

Usage

import React, { useRef } from "react"
import { useCreateLibraryPageWithAuth } from "embed-dossier-mstr-react"

const LibraryPageComponent = () => {
  const containerRef = useRef<HTMLDivElement>(null)

  const { libraryPage, isAuthenticated, error } = useCreateLibraryPageWithAuth({
    serverUrlLibrary:
      "https://your-microstrategy-server.com/MicroStrategyLibrary",
    placeholder: containerRef.current,
    loginMode: "guest", // or "standard", "saml", "oidc", "ldap"
    // Include username and password for "standard" or "ldap" authentication
    // username: "username",
    // password: "password",
    config: {
      // Optional configuration options
      navigationBar: {
        enabled: true,
        gotoLibrary: true,
        title: "My Library",
      },
    },
  })

  // You can use libraryPage, isAuthenticated, and error as needed

  return (
    <>
      {error && <div className="error">{error}</div>}
      <div ref={containerRef} style={{ width: "100%", height: "600px" }}></div>
    </>
  )
}

export default LibraryPageComponent

Parameters

The hook accepts a single object with the following properties:

ParameterTypeRequiredDefaultDescription
serverUrlLibrarystringYes-The URL of the MicroStrategy Library server.
placeholderHTMLDivElement | nullYes-The DOM element where the Library page will be embedded.
loginMode"guest" | "standard" | "saml" | "oidc" | "ldap"Yes-The authentication mode to use.
usernamestringConditional-Required when loginMode is "standard" or "ldap".
passwordstringConditional-Required when loginMode is "standard" or "ldap".
configOmit<EmbedLibraryPageConfig, "placeholder" | "serverUrl">No-Additional configuration options for the Library page.

Config Options

The config parameter can include any of the MicroStrategy Library page embedding options except for placeholder and serverUrl which are provided separately.

Common configuration options include:

{
  // Enable or disable the navigation bar
  navigationBar: {
    enabled: boolean,
    gotoLibrary: boolean,
    title: string,
    // Additional navigation bar options...
  },

  // Control which items appear in the library
  filters: {
    // Filter options...
  },

  // Control which actions are available
  enabledActions: {
    // Action settings...
  }
}

Return Value

The hook returns an object with the following properties:

PropertyTypeDescription
libraryPageEmbedLibraryPage | nullThe embedded Library page instance. This is null until the page is successfully initialized.
isAuthenticatedbooleanIndicates whether authentication was successful.
errorstring | nullError message if authentication or initialization fails, or null if there is no error.

Authentication Modes

Guest Authentication

const { libraryPage, isAuthenticated, error } = useCreateLibraryPageWithAuth({
  serverUrlLibrary: "https://your-server.com/MicroStrategyLibrary",
  placeholder: containerRef.current,
  loginMode: "guest",
})

Standard Authentication

const { libraryPage, isAuthenticated, error } = useCreateLibraryPageWithAuth({
  serverUrlLibrary: "https://your-server.com/MicroStrategyLibrary",
  placeholder: containerRef.current,
  loginMode: "standard",
  username: "username",
  password: "password",
})

SAML Authentication

const { libraryPage, isAuthenticated, error } = useCreateLibraryPageWithAuth({
  serverUrlLibrary: "https://your-server.com/MicroStrategyLibrary",
  placeholder: containerRef.current,
  loginMode: "saml",
})

OIDC Authentication

const { libraryPage, isAuthenticated, error } = useCreateLibraryPageWithAuth({
  serverUrlLibrary: "https://your-server.com/MicroStrategyLibrary",
  placeholder: containerRef.current,
  loginMode: "oidc",
})

LDAP Authentication

const { libraryPage, isAuthenticated, error } = useCreateLibraryPageWithAuth({
  serverUrlLibrary: "https://your-server.com/MicroStrategyLibrary",
  placeholder: containerRef.current,
  loginMode: "ldap",
  username: "username",
  password: "password",
})

Working with the Library Page

Once the Library page is initialized, you can use the libraryPage object to interact with it:

// Example: Navigate to a specific folder
if (libraryPage) {
  libraryPage.navigateToFolder("FOLDER_ID")
}

// Example: Check current folder
if (libraryPage) {
  const currentFolder = await libraryPage.getCurrentFolder()
  console.log("Current folder:", currentFolder)
}

Error Handling

The hook provides error information that you can use to display appropriate messages to users:

const { error } = useCreateLibraryPageWithAuth({
  // configuration...
})

return (
  <div>
    {error && <div className="alert alert-danger">{error}</div>}
    <div ref={containerRef} style={{ height: "600px" }}></div>
  </div>
)

Dependencies

This hook internally uses the useLoadMstrSDK hook to load the MicroStrategy SDK before attempting to authenticate and embed the Library page.