add render options and revamped url builder

Directory.Build.props

@@ -1,7 +1,7 @@
 <Project>
 
     <PropertyGroup>
-        <Version>0.5.1</Version>
+        <Version>0.6.0</Version>
         <Company>Code Happy, LLC</Company>
         <Authors>Code Happy, LLC</Authors>
         <Product>HTML/CSS To Image API</Product>

src/HtmlCssToImage.Blazor/HCTI_OgMetaTag_Base.cs

@@ -1,6 +1,7 @@
 using System.Text.Json;
 using System.Text.Json.Nodes;
 using System.Text.Json.Serialization.Metadata;
+using HtmlCssToImage.Models;
 using HtmlCssToImage.Models.Requests;
 using Microsoft.AspNetCore.Components;
 using Microsoft.AspNetCore.Components.Rendering;
@@ -15,6 +16,8 @@ public abstract class HCTI_OgMetaTagBase:ComponentBase
 
     [Parameter] public string? OgMetaType { get; set; }
 
+    [Parameter] public RenderImageOptions? RenderOptions { get; set; }
+
     protected string? MetaUrl { get; set; }
 
     protected abstract void SetMetaUrl();
@@ -44,4 +47,4 @@ private void BuildMetaRenderTree(RenderTreeBuilder builder)
         builder.AddAttribute(2, "content", MetaUrl);
         builder.CloseElement();
     }
-}
+}

src/HtmlCssToImage.Blazor/HCTI_Templated_OgMetaTag.cs

@@ -23,22 +23,59 @@ protected override void SetMetaUrl()
     {
         if (TemplateValues is JsonObject jo)
         {
-            MetaUrl= HtmlCssToImageClient.CreateTemplatedImageUrl(TemplateId, jo, TemplateVersion);
+            MetaUrl = RenderOptions is null
+                ? HtmlCssToImageClient.CreateTemplatedImageUrl(TemplateId, jo, TemplateVersion)
+                : HtmlCssToImageClient.CreateTemplatedImageUrl(
+                    TemplateId,
+                    jo,
+                    TemplateVersion,
+                    RenderOptions);
         }
         else if(TemplateValues!=null)
         {
             if (TypeInfo != null)
             {
-                MetaUrl= HtmlCssToImageClient.CreateTemplatedImageUrl(TemplateId, TemplateValues, TypeInfo, TemplateVersion);
+                MetaUrl = RenderOptions is null
+                    ? HtmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        TypeInfo,
+                        TemplateVersion)
+                    : HtmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        TypeInfo,
+                        TemplateVersion,
+                        RenderOptions);
             }else if (JsonSerializerOptions != null)
             {
-                MetaUrl= HtmlCssToImageClient.CreateTemplatedImageUrl(TemplateId, TemplateValues, JsonSerializerOptions, TemplateVersion);
+                MetaUrl = RenderOptions is null
+                    ? HtmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        JsonSerializerOptions,
+                        TemplateVersion)
+                    : HtmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        JsonSerializerOptions,
+                        TemplateVersion,
+                        RenderOptions);
             }
             else
             {
-                MetaUrl= HtmlCssToImageClient.CreateTemplatedImageUrl(TemplateId, TemplateValues, TemplateVersion);
+                MetaUrl = RenderOptions is null
+                    ? HtmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        TemplateVersion)
+                    : HtmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        TemplateVersion,
+                        RenderOptions);
             }
 
         }
     }
-}
+}

src/HtmlCssToImage.Blazor/HCTI_Url_OgMetaTag.cs

@@ -16,7 +16,9 @@ public class HCTI_Url_OgMetaTag:HCTI_OgMetaTagBase
 
     protected override void SetMetaUrl()
     {
-        MetaUrl= HtmlCssToImageClient.CreateAndRenderUrl(ImageRequest);
+        MetaUrl = RenderOptions is null
+            ? HtmlCssToImageClient.CreateAndRenderUrl(ImageRequest)
+            : HtmlCssToImageClient.CreateAndRenderUrl(ImageRequest, RenderOptions);
     }
 
-}
+}

src/HtmlCssToImage.Blazor/README.md

