LgDocument

LgDocument downloads a document from a controller URI, creates a blob URL on the client side, and displays it as an image, video, or embedded frame. Use it to present files protected by Lagoon authentication or public documents interpretable by the browser.

<LgDocument ControllerUri="api/documents/preview/42" />

• Namespace : Lagoon.UI.Components
• Inherits from : LgComponentBase
• NuGet package : Lagoon.UI

Usage

Endpoint contract

ControllerUri is called via GET by the component's JavaScript. Unless AnonymousRequest is true, the component requests an access token and sends it to the endpoint. When AllowDelete is true, the same URI must also accept DELETE.

GET — Download the document (ControllerUri)

DocumentsController.cs

[ApiController]
[Route("api/documents")]
public class DocumentsController : LgControllerBase
{
    // Business service responsible for retrieving document metadata and server path.
    private readonly DocumentService _documentService;

    // Initializes the controller with the document access service.
    public DocumentsController(DocumentService documentService)
    {
        _documentService = documentService;
    }

    // Returns the stream expected by LgDocument to create the blob URL on the client side.
    [HttpGet("preview/{documentId:guid}")]
    public async Task<ActionResult<FileStream>> PreviewAsync(Guid documentId)
    {
        DocumentFile document = await _documentService.GetFileAsync(documentId);
        return FileContent(document.Path, document.ContentType, document.FileName, false);
    }
}

• Input : route or query parameters defined by your URI, for example Guid documentId.
• Output : file content, typically ActionResult<FileStream> returned via FileContent(...) from LgControllerBase.
• Error : let LgControllerBase produce a consistent error response via Problem(ex) if you wrap your logic in a try / catch.

DELETE — Delete the document (ControllerUri)

DocumentsController.cs

[ApiController]
[Route("api/documents")]
public class DocumentsController : LgControllerBase
{
    // Business service responsible for deleting the file and its metadata.
    private readonly DocumentService _documentService;

    // Initializes the controller with the document access service.
    public DocumentsController(DocumentService documentService)
    {
        _documentService = documentService;
    }

    // Deletes the document when AllowDelete is enabled on LgDocument.
    [HttpDelete("preview/{documentId:guid}")]
    public async Task<IActionResult> DeleteAsync(Guid documentId)
    {
        await _documentService.DeleteAsync(documentId);
        return NoContent();
    }
}

• Input : the same parameters as the URI shown by ControllerUri.
• Output : any successful HTTP response is suitable; the component then triggers OnDelete if a handler is defined.

Display a protected image

By default, the request is authenticated. Kind="DocumentKind.Image" renders the document in an internal image element. For an image, ClickBehaviour can open the image in a modal, in a new tab, or trigger its download.

GalleryPage.razor

<LgDocument Kind="DocumentKind.Image"
            ControllerUri="@ImageUri"
            Filename="@ImageFileName"
            ClickBehaviour="DocumentClickBehaviour.OpenInModal"
            Tooltip="#OpenImagePreview" />

GalleryPage.razor.cs

public partial class GalleryPage : LgPage
{
    // URI of the controller that returns the binary content of the image.
    private string ImageUri { get; set; } = "api/documents/preview/4cf9aaf7-4d2f-4d68-9db7-e1285d1b5f61";

    // Name proposed when downloading or opening the document.
    private string ImageFileName { get; set; } = "image-preview.png";
}

Display a PDF or embedded document

The default value of Kind is DocumentKind.IFrame. It is suitable for PDFs and formats that the browser can display in an embedded frame.

ContractPage.razor

<LgDocument ControllerUri="@ContractUri"
            Filename="@ContractFileName"
            ShowDownloadProgression="true" />

ContractPage.razor.cs

public partial class ContractPage : LgPage
{
    // URI of the controller that provides the PDF to preview.
    private string ContractUri { get; set; } = "api/documents/preview/2fbb8c23-9f9f-4e42-b8b4-39c7cf67290b";

    // File name used when the user opens or downloads the document.
    private string ContractFileName { get; set; } = "contract.pdf";
}

Display a video

DocumentKind.Video renders the document as a video. Reserve this mode for reasonable-sized files: the component downloads the entire file before display.

VideoPage.razor

<LgDocument Kind="DocumentKind.Video"
            ControllerUri="@VideoUri"
            Filename="@VideoFileName"
            VideoAutoPlay="true"
            VideoControlsDisabled="false" />

VideoPage.razor.cs

public partial class VideoPage : LgPage
{
    // URI of the controller that returns the complete video file.
    private string VideoUri { get; set; } = "api/documents/preview/7f6202fa-b4bb-4e84-8918-0532feef8f7e";

    // Name proposed when downloading the video.
    private string VideoFileName { get; set; } = "training-video.mp4";
}

Customize loading and rendering

LoaderContent receives the download progress, with -1 in case of error. ChildContent receives the blob URL of the document and replaces the internal rendering.

CustomDocumentPage.razor

<LgDocument ControllerUri="@DocumentUri" ShowDownloadProgression="true">
    <LoaderContent Context="progression">
        <LgCircleProgress Value="@Math.Max(progression, 0)" Min="0" Max="100" />
    </LoaderContent>
    <ChildContent Context="blobUrl">
        <LgButton Text="#OpenDocument"
                  Kind="ButtonKind.Link"
                  Uri="@blobUrl"
                  Target="_blank" />
    </ChildContent>
