Skip to content

Latest commit

 

History

History
646 lines (449 loc) · 17.1 KB

README.md

File metadata and controls

646 lines (449 loc) · 17.1 KB
Raw

buttercms-csharp

.NET Standard (2.1) Library for ButterCMS API.

Documentation

For a comprehensive list of examples, check out the API documentation.

Installation

To install ButterCMS, run the following command in the Package Manager Console

PM> Install-Package ButterCMS

The library can also be installed to the project via .NET CLI

dotnet add package ButterCMS

Or by adding the package manually to the project file

<ItemGroup>
<PackageReference Include="ButterCMS" Version="2.0.2" />
</ItemGroup>

Usage

To get started with the Butter API, instantiate the ButterCMSClient with the API key found in the Butter Admin Settings. An optional timeout parameter can be passed as a TimeSpan; the default is 10 seconds.

using ButterCMS;
...
var butterClient = new ButterCMSClient("API KEY");

If the application will be making many Butter API calls, it is recommended to store and re-use the client object.

Each Butter client method has a synchronous version and an asynchronous version. Asynchronous methods are appended with the word "Async".

Preview mode

Preview mode can be used to setup a staging website for previewing content fields or for testing content during local development. To fetch content from preview mode add an additional argument, true, to the package initialization:

using ButterCMS;
...
bool previewMode = true;

var butterClient = new ButterCMSClient("API KEY", null, 3, null, previewMode);

Sections

Posts

List Posts

Listing posts returns a PostsResponse object. This object consists of a metadata object and IEnumerable<Post>

ListPosts() Parameters

Parameter Default Description
page(optional) 1 Used to paginate through older posts.
pageSize(optional) 10 Used to set the number of blog posts shown per page.
excludeBody(optional) false When true, does not return the full post body. Useful for keeping response size down when showing a list of blog posts.
authorSlug(optional) Filter posts by an author’s slug.
categorySlug(optional) Filter posts by a category’s slug.

Examples

PostsResponse posts = butterClient.ListPosts();

PostsResponse filteredPosts = await butterClient.ListPostsAsync(page: 2, pageSize: 5, excludeBody: true, authorSlug: "alice", categorySlug: "dot-net");

Retrieving a Single Post

Retrieving a single Post will return a PostResponse object. This object consists of a single Post and Post Metadata. Post Metadata offers hints about the Previous and Next posts.

RetrievePost() Parameters

Parameter Description
slug The slug of the post to be retrieved.

Examples

PostResponse controversialPost = butterClient.RetrievePost("tabs-vs-spaces-throwdown");

PostResponse safePost = await butterClient.RetrievePostAsync("puppies-and-kittens");

Searching Posts

Searching posts will return the same object as listing posts, PostsResponse

SearchPosts() Parameters

Parameter Default Description
query Search query
page(optional) 1 Used to paginate through older posts.
pageSize(optional) 10 Used to set the number of blog posts shown per page.

Examples

PostsResponse posts = butterClient.SearchPosts("spaceships");

PostsResponse caffeinePosts = await butterClient.SearchPostsAsync(query: "coffee", page: 3, pageSize: 5);

Authors

List Authors

Listing Authors returns IEnumerable<Author>

ListAuthors() Parameters

Parameter Description
includeRecentPosts(optional) If true, will return the author's recent posts in the response

Examples

IEnumerable<Author> authors = butterClient.ListAuthors();

IEnumerable<Author> authorsWithPosts = await butterClient.ListAuthorsAsync(includeRecentPosts: true);

Retrieve a Single Author

Retrieving an author returns an Author object

RetrieveAuthor() Parameters

Parameter Description
authorSlug The slug of the author to be retrieved.
includeRecentPosts(optional) If true, will return the author's recent posts in the response

Examples

Author sally = butterClient.RetrieveAuthor("sally");

Author tylerAndPosts = await butterClient.RetrieveAuthorAsync(authorSlug: "tyler", includeRecentPosts: true);

Categories

List Categories

Listing Categories returns IEnumerable<Category>

ListCategories() Parameters

Parameter Description
includeRecentPosts(optional) If true, will return recent posts along with categories

Examples

IEnumerable<Category> categories = butterClient.ListCategories();

IEnumerable<Category> categoriesWithPosts = await butterClient.ListCategoriesAsync(includeRecentPosts: true);

Retrieve a Single Category

Retrieving a single category returns Category

RetrieveCategory() Parameters

Parameter Description
categorySlug The slug of the category to be retrieved.
includeRecentPosts(optional) If true, will return recent posts along with category

Examples

 Category dotnetCategory = butterClient.RetrieveCategory("dotnet");

 Category fsharpCategoryWithPosts = await butterClient.RetrieveCategoryAsync(categorySlug: "fsharp", includeRecentPosts: true);

Feeds

