The way to construct a Feather CMS module?

Module era utilizing Swift templates

There’s an open supply template primarily based generator software for Swift that I’ve created, as a result of I wanted one thing to shortly arrange each VIPER and Feather modules. We’re going to use this generator to begin constructing our customized Feather module. You possibly can set up Swift template by 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 obtainable on GitHub that you should use for producing modules which are appropriate 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 by way of 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’ll be able to constructing a characteristic wealthy module in just some minutes. That is proper, I will present you how you can make one utilizing Swift template and the Feather module template starter equipment. To begin 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 Package deal.swift

Replace your Swift package deal dependencies. You should utilize the Swift Package deal Supervisor and the command line (swift package deal replace) in case you are constructing the server with out Xcode. Alternatively you’ll be able to open the package deal 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.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 have 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 pieces 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 include a NewsModel, we simply want to increase this mannequin with a number of extra fields.

import FeatherCore

last 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 may 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 a a lot increased stage (ORM) abstraction layer. Fairly normal Vapor and Fluent stuff these days. 🙃

The id is a singular 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 the 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 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 essential we are able to revert the method by deleting the complete desk.

Metadata in Feather CMS

In Feather CMS all the pieces that may be publicly accessed by the site 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 grow to be a metadata reference, we simply need to implement a particular protocol on the item that we wish to use as a frontend content material, plus now we have to setup a customized middleware as a way 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 fashion our referenced metadata can know much more data 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 when 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 Website positioning-friendly public pages in your web site backed by your personal enterprise fashions with out pondering an excessive amount of concerning the underlying knowledge construction.

Enter types

The default template additionally offers 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 additional 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 listing, create, replace or view our mannequin with all of the obtainable fields utilizing the Content material Administration System. The generated template offers us the entire CRUD operations free of charge, however the interface solely works with the title area, so now we have so as to add the opposite newly created properties if we would like 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 the CMS. The shape has to outline the fields that you should use within the Leaf template file to render them visually. The sphere definitions within the kind are all about knowledge illustration, however they do not specify the appear and feel of the objects on the admin interface. In different phrases these fields aren’t essential view representations, however extra like knowledge switch objects. We’re going to put the precise view right into a separate Leaf template file in a while. 🍃

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

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

For the reason that kind is tied to an underlying mannequin, we additionally need to learn the mannequin knowledge earlier than we render our kind so we are able to render authentic area values, and after the consumer submits the shape we’d wish to write the enter date to the mannequin. After all the write methodology will probably be referred to as solely when the incoming kind fields are legitimate. You possibly can carry out extra database checks you probably have particular validation wants earlier than you really 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 named (after the fields are validated), we are able to use the willSave perform to avoid wasting the picture to a last 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

last 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 can assist 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. Varieties cannot render themselves, so that they nonetheless want a controller object that may management them and a router to register the mandatory URLs that we are able to use to hook them as much as the admin interface. Varieties often want one URL that may be reached by 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 have to help information administration. Templates are positioned within the Bundle/Templates folder below 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 listing template file for the CRUD operations. 🔨

These templates observe 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 supplies us numerous templates that we are able to use to simplify issues. There are pre-baked templates for enter types (Admin/Type), lists (Admin/Desk), to current affirmation earlier than delete (Admin/Delete) operation and to easily view the small print (Admin/Element) of a mannequin. You must benefit from these templates if doable. 😉

The admin module additionally offers us reusable kind fields. Let’s alter the Edit template, we’ll add varied 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 parts. You should utilize all sort of built-in kind parts, plus each single kind is CSRF and double-submission protected, which means that you might be secure from CSRF assaults by default when you observe this design sample.

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

Admin controllers

The underlying ViperKit framework can assist us quite a bit with the mandatory controller setup. Luckily Feather comes with an extension that makes issues much more easy if we simply wish to present a CRUD interface for a given mannequin. If you happen to check out the NewsAdminController you will see that you simply solely need to setup the referneced module, mannequin and kind sorts as a way 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 by utilizing the beforeDelete methodology. Additionally it is doable to increase the listing performance or alter the replace, create strategies, it is 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 all the pieces that you will have to handle your mannequin utilizing the CMS. It will present an inventory, 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 a must to implement some hook features within the module file. Luckily the bottom template already hooks up all the pieces, 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. This can be a nice option to render information entries in a Website positioning pleasant method. It’s doable to create a separate view object an move the request and the mannequin to it so it could possibly 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 might help content material filters for the information entries? This fashion we might use the markdown format (if we allow the markdown module) to write down the content material of a information merchandise. Here is how you 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 too create *-page hooks, that you should use to render customized templates with the assistance of the Frontend module. The frontend module comes with a web page mannequin, that you should use to show pages, however additionally it is 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 definately create a brand new web page with the next contents: [news-page]. This syntax implies 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 liable for displaying the listing of the information entries. If you happen to click on on an inventory 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 type on HTML parts, we are able to 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 when you construct and run all the pieces, first you will need to 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 how you can use Feather CMS, simply learn the consumer guide. As a free of charge it is best to have the ability to apply content material filters to your information merchandise, so you’ll be able to 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 exhausting 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 taking good care of smaller particulars resembling registering the required routes for modifying a database entry. Feather CMS will conceal this sort of complexity and supply dynamic extension factors for constructing your admin interfaces. On the frontend aspect you’ll be able to simply prolong the dynamic routing system, apply content material filters and even add your personal extension factors by hook features.

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