DashboardWidgetModel

View as Markdown

DashboardWidgetModel

DashboardWidgetModel holds the HTML file, title, width, state, and tags of a dashboard widget that you upload with the Upload method of Extension. A dashboard widget appears on the stack dashboard.

When to Use This Class: Use this class when the code of your dashboard widget is an HTML file on disk or in memory. It is also the only SDK model that sets the enable and default_width settings of a dashboard widget.

Conceptual Role: Implements IExtensionInterface, the interface that Extension.Upload takes. It builds the multipart/form-data body of the upload request and sets extension[type] to dashboard.

Returns: DashboardWidgetModel. The file and settings of a dashboard widget upload.

Properties

NameTypeRequiredDefaultDescription
TitlestringYesThe title constructor argumentName of the widget. Sent as extension[title], and as the file name of the upload.
Tagsstring?NoThe tags constructor argument, or null if you omit itTags for the widget. Sent as extension[tags] when it is not null.
ContentTypestringYesThe contentType constructor argumentMIME type of the uploaded file, for example text/html.
DefaultWidthstring?NoThe defaultWidth constructor argument, or null if you omit itWidth of the widget on the dashboard, full or half. Sent as extension[default_width] when it is not null.
EnableboolNoThe isEnable constructor argument, or false if you omit itWhether the dashboard shows the widget. Always sent as extension[enable].

Class-Level Notes

How the SDK builds the upload body.

Disabled by default.

  • isEnable defaults to false, so the SDK sends extension[enable] as false unless you pass true. Pass true to show the widget on the dashboard.

The interface it implements.

  • IExtensionInterface extends IUploadInterface. It requires Title, Tags, ContentType, and GetHttpContent().

Method Index

Method NameReturnsDescription
DashboardWidgetModelA new dashboard widget upload model.Creates the model from a file path, stream, byte array, or ByteArrayContent.
GetHttpContentThe multipart form body of the upload.Builds the request body that Upload sends.

Class-Level Snippet

The snippet below builds an enabled, half-width dashboard widget from an HTML file and uploads it to the stack.

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models.CustomExtension;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

DashboardWidgetModel model = new DashboardWidgetModel("<FILE_PATH>", "text/html", "Publishing Stats", true, "half");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Extension().Upload(model);
    Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["uid"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Methods

Each method of the DashboardWidgetModel class has its own section below, with its parameters, validation rules, behavior, and examples.

DashboardWidgetModel

DashboardWidgetModel creates a dashboard widget upload model from an HTML file, a stream, a byte array, or a ByteArrayContent.

NameTypeDescription
filePath (required)string

Path of the HTML file to upload.

Default: Not applicable
contentType (required)string

MIME type of the file, for example text/html.

Default: Not applicable
title (required)string

Name of the widget.

Default: Not applicable
isEnablebool

Whether the dashboard shows the widget.

Default: false
defaultWidthstring?

Width on the dashboard, full or half.

Default: null
tagsstring?

Tags for the widget.

Default: null
stream (required)Stream

Stream that holds the HTML file.

Default: Not applicable
bytes (required)byte[]

Content of the HTML file.

Default: Not applicable
byteArray (required)ByteArrayContent

HTTP content that holds the HTML file.

Default: Not applicable

Returns: DashboardWidgetModel. A new dashboard widget upload model.

Overloads

  • DashboardWidgetModel(string filePath, string contentType, string title, bool isEnable = false, string? defaultWidth = null, string? tags = null)
  • DashboardWidgetModel(Stream stream, string contentType, string title, bool isEnable = false, string? defaultWidth = null, string? tags = null)
  • DashboardWidgetModel(byte[] bytes, string contentType, string title, bool isEnable = false, string? defaultWidth = null, string? tags = null)
  • DashboardWidgetModel(ByteArrayContent byteArray, string contentType, string title, bool isEnable = false, string? defaultWidth = null, string? tags = null)

Validation

  • Throws ArgumentNullException (parameter title) if title is null, because the API needs a title for the extension.
  • Throws ArgumentNullException (parameter byteArray) if byteArray is null.
  • Throws ArgumentNullException (parameter mediaType) if contentType is null, because the SDK sets it as the MIME type of the file part.
  • Throws FormatException if contentType is not a valid MIME type.
  • The file path, stream, and byte array overloads read the file before they check title:
    • filePath set to null throws ArgumentNullException (parameter path), and a missing file throws FileNotFoundException or DirectoryNotFoundException.
    • stream set to null throws NullReferenceException. A stream that does not support Length, such as a network stream, throws NotSupportedException. Copy it into a MemoryStream first.
    • bytes set to null throws ArgumentNullException (parameter content).
  • The SDK does not check defaultWidth. A value other than full or half reaches the API with the upload.
  • The constructor sends no request. Errors from the API come from Extension.Upload.

Behavior

  • Reads the whole file into memory when you construct the model. The stream overload reads from the current position for stream.Length bytes.
  • Sets the MIME type of the file part to contentType. isEnable sets Enable, defaultWidth sets DefaultWidth, and the other arguments set the properties of the same name.
  • The file path overload opens the file with File.OpenRead and reads it. Use the byte array overload with File.ReadAllBytes when you want to control when the file closes.

Example

Basic usage: build a model from a file path

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models.CustomExtension;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

DashboardWidgetModel model = new DashboardWidgetModel("<FILE_PATH>", "text/html", "Publishing Stats");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Extension().Upload(model);
    Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["uid"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: build models from a stream, bytes, and ByteArrayContent

using System;
using System.IO;
using System.Net.Http;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models.CustomExtension;

ContentstackClient client = new ContentstackClient();
byte[] html = File.ReadAllBytes("<FILE_PATH>");

using MemoryStream stream = new MemoryStream(html);
DashboardWidgetModel fromStream = new DashboardWidgetModel(stream, "text/html", "Publishing Stats", true, "full", "reports");
DashboardWidgetModel fromBytes = new DashboardWidgetModel(html, "text/html", "Team Activity", true, "half", "reports");
DashboardWidgetModel fromContent = new DashboardWidgetModel(new ByteArrayContent(html), "text/html", "Release Calendar", false, null, null);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Extension().Upload(fromStream);
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

GetHttpContent

GetHttpContent builds the multipart/form-data body that Extension.Upload sends for a dashboard widget.

This method takes no parameters.

Returns: HttpContent. The multipart form body of the upload.

Validation

  • Throws no exception of its own. The constructor already checked the file and the title.
  • GetHttpContent sends no request. Extension.Upload calls it and sends the result.

Behavior

  • Returns a new MultipartFormDataContent on each call, with the form fields listed below in this order:
    • extension[upload]: the file, with Title as its file name
    • extension[title]: Title
    • extension[tags]: Tags, only when it is not null
    • extension[default_width]: DefaultWidth, only when it is not null
    • extension[enable]: true or false
    • extension[type]: dashboard
  • You do not need to call GetHttpContent yourself. Call it to inspect the form before an upload, for example in a unit test.

Example

Basic usage: inspect the form fields of a dashboard widget upload

using System;
using System.Net.Http;
using Contentstack.Management.Core.Models.CustomExtension;

DashboardWidgetModel model = new DashboardWidgetModel(new byte[] { 60, 112, 62 }, "text/html", "Publishing Stats", true, "half");

HttpContent content = model.GetHttpContent();
foreach (HttpContent part in (MultipartFormDataContent)content)
{
    Console.WriteLine(part.Headers.ContentDisposition?.Name);
}