The best way to construct a Feather CMS module?

Module era utilizing Swift templates

There may be an open supply template based mostly generator instrument for Swift that I’ve created, as a result of I wanted one thing to rapidly arrange each VIPER and Feather modules. We’re going to use this generator to start out constructing our customized Feather module. You may set up Swift template by way of the command line:

git clone https://github.com/BinaryBirds/swift-template.git
cd swift-template
make set up

Now we simply want a starter template, happily there’s a template obtainable on GitHub that you should utilize for producing modules which can be suitable with the newest model of Feather CMS. 🪶

We’re going to set up this template with the next command:

swift template set up https://github.com/feathercms/feather-module-template -g

Now we will bootstrap our customized module by way of the next command:

swift template generate MyModule --use feather-module --output ~/

You may alter the the title of the module, use an different template (should be put in regionally or globally) and specify the output listing the place you need to save the module recordsdata.

Constructing a information module for Feather CMS

In Feather CMS you may constructing a characteristic wealthy module in only a few minutes. That is proper, I will present you how one can make one utilizing Swift template and the Feather module template starter equipment. To start with you may must seize Feather CMS from GitHub and generate a brand new module utilizing the generator.

git clone https://github.com/feathercms/feather/
cd feather
swift template generate Information -u feather-module -o ./Sources/Feather/Modules
open Bundle.swift

Replace your Swift bundle dependencies. You should utilize the Swift Bundle Supervisor and the command line (swift bundle replace) in case you are constructing the server with out Xcode. Alternatively you may open the bundle manifest file and wait till Xcode resolves the dependencies. 📦

Earlier than we run the app, just be sure you have created an area .env or .env.improvement file that Feather can use to run the server.

BASE_URL="http://localhost:8080"


BASE_PATH="/path/to/feather/"

When utilizing Xcode, please double verify that you’ve got set a customized working listing. ⚠️

Time to allow our newly created module, open to the fundamental.swift file and append the NewsBuilder() occasion to the module configuration array. This may allow the pattern information module. Now if you happen to run Feather, the brand new module ought to work by default, however earlier than we truly check out every part we’re going to alter the generated information module supply just a bit bit. 🔨

Mannequin definition

Let’s begin by altering the mannequin definition for our information entries. This may permit us to retailer information objects within the persistent database utilizing the underlying Fluent framework. The generated information module will comprise a NewsModel, we simply want to increase this mannequin with a couple of extra fields.

import FeatherCore

remaining class NewsModel: ViperModel {
    typealias Module = NewsModule

    static let title = "information"

    struct FieldKeys {
        static var title: FieldKey { "title" }
        static var imageKey: FieldKey { "image_key" }
        static var excerpt: FieldKey { "excerpt" }
        static var content material: FieldKey { "content material" }
    }

    

    @ID() var id: UUID?
    @Area(key: FieldKeys.title) var title: String
    @Area(key: FieldKeys.imageKey) var imageKey: String
    @Area(key: FieldKeys.excerpt) var excerpt: String
    @Area(key: FieldKeys.content material) var content material: String

    init() { }

    init(id: UUID? = nil,
         title: String,
         imageKey: String,
         excerpt: String,
         content material: String)
    {
        self.id = id
        self.title = title
        self.imageKey = imageKey
        self.excerpt = excerpt
        self.content material = content material
    }
}

We outlined our Fluent database mannequin with the assistance of Swift property wrappers (@ID, @Area). They’ll permit Fluent to learn and write columns within the represented database desk, so we do not have to jot down SQL queries, however we will entry the entries by way of a a lot greater stage (ORM) abstraction layer. Fairly commonplace Vapor and Fluent stuff these days. 🙃

The id is a novel identifier, we’ll save the information title as a String, the imageKey is a particular property for saving picture URLs and the excerpt goes to be a brief “sneak-peak” of your complete content material. Now we simply have to jot down a migration script, as a result of in Vapor we have now to create or replace our database tables earlier than we might use the mannequin.

import Vapor
import Fluent

struct NewsMigration_v1_0_0: Migration {

    func put together(on db: Database) -> EventLoopFuture<Void> {
        db.schema(NewsModel.schema)
            .id()
            .area(NewsModel.FieldKeys.title, .string, .required)
            .area(NewsModel.FieldKeys.imageKey, .string, .required)
            .area(NewsModel.FieldKeys.excerpt, .string, .required)
            .area(NewsModel.FieldKeys.content material, .string, .required)
            .create()
    }

    func revert(on db: Database) -> EventLoopFuture<Void> {
        db.schema(NewsModel.schema).delete()
    }
}

This migration script will create the required fields contained in the information desk and if needed we will revert the method by deleting your complete desk.

Metadata in Feather CMS

