Find out how to construct a Feather CMS module?

Module technology utilizing Swift templates

There’s an open supply template primarily based generator device 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 possibly can set up Swift template via 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, fortuitously there’s a template out there on GitHub that you need to use for producing modules which might be appropriate with the most recent 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 are able to bootstrap our customized module through the next command:

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

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

Constructing a information module for Feather CMS

In Feather CMS you possibly can constructing a function wealthy module in just some minutes. That is proper, I am going to present you easy methods to 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 Package deal.swift

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

Earlier than we run the app, just remember to have created a neighborhood .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 examine that you have set a customized working listing. ⚠️

Time to allow our newly created module, open to the predominant.swift file and append the NewsBuilder() occasion to the module configuration array. This can allow the pattern information module. Now should you 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 can enable us to retailer information objects within the persistent database utilizing the underlying Fluent framework. The generated information module will include a NewsModel, we simply want to increase this mannequin with just a few extra fields.

import FeatherCore

remaining class NewsModel: ViperModel {
    typealias Module = NewsModule

    static let identify = "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?
    @Discipline(key: FieldKeys.title) var title: String
    @Discipline(key: FieldKeys.imageKey) var imageKey: String
    @Discipline(key: FieldKeys.excerpt) var excerpt: String
    @Discipline(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, @Discipline). They’ll enable Fluent to learn and write columns within the represented database desk, so we do not have to jot down SQL queries, however we are able to entry the entries via a a lot greater degree (ORM) abstraction layer. Fairly normal Vapor and Fluent stuff these days. 🙃

The id is a singular identifier, we will 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 entire content material. Now we simply have to jot down a migration script, as a result of in Vapor we now have to create or replace our database tables earlier than we may 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()
            .discipline(NewsModel.FieldKeys.title, .string, .required)
            .discipline(NewsModel.FieldKeys.imageKey, .string, .required)
            .discipline(NewsModel.FieldKeys.excerpt, .string, .required)
            .discipline(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 obligatory we are able to revert the method by deleting your entire desk.

Metadata in Feather CMS

In Feather CMS every part that may be publicly accessed via the website online must have an related metadata object. This metadata object is chargeable for managing the general public url (slug) and visibility of the referenced entity, it additionally shops many extra Search engine optimization associated particulars.

Something can grow to be a metadata reference, we simply should implement a particular protocol on the article that we wish to use as a frontend content material, plus we now have to setup a customized middleware so as to feed the metadata mannequin with some fundamental details about the refenreced object.

The generated template offers 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 fashion our referenced metadata can know much more information concerning the information feed merchandise.

import FeatherCore

extension NewsModel: MetadataRepresentable {

    var metadata: Metadata {
        .init(slug: Self.identify + "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 should you 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 an effective way to have good Search engine optimization-friendly public pages in your website backed by your individual enterprise fashions with out considering an excessive amount of concerning the underlying knowledge construction.

Enter types

The default template additionally offers us the flexibility to handle the pattern mannequin through the use of the CMS. We’ve got 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. We’ve got 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 alteration will enable us to record, create, replace or view our mannequin with all of the out there fields utilizing the Content material Administration System. The generated template offers us all the CRUD operations without spending a dime, however the interface solely works with the title discipline, so we now have so as to add the opposite newly created properties if we would like to have the ability to fully handle our mannequin.

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

The sector sorts are predefined objects within the ViewKit framework, a FormField is an object that encapsulates a generic worth and an elective error message. The FileFormField object is used to switch file knowledge whenever you wish to use a file add discipline inside your kind. After you specified the keys that you simply wish to use to ship the values, it’s important to record these kind fields utilizing the fields variable. Every thing what’s listed as a discipline will probably be robotically validated primarily based on the constraint that you have placed on every discipline (required, size, and so forth.).

If you wish to edit a metadata representable mannequin you normally wish to ship the metadata information with the mannequin knowledge, you possibly can fetch the referenced metadata object through the use of the findMetadata methodology on a Fluent mannequin, this can load the reference asynchronously. The initialize methodology is a perfect place to carry out async init duties. You may as well 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 should learn the mannequin knowledge earlier than we render our kind so we are able to render authentic discipline values, and after the person submits the shape we’d wish to write the enter date to the mannequin. In fact the write methodology will probably be known as solely when the incoming kind fields are legitimate. You possibly can carry out further database checks you probably have particular validation wants earlier than you truly save a mannequin.

The very last item that we wish to do is picture processing. We will 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 are able to use the willSave perform to save lots of 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 afterward to render the picture file with the assistance of the Liquid file storage element. 📁

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 principle motive why types exists is that I wished to separate tasks. A kind might help the controller to show a display screen contained in the CMS utilizing a mannequin, this fashion our controller recordsdata will probably be smaller and cleaner. Types cannot render themselves, in order that they nonetheless want a controller object that may management them and a router to register the required URLs that we are able to use to hook them as much as the admin interface. Types normally want one URL that may be reached via 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 will must help information administration. Templates are situated within the Bundle/Templates folder underneath the module listing. The Admin folder accommodates subfolders with mannequin names and each single mannequin that we wish to handle ought to have a view, edit, delete and record 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 primarily based on the values contained in the dictionary. The admin module offers us plenty of templates that we are able to use to simplify issues. There are pre-baked templates for enter types (Admin/Kind), lists (Admin/Desk), to current affirmation earlier than delete (Admin/Delete) operation and to easily view the main points (Admin/Element) of a mannequin. It is best to benefit from these templates if doable. 😉

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

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

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

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

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

    #(discipline = ["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 characterize our kind fiels as HTML kind components. You should utilize all type of built-in kind components, plus each single kind is CSRF and double-submission protected, which means that you might be secure from CSRF assaults by default should you comply with this design sample.

Now should you run the applying a lot of the performance ought to work with the newly created fields, however earlier than we achieve this, we must always speak about admin controllers.

Admin controllers

The underlying ViperKit framework might help us quite a bit with the required controller setup. Thankfully Feather comes with an extension that makes issues much more easy if we simply wish to present a CRUD interface for a given mannequin. Should you check out the NewsAdminController you may see that you simply solely should setup the referneced module, mannequin and kind sorts so as to make issues work. 💪

You possibly can prolong the performance of controllers by implementing particular lifecycle strategies, for instance we are able to delete the uploaded picture file from the file storage through the use of the beforeDelete methodology. Additionally it is doable to increase the record performance or alter the replace, create strategies, you need 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 brief, an admin controller has every part that you’re going to 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 it’s important to implement some hook features within the module file. Thankfully the bottom template already hooks up every part, so we simply have to vary our templates to show extra knowledge.

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. It is a nice option to render information entries in a Search engine optimization pleasant method. It’s doable to create a separate view object an go the request and the mannequin to it so it may render the frontend web page primarily based on a template file.

We will add only one little additional modification to our frontend view. Would not be cool if we may help content material filters for the information entries? This fashion we may use the markdown format (if we allow the markdown module) to jot down the content material of a information merchandise. This is easy methods to 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 may as well create *-page hooks, that you need to use to render customized templates with the assistance of the Frontend module. The frontend module comes with a web page mannequin, that you need to use to show pages, however it’s also doable 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 definitely create a brand new web page with the next contents: [news-page]. This syntax signifies that you wish 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 sound response object and if it finds one, it will use it to render the web page. 🤓

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

Feather makes use of the Peacock CSS library to place some model on HTML components, we are able to improve our information record 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 record</h1>
            <p class="margin-top-zero">Learn the most recent 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 format 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 should you construct and run every part, first you may should run the installer, after which you can log in to the admin interface and you may create & publish your very first information entry. You possibly can learn extra about easy methods to use Feather CMS, simply learn the person handbook. As a free of charge you need to be capable of apply content material filters to your information merchandise, so you possibly can benefit from 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 onerous at first sight, however I actually love this method as a result of I can concentrate on defining my enterprise fashions as an alternative of taking good care of smaller particulars akin to registering the required routes for enhancing a database entry. Feather CMS will conceal this type of complexity and supply dynamic extension factors for constructing your admin interfaces. On the frontend facet you possibly can simply prolong the dynamic routing system, apply content material filters and even add your individual extension factors via hook features.

There’s a lot extra to speak about, however this time I am going to cease proper right here, should you loved this tutorial please comply with me on twitter, subscribe to my publication or think about supporting me by buying my Sensible Server Aspect Swift ebook on Gumroad.