</LgDocument>

CustomDocumentPage.razor.cs

public partial class CustomDocumentPage : LgPage
{
    // URI of the controller called to create the blob URL passed to the custom content.
    private string DocumentUri { get; set; } = "api/documents/preview/854b69f6-5446-4c3d-9c63-99e8c3e3f4ef";
}

Cache multiple documents

Wrap multiple LgDocument components in LgDocumentsCache to reuse already-downloaded blob URLs. A reference to the cache allows you to remove an entry with Remove(...) or clear everything with Clear().

CachedGalleryPage.razor

<LgDocumentsCache @ref="DocumentsCache">
    <LgDocument Kind="DocumentKind.Image"
                ControllerUri="@FirstImageUri"
                Filename="@FirstImageFileName" />
    <LgDocument Kind="DocumentKind.Image"
                ControllerUri="@SecondImageUri"
                Filename="@SecondImageFileName" />
</LgDocumentsCache>

<LgButton Text="#RefreshDocuments" OnClick="RefreshDocumentsAsync" />

CachedGalleryPage.razor.cs

public partial class CachedGalleryPage : LgPage
{
    // Reference to the cache that stores the blob URLs of child documents.
    private LgDocumentsCache DocumentsCache { get; set; }

    // URI of the first document displayed in the gallery.
    private string FirstImageUri { get; set; } = "api/documents/preview/14153022-5d8f-45fe-9305-01dd176d60ce";

    // Name of the first document displayed in the gallery.
    private string FirstImageFileName { get; set; } = "first-image.png";

    // URI of the second document displayed in the gallery.
    private string SecondImageUri { get; set; } = "api/documents/preview/54db6764-0dd9-4531-9826-6490e29f26bf";

    // Name of the second document displayed in the gallery.
    private string SecondImageFileName { get; set; } = "second-image.png";

    // Clears the cache to force a new download on the next render.
    private Task RefreshDocumentsAsync(ActionEventArgs args)
    {
        DocumentsCache.Clear();
        return Task.CompletedTask;
    }
}

Properties

Name	Type	Default	Declared in	Description
ChildContent	RenderFragment<string>	null	LgDocument	Custom fragment receiving the blob URL of the downloaded document.
LoaderContent	RenderFragment<int>	null	LgDocument	Custom fragment displayed during download; the value received is the progress.
AllowDelete	bool	false	LgDocument	Displays a delete action and sends an HTTP DELETE request to ControllerUri.
AnonymousRequest	bool	false	LgDocument	Disables adding the authentication token to the download request.
AdditionalAttributes	IReadOnlyDictionary<string, object>	null	LgDocument	Additional attributes captured from the component markup.
ClickBehaviour	DocumentClickBehaviour	DocumentClickBehaviour.None	LgDocument	Behavior applied when clicking on the rendered image.
ControllerUri	string	null	LgDocument	Controller URI used to download the document and, if allowed, delete it.
CssClass	string	null	LgDocument	CSS classes added to the document container.
Filename	string	null	LgDocument	File name used for the modal, opening in a new tab, or download.
Kind	DocumentKind	DocumentKind.IFrame	LgDocument	Type of rendering used to present the document.
OnClick	EventCallback	default	LgDocument	Public event declared for a user click on the document.
OnDelete	EventCallback	default	LgDocument	Event triggered after a successful HTTP deletion.
ShowDownloadProgression	bool	false	LgDocument	Enables download progress tracking.
Tooltip	string	null	LgDocument	Tooltip associated with the document. Use a #... key.
TooltipIsHtml	bool	false	LgDocument	Indicates that the tooltip content is in HTML format.
VideoAutoPlay	bool	false	LgDocument	Requests autoplay when the document is a video.
VideoControlsDisabled	bool	false	LgDocument	Disables video controls when the document is a video.

Events

Name	Type	Description
OnClick	EventCallback	Public event declared for user click on the document. The internal rendering uses ClickBehaviour for the built-in click action on an image.
OnDelete	EventCallback	Triggered after a successful DELETE call to ControllerUri.

Associated enumerations

DocumentClickBehaviour

Default value: DocumentClickBehaviour.None.

Value	Description
None	Does nothing when clicking on the image.
OpenInModal	Opens the document in a Lagoon modal when clicking on the image.
OpenInNewTab	Opens the document in a new browser tab when clicking on the image.
Download	Triggers the download of the document when clicking on the image.

DocumentKind

Default value: DocumentKind.IFrame.

Value	Description
IFrame	Renders the document in an embedded frame.
Image	Renders the document as an image.
Video	Renders the document as a video; the entire file is downloaded before display.

Accessibility

Provide Tooltip with a translated key when the document or delete action needs explanation. For important images, supplement AdditionalAttributes with alternative text or provide an accessible ChildContent. The IFrame mode and blob URLs depend on browser support: provide a link or download action for critical documents.

Related components

• LgDocumentsCache : caches documents downloaded by multiple child LgDocument components.
• LgInputFile : uploads files that LgDocument can then display.
• LgButton : provides a custom action in ChildContent.
• LgCircleProgress : displays custom progress via LoaderContent.