In Feather CMS every part that may be publicly accessed by way of the website must have an related metadata object. This metadata object is liable for managing the general public url (slug) and visibility of the referenced entity, it additionally shops many extra Website positioning associated particulars.

Something can change into a metadata reference, we simply must implement a particular protocol on the thing that we need to use as a frontend content material, plus we have now to setup a customized middleware so as to feed the metadata mannequin with some fundamental details about the refenreced object.

The generated template supplies a default metadata represantation for the pattern mannequin, we simply have to increase the NewsModel+Metadata.swift file with the brand new fields that we added to our mannequin. This manner our referenced metadata can know much more data concerning the information feed merchandise.

import FeatherCore

extension NewsModel: MetadataRepresentable {

    var metadata: Metadata {
        .init(slug: Self.title + "https://theswiftdev.com/" + title.slugify(),
              title: title,
              excerpt: excerpt,
              imageKey: imageKey)
    }
}

This MetadataRepresentable protocol is used once we save a information mannequin, Feather will create an related Metadata object with the returned title, excerpt and imageKey values. This connection works robotically if you happen to register a database middleware within the boot perform of your module file.

func boot(_ app: Utility) throws {
    
    app.databases.middleware.use(MetadataModelMiddleware<NewsModel>())

    
}

Utilizing the metadata API is a good way to have good Website positioning-friendly public pages in your web site backed by your personal enterprise fashions with out considering an excessive amount of concerning the underlying information construction.

Enter varieties

The default template additionally offers us the power to handle the pattern mannequin through the use of the CMS. Now we have to increase this performance a bit, as a result of we have added some additional fields.

The LeafRepresentable protocol is a part of the Leaf framework, it permits us to render fashions utilizing the template engine. Now we have so as to add our personal properties contained in the NewsModel+View.swift file.

import FeatherCore

extension NewsModel: LeafDataRepresentable {

    var leafData: LeafData {
        .dictionary([
            "id": id,
            "title": title,
            "imageKey": imageKey,
            "excerpt": excerpt,
            "content": content,
        ])
    }
}

This variation will permit us to listing, create, replace or view our mannequin with all of the obtainable fields utilizing the Content material Administration System. The generated template offers us all the CRUD operations free of charge, however the interface solely works with the title area, so we have now so as to add the opposite newly created properties if we wish to have the ability to utterly handle our mannequin.

The ModelForm protocol permits us to supply edit (create, replace) performance for a given mannequin by way of the CMS. The shape has to outline the fields that you should utilize within the Leaf template file to render them visually. The sector definitions within the kind are all about information illustration, however they do not specify the feel and appear of the gadgets on the admin interface. In different phrases these fields aren’t needed view representations, however extra like information switch objects. We’re going to put the precise view right into a separate Leaf template file in a while. 🍃

The sector varieties are predefined objects within the ViewKit framework, a FormField is an object that encapsulates a generic worth and an optionally available error message. The FileFormField object is used to switch file information whenever you need to use a file add area inside your kind. After you specified the keys that you just need to use to ship the values, you must listing these kind fields utilizing the fields variable. All the things what’s listed as a area might be robotically validated based mostly on the constraint that you’ve got placed on every area (required, size, and so on.).

If you wish to edit a metadata representable mannequin you normally need to ship the metadata data with the mannequin information, you may fetch the referenced metadata object through the use of the findMetadata methodology on a Fluent mannequin, this may load the reference asynchronously. The initialize methodology is a perfect place to carry out async init duties. You can even override the leafData variable to ship further data subsequent to the modelId, fields and notification keys.

Because the kind is tied to an underlying mannequin, we additionally must learn the mannequin information earlier than we render our kind so we will render unique area values, and after the person submits the shape we’d need to write the enter date to the mannequin. In fact the write methodology might be referred to as solely when the incoming kind fields are legitimate. You may carry out further database checks you probably have particular validation wants earlier than you truly save a mannequin.

The very final thing that we need to do is picture processing. We are able to use the processAfterFields methodology to add our picture into a short lived location, then earlier than the save methodology is known as (after the fields are validated), we will use the willSave perform to avoid wasting the picture to a remaining location and replace our mannequin with the important thing that represents our uploaded picture file. You should utilize this key in a while to render the picture file with the assistance of the Liquid file storage part. 📁

import FeatherCore

