CustomWidgetModel

View as Markdown

CustomWidgetModel

CustomWidgetModel holds the HTML file, title, tags, and scope of a custom widget that you upload with the Upload method of Extension. A custom widget appears in the sidebar of the entry editor.

When to Use This Class: Use this class when the code of your widget is an HTML file on disk or in memory. For a widget that another server hosts, use ExtensionModel with the Create method instead.

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 widget.

Returns: CustomWidgetModel. The file and settings of a custom 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.
ScopeExtensionScope?NoThe scope constructor argument, or null if you omit itContent types that show the widget.
ContentTypestringYesThe contentType constructor argumentMIME type of the uploaded file, for example text/html.

Class-Level Notes

How the SDK builds the upload body.

  • The CustomWidgetModel constructor reads the whole file into memory and sets the MIME type of the file part from contentType.
  • Extension.Upload calls GetHttpContent, which reads Title, Tags, and Scope at that moment.
  • The Upload a widget request of the Content Management API reference describes the form fields.

Known issue The API does not receive Scope, because the SDK adds it to the form as a part with no field name. To limit a widget to some content types, create it with ExtensionModel.Scope and the Create method.

The interface it implements.

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

Method Index

Method NameReturnsDescription
CustomWidgetModelA new custom 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 a custom 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>");

CustomWidgetModel model = new CustomWidgetModel("<FILE_PATH>", "text/html", "SEO Checker", "seo");

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 CustomWidgetModel class has its own section below, with its parameters, validation rules, behavior, and examples.

CustomWidgetModel

CustomWidgetModel creates a custom 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
tagsstring?

Tags for the widget.

Default: null
scopeExtensionScope?

Content types that show 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: CustomWidgetModel. A new custom widget upload model.

Overloads

  • CustomWidgetModel(string filePath, string contentType, string title, string? tags = null, ExtensionScope? scope = null)
  • CustomWidgetModel(Stream stream, string contentType, string title, string? tags = null, ExtensionScope? scope = null)
  • CustomWidgetModel(byte[] bytes, string contentType, string title, string? tags = null, ExtensionScope? scope = null)
  • CustomWidgetModel(ByteArrayContent byteArray, string contentType, string title, string? tags = null, ExtensionScope? scope = 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 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, and stores the other arguments in 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.

Known issue The API does not receive scope, because the SDK adds it to the form as a part with no field name. To limit a widget to some content types, create it with ExtensionModel.Scope and the Create method.

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>");

CustomWidgetModel model = new CustomWidgetModel("<FILE_PATH>", "text/html", "SEO Checker");

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.Collections.Generic;
using System.IO;
using System.Net.Http;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Models.CustomExtension;

ContentstackClient client = new ContentstackClient();
byte[] html = File.ReadAllBytes("<FILE_PATH>");
ExtensionScope scope = new ExtensionScope { ContentTypes = new List<string> { "$all" } };

using MemoryStream stream = new MemoryStream(html);
CustomWidgetModel fromStream = new CustomWidgetModel(stream, "text/html", "SEO Checker", "seo", scope);
CustomWidgetModel fromBytes = new CustomWidgetModel(html, "text/html", "Readability", "content", scope);
CustomWidgetModel fromContent = new CustomWidgetModel(new ByteArrayContent(html), "text/html", "Link Checker", null, null);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Extension().Upload(fromBytes);
    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 custom 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. A Scope whose ContentTypes is null serializes as {"content_types":null}.
  • 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
    • a part with Scope as JSON, only when Scope is not null. This part has no field name, so the API does not read it.
    • extension[type]: widget
  • 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 custom widget upload

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

CustomWidgetModel model = new CustomWidgetModel(new byte[] { 60, 112, 62 }, "text/html", "SEO Checker", "seo");

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