Tips on 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 begin constructing our customized Feather module. You may set up Swift template by means 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, thankfully there’s a template out there 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 are able to bootstrap our customized module through the next command:

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

You may alter the the identify of the module, use an different template (should be put in domestically 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’ll be able to constructing a characteristic wealthy module in only a few minutes. That is proper, I am going to present you methods to make one utilizing Swift template and the Feather module template starter equipment. To start with you will have to 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 use the Swift Bundle Supervisor and the command line (swift bundle replace) in case you are constructing the server with out Xcode. Alternatively you’ll be able to open the bundle manifest file and wait till Xcode resolves the dependencies. 📦

Earlier than we run the app, just be sure you have created a neighborhood .env or .env.growth 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 foremost.swift file and append the NewsBuilder() occasion to the module configuration array. It will allow the pattern information module. Now when you run Feather, the brand new module ought to work by default, however earlier than we really check out all the things 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. It will enable 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

closing 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?
    @Subject(key: FieldKeys.title) var title: String
    @Subject(key: FieldKeys.imageKey) var imageKey: String
    @Subject(key: FieldKeys.excerpt) var excerpt: String
    @Subject(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, @Subject). They are going to enable Fluent to learn and write columns within the represented database desk, so we do not have to write down SQL queries, however we are able to entry the entries by means of a a lot larger degree (ORM) abstraction layer. Fairly normal Vapor and Fluent stuff these days. 🙃

The id is a novel 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 complete content material. Now we simply have to write down a migration script, as a result of in Vapor now we 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 mandatory we are able to revert the method by deleting your complete desk.

Metadata in Feather CMS

In Feather CMS all the things that may be publicly accessed by means of the website online must have an related metadata object. This metadata object is accountable for managing the general public url (slug) and visibility of the referenced entity, it additionally shops many extra Search engine optimisation associated particulars.

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

The generated template gives 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 information in regards to 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 mechanically when you register a database middleware within the boot operate 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 optimisation-friendly public pages in your website backed by your individual enterprise fashions with out considering an excessive amount of in regards to the underlying information construction.

Enter types

The default template additionally provides us the flexibility to handle the pattern mannequin by utilizing the CMS. We have now to increase this performance a bit, as a result of we have added some further fields.

The LeafRepresentable protocol is a part of the Leaf framework, it permits us to render fashions utilizing the template engine. We have now 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 enable us to checklist, create, replace or view our mannequin with all of the out there fields utilizing the Content material Administration System. The generated template provides us all the CRUD operations without cost, however the interface solely works with the title discipline, so now we 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 by means 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 type are all about information illustration, however they do not specify the feel and appear of the objects on the admin interface. In different phrases these fields usually are not mandatory 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 while you need to use a file add discipline inside your type. After you specified the keys that you simply need to use to ship the values, it’s a must to checklist these type fields utilizing the fields variable. The whole lot what’s listed as a discipline will likely be mechanically validated primarily based on the constraint that you’ve got placed on every discipline (required, size, and so on.).

If you wish to edit a metadata representable mannequin you normally need to ship the metadata information with the mannequin information, you’ll be able to fetch the referenced metadata object by utilizing the findMetadata technique on a Fluent mannequin, it will load the reference asynchronously. The initialize technique is a perfect place to carry out async init duties. You too can override the leafData variable to ship further data subsequent to the modelId, fields and notification keys.

Because the type is tied to an underlying mannequin, we additionally must learn the mannequin information earlier than we render our type so we are able to render unique discipline values, and after the consumer submits the shape we’d need to write the enter date to the mannequin. After all the write technique will likely be known as solely when the incoming type fields are legitimate. You may carry out further database checks if in case you have particular validation wants earlier than you really save a mannequin.

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

import FeatherCore

closing 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 types exists is that I wished to separate tasks. A type may also help the controller to show a display screen contained in the CMS utilizing a mannequin, this manner our controller recordsdata will likely be smaller and cleaner. Types 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 are able to use to hook them as much as the admin interface. Types normally want one URL that may be reached by means of a GET request for rendering the preliminary type 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 have to assist information administration. Templates are situated within the Bundle/Templates folder underneath the module listing. The Admin folder comprises subfolders with mannequin names and each single mannequin that we need to handle ought to have a view, edit, delete and checklist 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 gives us numerous 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 small print (Admin/Element) of a mannequin. It’s best to reap the benefits of these templates if potential. 😉

The admin module additionally provides us reusable type fields. Let’s alter the Edit template, we will add varied 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 symbolize our type fiels as HTML type parts. You should use all form of built-in type parts, plus each single type is CSRF and double-submission protected, because of this you’re protected from CSRF assaults by default when you comply with this design sample.

Now when you run the applying 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 loads with the required controller setup. Thankfully Feather comes with an extension that makes issues much more easy if we simply need to present a CRUD interface for a given mannequin. In case you check out the NewsAdminController you will see that you simply solely must setup the referneced module, mannequin and type varieties with the intention to make issues work. 💪

You may 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 by utilizing the beforeDelete technique. Additionally it is potential to increase the checklist performance or alter the replace, create strategies, you must 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 all the things that you’re going to have to handle your mannequin utilizing the CMS. It’s going to present a listing, get, create, replace and delete view in your mannequin.

The frontend hooks

If you wish to show information entries on the frontend as devoted pages it’s a must to implement some hook features within the module file. Thankfully the bottom template already hooks up all the things, so we simply have to alter 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 solution to render information entries in a Search engine optimisation pleasant method. It’s potential to create a separate view object an cross 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 further modification to our frontend view. Would not be cool if we may assist content material filters for the information entries? This manner we may use the markdown format (if we allow the markdown module) to write down the content material of a information merchandise. This is 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 too can 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 potential to attach a web page mannequin with Swift and Leaf code, that is the way it works in a nutshell. You register a hook operate (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 operate with a sound 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 accountable for displaying the checklist of the information entries. In case 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’s going to render it utilizing the Frontend/Information template.

Feather makes use of the Peacock CSS library to place some type on HTML parts, we are able to improve our information checklist 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 checklist</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 when you construct and run all the things, first you will 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 methods to use Feather CMS, simply learn the consumer guide. As a free of charge you must be capable of apply content material filters to your information merchandise, so you’ll be able to reap the benefits 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 method as a result of I can give attention to defining my enterprise fashions as an alternative of taking good care of smaller particulars reminiscent of registering the required routes for enhancing a database entry. Feather CMS will cover this sort of complexity and supply dynamic extension factors for constructing your admin interfaces. On the frontend facet you’ll be able to simply prolong the dynamic routing system, apply content material filters and even add your individual extension factors by means of hook features.

There’s a lot extra to speak about, however this time I am going to cease proper right here, when you loved this tutorial please comply with me on twitter, subscribe to my e-newsletter or contemplate supporting me by buying my Sensible Server Facet Swift e-book on Gumroad.