Carbide for Umbraco

Using Carbide

Simply include the git repo as a submodule in your Umbraco solution, and add a project reference to it in any other projects. You can also place the project into your solution, but you'll lose the benefit of a single source for Carbide updates.

Once you add the project to your solution, be sure to reference it in your code where applicable. And since Carbide uses Halide for the standard ASP.NET/MVC side of things, you will want to include a reference to that library as well, to gain the additional benefits:

using Fynydd.Halide;
using Fynydd.Halide.Constants;
using Fynydd.Carbide;

or in Razor views...

@using Fynydd.Halide
@using Fynydd.Halide.Constants
@using Fynydd.Carbide

Classes and namespaces

Following are the namespaces and classes available in Carbide. Classes and properties are documented and should provide Intellisense tips in Visual Studio. Much of Carbide leverages Halide, so you'll want to look there for information on additional features it provides.

ContentHelpers

These are static extension methods to use for retrieving IPublishedContent properties and nodes with as little code as possible, and in a way that's predictable. For example SafeGetValue<T>() provides a simple way to get a property value that always returns a value, so no null checks, and foreach loops work even when the value is empty.

Example for retrieving property values from IPublishedContent:

var text = Model.SafeGetValue("buttonText");
var age = Model.SafeGetValue<int>("ageInYears");

Example for iterating IPublishedContent nested content without a null check:

foreach (var subunit in Model.SafeGetNestedContentItems("technologySubunits"))

Retrieve a UDI from any IPublishedContent object:

var value = Model.GetUdi();

Example for retrieving a URL to IPublishedContent media:

var backgroundImageUrl = Model.SafeGetMediaPickerItemUrl("featurePhoto", width: 800, quality: 80, filters: "filter=greyscale");

There are lots of other methods for retrieving content and evaluating the existence of property data. See what's available by using Intellisense on IPublishedContent objects, or look at the class file.

FormValidators

Additional MVC model and client-side validators for your forms. To use client-side validation features, be sure to include the scripts:

<script src="@Html.Raw(Url.Content("~/umbraco/api/carbidesupport/scripts/?file=FormValidationHelpers"))"></script>
  1. MinimumFileSizeValidator
    Model usage:
    Where # is the number of megabytes.
    [MinimumFileSizeValidator(#)]
  2. MaximumFileSizeValidator
    Model usage:
    Where # is the number of megabytes.
    [MaximumFileSizeValidator(#)]
  3. ValidFileTypeValidator
    Model usage:
    Accepts a string array list of valid file extensions, without leading periods.
    [ValidFileTypeValidator(new string[] { "pdf", "docx" })]

MediaHelpers

Although the IPublishedContent methods in ContentHelpers also help with using media, these static methods go one step further by providing functions to generate YouTube markup, process SVG images, and more.

Here's an example for rendering a YouTube embed:

var output = MediaHelpers.GetYoutubeEmbedCode(Model.SafeGetValue("videoUrl"));

Media property retrieval is performed from extension methods in the ContentHelpers class for IPublishedContent, since media uses the same object type. The methods in MediaHelpers focus on handling other types of media.

SEO Helpers

Following are features to help with SEO and site indexing.

  1. RobotsTxt

    If you add the following to your web.config, instances of {HTTP_HOST} in a robots.txt file at the root of your site will be swapped for the actual domain of the current site and served dynamically.

    <system.webServer>
  <handlers>
     <add name="RobotsTxt" path="/robots.txt" verb="*" type="Fynydd.Carbide.RobotsTxt" resourceType="Unspecified" preCondition="integratedMode" />

WebAPI/Controller Endpoints

Following are the endpoints provided by Carbide.

JavaScripts:

/umbraco/api/carbidesupport/scripts/
Use this URL to generate a path to a JavaScript resource for client-side validation support, etc.

Content caches:

/umbraco/api/carbidesupport/rebuildcache/
Rebuild the content cache and Examine indexes, and refresh the content cache.

/umbraco/api/carbidesupport/rebuildimagecache/
Delete all cached images made by ImageProcessor.Web.

/umbraco/api/carbidesupport/prerenderpages/
Iterate all page templates and prerender one page per template to speed up initial page load after deployments, etc.

/umbraco/api/carbidesupport/rebuildcachestatus/
Get the current status of a cache rebuild.

/umbraco/api/carbidesupport/rebuildcachestatushistory/
Get the last status of a cache rebuild.

Dynamic SVG support:

/umbraco/api/carbidefile/svg/
Use this URL to generate a path to an SVG resource. Allows recoloring and file cleanup to be performed.

Need help using this?

If you need help with this or any of our other open source projects, Fynydd can consult with you to get your project moving in the right direction. Just let us know by visiting our contact page where you can reach out or talk to us directly on our free slack community.

← Back to Carbide for Umbraco