Each of the feeds methods returns an XmlDocument.

RSS Feed

Retrieve a fully generated RSS feed for your blog.

Examples

 XmlDocument rssFeed = butterClient.GetRSSFeed();

 XmlDocument rssFeed = await butterClient.GetRSSFeedAsync();

Atom Feed

Retrieve a fully generated Atom feed for your blog.

Examples

 XmlDocument atomFeed = butterClient.GetAtomFeed();

 XmlDocument atomFeed = await butterClient.GetAtomFeedAsync();

Sitemap

Retrieve a fully generated sitemap for your blog.

Examples

 XmlDocument siteMap = butterClient.GetSitemap();

 XmlDocument siteMap = await butterClient.GetSitemapAsync();

Collections

New in version 1.3.0

By the power of .NET generics, Collections can now be deserialized by the library! The former method that would defer deserialization is still available to ease transition.

RetrieveContentFields() Parameters

Parameter Description
key String array of the Collection key
parameterDictionary(optional) Dictionary of additional parameters, such as "locale" or "preview"

RetrieveContentFields() Exceptions:

Exception Description
ContentFieldObjectMismatchException This exception will be thrown when the library can't fit the returned data into the passed object class.

Examples

var key = new string[1] { "collection_key" };
var dict = new Dictionary<string, string>()
            {
                { "locale", "de" }
            };
var teamMembersAndHeadline = butterClient.RetrieveContentFields<TeamMembersHeadline>(key, dict);

** Collection JSON documentation** :

As demonstrated in the Collection documentation, any number of user-defined Collections can be retrieved from the API, these can get complicated in C# and you may choose to handle the response yourself. The RetrieveContentFieldsJSON() method will return the raw JSON response from the Butter API.

RetrieveContentFieldsJSON() Parameters

Parameter Description
key String array of the Collection key
parameterDictionary(optional) Dictionary of additional parameters, such as "locale" or "preview"

Examples

var key = new string[1] { "collection_key" };
var dict = new Dictionary<string, string>()
            {
                { "locale", "de" }
            };
var contentFields = await butterClient.RetrieveContentFieldsJSONAsync(key, dict);

Pages

ButterCMS Pages can be retrieved by first defining the custom Page Type as a class. These custom Page Types are defined in the Butter admin.

List Pages

Listing Pages returns a PagesResponse<T> object. Full API documentation can be found at https://buttercms.com/docs/api/#list-pages-for-a-page-type.

ListPages() Parameters

Parameter Description
pageType Desired page type
parameterDictionary Dictionary of additional parameters. These options are described in greater detail in the full API documentation.

ListPages() Exceptions

Exception Description
PagesObjectMismatchException This exception will be thrown when the library can't fit the returned data into the passed object class.

Retrieve a Single Page

Retrieving a single page returns a PageResponse<T> object

RetrievePage() Parameters

Parameter Description
pageType Desired page type
pageSlug Slug of the desired page
parameterDictionary Dictionary of additional parameters

RetrievePage() Exceptions:

Exception Description
PagesObjectMismatchException This exception will be thrown when the library can't fit the returned data into the passed object class.

Examples

Page Type Definition in the Butter Admin

alt text

Controller and ViewModel examples
public namespace HungryDevApp
{
    public class RecipePage
    {
        public string category { get; set; }
        public string recipe_name { get; set; }
        public string main_ingredient { get; set; }
        public double estimated_cooking_time_in_minutes { get; set; }
        public string ingredient_list { get; set; }
        public string instructions { get; set; }
    }

    public class RecipesController : Controller
    {
        [Route(recipes/)]
        public virtual ActionResult Index(int page = 1, int pageSize = 10)
        {
            var butterClient = new ButterCMSClient("API KEY");

            var parameterDict = new Dictionary<string, string>()
            {
                {"page", page.ToString()},
                {"page_size", pageSize.ToString()}
            };

            PagesResponse<RecipePage> recipePages = butterClient.ListPages<RecipePage>("recipe", parameterDict);

            var viewModel = new RecipesViewModel();
            viewModel.PreviousPageNumber = recipePages.Meta.PreviousPage;
            viewModel.NextPageNumber = recipePages.Meta.NextPage;
            viewModel.PagesCount = recipePages.Meta.Count;

            viewModel.Recipes = new List<RecipeViewModel>();
            foreach (Page<RecipePage> recipe in recipePages.Data)
            {
                RecipeViewModel recipeViewModel = new RecipeViewModel();
                recipeViewModel.Category = recipe.Fields.category;
                recipeViewModel.RecipeName = recipe.Fields.recipe_name;
                recipeViewModel.MainIngredient = recipe.Fields.main_ingredient;
                recipeViewModel.EstimatedCookingTimeInMinutes = recipe.Fields.estimated_cooking_time_in_minutes;
                recipeViewModel.IngredientList = recipe.Fields.ingredient_list;
                recipeViewModel.Instructions = recipe.Fields.instructions;

                viewModel.Recipes.Add(recipeViewModel);
            }

            return View(viewModel);
        }

