diff --git a/Directory.Build.props b/Directory.Build.props index 0c367ff..5736e1e 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -1,7 +1,7 @@ - 0.4.1 + 0.5.0 Code Happy, LLC Code Happy, LLC HTML/CSS To Image API diff --git a/src/HtmlCssToImage/Client/HtmlCssToImageClient.Urls.cs b/src/HtmlCssToImage/Client/HtmlCssToImageClient.Urls.cs index f3beb40..c0c7da8 100644 --- a/src/HtmlCssToImage/Client/HtmlCssToImageClient.Urls.cs +++ b/src/HtmlCssToImage/Client/HtmlCssToImageClient.Urls.cs @@ -1,5 +1,6 @@ using System.Buffers; using System.Diagnostics.CodeAnalysis; +using System.Numerics; using System.Text.Json; using System.Text.Json.Nodes; using System.Text.Json.Serialization.Metadata; @@ -105,74 +106,67 @@ internal static void CreateAndRenderUrlQueryString(CreateUrlImageRequest request { QueryStringEncoder.EncodeSafeKey("url", request.Url, ref chars); - if (request.FullScreen == true) - { - QueryStringEncoder.EncodeSafeKeyValue("full_screen", "true", ref chars); - } - - if (request.BlockConsentBanners == true) - { - QueryStringEncoder.EncodeSafeKeyValue("block_consent_banners", "true", ref chars); - } - - if (request.DisableTwemoji == true) - { - QueryStringEncoder.EncodeSafeKeyValue("disable_twemoji", "true", ref chars); - } - - if (request.MaxRenderOnce == true) - { - QueryStringEncoder.EncodeSafeKeyValue("max_render_once", "true", ref chars); - } - - if (request.RenderWhenReady == true) - { - QueryStringEncoder.EncodeSafeKeyValue("render_when_ready", "true", ref chars); - } + AppendBoolIfTrue("full_screen",request.FullScreen, ref chars); + AppendBoolIfTrue("block_consent_banners",request.BlockConsentBanners, ref chars); + AppendBoolIfTrue("disable_twemoji",request.DisableTwemoji, ref chars); + AppendBoolIfTrue("max_render_once",request.MaxRenderOnce, ref chars); + AppendBoolIfTrue("render_when_ready",request.RenderWhenReady, ref chars); if (request.ColorScheme != null) { - QueryStringEncoder.EncodeSafeKeyValue("color_scheme", Helpers.EnumToString.ColorSchemeString(request.ColorScheme.Value), ref chars); + QueryStringEncoder.EncodeSafeKeyValue("color_scheme", request.ColorScheme.Value.ColorSchemeString(), ref chars); } + AppendNumberIfNotNull("device_scale", request.DeviceScale, ref chars); + AppendNumberIfNotNull("max_wait_ms", request.MaxWaitMs, ref chars); + AppendNumberIfNotNull("ms_delay", request.MsDelay, ref chars); + AppendNumberIfNotNull("viewport_height", request.ViewportHeight, ref chars); + AppendNumberIfNotNull("viewport_width", request.ViewportWidth, ref chars); - if (request.DeviceScale != null) + if (!string.IsNullOrWhiteSpace(request.Css)) { - QueryStringEncoder.WriteSafeKey("device_scale", request.DeviceScale.Value, ref chars); + QueryStringEncoder.EncodeSafeKey("css", request.Css, ref chars); } - if (request.MaxWaitMs != null) + if (!string.IsNullOrWhiteSpace(request.Selector)) { - QueryStringEncoder.WriteSafeKey("max_wait_ms", request.MaxWaitMs.Value, ref chars); + QueryStringEncoder.EncodeSafeKey("selector", request.Selector, ref chars); } - if (request.MsDelay != null) + if (!string.IsNullOrWhiteSpace(request.Timezone)) { - QueryStringEncoder.WriteSafeKey("ms_delay", request.MsDelay.Value, ref chars); + QueryStringEncoder.EncodeSafeKey("timezone", request.Timezone, ref chars); } - - if (request.ViewportHeight != null) + AppendBoolIfTrue("viewport_mobile", request.ViewportMobile, ref chars); + AppendBoolIfTrue("viewport_landscape", request.ViewportLandscape, ref chars); + AppendBoolIfTrue("viewport_touch", request.ViewportTouch, ref chars); + if (request.MediaType != null) { - QueryStringEncoder.WriteSafeKey("viewport_height", request.ViewportHeight.Value, ref chars); + QueryStringEncoder.EncodeSafeKeyValue("media_type", request.MediaType.Value.MediaTypeString(), ref chars); } - if (request.ViewportWidth != null) + if (!string.IsNullOrWhiteSpace(request.ProxyId)) { - QueryStringEncoder.WriteSafeKey("viewport_width", request.ViewportWidth.Value, ref chars); + QueryStringEncoder.EncodeSafeKey("proxy_id", request.ProxyId, ref chars); } - if (!string.IsNullOrWhiteSpace(request.Css)) - { - QueryStringEncoder.EncodeSafeKey("css", request.Css, ref chars); - } + AppendNumberIfNotNull("jumbo_max_width", request.JumboMaxWidth, ref chars); + AppendNumberIfNotNull("jumbo_max_height", request.JumboMaxHeight, ref chars); - if (!string.IsNullOrWhiteSpace(request.Selector)) + } + + private static void AppendNumberIfNotNull(ReadOnlySpan key, T? value, ref ArrayOrSpan chars) where T : struct, INumber + { + if (value != null) { - QueryStringEncoder.EncodeSafeKey("selector", request.Selector, ref chars); + QueryStringEncoder.WriteSafeKey(key, value.Value, ref chars); } + } - if (!string.IsNullOrWhiteSpace(request.Timezone)) + private static void AppendBoolIfTrue(ReadOnlySpan key, bool? value, ref ArrayOrSpan chars) + { + if (value == true) { - QueryStringEncoder.EncodeSafeKey("timezone", request.Timezone, ref chars); + QueryStringEncoder.EncodeSafeKeyValue(key, "true", ref chars); } } diff --git a/src/HtmlCssToImage/Helpers/EnumToString.cs b/src/HtmlCssToImage/Helpers/EnumToString.cs index 7d80258..c26ee4d 100644 --- a/src/HtmlCssToImage/Helpers/EnumToString.cs +++ b/src/HtmlCssToImage/Helpers/EnumToString.cs @@ -6,10 +6,18 @@ namespace HtmlCssToImage.Helpers; internal static class EnumToString { [MethodImpl(MethodImplOptions.AggressiveInlining)] - internal static string ColorSchemeString(ColorSchemeType type) => type switch + internal static string ColorSchemeString(this ColorSchemeType type) => type switch { ColorSchemeType.dark => nameof(ColorSchemeType.dark), ColorSchemeType.light => nameof(ColorSchemeType.light), _ => throw new ArgumentOutOfRangeException(nameof(type), type, null) }; + + [MethodImpl(MethodImplOptions.AggressiveInlining)] + internal static string MediaTypeString(this MediaType type) => type switch + { + MediaType.screen => nameof(MediaType.screen), + MediaType.print => nameof(MediaType.print), + _ => throw new ArgumentOutOfRangeException(nameof(type), type, null) + }; } \ No newline at end of file diff --git a/src/HtmlCssToImage/Models/Requests/CreateHtmlCssImageRequest.cs b/src/HtmlCssToImage/Models/Requests/CreateHtmlCssImageRequest.cs index 64091fc..c9929df 100644 --- a/src/HtmlCssToImage/Models/Requests/CreateHtmlCssImageRequest.cs +++ b/src/HtmlCssToImage/Models/Requests/CreateHtmlCssImageRequest.cs @@ -25,6 +25,7 @@ public class CreateHtmlCssImageRequest:CreateImageCommonOptions, IBatchAllowedIm /// Gets or sets the Google Fonts to be included when generating an image. /// This property allows specifying one or more Google Fonts /// You must also set the font-family in your CSS to use the loaded font(s). + /// Read the Google Fonts Guide for more information. /// [JsonConverter(typeof(GoogleFontsJsonConverter))] public string[]? GoogleFonts { get; set; } diff --git a/src/HtmlCssToImage/Models/Requests/CreateImageCommonOptions.cs b/src/HtmlCssToImage/Models/Requests/CreateImageCommonOptions.cs index 54cf50e..5f14bde 100644 --- a/src/HtmlCssToImage/Models/Requests/CreateImageCommonOptions.cs +++ b/src/HtmlCssToImage/Models/Requests/CreateImageCommonOptions.cs @@ -11,88 +11,105 @@ namespace HtmlCssToImage.Models.Requests; [JsonDerivedType(typeof(CreateUrlImageRequest))] public abstract class CreateImageCommonOptions { - /// - /// A CSS selector to target a specific element on the page. The API will crop the image to the dimensions of this element. - /// - public string? Selector { get; set; } - - /// - /// Adjusts the pixel ratio for the screenshot. The default is 2 which is equivalent to a 4K monitor. - /// - public double? DeviceScale { get; set; } - - /// - /// Set the height of Chrome's viewport. This will disable automatic cropping. - /// - public uint? ViewportHeight { get; set; } - - /// - /// Set the width of Chrome's viewport. This will disable automatic cropping. - /// - public uint? ViewportWidth { get; set; } - - /// - /// Sets a limit on time to wait until the screenshot is taken. Use this if your page loads a lot of extra irrelevant content, and you want to reduce the render time. - /// - public uint? MaxWaitMs { get; set; } - - /// - /// Adds extra time before taking the screenshot, like if you need to wait for Javascript to execute - /// - public uint? MsDelay { get; set; } - - /// - /// This will wait until 'ScreenshotReady()' is called from Javascript to take the screenshot. - /// - public bool? RenderWhenReady { get; set; } - - /// - /// Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most scenarios. - /// - public bool? MaxRenderOnce { get; set; } - - /// - /// Twemoji is used to render emoji as a fallback for native emoji fonts. This option will disable that behavior. - /// - public bool? DisableTwemoji { get; set; } - - /// - /// Options for generating a PDF from the HTML/CSS. - /// - public PDFOptions? PDFOptions { get; set; } - - /// - /// Set Chrome to render assuming the user has explicitly set their browser to Light or Dark mode. - /// - public ColorSchemeType? ColorScheme { get; set; } - - /// - /// Sets the timezone for the browser instance. Use IANA timezone format (e.g. 'America/New_York'). - /// - public string? Timezone { get; set; } - - /// - /// Gets or sets a value indicating whether the viewport should be rendered as if it's being viewed from a mobile device. - /// - public bool? ViewportMobile { get; set; } - - /// - /// Gets or sets a value indicating whether the viewport should be in landscape orientation. - /// - public bool? ViewportLandscape { get; set; } - - /// - /// Gets or sets a value indicating whether touch interactions are enabled within the viewport. - /// - public bool? ViewportTouch { get; set; } - /// - /// Gets or sets the media type to use for rendering. - /// - public MediaType? MediaType { get; set; } - - /// - /// Gets or sets the proxy ID to use for rendering. - /// - public string? ProxyId { get; set; } - + /// + /// A CSS selector to target a specific element on the page. The API will crop the image to the dimensions of this element. + /// Read the selector Guide for more information. + /// + public string? Selector { get; set; } + + /// + /// Adjusts the pixel ratio for the screenshot. The default is 2 which is equivalent to a 4K monitor. + /// Read the device_scale Guide for more information. + /// + public double? DeviceScale { get; set; } + + /// + /// Set the height of Chrome's viewport. This will disable automatic cropping. + /// + public uint? ViewportHeight { get; set; } + + /// + /// Set the width of Chrome's viewport. This will disable automatic cropping. + /// + public uint? ViewportWidth { get; set; } + + /// + /// Sets a limit on time to wait until the screenshot is taken. Use this if your page loads a lot of extra irrelevant content, and you want to reduce the render time. + /// + public uint? MaxWaitMs { get; set; } + + /// + /// Adds extra time before taking the screenshot, like if you need to wait for Javascript to execute + /// See the ms_delay docs for more information. + /// + public uint? MsDelay { get; set; } + + /// + /// This will wait until 'ScreenshotReady()' is called from Javascript to take the screenshot. + /// Read the Render When Ready Guide for more information. + /// + public bool? RenderWhenReady { get; set; } + + /// + /// Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most scenarios. + /// + public bool? MaxRenderOnce { get; set; } + + /// + /// Twemoji is used to render emoji as a fallback for native emoji fonts. This option will disable that behavior. + /// + public bool? DisableTwemoji { get; set; } + + /// + /// Options for generating a PDF from the HTML/CSS. + /// + public PDFOptions? PDFOptions { get; set; } + + /// + /// Set Chrome to render assuming the user has explicitly set their browser to Light or Dark mode. + /// Read the color_scheme Guide for more information. /// + public ColorSchemeType? ColorScheme { get; set; } + + /// + /// Sets the timezone for the browser instance. Use IANA timezone format (e.g. 'America/New_York'). + /// + public string? Timezone { get; set; } + + /// + /// Gets or sets a value indicating whether the viewport should be rendered as if it's being viewed from a mobile device. + /// + public bool? ViewportMobile { get; set; } + + /// + /// Gets or sets a value indicating whether the viewport should be in landscape orientation. + /// + public bool? ViewportLandscape { get; set; } + + /// + /// Gets or sets a value indicating whether touch interactions are enabled within the viewport. + /// + public bool? ViewportTouch { get; set; } + + /// + /// Gets or sets the media type to use for rendering. + /// + public MediaType? MediaType { get; set; } + + /// + /// Gets or sets the proxy ID to use for rendering. + /// Read the Proxy Guide for more information. + /// + public string? ProxyId { get; set; } + + /// + /// Gets or sets the maximum width of the rendered image in jumbo mode. Consumes extra renders, requires to be defined as well. + /// Read the Jumbo Images Guide for more information. + /// + public uint? JumboMaxWidth { get; set; } + + /// + /// Gets or sets the maximum height of the rendered image in jumbo mode. Consumes extra renders, requires to be defined as well. + /// Read the Jumbo Images Guide for more information. + /// + public uint? JumboMaxHeight { get; set; } } \ No newline at end of file diff --git a/src/HtmlCssToImage/Models/Requests/CreateTemplateRequest.cs b/src/HtmlCssToImage/Models/Requests/CreateTemplateRequest.cs index 63535fe..806d46b 100644 --- a/src/HtmlCssToImage/Models/Requests/CreateTemplateRequest.cs +++ b/src/HtmlCssToImage/Models/Requests/CreateTemplateRequest.cs @@ -22,11 +22,13 @@ public class CreateTemplateRequest /// /// A CSS selector to target a specific element on the page. The API will crop the image to the dimensions of this element. + /// Read the selector Guide for more information. /// public string? Selector { get; set; } /// /// Adjusts the pixel ratio for the screenshot. The default is 2 which is equivalent to a 4K monitor. + /// Read the device_scale Guide for more information. /// public double? DeviceScale { get; set; } @@ -47,11 +49,13 @@ public class CreateTemplateRequest /// /// Adds extra time before taking the screenshot, like if you need to wait for Javascript to execute + /// See the ms_delay docs for more information. /// public uint? MsDelay { get; set; } /// /// This will wait until 'ScreenshotReady()' is called from Javascript to take the screenshot. + /// Read the Render When Ready Guide for more information. /// public bool? RenderWhenReady { get; set; } @@ -68,6 +72,7 @@ public class CreateTemplateRequest /// /// Set Chrome to render assuming the user has explicitly set their browser to Light or Dark mode. + /// Read the color_scheme Guide for more information. /// public ColorSchemeType? ColorScheme { get; set; } @@ -90,6 +95,7 @@ public class CreateTemplateRequest /// Gets or sets the Google Fonts to be included when generating an image. /// This property allows specifying one or more Google Fonts /// You must also set the font-family in your CSS to use the loaded font(s). + /// Read the Google Fonts Guide for more information. /// [JsonConverter(typeof(GoogleFontsJsonConverter))] public string[]? GoogleFonts { get; set; } @@ -108,6 +114,7 @@ public class CreateTemplateRequest /// Gets or sets a value indicating whether touch interactions are enabled within the viewport. /// public bool? ViewportTouch { get; set; } + /// /// Gets or sets the media type to use for rendering. /// @@ -115,6 +122,19 @@ public class CreateTemplateRequest /// /// Gets or sets the proxy_id to use for rendering. + /// Read the Proxy Guide for more information. /// public string? ProxyId { get; set; } + + /// + /// Gets or sets the maximum width of the rendered image in jumbo mode. Consumes extra renders, requires to be defined as well. + /// Read the Jumbo Images Guide for more information. + /// + public uint? JumboMaxWidth { get; set; } + + /// + /// Gets or sets the maximum height of the rendered image in jumbo mode. Consumes extra renders, requires to be defined as well. + /// Read the Jumbo Images Guide for more information. + /// + public uint? JumboMaxHeight { get; set; } } \ No newline at end of file diff --git a/src/HtmlCssToImage/Models/Requests/CreateUrlImageRequest.cs b/src/HtmlCssToImage/Models/Requests/CreateUrlImageRequest.cs index 7e0152d..ccc9b4c 100644 --- a/src/HtmlCssToImage/Models/Requests/CreateUrlImageRequest.cs +++ b/src/HtmlCssToImage/Models/Requests/CreateUrlImageRequest.cs @@ -24,6 +24,7 @@ public class CreateUrlImageRequest:CreateImageCommonOptions, IBatchAllowedImageR /// /// Indicates whether the screenshot should capture the entire webpage in full height. + /// Read the full_screen Guide for more information. /// /// /// When set to true, this property ensures that the screenshot includes the full vertical content of the webpage, @@ -34,6 +35,7 @@ public class CreateUrlImageRequest:CreateImageCommonOptions, IBatchAllowedImageR /// /// Attempt to block cookie/consent banners from displaying. + /// Read the Blocking Cookie Banners Guide for more information. /// public bool? BlockConsentBanners { get; set; } } \ No newline at end of file diff --git a/src/HtmlCssToImage/Models/Template.cs b/src/HtmlCssToImage/Models/Template.cs index 3f37cac..e3b31d2 100644 --- a/src/HtmlCssToImage/Models/Template.cs +++ b/src/HtmlCssToImage/Models/Template.cs @@ -150,5 +150,15 @@ public class Template /// public string? ProxyId { get; init; } + /// + /// Gets or sets the maximum width of the rendered image in jumbo mode. + /// + public uint? JumboMaxWidth { get; init; } + + /// + /// Gets or sets the maximum height of the rendered image in jumbo mode. + /// + public uint? JumboMaxHeight { get; init; } + } \ No newline at end of file