@@ -62,6 +62,7 @@ Use the `HCTI_Templated_OgMetaTag<T>` component to generate OG meta tags using a
 | `TypeInfo`              |          | A `System.Text.Json.JsonTypeInfo<T>` instance that will be used to serialize `TemplateValues`                 |
 | `JsonSerializerOptions` |          | A `System.Text.Json.JsonSerializerOptions` instance that will be used to serialize `TemplateValues` if provided |
 | `TemplateVersion`       |          | An optional version of the template to use, if not specified, the latest version will be used                 |
+| `RenderOptions`         |          | Optional output format, sizing, DPI, and cropping options supplied as a `RenderImageOptions` instance.        |
 | `OgMetaType`            |          | The type of meta tag to generate, such as `twitter:image`. When not specified, `og:image` will be used.       | 
 
 #### Template Values
@@ -77,6 +78,7 @@ Use the `HCTI_Url_OgMetaTag` component to generate an OG meta tag with a URL-gen
 | Parameter      | Required | Description                                                                                                                             |
 |----------------| :------: |-----------------------------------------------------------------------------------------------------------------------------------------|
 | `ImageRequest` | ✅ | An instance of [`HtmlCssToImage.Models.Requests.CreateUrlImageRequest`](../HtmlCssToImage/Models/Requests/CreateUrlImageRequest.cs) |
+| `RenderOptions` | | Optional output format, sizing, DPI, and cropping options supplied as a `RenderImageOptions` instance. |
 | `OgMetaType`   | | The type of meta tag to generate, such as `twitter:image`. When not specified, `og:image` will be used.                                 |
 
 #### Image Request
@@ -98,4 +100,4 @@ Check out the [Sample Project](https://github.com/htmlcsstoimage/dotnet-client/b
 > Check out the [HTML/CSS To Image Docs](https://docs.htmlcsstoimage.com) for more details on the API's capabilities.
 
 > [!TIP]
-> Get started for free at [htmlcsstoimage.com](https://htmlcsstoimage.com).
+> Get started for free at [htmlcsstoimage.com](https://htmlcsstoimage.com).

src/HtmlCssToImage.TagHelpers/HCTI_OgMetaTagHelperBase.cs

@@ -1,3 +1,4 @@
+using HtmlCssToImage.Models;
 using Microsoft.AspNetCore.Razor.TagHelpers;
 
 namespace HtmlCssToImage.TagHelpers;
@@ -13,6 +14,8 @@ public HCTI_OgMetaTagHelperBase(IHtmlCssToImageClient htmlCssToImageClient)
 
     [HtmlAttributeName("og-meta-type")] public string? OgMetaType { get; set; }
 
+    [HtmlAttributeName("render-options")] public RenderImageOptions? RenderOptions { get; set; }
+
     protected string? MetaUrl { get; set; }
 
     protected abstract void SetMetaUrl();
@@ -31,4 +34,4 @@ public override void Process(TagHelperContext context, TagHelperOutput output)
         output.Attributes.SetAttribute("content", MetaUrl);
         output.TagMode = TagMode.SelfClosing;
     }
-}
+}

src/HtmlCssToImage.TagHelpers/HCTI_Templated_OgMetaTagHelper.cs

@@ -31,20 +31,46 @@ protected override void SetMetaUrl()
     {
         if (TemplateValues is JsonObject jo)
         {
-            MetaUrl= _htmlCssToImageClient.CreateTemplatedImageUrl(TemplateId, jo, TemplateVersion);
+            MetaUrl = RenderOptions is null
+                ? _htmlCssToImageClient.CreateTemplatedImageUrl(TemplateId, jo, TemplateVersion)
+                : _htmlCssToImageClient.CreateTemplatedImageUrl(
+                    TemplateId,
+                    jo,
+                    TemplateVersion,
+                    RenderOptions);
         }
         else if(TemplateValues!=null)
         {
             if (JsonSerializerOptions != null)
             {
-                MetaUrl= _htmlCssToImageClient.CreateTemplatedImageUrl(TemplateId, TemplateValues, JsonSerializerOptions, TemplateVersion);
+                MetaUrl = RenderOptions is null
+                    ? _htmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        JsonSerializerOptions,
+                        TemplateVersion)
+                    : _htmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        JsonSerializerOptions,
+                        TemplateVersion,
+                        RenderOptions);
             }
             else
             {
-                MetaUrl= _htmlCssToImageClient.CreateTemplatedImageUrl(TemplateId, TemplateValues, TemplateVersion);
+                MetaUrl = RenderOptions is null
+                    ? _htmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        TemplateVersion)
+                    : _htmlCssToImageClient.CreateTemplatedImageUrl(
+                        TemplateId,
+                        TemplateValues,
+                        TemplateVersion,
+                        RenderOptions);
             }
 
         }
     }
 