remaining class NewsEditForm: ModelForm {

    typealias Mannequin = NewsModel

    var modelId: UUID?
    var picture = FileFormField(key: "picture").required()
    var title = FormField<String>(key: "title").required().size(max: 250)
    var excerpt = FormField<String>(key: "excerpt").required().size(max: 250)
    var content material = FormField<String>(key: "content material").required()
    var notification: String?

    var metadata: Metadata?

    var fields: [FormFieldRepresentable] {
        [image, title, excerpt, content]
    }

    var leafData: LeafData {
        .dictionary([
            "modelId": modelId?.encodeToLeafData() ?? .string(nil),
            "fields": fieldsLeafData,
            "notification": .string(notification),
            "metadata": metadata?.leafData ?? .dictionary(nil),
        ])
    }

    init() {}

    func initialize(req: Request) -> EventLoopFuture<Void> {
        var future = req.eventLoop.future()
        if let id = modelId {
            future = Mannequin.findMetadata(reference: id, on: req.db).map { [unowned self] in metadata = $0 }
        }
        return future
    }

    func processAfterFields(req: Request) -> EventLoopFuture<Void> {
        picture.uploadTemporaryFile(req: req)
    }

    func learn(from enter: Mannequin)  {
        title.worth = enter.title
        excerpt.worth = enter.excerpt
        picture.worth.originalKey = enter.imageKey
        content material.worth = enter.content material
    }

    func write(to output: Mannequin) {
        output.title = title.worth!
        output.excerpt = excerpt.worth!
        output.content material = content material.worth!
    }

    func willSave(req: Request, mannequin: Mannequin) -> EventLoopFuture<Void> {
        picture.save(to: Mannequin.path, req: req).map { key in
            if let key = key {
                mannequin.imageKey = key
            }
        }
    }
}

The primary cause why varieties exists is that I needed to separate duties. A kind may also help the controller to show a display contained in the CMS utilizing a mannequin, this manner our controller recordsdata might be smaller and cleaner. Kinds cannot render themselves, so that they nonetheless want a controller object that may management them and a router to register the required URLs that we will use to hook them as much as the admin interface. Kinds normally want one URL that may be reached by way of a GET request for rendering the preliminary kind and one other one which can be utilized to POST (submit) the shape. ↗️

Admin views

The pattern module already contains the templates that we’ll must help information administration. Templates are situated within the Bundle/Templates folder beneath the module listing. The Admin folder incorporates subfolders with mannequin names and each single mannequin that we need to handle ought to have a view, edit, delete and listing template file for the CRUD operations. 🔨

These templates comply with the identical sample. Each single on of them begins with a dictionary definiton that’s utilized by one other template (inlined on the finish of the file) to render the view based mostly on the values contained in the dictionary. The admin module supplies us plenty of templates that we will use to simplify issues. There are pre-baked templates for enter varieties (Admin/Type), lists (Admin/Desk), to current affirmation earlier than delete (Admin/Delete) operation and to easily view the main points (Admin/Element) of a mannequin. You must make the most of these templates if attainable. 😉

The admin module additionally offers us reusable kind fields. Let’s alter the Edit template, we’ll add numerous enter fields for the shape fields that we outlined beforehand.

#outline(fields):
    #var(area = nil)

    #(area = ["id": "image", "data": fields.image, "accept": "image/*", "required": true])
    #inline("Admin/Fields/File")

    #(area = ["id": "title", "required": true, "data": fields.title])
    #inline("Admin/Fields/Textual content")

    #(area = ["id": "excerpt", "size": "s", "data": fields.excerpt])
    #inline("Admin/Fields/Textarea")

    #(area = ["id": "content", "size": "xl", "data": fields.content])
    #inline("Admin/Fields/Textarea")

#enddefine

Contained in the Bundle/Templates/Admin/Information/Edit.html file we simply have so as to add three new fields to symbolize our kind fiels as HTML kind components. You should utilize all sort of built-in kind components, plus each single kind is CSRF and double-submission protected, because of this you might be protected from CSRF assaults by default if you happen to comply with this design sample.

Now if you happen to run the appliance many of the performance ought to work with the newly created fields, however earlier than we accomplish that, we should always discuss admin controllers.

Admin controllers

The underlying ViperKit framework may also help us so much with the required controller setup. Fortuitously Feather comes with an extension that makes issues much more easy if we simply need to present a CRUD interface for a given mannequin. When you check out the NewsAdminController you may see that you just solely must setup the referneced module, mannequin and kind varieties so as to make issues work. 💪

You may lengthen the performance of controllers by implementing particular lifecycle strategies, for instance we will delete the uploaded picture file from the file storage through the use of the beforeDelete methodology. It is usually attainable to increase the listing performance or alter the replace, create strategies, it’s best to check out the AdminViewController protocol in case you are within the particulars.

import FeatherCore
import Fluent

struct NewsAdminController: ViperAdminViewController {

    typealias Module = NewsModule
    typealias Mannequin = NewsModel
    typealias CreateForm = NewsEditForm
    typealias UpdateForm = NewsEditForm

    func listQuery(search: String, queryBuilder: QueryBuilder<Mannequin>, req: Request) {
        queryBuilder.filter(.$title ~~ search)
    }

