Umbraco Font Awesome Extension - documentation, installation and usage examples

by Matt Barlow  10 Dec, 2019  0 comments

There are two methods to install our Umbraco Font Awesome Extension:

  • via nuget (the package manager for Visual Studio) or,
  • the Umbraco back office

Installation via nuget

Open visual studio, then the nuget property package manager console, type the following to install the package.

PM> Install-Package FontAwesomePropertyEditor

Installation via the Umbraco back office

In the packages section search for "u8 fontawesome links".

Navigate to the packages section

Locate our Font Awesome Property editor in the Umbraco back office.

Then click "install package", on the next screen check "I accept terms of use" then click the install package button.

Review the package details

Check details and install package.


Using the Font Awesome Extension

There are two property editors installed, one is for adding Font Awesome Icons to your document, the other is for adding Font Awesome Links. Links allow you to have a list of links each with a pickable icon, whilst Icons don't have an associated link, it's just a pickable icon.

Pick the editor

Within the pickers category choose the property editor.

Font Awesome Icon

To add an icon to your documents types select your document then add a property of type "Font Awesome Icon".

Next, set the configuration for the property. When naming, it is good practice to name the the editor based on the configuration chosen. So if the configuration has no minimum or maximum number of items picked then I would name the editor "Font Awesome Icon (no min - no max)".

Configure 

Set the configuration for the property editor.

If I want only one icon to be picked, then I can set the minimum number of items to 0, and the max to 1. I would call the editor "Font Awesome Icon (no min - max 1)".

Using a naming convention like this means that it's quick and easy to reuse the property editor on different document types.

After setting up the editor it's ready to be used when creating a property on your document. Add a name for your property as normal as well as your property description, save the changes, then you are ready to go.

Add your property

Add the settings for the property.

Create some content using your new property, select an icon by clicking the +icon text.

Populate property

Set the content for your property.


Using a single icon in your front-end razor view

When the property editor is configured to have a maximum of one item then the strongly typed property will be a single instance of the class.

To use this property in your view you should add a reference to the the Font Awesome models classes. Add the following code for a single icon:

@using FaLinksPropertyEditor.Models

Then depending which mode of models builder you have, where my property is called blogIcon, to get the strongly typed model value (without models builder) you can then use:

var blogIcon = Model.Value<FaLinksPropertyEditor.Models.FaIcon>("blogIcon");

You can then access the strongly typed properties on blogIcon, there are two ways to render the icons. The first way, is to use the class name (prefered):

<div>
	<span class="icon">
		<i class="@blogIcon.ClassName"></i>
	</span>
</div>

The second way is to output the svg directly:

<div>
	<span class="icon">@Html.Raw(blogIcon.Svg)</span>
</div>

Or if you are inheriting from your model and using models builder, you can access the property directly. Where YourModel is your models builder model and BlogIcon is property on your model.

@inherits UmbracoViewPage<YourModel>
@using FaLinksPropertyEditor.Models

<div>
	<span class="icon">
		<i class="@Model.BlogIcon.ClassName"></i>
	</span>
</div>

@Html.Raw(Model.BlogIcon.Svg)

Using multiple icons in your front-end razor view

When the the maxium is not set to 1, then it's assumed multiple icons can be returned, so the strongly typed property will be an IEnumerable of the Icon class:

var blogIcons = Model.Value<IEnumerable<FaIcon>>("blogIcons").ToList();

Then to loop through the list of of icons would be:

@foreach(var blogIcon in blogIcons)
{
	<i class="blogIcon.ClassName"></i>
}

Avoiding null reference errors

When a value has not been set for the property then the returned object is null. This will cause a null reference error on the front-end. To stop this occurring you should always check for null before using the property.

@if (Model.BlogIcon != null)
{
	<i class="@Model.BlogIcon.ClassName"></i>
	@Html.Raw(Model.BlogIcon.Svg)
}

Using Font Awesome Links

Having discussed the Font Awesome Icon, we go onto Font Awesome Links. This property editor allows you to assign a Font Awesome Icon to a link. The usage instructions are the same as above, with a few additions.

You can select a link that is associated with an icon, and you have the additional option of setting a list of class names that can be picked from, say for example I have some CSS classes that will make the link a button using the primary color scheme. I would then add a friendly name "Primary" then the class name "is-primary" in the second field.

I also want to decide on the size on the button, so I can then utilise the secondary class drop down settings to add button sizes, eg: "Medium Button" for the name, and "btn is-medium" for the class.

Link Settings

Adding style and button class settings.

Once you have assigned your property editor to a property on your document type then you can add an icon, select a link and also choose your primary and secondary classes.

Populated Links

Example of a list of links with associated icons.

Using the Font Awesome Links in your front end razor view is almost the same as when rendering the icons, however the model used is of type "FaLink", eg:

var pageLinks = Model.Value<IEnumerable<FaLink>>("pageLinks").ToList();

@foreach(var faLink in pageLinks)
{ 
	if(faLink != null)
	{
		if (faLink.Link.HasValue())
		{
			<a href="@faLink.Link.Url" class="@faLink.PrimaryClass @faLink.SecondaryClass" target="@faLink.Link.Target">
				@if (faLink.ClassName.HasValue())
				{
					<span class="icon @classListIcon">
						<i class="@faLink.ClassName"></i>
					</span>
					@:&nbsp;
				}
				@faLink.Link.Name
			</a>
		}
	}
}

This wraps up how to use our Font Awesome Extension, as you can see, its a highly configurable property editor that will supercharge your editor experience. For more full usage examples please head over to github to see our Bulma Starter Kit code example.

As always, thanks for taking the time to read this, please reach out to me if you have any comments or suggestions.

Happy Umbracoing!

-- Matt

 

About

About Matt Barlow

Matt is a full-stack C# developer specialising in Umbraco, he works in London and is the creator of Jacker.io.

Related articles

Previous

Code Garden 2019 - take aways from the biggest Umbraco conference

I went to Umbraco Code Garden in Odense this year. Get some insights from the best Umbraco talks.

Matt Barlow  Matt Barlow

Next

How to add a free SSL certificate to your Umbraco site in 5 minutes

A tutorial explaining the steps for adding a free SSL certificate from Let's Encrypt to your Umbraco site quickly.

Matt Barlow  Matt Barlow