-}
+}

src/HtmlCssToImage.TagHelpers/HCTI_Url_OgMetaTagHelper.cs

@@ -20,7 +20,9 @@ public HCTI_Url_OgMetaTagHelper(IHtmlCssToImageClient htmlCssToImageClient) : ba
 
     protected override void SetMetaUrl()
     {
-         MetaUrl= _htmlCssToImageClient.CreateAndRenderUrl(ImageRequest);
+        MetaUrl = RenderOptions is null
+            ? _htmlCssToImageClient.CreateAndRenderUrl(ImageRequest)
+            : _htmlCssToImageClient.CreateAndRenderUrl(ImageRequest, RenderOptions);
     }
 
-}
+}

src/HtmlCssToImage.TagHelpers/README.md

@@ -72,6 +72,7 @@ Use the `<hcti-og-templated>` tag to generate OG meta tags using a HCTI template
 | `template-values` |     ✅      | A JSON-serializable object that will serve as the `template_values` in the request. |
 | `json-options` |            | A `System.Text.Json.JsonSerializerOptions` instance that will be used to serialize `template-values` |
 | `template-version` |            | An optional version of the template to use, if not specified, the latest version will be used |
+| `render-options` | | Optional output format, sizing, DPI, and cropping options supplied as a `RenderImageOptions` instance. |
 | `og-meta-type` | | The type of meta tag to generate, such as `twitter:image`. When not specified, `og:image` will be used. | 
 
 #### Template Values
@@ -85,6 +86,7 @@ Use the `<hcti-og-url>` tag to generate an OG meta tag with a URL-generating ima
 | Parameter | Required | Description                                                                                                                             |
 | --------- | :------: |-----------------------------------------------------------------------------------------------------------------------------------------|
 | `image-request` | ✅ | An instance of [`HtmlCssToImage.Models.Requests.CreateUrlImageRequest`](../HtmlCssToImage/Models/Requests/CreateUrlImageRequest.cs) |
+| `render-options` | | Optional output format, sizing, DPI, and cropping options supplied as a `RenderImageOptions` instance. |
 | `og-meta-type` | | The type of meta tag to generate, such as `twitter:image`. When not specified, `og:image` will be used.                                 |
 
 #### Image Request