    func beforeDelete(req: Request, mannequin: Mannequin) -> EventLoopFuture<Mannequin> {
        req.fs.delete(key: mannequin.imageKey).map { mannequin }
    }
}

Lengthy story quick, an admin controller has every part that you will must handle your mannequin utilizing the CMS. It’s going to present a listing, get, create, replace and delete view on your mannequin.

The frontend hooks

If you wish to show information entries on the frontend as devoted pages you must implement some hook features within the module file. Fortuitously the bottom template already hooks up every part, so we simply have to vary our templates to show extra information.

The “frontend-page” hook can be utilized to fetch metadata objects for a given path and return a response if a mannequin exists for a given slug. This can be a nice method to render information entries in a Website positioning pleasant method. It’s attainable to create a separate view object an cross the request and the mannequin to it so it may possibly render the frontend web page based mostly on a template file.

We will add only one little additional modification to our frontend view. Would not be cool if we might help content material filters for the information entries? This manner we might use the markdown format (if we allow the markdown module) to jot down the content material of a information merchandise. Here is how one can do it.

struct NewsFrontendView {

    

    func information(_ information: NewsModel) -> EventLoopFuture<View> {
        var ctx = information.leafDataWithJoinedMetadata.dictionary!
        ctx["content"] = .string(information.filter(information.content material, req: req))
        return render("Information", [
            "news": .dictionary(ctx)
        ])
    }
}

You can even create *-page hooks, that you should utilize to render customized templates with the assistance of the Frontend module. The frontend module comes with a web page mannequin, that you should utilize to show pages, however it’s also attainable to attach a web page mannequin with Swift and Leaf code, that is the way it works in a nutshell. You register a hook perform (in our case “news-page”), then you definately create a brand new web page with the next contents: [news-page]. This syntax implies that you need to name a Feather hook, as an alternative of rendering the contents of the web page, so the system will search for a hook perform with a legitimate response object and if it finds one, it’s going to use it to render the web page. 🤓

In our case, the “news-page” hook makes use of the Frontend/NewsList template, that’s liable for displaying the listing of the information entries. When you click on on a listing merchandise, the frontend-page hook tries to load the information based mostly on the permalink (referenced metadata slug) and if there’s a match it’s going to render it utilizing the Frontend/Information template.

Feather makes use of the Peacock CSS library to place some type on HTML components, we will improve our information listing template. Simply alter the Frontend/NewList file, like this:

#outline(physique):

<div class="container">
    <div class="margin margin-bottom-xl">
        <header class="margin-bottom">
            <h1>Information listing</h1>
            <p class="margin-top-zero">Learn the newest information</p>
        </header>

        <part>
            #for(merchandise in information):
            <div class="background margin-bottom padding shadow">
                <a href="/#(merchandise.metadata.slug)">
                    <img src="#(merchandise.imageKey.resolve())" class="size-width-full">
                    <h2 class="margin-top-zero">#(merchandise.title)</h2>
                    <p class="margin-top-zero">#(merchandise.excerpt)</p>
                </a>
            </div>
            #endfor
        </part>
    </div>
</div>

#enddefine

#inline("Frontend/Index")

The final step is to show a correct information entry with the brand new fields. Within the Frontend/Information file replace the physique and use the next structure for the entry web page.

#outline(physique):

<div class="container">
    <div class="margin margin-bottom-xl">
        <h1>#(information.title)</h1>
        <p class="margin-top-zero">#(information.excerpt)</p>
        <img src="#(information.imageKey.resolve())" class="size-width-full margin-vertical">
        #(information.content material)
    </div>
</div>

#enddefine

#inline("Frontend/Index")

Now if you happen to construct and run every part, first you may must run the installer, after which you could log in to the admin interface and you’ll create & publish your very first information entry. You may learn extra about how one can use Feather CMS, simply learn the person handbook. As a free of charge it’s best to be capable to apply content material filters to your information merchandise, so you may make the most of the built-in markdown or the Swift syntax highlighter filters. 🤩

Abstract

On this tutorial we have created a model new module for Feather CMS utilizing loads of underlying frameworks and instruments. This may be arduous at first sight, however I actually love this strategy as a result of I can concentrate on defining my enterprise fashions as an alternative of caring for smaller particulars comparable to registering the required routes for enhancing a database entry. Feather CMS will disguise this type of complexity and supply dynamic extension factors for constructing your admin interfaces. On the frontend aspect you may simply lengthen the dynamic routing system, apply content material filters and even add your personal extension factors by way of hook features.

There may be a lot extra to speak about, however this time I will cease proper right here, if you happen to loved this tutorial please comply with me on twitter, subscribe to my publication or take into account supporting me by buying my Sensible Server Aspect Swift e book on Gumroad.