Jump to main content

Build a code block for Piranha CMS with Prism.js

2021-08-02 Piranha
Would you like to display code on your Piranha website like the examples below? With Prism.js it’s easy. This guide will help you build a custom block which does just that.

Add Prism.JS to your project

First thing we need to do is to include the requires Javascript and CSS files to our project. Go to Prismjs.com. Under the section “Basic usage” you’ll find different ways to include the required files into your project. You can either download them or preferably use a CDN to reduce server load.

Make sure you get the following files, either one by one or as a bundle:

  • prism.min.css
  • prism-line-numbers.min.css
  • prism.min.js
  • prism-autoloader.min.js
  • prism-line-numbers.min.js
_Layout.css - CSS files goes in the <head>
<!-- Note that this is just an example and the files might be outdated -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.23.0/themes/prism.min.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.23.0/plugins/line-numbers/prism-line-numbers.min.css" />
_Layout.css - Javascript files goes in the body right before the closing </body> tag
<!-- Note that this is just an example and the files might be outdated -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.23.0/prism.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.23.0/plugins/autoloader/prism-autoloader.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.23.0/plugins/line-numbers/prism-line-numbers.min.js"></script>

Create an Enum to handle different Code languages

Now when you have the latest Javascript and CSS files for Prism.Js we're ready to start building the components for your new block. We want to have the possibility to use multiple code languages and not just one. Therefore we need to create an Enum. An enum can be used to populate a SelectField with options in Piranha. In this guide we named the enum CodeType and the file CodeType.cs
You can preferably put the Enum in a separate folder called Enums

CodeType.cs - An enum that will help us populate the SelecField for our code language picker
public enum CodeType
{
    Bash,
    CSS,
    Dotnet,
    Html,
    Javascript,
    Python
}

public static class CodeTypeExtension
{
    public static string GetPrismClass(this CodeType codeType)
    {
        switch (codeType)
        {
            case CodeType.Bash:
                return "bash";
            case CodeType.CSS:
                return "css";
            case CodeType.Dotnet:
                return "dotnet";
            case CodeType.Html:
                return "html";
            case CodeType.Javascript:
                return "javascript";
            case CodeType.Python:
                return "python";
            default:
                return string.Empty;
        }
    }
}

Adding the block model

We are now ready to start building a model for our block. Create a new class and name it CodeBlock. Make sure it inherits from the class Block. It’s important that all the field properties have the Data annotation [Field] so Piranha understands what to do with the properties

CodeBlock.cs - Block model
[BlockType(Name = "Code", Category = "Special", Icon = "fas fa-code")]
public class CodeBlock : Block
{
    [Field(Title = "Code title")]
    public StringField CodeTitle { get; set; }

    [Field(Title = "Code type", Options = FieldOption.HalfWidth)]
    public SelectField<CodeType> CodeType { get; set; }

    [Field(Title = "Show line numbers", Options = FieldOption.HalfWidth)]
    public CheckBoxField ShowLineNumbers { get; set; }

    [Field]
    public TextField Code { get; set; }
}

Creating a new view

Our block needs a view. Create a separate folder for your block views if you don’t have one already. Create a new view with the same name you had for your model. In this case the file will be called CodeBlock.cshtml

At the top of the file we’ll add our model. Make sure you have the right namespace which might differ from this example.

CodeBlock.cshtml - View
@model CodeBlock

@{ 
    string codeClass = CodeTypeExtension.GetPrismClass(Model.CodeType.Value);

    if (!string.IsNullOrEmpty(codeClass))
    {
        codeClass = $"language-{codeClass}";
    }
}

<div class="block block-code">
    @if (!string.IsNullOrEmpty(Model.CodeTitle))
    {
        <span class="block-code-title">@Model.CodeTitle</span>
    }

    <pre class="@(Model.ShowLineNumbers.Value ? "line-numbers" : "")"><code class="@codeClass">@Model.Code.Value</code></pre>
</div>

Register your new block

The last step is to register your new block in the Configure() method in Startup.cs. If the block is not registered there then it won’t show up in the manager.

Startup.cs - All custom blocks must be registered in the Configure() method
Piranha.App.Blocks.Register<CodeBlock>();
How about another great post? Next

You might also want to read the following

2021-08-12 Piranha

Edit block templates inside the manager with Scriban

Want to edit block templates without rebuilding your project? Let Scriban help you with that. Scriban parses your custom Html and objects and then gives you HTML ready to be used anywhere.

2021-08-11 Piranha

Track users with Google Analytics on your Piranha site

Keep a track on your visitors and which pages are popular with Google Analytics. This post gives you a great example on how you can implement a dynamic way to add end edit your tracking codes

2021-08-10 Piranha

Manage your footer with a region

Footers are a basic component of almost all websites. Therefor we'll make it as easy as possible for us to manage ours by turning it into a region area on our site model. This guide uses Bootstrap 5

2021-08-08 Piranha

Carousel block for Piranha with Bootstrap

A good image slider or carousel can complete your website. This post will give you a quick example on how you can add your own carousel to your Piranha site

2021-08-07 Piranha

Youtube block for Piranha

Want to show Youtube videos on your Piranha site? This post will give you a quick example on how you could implement a Youtube block on your site, either for showing useful videos or Rick-Rolling your visitors

2021-08-05 Piranha

Accordion block with Bootstrap 5

Sometimes you have way to much text to fit on a page. A simple way to structure and group important content is by using an accordion. This post will give you an idea on how you can implement your own accordion on a Piranha site