|
1 | | -# contentstack-utils-dotnet |
| 1 | +# Contentstack Utils Dotnet |
| 2 | + |
| 3 | +Contentstack is a headless CMS with an API-first approach. It is a CMS that developers can use to build powerful cross-platform applications in their favorite languages. Build your application frontend, and Contentstack will take care of the rest. Read More. |
| 4 | + |
| 5 | + |
| 6 | +This guide will help you get started with Contentstack .NET Utils SDK to build apps powered by Contentstack. |
| 7 | + |
| 8 | +## Prerequisites |
| 9 | +To get started with .NET, you will need the following: |
| 10 | + |
| 11 | +- .NET version 3.1 or later |
| 12 | + |
| 13 | +## Setup and Installation |
| 14 | + |
| 15 | +Note: If you are using Contentstack .NET SDK, you don’t need to download the Contentstack.Utils package separately as it will be already available for use. |
| 16 | + |
| 17 | +To download the Contentstack.Utils module, open the terminal and perform any of the following options: |
| 18 | + |
| 19 | +- Via Package Manager: |
| 20 | +```sh |
| 21 | +PM> Install-Package contentstack.utils |
| 22 | +``` |
| 23 | + |
| 24 | +- Via .NET CLI: |
| 25 | +```sh |
| 26 | +dotnet add package contentstack.utils |
| 27 | +``` |
| 28 | + |
| 29 | +After successful installation, to use the module in your application, you need to add a namespace to your class: |
| 30 | +```c# |
| 31 | +using Contentstack.Utils |
| 32 | +``` |
| 33 | + |
| 34 | +## Usage |
| 35 | + |
| 36 | +Let’s learn how you can use .NET Utils SDK to render embedded items by performing the following steps: |
| 37 | + |
| 38 | +1. ### Create CustomRenderOption class |
| 39 | + |
| 40 | +To render embedded items on the front-end, use the CustomRenderOption class, and define the UI elements you want to show in the front-end of your website, as shown in the example below. In this example, we have specified the cases for each method of adding embedded items: Block, Inline, Link, Display and Download (for asset). |
| 41 | +```c# |
| 42 | +using System.Collections.Generic; |
| 43 | +using Contentstack.Utils.Interfaces; |
| 44 | +using Contentstack.Utils.Models; |
| 45 | +using Contentstack.Utils.Enums; |
| 46 | +public class CustomRenderOption: Options |
| 47 | +{ |
| 48 | + public CustomRenderOption(IEntryEmbedable entry) : base(entry) |
| 49 | + { |
| 50 | + } |
| 51 | + public override string RenderOption(IEmbeddedObject embeddedObject, Metadata metadata) |
| 52 | + { |
| 53 | + switch (metadata.StyleType) |
| 54 | + { |
| 55 | + |
| 56 | + //if you have added embedded object using the “Block” option |
| 57 | + case StyleType.Block: |
| 58 | + string renderString = ""; |
| 59 | + if (embeddedObject is IEmbeddedEntry) |
| 60 | + { |
| 61 | + renderString += $"<div> <b>{((IEmbeddedEntry)embeddedObject).Title}</b></div>"; |
| 62 | + } |
| 63 | + else if (embeddedObject is IEmbeddedContentTypeUid) |
| 64 | + { |
| 65 | + renderString += $"<div> <b>{embeddedObject.Uid}</b></div>"; |
| 66 | + } |
| 67 | + return renderString; |
| 68 | + |
| 69 | + //if you have added embedded object using the “Inline” option |
| 70 | + case StyleType.Inline: |
| 71 | + if (embeddedObject is IEmbeddedEntry) |
| 72 | + { |
| 73 | + return $"<span><b>{((IEmbeddedEntry)embeddedObject).Title}</b></span>"; |
| 74 | + } |
| 75 | + else if (embeddedObject is IEmbeddedContentTypeUid) |
| 76 | + { |
| 77 | + return $"<span><b>{embeddedObject.Uid}</b></span>"; |
| 78 | + } |
| 79 | + return "<span>" + embeddedObject.Uid + "</span>"; |
| 80 | + |
| 81 | + //if you have added embedded object using the “Link” option |
| 82 | + case StyleType.Link: |
| 83 | + if (embeddedObject is IEmbeddedEntry) |
| 84 | + { |
| 85 | + return $"<span> Please find link to: <a><b>{metadata.Text ?? ((IEmbeddedEntry)embeddedObject).Title}</b></a></span>"; |
| 86 | + } |
| 87 | + else if (embeddedObject is IEmbeddedContentTypeUid) |
| 88 | + { |
| 89 | + return $"<span> Please find link to: <a><b>{metadata.Text ?? embeddedObject.Uid}</b></a></span>"; |
| 90 | + } |
| 91 | + return "<a href=\"" + embeddedObject.Uid + "\">" + (metadata.Text ?? embeddedObject.Uid) + "</a></span>"; |
| 92 | + |
| 93 | + //if you have embedded an asset into the RTE field |
| 94 | + case StyleType.Display: |
| 95 | + if (embeddedObject is IEmbeddedAsset) |
| 96 | + { |
| 97 | + return $"<b>{((IEmbeddedAsset)embeddedObject).Title}</b><p>{((IEmbeddedAsset)embeddedObject).FileName} image: <img src=\"{((IEmbeddedAsset)embeddedObject).Url}\" alt=\"{((IEmbeddedAsset)embeddedObject).Title}\"/></p>"; |
| 98 | + } |
| 99 | + return "<img src=\"" + embeddedObject.Uid + "\" alt=\"" + embeddedObject.Uid + "\" />"; |
| 100 | + |
| 101 | + //if you have embedded an asset directly via a download link. |
| 102 | + case StyleType.Download: |
| 103 | + if (embeddedObject is IEmbeddedAsset) |
| 104 | + { |
| 105 | + return "<span> Please find link to: <a href=\"" + ((IEmbeddedAsset)embeddedObject).Url + "\">" + (metadata.Text ?? ((IEmbeddedAsset)embeddedObject).Title) + "</a></span>"; |
| 106 | + } |
| 107 | + return "<a href=\"" + embeddedObject.Uid + "\">" + (metadata.Text ?? embeddedObject.Uid) + "</a>"; |
| 108 | + } |
| 109 | + return base.RenderOption(embeddedObject, metadata); |
| 110 | + } |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +2. ### Initialize the class |
| 115 | +Initialize either the Options or CustomRenderOption class to use them for rendering embedded items as shown below: |
| 116 | +```c# |
| 117 | +//To use the default render option: |
| 118 | +Options defaultRender = new Options(entry); |
| 119 | + |
| 120 | +//To use CustomRenderOptions: |
| 121 | +CustomRenderOption defaultRender = new CustomRenderOption(entry); |
| 122 | + ``` |
| 123 | +> Note: Make sure the entry parameter has implemented the IEmbeddedObject property. |
| 124 | +
|
| 125 | +## Basic Queries |
| 126 | + |
| 127 | +Contentstack Utils SDK lets you interact with the Content Delivery APIs and retrieve embedded items from the RTE field of an entry. |
| 128 | + |
| 129 | +### Fetch Embedded Item(s) from a Single Entry |
| 130 | + |
| 131 | +To get an embedded item of a single entry, you need to provide the stack API key, environment name, delivery token, content type and entry UID: |
| 132 | +```c# |
| 133 | +using Contentstack.Core; // ContentstackClient |
| 134 | +using Contentstack.Core.Models; // Stack, Query, Entry, Asset, ContentType, ContentstackCollection |
| 135 | +using Contentstack.Core.Configuration; // ContentstackOptions |
| 136 | +using Contentstack.Utils; // Utils.RenderContent |
| 137 | +Using Contentstack.Utils.Models; // Options, Metadata |
| 138 | +ContentstackClient client = new ContentstackClient("api_key", "delivery_token", "enviroment_name"); |
| 139 | + |
| 140 | +client.ContentType("product").Entry("<entry_uid>"); |
| 141 | + .includeEmbeddedItems() |
| 142 | + .Fetch<Product>().ContinueWith((response) => { |
| 143 | + if (!response.IsFaulted) { |
| 144 | + // To use the default render option: |
| 145 | + string result = Utils.RenderContent(response.result.rte, new Option(response.result)); |
| 146 | + // To use the Custom render option: |
| 147 | + string result = Utils.RenderContent(response.result.rte, new CustomRenderOption(response.result)); |
| 148 | + } |
| 149 | +}); |
| 150 | + ``` |
| 151 | + |
| 152 | +### Fetch Embedded Item(s) from Multiple Entries |
| 153 | + |
| 154 | +To get embedded items from multiple entries, you need to provide the stack API key, environment name, delivery token, content type UID. You can use the path variable in case the entries have multiple RTE fields. |
| 155 | +```c# |
| 156 | +using Contentstack.Core; // ContentstackClient |
| 157 | +using Contentstack.Core.Models; // Stack, Query, Entry, Asset, ContentType, ContentstackCollection |
| 158 | +using Contentstack.Core.Configuration; // ContentstackOptions |
| 159 | +using Contentstack.Utils; // Utils.RenderContent |
| 160 | +Using Contentstack.Utils.Models; // Options, Metadata |
| 161 | + |
| 162 | +ContentstackClient client = new ContentstackClient("api_key", "delivery_token", "enviroment_name"); |
| 163 | + |
| 164 | +client.ContentType("product").Query() |
| 165 | + .includeEmbeddedItems(); |
| 166 | + .Find<Product>().ContinueWith((t) => { |
| 167 | + if (!t.IsFaulted) { |
| 168 | + ContentstackCollection<Product> result = t.Result; |
| 169 | + foreach (var product in result.Items) |
| 170 | + { |
| 171 | + // To use the default render option |
| 172 | + string result = Utils.RenderContent(product.rte, new Option(product)); |
| 173 | + // To use the Custom render option |
| 174 | + string result = Utils.RenderContent(product.rte, new CustomRenderOption(product)); |
| 175 | + } |
| 176 | + } |
| 177 | + }); |
| 178 | +``` |
0 commit comments