Front End Widgets - Part 1 - Creating the DB Model

After familiarizing myself with KeystoneJS I decided to use it as the CMS (content management system) of choice for my clients. This requires customizing a lot of features. After a couple false starts, I realized that the vast majority of the customization I needed to do could be accomplished by a generic front end 'widget'.

What I mean by a front end widget is a generic database model that will allow me store values for a couple images and paragraphs. I can then retrieve this wiget and display it on the front end. I realize this sounds archaic. Just bear with me, because if you are like me and need to customize KeystoneJS to create a CMS for your clients, you're going to want to see this. It's going to be a game changer for you, like it has been for me.

Here is how the tutorial breaks down:

• Part 1 - Creating the Database Model
• Part 2 - Opening the KeystoneJS API
• Part 3 - Displaying the Widget on the Front End
• Part 4 - Editing the Widget on an Artificial Back End
• Part 5 - Password Protecting the Artificial Back End

Even if you don't like my idea of the wiget. This tutorial should provide a lot of value to developers aspiring to customize KeystoneJS for their own needs.

Note: I used Handlebars instead of the default of Jade as my template of choice. When using the yo keystone command during setup of KeystoneJS, it asks you which one you want to use. If you follow the tutorials on this blog, then make sure you choose Handlebars (hbs), otherwise they won't work.

Creating the Database Model

The nice thing about KeystoneJS is the simple format for creating new MongoDB database models. Create a file called FrontendWidget.js in the models/ directory and paste this code into it:

var keystone = require('keystone');
var Types = keystone.Field.Types;

/**
 * Frontend Widget Model
 * ===========
 * Frontend Widgets are simply links to image URLs that will be posted to the front-end.
 * This model intended can be updated with a custom UI or the KeystoneJS backend.
 */

var FrontendWidget = new keystone.List('FrontendWidget', {
        map: { name: 'title' }
});

FrontendWidget.add({
        title: { type: String, required: true },
        url1: { type: String },
        alt1: { type: String },
        attributes1: { type: String },
        category: { type: String },      //Used to categorize widgets.
        priorityId: { type: String },    //Used to prioritize display order.
        url2: { type: String },
        alt2: { type: String },
        attributes2: { type: String },
        content1: { type: String },
        content2: { type: String },
        content3: { type: String },
        content4: { type: String },
        trans1: { type: String }, //default transformaiton
        trans2: { type: String }

});


FrontendWidget.defaultColumns = 'title';
FrontendWidget.register();

 

You don't have to follow the exact field entries above. Some of them, like trans1 and trans2 may not be of any use to you. Once you run through this tutorial and understand what is being done and how it's being used, feel free to make changes to your model to make it suit your needs. 

After creating that file, restart KeystoneJS, log into the back end of the Admin UI and you will see an entry for your front end widget. Isn't that awesome!? KeystoneJS automtically creates the back end pages you need to add and edit widgets. Cool!

Still, if you're like me, you probably don't want to confuse your client by letting them loose in the Admin UI. Too many options, buttons, and things to mess up. Later on in this tutorial, I'll show you how to create a front end, which I like to call the Artificial Back End, to allow them to edit the widget through the API. This allows you to remove surperfluous entries and customize the widget on-the-fly so that clients don't run amok or get confused.