        [Route(recipe/{slug})]
        public virtual ActionResult Recipe(string slug)
        {
            var butterClient = new ButterCMSClient("API KEY");

            PageResponse<RecipePage> recipe = butterClient.RetrievePage<RecipePage>("recipe", slug);

            var viewModel = new RecipeViewModel();
            viewModel.Category = recipe.Data.Fields.category;
            viewModel.RecipeName = recipe.Data.Fields.recipe_name;
            viewModel.MainIngredient = recipe.Data.Fields.main_ingredient;
            viewModel.EstimatedCookingTimeInMinutes = recipe.Data.Fields.estimated_cooking_time_in_minutes;
            viewModel.IngredientList = recipe.Data.Fields.ingredient_list;
            viewModel.Instructions = recipe.Data.Fields.instructions;

            return View(viewModel);
        }
    }

    public class RecipesViewModel
    {
        public List<RecipeViewModel> Recipes { get; set; }
        public int? PreviousPageNumber { get; set; }
        public int? NextPageNumber { get; set; }
        public int PagesCount { get; set; }
    }

    public class RecipeViewModel
    {
        public string Category { get; set; }
        public string RecipeName { get; set; }
        public string MainIngredient { get; set; }
        public double EstimatedCookingTimeInMinutes { get; set; }
        public string IngredientList { get; set; }
        public string Instructions { get; set; }
    }

}
Example View usage for ListPages
@using HungryDevApp
@{
Layout = "~/Views/Shared/Layouts/_Layout.cshtml";
}
@model RecipesViewModel
<div>
    <a href="/recipes/?page=@{Model.PreviousPageNumber}&pageSize=10">Previous page</a>
    <a href="/recipes/?page=@{Model.NextPageNumber}&pageSize=10">Next page</a>
</div>
<div>
    <p>@{Model.PagesCount} recipes total</p>
</div>
<div>
    <ul>
        @foreach(var page in Model.Recipes)
        {
            <li>
                <a href="/recipe/@{page.Slug}">@{page.RecipeName}
            </li>
        }
    </ul>
</div>
Example View usage for RetrievePage
@using HungryDevApp
@{
Layout = "~/Views/Shared/Layouts/_Layout.cshtml";
}
@model RecipeViewModel
<div>
    <h2>@{Model.RecipeName}</h2>
    <p>Estimated cooking time: @{Model.EstimatedCookingTimeInMinutes} minutes</p>
    <h3>Ingredients:</h3>
    <p>@{Model.IngredientList}</p>
    <h3>Instructions:</h3>
    <p>@{Model.Instructions}</p>
</div>

Class Definitions

PostsResponse Class

Property Type
Meta PostsMeta
Data IEnumerable<Post>

PostsMeta Class

Property Type
Count int
NextPage int?
PreviousPage int?

Post Class

Property Type
Url string
Created DateTime
Published DateTime
Author Author
Categories IEnumerable<Category>
FeaturedImage string
FeaturedImageAlt string
Slug string
Title string
Body string
Summary string
SeoTitle string
MetaDescription string
Status PostStatusEnum

PostStatusEnum

Constant Value
Unknown 0
Draft 1
Published 2

PostResponse Class

Property Type
Meta PostMeta
Data Post

PostMeta Class

Property Type
NextPost PostLight
PreviousPost PostLight

PostLight Class

Property Type
Slug string
Title string
FeaturedImage string

Author Class

Property Type
FirstName string
LastName string
Email string
Slug string
Bio string
Title string
LinkedinUrl string
FacebookUrl string
InstagramUrl string
PinterestUrl string
TwitterHandle string
ProfileImage string
RecentPosts IEnumerable<Post>

Category Class

Property Type
Name string
Slug string
RecentPosts IEnumerable<Post>

PagesResponse Class

Property Type
Meta PageMeta
Data IEnumerable<Page<T>>

PageMeta Class

Property Type
Count int
PreviousPage int?
NextPage int?

PageResponse Class

Property Type
Data Page<T>

Page Class

Property Type
Slug string
Updated DateTime
Published DateTime?
PageType string
Fields T

Exceptions

Testing

To run SDK test just simply:

PM> dotnet test

Or use Visual Studio Test Explorer.

InvalidKeyException

The library throws this exception when the Butter API key used to instatiate the client was not valid.

ContentFieldObjectMismatchException

This exception will be thrown when the library can't fit the returned data from a Content Field request into the passed object class.

PagesObjectMismatchException

This exception will be thrown when the library can't fit the returned data from a Pages request into the passed object class.