@@ -105,4 +107,4 @@ Check out the [Sample Project](https://github.com/htmlcsstoimage/dotnet-client/b
 > Check out the [HTML/CSS To Image Docs](https://docs.htmlcsstoimage.com) for more details on the API's capabilities.
 
 > [!TIP]
-> Get started for free at [htmlcsstoimage.com](https://htmlcsstoimage.com).
+> Get started for free at [htmlcsstoimage.com](https://htmlcsstoimage.com).

src/HtmlCssToImage/Client/HtmlCssToImageClient.Urls.CreateAndRender.cs

@@ -0,0 +1,134 @@
+using System.Numerics;
+using HtmlCssToImage.Helpers;
+using HtmlCssToImage.Models;
+using HtmlCssToImage.Models.Requests;
+
+namespace HtmlCssToImage;
+
+public partial class HtmlCssToImageClient
+{
+    internal static void CreateAndRenderUrlQueryString(CreateUrlImageRequest request, ref UrlStringBuilder builder)
+    {
+        builder.EncodeSafeKey("url", request.Url);
+
+        AppendBoolIfTrue("full_screen", request.FullScreen, ref builder);
+        AppendBoolIfTrue("block_consent_banners", request.BlockConsentBanners, ref builder);
+        AppendBoolIfTrue("disable_twemoji", request.DisableTwemoji, ref builder);
+        AppendBoolIfTrue("max_render_once", request.MaxRenderOnce, ref builder);
+        AppendBoolIfTrue("render_when_ready", request.RenderWhenReady, ref builder);
+
+        if (request.ColorScheme != null)
+        {
+            builder.EncodeSafeKeyValue("color_scheme", request.ColorScheme.Value.ColorSchemeString());
+        }
+
+        AppendNumberIfNotNull("device_scale", request.DeviceScale, ref builder);
+        AppendNumberIfNotNull("max_wait_ms", request.MaxWaitMs, ref builder);
+        AppendNumberIfNotNull("ms_delay", request.MsDelay, ref builder);
+        AppendNumberIfNotNull("viewport_height", request.ViewportHeight, ref builder);
+        AppendNumberIfNotNull("viewport_width", request.ViewportWidth, ref builder);
+
+        if (!string.IsNullOrWhiteSpace(request.Css))
+        {
+            builder.EncodeSafeKey("css", request.Css);
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.Selector))
+        {
+            builder.EncodeSafeKey("selector", request.Selector);
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.Timezone))
+        {
+            builder.EncodeSafeKey("timezone", request.Timezone);
+        }
+
+        AppendBoolIfTrue("viewport_mobile", request.ViewportMobile, ref builder);
+        AppendBoolIfTrue("viewport_landscape", request.ViewportLandscape, ref builder);
+        AppendBoolIfTrue("viewport_touch", request.ViewportTouch, ref builder);
+        if (request.MediaType != null)
+        {
+            builder.EncodeSafeKeyValue("media_type", request.MediaType.Value.MediaTypeString());
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.ProxyId))
+        {
+            builder.EncodeSafeKey("proxy_id", request.ProxyId);
+        }
+
+        AppendNumberIfNotNull("jumbo_max_width", request.JumboMaxWidth, ref builder);
+        AppendNumberIfNotNull("jumbo_max_height", request.JumboMaxHeight, ref builder);
+    }
+
+    private static void AppendNumberIfNotNull<T>(ReadOnlySpan<char> key, T? value, ref UrlStringBuilder builder) where T : struct, INumber<T>
+    {
+        if (value != null)
+        {
+            builder.WriteSafeKey(key, value.Value);
+        }
+    }
+
+    private static void AppendBoolIfTrue(ReadOnlySpan<char> key, bool? value, ref UrlStringBuilder builder)
+    {
+        if (value == true)
+        {
+            builder.EncodeSafeKeyValue(key, "true");
+        }
+    }
+
+    /// <inheritdoc />
+    public string CreateAndRenderUrl(CreateUrlImageRequest request, RenderImageFormat format = RenderImageFormat.PNG)
+    {
+        var pathFormat = format == RenderImageFormat.PNG ? null : (RenderImageFormat?)format;
+        return CreateAndRenderUrl(request, pathFormat, null);
+    }
+
+    /// <inheritdoc />
+    public string CreateAndRenderUrl(CreateUrlImageRequest request, RenderImageOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        return CreateAndRenderUrl(request, options.Format, options);
+    }
+
+    private string CreateAndRenderUrl(
+        CreateUrlImageRequest request,
+        RenderImageFormat? pathFormat,
+        RenderImageOptions? options)
+    {
+        UrlStringBuilder builder = new(stackalloc char[512]);
+        try
+        {
+            builder.AppendLiteral(_apiHost);
+            builder.AppendLiteral(CREATE_AND_RENDER_PATH);
+            builder.AppendLiteral('/');
+            builder.AppendLiteral(_apiId);
+            builder.AppendLiteral('/');
+            var tokenPosition = builder.ReserveLiteral(HmacToken.TokenLength);
+
+            if (pathFormat.HasValue)
+            {
+                builder.AppendLiteral('/');
+                builder.AppendLiteral(pathFormat.Value.RenderFormatToExtensionWithoutDot());
+            }
+
+            CreateAndRenderUrlQueryString(request, ref builder);
+            options?.AppendToBuilder(ref builder, includeFormat: false);
+
+            var queryString = builder.QueryString(false);
+            HmacToken.WriteToken(
+                queryString,
+                _apiKey,
+                builder.ReservedLiteral(tokenPosition, HmacToken.TokenLength));
+
+            return builder.FullSpan.ToString();
+        }
+        finally
+        {
+            builder.Dispose();
+        }
+    }
+
+    /// <inheritdoc />
+    public string ImageUrl(string imageId, RenderImageOptions options) =>
+        RenderImageOptions.ToUrl(_apiHost, imageId, options);
+}