CustomWidgetModel
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
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| Title | string | Yes | The title constructor argument | Name of the widget. Sent as extension[title], and as the file name of the upload. |
| Tags | string? | No | The tags constructor argument, or null if you omit it | Tags for the widget. Sent as extension[tags] when it is not null. |
| Scope | ExtensionScope? | No | The scope constructor argument, or null if you omit it | Content types that show the widget. |
| ContentType | string | Yes | The contentType constructor argument | MIME 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 Name | Returns | Description |
|---|---|---|
| CustomWidgetModel | A new custom widget upload model. | Creates the model from a file path, stream, byte array, or ByteArrayContent. |
| GetHttpContent | The 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.
| Name | Type | Description |
|---|---|---|
| filePath (required) | string | Path of the HTML file to upload. |
| contentType (required) | string | MIME type of the file, for example text/html. |
| title (required) | string | Name of the widget. |
| tags | string? | Tags for the widget. |
| scope | ExtensionScope? | Content types that show the widget. |
| stream (required) | Stream | Stream that holds the HTML file. |
| bytes (required) | byte[] | Content of the HTML file. |
| byteArray (required) | ByteArrayContent | HTTP content that holds the HTML file. |
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);
}